Skip to content

Commit a790887

Browse files
committed
fix(spec): view form spells out its composite children so their rows get catalog keys
The view form declared selection, pagination, userFilters, appearance, userActions, navigation and sharing as composites with no children, so the i18n extractor emitted no key for any of their rows. Each child is now declared with the hint the panel already showed (its schema description), userFilters.fields is enumerated as a repeater with titled row properties, and the retired navigation.view / sharing.type tombstones are no longer offered. Claude-Session: https://claude.ai/code/session_01WGufzjGQVFPCizmQreyKkv Co-authored-by: Claude <noreply@anthropic.com>
1 parent a26abbc commit a790887

3 files changed

Lines changed: 241 additions & 18 deletions

File tree

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
/**
4+
* #30267 — the view form spells out every composite's children, and each
5+
* child's hint is the schema's own `.describe()` text.
6+
*
7+
* ## Why the children are declared at all
8+
*
9+
* `os i18n extract` walks a form field's DECLARED `fields` and nothing else.
10+
* A composite left to the panel's schema-derived list (`SchemaForm` falls back
11+
* to `schema.properties` when the form names no children) therefore had no
12+
* `metadataForms.view.fields['<parent>.<child>']` key for any of its rows: a
13+
* zh-CN Studio read ~70 English rows under 表格选项 / 分页 / 终端用户控制 /
14+
* 导航与共享.
15+
*
16+
* ## What declaring them costs, pinned here
17+
*
18+
* - **Completeness.** Once a composite declares children the panel renders
19+
* exactly those, so a key added to the schema block later would silently
20+
* drop out of the panel. Each declared list is held EQUAL to the schema's
21+
* live keys — every property except the `retiredKey()` tombstones, which a
22+
* form must never offer (the schema-derived list used to render
23+
* `navigation.view` and `sharing.type` as editable rows).
24+
* - **One English string.** A declared `helpText` replaces the schema
25+
* description the panel showed before, so it is held equal to that
26+
* description: an English console reads the same hint it read before, and
27+
* the two cannot drift apart. A child whose schema has no description
28+
* (`navigation.mode`) declares none.
29+
* - **Repeater row names.** `userFilters.fields` is enumerated as a repeater;
30+
* each row child's `label` is the item schema's `.meta({ title })` — the
31+
* column head the panel reads (`repeater-item-titles.test.ts` requires the
32+
* titles, this file requires the two equal).
33+
*/
34+
35+
import { describe, it, expect } from 'vitest';
36+
import { z } from 'zod';
37+
38+
import { viewForm } from './view.form';
39+
import { ViewSchema } from './view.zod';
40+
41+
type Node = Record<string, any>;
42+
type FormField = { field?: string; type?: string; label?: string; helpText?: string; fields?: FormField[] };
43+
44+
const RETIRED_PREFIX = '[REMOVED] ';
45+
46+
/** The list-view JSON Schema, derived the way Studio's view inspector derives it. */
47+
const LIST: Node = (z.toJSONSchema(ViewSchema, { io: 'input', unrepresentable: 'any' }) as Node).properties.list;
48+
49+
function formField(name: string): FormField {
50+
for (const section of (viewForm.sections ?? []) as Array<{ fields?: FormField[] }>) {
51+
for (const f of section.fields ?? []) if (f?.field === name) return f;
52+
}
53+
throw new Error(`viewForm declares no top-level field \`${name}\``);
54+
}
55+
56+
function liveKeys(props: Record<string, Node>): string[] {
57+
return Object.entries(props)
58+
.filter(([, v]) => !String(v?.description ?? '').startsWith(RETIRED_PREFIX))
59+
.map(([k]) => k);
60+
}
61+
62+
/** The composites this card spelled out, plus the one spelled out before it. */
63+
const COMPOSITES = ['selection', 'pagination', 'userFilters', 'appearance', 'userActions', 'addRecord', 'navigation', 'sharing'] as const;
64+
65+
describe('#30267 — view form composites declare their children', () => {
66+
it('reads a real schema (control: the derivation is not empty)', () => {
67+
expect(Object.keys(LIST.properties.userActions.properties)).toContain('editInline');
68+
expect(LIST.properties.navigation.properties.view.description.startsWith(RETIRED_PREFIX)).toBe(true);
69+
});
70+
71+
for (const name of COMPOSITES) {
72+
it(`${name}: declares exactly the schema's live keys, in a composite`, () => {
73+
const f = formField(name);
74+
expect(f.type).toBe('composite');
75+
const declared = (f.fields ?? []).map((c) => c.field);
76+
expect(declared.length, `${name} declares no children`).toBeGreaterThan(0);
77+
expect([...declared].sort()).toEqual(liveKeys(LIST.properties[name].properties).sort());
78+
});
79+
80+
it(`${name}: each declared hint is the schema description it replaces`, () => {
81+
const f = formField(name);
82+
const props = LIST.properties[name].properties as Record<string, Node>;
83+
for (const child of f.fields ?? []) {
84+
expect(child.helpText, `${name}.${child.field}`).toBe(props[child.field!]?.description);
85+
}
86+
});
87+
}
88+
89+
it('never offers a retired key: navigation.view, sharing.type, addRecord.mode / formView', () => {
90+
const names = (n: string) => (formField(n).fields ?? []).map((c) => c.field);
91+
expect(names('navigation')).not.toContain('view');
92+
expect(names('sharing')).not.toContain('type');
93+
expect(names('addRecord')).not.toContain('mode');
94+
expect(names('addRecord')).not.toContain('formView');
95+
});
96+
97+
it('top-level rows that gained a hint carry their schema description', () => {
98+
for (const name of ['resizable', 'compactToolbar', 'rowHeight', 'selection', 'pagination', 'addRecord', 'showRecordCount', 'navigation', 'sharing']) {
99+
expect(formField(name).helpText, name).toBe(LIST.properties[name].description);
100+
}
101+
});
102+
103+
it('userFilters.fields is a repeater whose row labels are the item schema titles', () => {
104+
const repeater = (formField('userFilters').fields ?? []).find((c) => c.field === 'fields');
105+
expect(repeater?.type).toBe('repeater');
106+
const items = LIST.properties.userFilters.properties.fields.items.properties as Record<string, Node>;
107+
const rows = repeater?.fields ?? [];
108+
expect(rows.map((r) => r.field).sort()).toEqual(liveKeys(items).sort());
109+
for (const row of rows) {
110+
expect(row.label, `userFilters.fields.${row.field}`).toBe(items[row.field!]?.title);
111+
expect(typeof row.label).toBe('string');
112+
}
113+
});
114+
});

‎packages/spec/src/ui/view.form.ts‎

Lines changed: 111 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,15 @@
1111
*
1212
* Visibility predicates use the `type` discriminator to reveal only
1313
* the surface-specific block.
14+
*
15+
* Composite children are spelled out, each with the hint the panel shows
16+
* (#30267). `os i18n extract` walks only DECLARED children, so a composite
17+
* left to the schema-derived list had no catalog key for any of its rows and
18+
* read English in every locale. A declared child's `helpText` is its schema
19+
* `.describe()` text, the hint the panel showed before it was declared;
20+
* `view-form-composite-children.test.ts` holds the two equal and holds each
21+
* child list equal to the schema's live keys, so a key added to a block
22+
* cannot go missing from the panel.
1423
*/
1524

1625
import { defineForm } from './view.zod';
@@ -95,11 +104,17 @@ export const viewForm = defineForm({
95104
collapsed: true,
96105
columns: 2,
97106
fields: [
98-
{ field: 'resizable', colSpan: 1 },
107+
{ field: 'resizable', colSpan: 1, helpText: 'Enable column resizing' },
99108
// `striped` / `bordered` inputs removed with the keys (#7176 — pass-through-only, retired).
100-
{ field: 'compactToolbar', colSpan: 1 },
101-
{ field: 'rowHeight', colSpan: 1 },
102-
{ field: 'selection', type: 'composite', colSpan: 2 },
109+
{ field: 'compactToolbar', colSpan: 1, helpText: 'Collapse Group/Color/Density/Hide-fields into a single View settings popover' },
110+
{ field: 'rowHeight', colSpan: 1, helpText: 'Row height / density setting' },
111+
{
112+
field: 'selection',
113+
type: 'composite',
114+
colSpan: 2,
115+
helpText: 'Row selection configuration',
116+
fields: [{ field: 'type', helpText: 'Selection mode' }],
117+
},
103118
],
104119
},
105120
// `pagination` is NOT grid-only: every view type accepts it, and
@@ -113,7 +128,17 @@ export const viewForm = defineForm({
113128
description: 'Page size and page-size options — every view type accepts them, not only grids.',
114129
collapsible: true,
115130
collapsed: true,
116-
fields: [{ field: 'pagination', type: 'composite' }],
131+
fields: [
132+
{
133+
field: 'pagination',
134+
type: 'composite',
135+
helpText: 'Pagination configuration',
136+
fields: [
137+
{ field: 'pageSize', helpText: 'Number of records per page. On a view with no pager (kanban, gallery, timeline) it is the fetch ceiling, and the renderer owes two things: bound its fetch at this number, and, when the filtered set is larger than it, show a visible truncation signal saying what is on screen is not the whole set' },
138+
{ field: 'pageSizeOptions', helpText: 'Available page size options' },
139+
],
140+
},
141+
],
117142
},
118143
{
119144
name: 'kanban',
@@ -172,14 +197,62 @@ export const viewForm = defineForm({
172197
collapsible: true,
173198
collapsed: true,
174199
fields: [
175-
{ field: 'userFilters', type: 'composite', helpText: 'Quick-filter bar: element style (dropdown / tabs / toggle) + exposed fields or tab presets' },
200+
{
201+
field: 'userFilters',
202+
type: 'composite',
203+
helpText: 'Quick-filter bar: element style (dropdown / tabs / toggle) + exposed fields or tab presets',
204+
fields: [
205+
{ field: 'element', helpText: 'Filter control style on object views: "dropdown" (per-field value chips). "toggle" is deprecated. "tabs" is page-only — use `listViews` for named presets.' },
206+
{
207+
field: 'fields',
208+
type: 'repeater',
209+
helpText: 'Fields exposed as quick filters (dropdown/toggle elements)',
210+
// Row-property names: every authorable row property, `label`
211+
// equal to the item schema's `.meta({ title })`, as `columns`
212+
// above does.
213+
fields: [
214+
{ field: 'field', label: 'Field' },
215+
{ field: 'label', label: 'Label' },
216+
{ field: 'type', label: 'Type' },
217+
{ field: 'options', label: 'Options' },
218+
{ field: 'showCount', label: 'Show Count' },
219+
{ field: 'defaultValues', label: 'Default Values' },
220+
],
221+
},
222+
],
223+
},
176224
// [#20301] The `tabs` repeater was REMOVED with the key it wrote — now a
177225
// `retiredKey()` tombstone on `ListViewSchema` (no renderer ever mounted a
178226
// tab bar for it). A form input for an unwritable key is the
179227
// false-compliant UI half of a retirement; named presets are `listViews`
180228
// entries, each a tab in the saved-view switcher.
181-
{ field: 'appearance', type: 'composite', helpText: 'allowedVisualizations: which renderers users may switch between' },
182-
{ field: 'userActions', type: 'composite', helpText: 'Toolbar toggles: sort / search / filter / row height' },
229+
{
230+
field: 'appearance',
231+
type: 'composite',
232+
helpText: 'allowedVisualizations: which renderers users may switch between',
233+
fields: [
234+
{ field: 'showDescription', helpText: 'Show the view description text' },
235+
{ field: 'allowedVisualizations', helpText: 'Whitelist of visualization types users can switch between (e.g. ["grid", "gallery", "kanban"])' },
236+
],
237+
},
238+
{
239+
field: 'userActions',
240+
type: 'composite',
241+
helpText: 'Toolbar toggles: sort / search / filter / row height',
242+
fields: [
243+
{ field: 'sort', helpText: 'Allow users to sort records' },
244+
{ field: 'search', helpText: 'Allow users to search records' },
245+
{ field: 'filter', helpText: 'Allow users to filter records' },
246+
{ field: 'refresh', helpText: 'Allow users to reload the view data from the backend without a full page reload' },
247+
{ field: 'rowHeight', helpText: 'Allow users to toggle row height/density' },
248+
{ field: 'group', helpText: 'Allow users to change record grouping from the toolbar. Toggle only — the grouping itself is configured in the view-level `grouping` block.' },
249+
{ field: 'addRecordForm', helpText: 'Add records through a form instead of inline' },
250+
{ field: 'editInline', helpText: 'Allow users to edit records inline. On by default: a user who may update the object edits a cell in place with the field\'s type-aware widget (the same control the form uses), under the permission gate that already decides whether the object is editable at all. Declare `editInline: false` to make the list read-only in place.' },
251+
{ field: 'hideFields', helpText: 'Allow users to hide/show fields from the toolbar (the affordance behind the view-level `hiddenFields` list). Boolean toggle — distinct from the record-details component\'s `hideFields`, which is an array of field names to omit. On by default: a reader hides and shows columns for themselves; declare `hideFields: false` to withhold the control.' },
252+
{ field: 'rowColor', helpText: 'Allow users to configure row colouring from the toolbar. Boolean toggle — the colour rules themselves live in the view-level `rowColor` block. Off by default: row colouring is opt-in.' },
253+
{ field: 'buttons', helpText: 'Custom action button IDs to show in the toolbar' },
254+
],
255+
},
183256
// [#24692] Spelled out so the form offers exactly the two live keys:
184257
// `mode` and `formView` are `retiredKey()` tombstones on
185258
// `AddRecordConfigSchema` (no renderer ever read them — the Add button
@@ -189,9 +262,13 @@ export const viewForm = defineForm({
189262
{
190263
field: 'addRecord',
191264
type: 'composite',
192-
fields: [{ field: 'enabled' }, { field: 'position' }],
265+
helpText: 'Add record entry point configuration',
266+
fields: [
267+
{ field: 'enabled', helpText: 'Show the add record entry point — REQUIRED: `true` draws the Add button, `false` declares it off' },
268+
{ field: 'position', helpText: 'Position of the add record button: `top` (the toolbar, the default), `bottom` (under the list) or `both`' },
269+
],
193270
},
194-
{ field: 'showRecordCount' },
271+
{ field: 'showRecordCount', helpText: 'Show record count at the bottom of the list' },
195272
],
196273
},
197274
{
@@ -201,8 +278,30 @@ export const viewForm = defineForm({
201278
collapsible: true,
202279
collapsed: true,
203280
fields: [
204-
{ field: 'navigation', type: 'composite' },
205-
{ field: 'sharing', type: 'composite' },
281+
// Children spelled out (#30267) so the i18n extractor emits a catalog
282+
// key per row, and so the form offers only the live keys:
283+
// `navigation.view` and `sharing.type` are `retiredKey()` tombstones
284+
// the schema-derived list used to render as editable rows.
285+
{
286+
field: 'navigation',
287+
type: 'composite',
288+
helpText: 'Configuration for item click navigation (drawer by default, page, new_window or none)',
289+
fields: [
290+
{ field: 'mode' },
291+
{ field: 'preventNavigation', helpText: 'Disable standard navigation entirely' },
292+
{ field: 'openNewTab', helpText: 'Force open in new tab (applies to page mode)' },
293+
{ field: 'size', helpText: 'Overlay size bucket for the drawer detail: \'auto\' (default — renderer derives from field count + viewport; AI writes nothing) or a coarse override sm/md/lg/xl/full. Prefer this over the pixel `width`; page mode ignores it.' },
294+
{ field: 'width', helpText: '[DEPRECATED → size] Pixel/percent width of the drawer (e.g. "600px"). A pixel width cannot be chosen at authoring time without knowing the client viewport — use the `size` bucket.' },
295+
],
296+
},
297+
{
298+
field: 'sharing',
299+
type: 'composite',
300+
helpText: 'View sharing configuration: who locked the view configuration',
301+
fields: [
302+
{ field: 'lockedBy', helpText: 'User who locked the view configuration' },
303+
],
304+
},
206305
],
207306
},
208307
],

‎packages/spec/src/ui/view.zod.ts‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2007,16 +2007,24 @@ export const ViewTabSchema = lazySchema(() => strictObject({
20072007
* Rendering details (widget, options) default to inference from the field
20082008
* definition on the source object — authors only override when needed.
20092009
*
2010+
* Each property carries a `.meta({ title })` because `view.form.ts` enumerates
2011+
* `userFilters.fields` as a repeater: the title is the English column head
2012+
* Studio reads, and the form's declared row `label` repeats it so the i18n
2013+
* extractor emits a catalog key per column (#30267).
2014+
*
20102015
* @see Airtable Interface → "User filters" panel (Dropdowns element)
20112016
*/
20122017
export const UserFilterFieldSchema = lazySchema(() => strictObject({
20132018
surface: 'this user filter field',
20142019
history: VIEW_HISTORY,
20152020
}, {
2016-
field: z.string().describe('Field name on the source object (must exist — checked by reference diagnostics)'),
2017-
label: I18nLabelSchema.optional().describe('Display label override (defaults to the field label)'),
2021+
field: z.string().describe('Field name on the source object (must exist — checked by reference diagnostics)')
2022+
.meta({ title: 'Field' }),
2023+
label: I18nLabelSchema.optional().describe('Display label override (defaults to the field label)')
2024+
.meta({ title: 'Label' }),
20182025
type: z.enum(['select', 'multi-select', 'boolean', 'date-range', 'text']).optional()
2019-
.describe('Filter control type. Omit to infer from the field definition'),
2026+
.describe('Filter control type. Omit to infer from the field definition')
2027+
.meta({ title: 'Type' }),
20202028
options: z.array(strictObject({
20212029
surface: 'this user filter option',
20222030
history: VIEW_HISTORY,
@@ -2033,10 +2041,12 @@ export const UserFilterFieldSchema = lazySchema(() => strictObject({
20332041
value: z.union([z.string(), z.number(), z.boolean()]).describe('Option value'),
20342042
label: I18nLabelSchema.describe('Option label'),
20352043
color: z.string().optional().describe('Option color token/hex'),
2036-
})).optional().describe('Static options. Omit to derive from the field definition (select options / lookup records)'),
2037-
showCount: z.boolean().optional().describe('Show per-option record counts'),
2044+
})).optional().describe('Static options. Omit to derive from the field definition (select options / lookup records)')
2045+
.meta({ title: 'Options' }),
2046+
showCount: z.boolean().optional().describe('Show per-option record counts').meta({ title: 'Show Count' }),
20382047
defaultValues: z.array(z.union([z.string(), z.number(), z.boolean()])).optional()
2039-
.describe('Pre-selected values when the view loads'),
2048+
.describe('Pre-selected values when the view loads')
2049+
.meta({ title: 'Default Values' }),
20402050
}).describe('Quick-filter field configuration'));
20412051

20422052
/**

0 commit comments

Comments
 (0)