feat(app-shell): ADR-0047 — usable interface-page config panel (#1704)

xuyushun441-sys · os-zhuang · claude · web-flow · commit b3a87eb2fc75 · 2026-06-13T22:39:00.000+08:00
* feat(app-shell): ADR-0047 — usable interface-page config panel

Three protocol-driven fixes so the interface/list page inspector is
usable (Airtable-parity), keeping the panel schema-driven:

  • SchemaForm: honour FormSectionSpec.collapsible/collapsed — render
    collapsible sections in a Collapsible with a chevron (defaultOpen =
    !collapsed). The spec already declares these flags; the renderer
    ignored them, so everything rendered flat/expanded.
  • Widget: array-of-enum → a real multi-select (MultiSelectWidget) of
    toggleable chips instead of the free-text tag fallback. Drives
    appearance.allowedVisualizations (pick, don't type).
  • InterfaceListPage: derive a default viz binding from the object when
    a viz is whitelisted but unbound (kanban groupField from the first
    select/status field, calendar from a date field, gallery from an
    image field) — like defaultColumnsFromObject. Fixes 'added kanban but
    the switcher only shows Grid': ListView only offers a viz when its
    binding resolves.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;

* test(app-shell): ADR-0047 interface-panel — multiselect, collapsible sections, default viz bindings

  • MultiSelectWidget: chips from enum, ordered toggle, clear→undefined, readOnly
  • SchemaForm: collapsed section hides body until expanded; collapsed:false
    opens; object/CEL visibleOn hides a section when false
  • InterfaceListPage default viz bindings (exported): kanban groupField from
    first select/status field, calendar date field, gallery cover; skips
    hidden/system fields

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;

---------

Co-authored-by: Jack Zhuang &lt;277994282+os-zhuang@users.noreply.github.com&gt;
Co-authored-by: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/packages/app-shell/src/views/InterfaceListPage.defaults.test.tsx b/packages/app-shell/src/views/InterfaceListPage.defaults.test.tsx
@@ -0,0 +1,54 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import {
+  defaultKanbanFromObject,
+  defaultCalendarFromObject,
+  defaultGalleryFromObject,
+} from './InterfaceListPage';
+
+/**
+ * ADR-0047: when a page whitelists a visualization (appearance.allowedVisualizations)
+ * but the source view carries no binding for it, InterfaceListPage derives a
+ * sensible default from the object's fields — so the switcher actually offers
+ * and renders the viz (Airtable auto-picks a stack field on switch). Without
+ * this, ListView.availableViews silently drops the whitelisted viz.
+ */
+const taskObject = {
+  fields: {
+    id: { type: 'autonumber' },
+    title: { type: 'text' },
+    status: { type: 'select' },
+    due_date: { type: 'date' },
+    cover: { type: 'image' },
+    created_at: { type: 'datetime' },
+  },
+};
+
+describe('InterfaceListPage default viz bindings', () => {
+  it('kanban: picks the first select field as the group field (both aliases)', () => {
+    expect(defaultKanbanFromObject(taskObject)).toEqual({ groupField: 'status', groupByField: 'status' });
+  });
+
+  it('kanban: falls back to a status-like field name when no select type exists', () => {
+    const obj = { fields: { title: { type: 'text' }, stage: { type: 'text' } } };
+    expect(defaultKanbanFromObject(obj)).toEqual({ groupField: 'stage', groupByField: 'stage' });
+  });
+
+  it('kanban: undefined when nothing groupable', () => {
+    expect(defaultKanbanFromObject({ fields: { title: { type: 'text' }, note: { type: 'text' } } })).toBeUndefined();
+  });
+
+  it('calendar: picks the first date field (skipping system audit columns)', () => {
+    expect(defaultCalendarFromObject(taskObject)).toEqual({ startDateField: 'due_date' });
+  });
+
+  it('gallery: picks the first image field', () => {
+    expect(defaultGalleryFromObject(taskObject)).toEqual({ coverField: 'cover' });
+  });
+
+  it('ignores hidden and system fields', () => {
+    const obj = { fields: { created_at: { type: 'datetime' }, hidden_sel: { type: 'select', hidden: true }, real_sel: { type: 'select' } } };
+    expect(defaultKanbanFromObject(obj)).toEqual({ groupField: 'real_sel', groupByField: 'real_sel' });
+  });
+});
diff --git a/packages/app-shell/src/views/InterfaceListPage.tsx b/packages/app-shell/src/views/InterfaceListPage.tsx
@@ -82,6 +82,59 @@ function defaultColumnsFromObject(objectDef: any): string[] {
   return [];
 }
 
+/**
+ * Default visualization bindings derived from the object's fields.
+ *
+ * ADR-0047: an interface page sets `appearance.allowedVisualizations` to
+ * whitelist renderers, but a viz only renders when its field binding
+ * resolves (kanban needs a group field, calendar a date, gallery a cover).
+ * The page config has nowhere to set those, so — like `defaultColumnsFromObject`
+ * — we auto-pick a sensible binding from the object (Airtable does the same
+ * when you switch to Kanban). Without this, a whitelisted kanban is silently
+ * dropped from the switcher and the author gets no feedback.
+ */
+function firstFieldMatching(
+  objectDef: any,
+  pred: (name: string, f: any) => boolean,
+): string | undefined {
+  const fields = objectDef?.fields;
+  if (!fields || typeof fields !== 'object') return undefined;
+  const hit = Object.entries(fields).find(
+    ([name, f]: [string, any]) => f && !f.hidden && !SYSTEM_FIELDS.has(name) && pred(name, f),
+  );
+  return hit?.[0];
+}
+
+const SELECT_TYPES = new Set(['select', 'multiselect', 'radio', 'enum', 'boolean']);
+const DATE_TYPES = new Set(['date', 'datetime', 'time']);
+const IMAGE_TYPES = new Set(['image', 'file', 'attachment', 'avatar', 'photo']);
+
+export function defaultKanbanFromObject(objectDef: any): { groupField: string; groupByField: string } | undefined {
+  const field =
+    firstFieldMatching(objectDef, (_n, f) => SELECT_TYPES.has(f.type)) ??
+    firstFieldMatching(objectDef, (n) => /status|stage|state|priority|category|kind/i.test(n));
+  // ListView reads `groupField` to render and `groupByField || groupField`
+  // to decide the viz is available — set both so it resolves either way.
+  return field ? { groupField: field, groupByField: field } : undefined;
+}
+
+function defaultDateField(objectDef: any): string | undefined {
+  return (
+    firstFieldMatching(objectDef, (_n, f) => DATE_TYPES.has(f.type)) ??
+    firstFieldMatching(objectDef, (n) => /date|due|start|end|deadline|schedule/i.test(n))
+  );
+}
+
+export function defaultCalendarFromObject(objectDef: any): { startDateField: string } | undefined {
+  const field = defaultDateField(objectDef);
+  return field ? { startDateField: field } : undefined;
+}
+
+export function defaultGalleryFromObject(objectDef: any): { coverField: string } | undefined {
+  const field = firstFieldMatching(objectDef, (_n, f) => IMAGE_TYPES.has(f.type));
+  return field ? { coverField: field } : undefined;
+}
+
 export function InterfaceListPage({ page, className }: InterfaceListPageProps) {
   const { t } = useObjectTranslation();
   const { objects } = useMetadata();
@@ -163,8 +216,22 @@ export function InterfaceListPage({ page, className }: InterfaceListPageProps) {
     const view = viewDef || {};
     const appearance = cfg.appearance ?? view.appearance;
     const allowed: string[] = appearance?.allowedVisualizations || [];
+    const allowedSet = new Set(allowed);
     const userActions = cfg.userActions || {};
 
+    // Viz field bindings: the referenced view's config wins; otherwise, when
+    // the author whitelisted a viz, derive a sensible default binding from the
+    // object so the switcher actually offers (and renders) it. Only derive for
+    // whitelisted types — an un-whitelisted viz is never reachable.
+    const kanban =
+      view.kanban ?? (allowedSet.has('kanban') ? defaultKanbanFromObject(objectDef) : undefined);
+    const calendar =
+      view.calendar ?? (allowedSet.has('calendar') ? defaultCalendarFromObject(objectDef) : undefined);
+    const timeline =
+      view.timeline ?? (allowedSet.has('timeline') ? defaultCalendarFromObject(objectDef) : undefined);
+    const gallery =
+      view.gallery ?? (allowedSet.has('gallery') ? defaultGalleryFromObject(objectDef) : undefined);
+
     // Inherited data semantics (the iron rule: all from the view) + the
     // page's own always-on criteria (`filterBy`).
     const filters = [
@@ -190,10 +257,10 @@ export function InterfaceListPage({ page, className }: InterfaceListPageProps) {
       pagination: view.pagination,
       searchableFields: view.searchableFields,
       emptyState: view.emptyState,
-      kanban: view.kanban,
-      calendar: view.calendar,
-      gallery: view.gallery,
-      timeline: view.timeline,
+      kanban,
+      calendar,
+      gallery,
+      timeline,
       gantt: view.gantt,
 
       // Presentation policy — the page layer (ADR-0047).
diff --git a/packages/app-shell/src/views/metadata-admin/MultiSelectWidget.test.tsx b/packages/app-shell/src/views/metadata-admin/MultiSelectWidget.test.tsx
@@ -0,0 +1,67 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render, screen, fireEvent, cleanup } from '@testing-library/react';
+import { WIDGETS } from './widgets';
+
+afterEach(cleanup);
+
+const MultiSelect = WIDGETS['multiselect'];
+
+// `appearance.allowedVisualizations` serialises (Zod z.enum) as
+// { type: 'array', items: { type: 'string', enum: [...] } }.
+const vizSchema = {
+  type: 'array',
+  items: { type: 'string', enum: ['grid', 'kanban', 'calendar', 'gallery'] },
+};
+
+/**
+ * ADR-0047 multi-select widget — picks from a fixed option set (array of
+ * enum) instead of the free-text tag fallback the generic array renderer
+ * used. Author picks the real allowed values; can't mistype them.
+ */
+describe('multiselect widget', () => {
+  it('renders a chip per enum value with humanised labels', () => {
+    render(<MultiSelect value={[]} onChange={() => {}} schema={vizSchema} />);
+    expect(screen.getByRole('checkbox', { name: 'Grid' })).toBeInTheDocument();
+    expect(screen.getByRole('checkbox', { name: 'Kanban' })).toBeInTheDocument();
+    expect(screen.getByRole('checkbox', { name: 'Calendar' })).toBeInTheDocument();
+    expect(screen.getByRole('checkbox', { name: 'Gallery' })).toBeInTheDocument();
+  });
+
+  it('reflects the selected subset via aria-checked', () => {
+    render(<MultiSelect value={['grid', 'kanban']} onChange={() => {}} schema={vizSchema} />);
+    expect(screen.getByRole('checkbox', { name: 'Grid' })).toHaveAttribute('aria-checked', 'true');
+    expect(screen.getByRole('checkbox', { name: 'Kanban' })).toHaveAttribute('aria-checked', 'true');
+    expect(screen.getByRole('checkbox', { name: 'Calendar' })).toHaveAttribute('aria-checked', 'false');
+  });
+
+  it('toggling an option adds it, preserving enum declaration order', () => {
+    const onChange = vi.fn();
+    render(<MultiSelect value={['kanban']} onChange={onChange} schema={vizSchema} />);
+    fireEvent.click(screen.getByRole('checkbox', { name: 'Grid' }));
+    // grid precedes kanban in the enum → ordered output, not insertion order.
+    expect(onChange).toHaveBeenCalledWith(['grid', 'kanban']);
+  });
+
+  it('toggling a selected option removes it', () => {
+    const onChange = vi.fn();
+    render(<MultiSelect value={['grid', 'kanban']} onChange={onChange} schema={vizSchema} />);
+    fireEvent.click(screen.getByRole('checkbox', { name: 'Grid' }));
+    expect(onChange).toHaveBeenCalledWith(['kanban']);
+  });
+
+  it('clearing the last option emits undefined (omit, not empty array)', () => {
+    const onChange = vi.fn();
+    render(<MultiSelect value={['grid']} onChange={onChange} schema={vizSchema} />);
+    fireEvent.click(screen.getByRole('checkbox', { name: 'Grid' }));
+    expect(onChange).toHaveBeenCalledWith(undefined);
+  });
+
+  it('is read-only when readOnly — clicks do not emit', () => {
+    const onChange = vi.fn();
+    render(<MultiSelect value={['grid']} onChange={onChange} schema={vizSchema} readOnly />);
+    fireEvent.click(screen.getByRole('checkbox', { name: 'Kanban' }));
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/app-shell/src/views/metadata-admin/SchemaForm.collapsible.test.tsx b/packages/app-shell/src/views/metadata-admin/SchemaForm.collapsible.test.tsx
@@ -0,0 +1,73 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, afterEach } from 'vitest';
+import { render, screen, fireEvent, cleanup } from '@testing-library/react';
+import { SchemaForm } from './SchemaForm';
+
+afterEach(cleanup);
+
+const schema = {
+  type: 'object',
+  properties: {
+    openField: { type: 'string', title: 'Open Field' },
+    advancedField: { type: 'string', title: 'Advanced Field' },
+  },
+};
+
+/**
+ * ADR-0047: the spec form already declares which sections are collapsible
+ * and which start collapsed (Advanced, type-specific options). The renderer
+ * must honour those flags so the panel opens lean — previously they were
+ * ignored and every section rendered flat/expanded.
+ */
+describe('SchemaForm — collapsible sections', () => {
+  const form = {
+    type: 'simple' as const,
+    sections: [
+      { label: 'Basics', fields: [{ field: 'openField' }] },
+      { label: 'Advanced', collapsible: true, collapsed: true, fields: [{ field: 'advancedField' }] },
+    ],
+  };
+
+  it('a collapsed section hides its body until the header is clicked', () => {
+    render(<SchemaForm schema={schema} form={form} value={{ openField: '', advancedField: '' }} onChange={() => {}} />);
+    // Non-collapsible section's field is always present.
+    expect(screen.getByText('Open Field')).toBeInTheDocument();
+    // Collapsed section: header present, body (its field) not yet mounted.
+    expect(screen.getByText('Advanced')).toBeInTheDocument();
+    expect(screen.queryByText('Advanced Field')).not.toBeInTheDocument();
+    // Expand it.
+    fireEvent.click(screen.getByText('Advanced'));
+    expect(screen.getByText('Advanced Field')).toBeInTheDocument();
+  });
+
+  it('a collapsible section with collapsed:false renders open', () => {
+    const openForm = {
+      type: 'simple' as const,
+      sections: [
+        { label: 'Interface', collapsible: true, collapsed: false, fields: [{ field: 'openField' }] },
+      ],
+    };
+    render(<SchemaForm schema={schema} form={openForm} value={{ openField: '' }} onChange={() => {}} />);
+    expect(screen.getByText('Open Field')).toBeInTheDocument();
+  });
+
+  it('hides a section whose visibleOn predicate is false (object/CEL form)', () => {
+    const condForm = {
+      type: 'simple' as const,
+      sections: [
+        { label: 'Basics', fields: [{ field: 'openField' }] },
+        {
+          label: 'Layout',
+          visibleOn: { dialect: 'cel', source: "data.type != 'list'" },
+          fields: [{ field: 'advancedField' }],
+        },
+      ],
+    };
+    render(<SchemaForm schema={{ ...schema, properties: { ...schema.properties, type: { type: 'string' } } }} form={condForm} value={{ type: 'list', openField: '', advancedField: '' }} onChange={() => {}} />);
+    // type == 'list' → "data.type != 'list'" is false → Layout hidden.
+    expect(screen.queryByText('Layout')).not.toBeInTheDocument();
+    expect(screen.queryByText('Advanced Field')).not.toBeInTheDocument();
+    expect(screen.getByText('Open Field')).toBeInTheDocument();
+  });
+});
diff --git a/packages/app-shell/src/views/metadata-admin/SchemaForm.tsx b/packages/app-shell/src/views/metadata-admin/SchemaForm.tsx
@@ -49,6 +49,11 @@ import {
   TabsTrigger,
   TabsContent,
 } from '@object-ui/components';
+import {
+  Collapsible,
+  CollapsibleTrigger,
+  CollapsibleContent,
+} from '@object-ui/components';
 import { evaluatePredicate } from './predicate';
 import { WIDGETS, type WidgetContext } from './widgets';
 import { detectLocale, t, tFormat, translateValidationMessage } from './i18n';
@@ -199,6 +204,11 @@ function inferWidget(
   if (schema) {
     const type = schema.type;
     
+    // Array of enum → multi-select of the allowed values (picker, not free
+    // text). Checked before the generic string-array case because a Zod
+    // `z.enum` serialises as `items: { type: 'string', enum: [...] }`.
+    if (type === 'array' && Array.isArray(schema.items?.enum)) return 'multiselect';
+
     // Array of strings → string-tags
     if (type === 'array' && schema.items?.type === 'string') return 'string-tags';
     
@@ -541,21 +551,7 @@ function SectionedSchemaForm({
       });
     if (fields.length === 0) return null;
     const cols = s.columns ?? 1;
-    return (
-      <section
-        key={idx}
-        className="space-y-3 rounded-md border border-border/40 bg-card/30 p-4"
-      >
-        {s.label && (
-          <header>
-            <h3 className="text-sm font-semibold text-foreground/90">
-              {s.label}
-            </h3>
-            {s.description && (
-              <p className="text-xs text-muted-foreground">{s.description}</p>
-            )}
-          </header>
-        )}
+    const fieldsGrid = (
         <div
           className="grid gap-4"
           style={{
@@ -601,6 +597,56 @@ function SectionedSchemaForm({
             );
           })}
         </div>
+    );
+
+    // Collapsible section (FormSectionSpec.collapsible) — the spec marks
+    // rarely-used groups (Advanced, type-specific options) collapsible and
+    // often `collapsed: true`. Honour both so the panel opens lean and the
+    // author expands only what they need. Non-collapsible sections render
+    // as a plain bordered block (unchanged).
+    if (s.collapsible && s.label) {
+      return (
+        <Collapsible
+          key={idx}
+          defaultOpen={!s.collapsed}
+          className="rounded-md border border-border/40 bg-card/30"
+        >
+          <CollapsibleTrigger className="group flex w-full items-center justify-between gap-2 p-4 text-left">
+            <span>
+              <span className="block text-sm font-semibold text-foreground/90">
+                {s.label}
+              </span>
+              {s.description && (
+                <span className="mt-0.5 block text-xs text-muted-foreground">
+                  {s.description}
+                </span>
+              )}
+            </span>
+            <ChevronDown className="h-4 w-4 shrink-0 text-muted-foreground transition-transform group-data-[state=closed]:-rotate-90" />
+          </CollapsibleTrigger>
+          <CollapsibleContent className="space-y-3 px-4 pb-4">
+            {fieldsGrid}
+          </CollapsibleContent>
+        </Collapsible>
+      );
+    }
+
+    return (
+      <section
+        key={idx}
+        className="space-y-3 rounded-md border border-border/40 bg-card/30 p-4"
+      >
+        {s.label && (
+          <header>
+            <h3 className="text-sm font-semibold text-foreground/90">
+              {s.label}
+            </h3>
+            {s.description && (
+              <p className="text-xs text-muted-foreground">{s.description}</p>
+            )}
+          </header>
+        )}
+        {fieldsGrid}
       </section>
     );
   };
diff --git a/packages/app-shell/src/views/metadata-admin/widgets.tsx b/packages/app-shell/src/views/metadata-admin/widgets.tsx
