refactor(views): ListView's aria and sharing are the spec sub-shapes (#2890) (#2949)

Last rename batch in the ListView vocabulary migration.

`aria` is now the spec's AriaPropsSchema: `label` → `ariaLabel`, `describedBy` →
`ariaDescribedBy`, folded at the ListView boundary like every other legacy key.
Two things fall out of adopting the spec shape: `role` becomes authorable (the
region hardcoded `role="region"`; it now reads `aria.role` and falls back), and
`aria.live` stays as a documented local extension — no spec counterpart, and
dropping it would silently disable a shipped capability.

`sharing` is now the spec's ViewSharingSchema ({ type, lockedBy }), imported by
reference; the local four-key object is gone. `visibility` collapses onto the
two ownership kinds the spec models (only `private` is personal), and a bare
`enabled: true` maps to `personal` — the badge the user already saw, since the
old title fell back to 'private'.

Visible change: the share badge tooltip shows the spec ownership type, so
`visibility: 'team'` reads "Sharing: collaborative". The four-value audience has
no spec home and nothing but that tooltip consumed it; keeping a second audience
enum alive would re-open the fork this issue closes.

Also fixes the spec bridge, which was doing the opposite of its job: given a
spec-shaped `sharing`, transformListView DOWNGRADED it — inventing a legacy
`visibility` and an `enabled` flag the renderer then had to fold back. Both
sides speak ViewSharing now, so it passes through.

`conditionalFormatting` and `exportOptions` are deliberately NOT folded: both
objectui shapes are supersets carrying capability the spec cannot express (the
{field, operator, value} rule form; maxRecords / includeHeaders /
fileNamePrefix). Folding them onto the narrower spec shapes would delete working
features — they want promotion upstream, not a rename.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/listview-aria-sharing-vocabulary.md

@@ -0,0 +1,44 @@
+---
+"@object-ui/core": minor
+"@object-ui/types": minor
+"@object-ui/plugin-list": minor
+"@object-ui/react": minor
+---
+
+refactor(views): ListView's `aria` and `sharing` are the spec sub-shapes (#2890 scope A step 5)
+
+Last rename batch in the ListView vocabulary migration.
+
+**`aria`** is now the spec's `AriaPropsSchema`: `label` → `ariaLabel`,
+`describedBy` → `ariaDescribedBy`, folded at the ListView boundary like every
+other legacy key. Two things fall out of adopting the spec shape:
+
+- `role` becomes authorable. The list region hardcoded `role="region"`; it now
+  reads `aria.role` and falls back to `region`.
+- `aria.live` stays as a documented local extension — it has no spec
+  counterpart, and dropping it would silently disable a shipped capability.
+  Promote it rather than growing that extension.
+
+**`sharing`** is now the spec's `ViewSharingSchema` (`{ type, lockedBy }`),
+imported by reference — the local four-key object is gone. The legacy pair folds
+in: `visibility` collapses onto the two ownership kinds the spec models (only
+`private` is `personal`; `team` / `organization` / `public` are all
+`collaborative`), and a bare `enabled: true` maps to `personal`, which is the
+badge the user already saw (the old title fell back to `'private'`).
+
+*Visible change*: the share badge's tooltip shows the spec ownership type, so a
+view authored with `visibility: 'team'` reads "Sharing: collaborative" instead
+of "Sharing: team". The four-value audience has no spec home and nothing but
+that tooltip consumed it; keeping a second audience enum alive would re-open the
+fork this issue closes.
+
+Also fixes the **spec bridge**, which was doing the opposite of its job: given a
+spec-shaped `sharing`, `transformListView` *downgraded* it — inventing a legacy
+`visibility` audience and an `enabled` flag that the renderer then had to fold
+back. Both sides speak `ViewSharing` now, so it passes through.
+
+`conditionalFormatting` and `exportOptions` are deliberately **not** folded.
+Both objectui shapes are supersets carrying capability the spec cannot express —
+the `{ field, operator, value }` rule form, and `maxRecords` / `includeHeaders`
+/ `fileNamePrefix`. Folding them onto the narrower spec shapes would delete
+working features; they want promotion upstream, not a rename.

packages/core/src/utils/__tests__/normalize-list-view.test.ts

@@ -204,6 +204,55 @@ describe('normalizeListViewSchema (#2890)', () => {
     });
   });
 
+  describe('aria / sharing → the spec sub-shapes', () => {
+    it('folds the legacy ARIA spellings onto the spec AriaProps keys', () => {
+      const out = normalizeListViewSchema({
+        viewType: 'grid',
+        aria: { label: 'Accounts', describedBy: 'hint', live: 'polite' },
+      }) as Record<string, Record<string, unknown>>;
+      expect(out.aria).toEqual({ ariaLabel: 'Accounts', ariaDescribedBy: 'hint', live: 'polite' });
+    });
+
+    it('keeps `role` and lets the canonical spellings win', () => {
+      const out = normalizeListViewSchema({
+        viewType: 'grid',
+        aria: { ariaLabel: 'canonical', label: 'legacy', role: 'grid' },
+      }) as Record<string, Record<string, unknown>>;
+      expect(out.aria).toEqual({ ariaLabel: 'canonical', role: 'grid' });
+    });
+
+    it('collapses the visibility audience onto the spec ownership type', () => {
+      // Only `private` is personal; every wider audience is collaborative.
+      for (const [visibility, type] of Object.entries({
+        private: 'personal',
+        team: 'collaborative',
+        organization: 'collaborative',
+        public: 'collaborative',
+      })) {
+        const out = normalizeListViewSchema({ viewType: 'grid', sharing: { visibility } }) as Record<string, unknown>;
+        expect(out.sharing).toEqual({ type });
+      }
+    });
+
+    it('maps a bare `enabled: true` to `personal` — the badge it used to render', () => {
+      const out = normalizeListViewSchema({ viewType: 'grid', sharing: { enabled: true } }) as Record<string, unknown>;
+      expect(out.sharing).toEqual({ type: 'personal' });
+    });
+
+    it('leaves `enabled: false` without a type, so the share badge stays hidden', () => {
+      const out = normalizeListViewSchema({ viewType: 'grid', sharing: { enabled: false } }) as Record<string, unknown>;
+      expect(out.sharing).toEqual({});
+    });
+
+    it('preserves `lockedBy` and lets an explicit `type` win over `visibility`', () => {
+      const out = normalizeListViewSchema({
+        viewType: 'grid',
+        sharing: { type: 'collaborative', visibility: 'private', lockedBy: 'u1' },
+      }) as Record<string, unknown>;
+      expect(out.sharing).toEqual({ type: 'collaborative', lockedBy: 'u1' });
+    });
+  });
+
   describe('viewType defaulting', () => {
     it('defaults a missing view kind to the renderable `grid`', () => {
       expect(normalizeListViewSchema({ type: 'list-view' })).toEqual({ type: 'list-view', viewType: 'grid' });

packages/core/src/utils/normalize-list-view.ts

@@ -75,6 +75,24 @@ const SHOW_FLAG_TO_USER_ACTION: Record<string, string> = {
   showColor: 'rowColor',
 };
 
+/**
+ * Legacy `sharing.visibility` → the spec's `ViewSharing.type`. The spec models
+ * two ownership kinds; objectui's four-value audience enum collapses onto them:
+ * only `private` is personal, everything wider is collaborative.
+ */
+const VISIBILITY_TO_SHARING_TYPE: Record<string, 'personal' | 'collaborative'> = {
+  private: 'personal',
+  team: 'collaborative',
+  organization: 'collaborative',
+  public: 'collaborative',
+};
+
+/** Legacy ARIA spellings → the spec's `AriaProps` keys. */
+const ARIA_KEY_ALIASES: Record<string, string> = {
+  label: 'ariaLabel',
+  describedBy: 'ariaDescribedBy',
+};
+
 /**
  * ObjectUI's `list-view` node historically used a different vocabulary from
  * `@objectstack/spec` for the same concepts (`fields` where the spec says
@@ -116,6 +134,10 @@ const SHOW_FLAG_TO_USER_ACTION: Record<string, string> = {
  *    stays absent, because the defaults are per-toggle (search/sort/filter/
  *    rowHeight/group default ON, hideFields/rowColor default OFF) and belong to
  *    the renderer, not to the vocabulary bridge.
+ *  - `aria: { label, describedBy }` → the spec's `AriaProps`
+ *    (`{ ariaLabel, ariaDescribedBy }`), and `sharing: { visibility, enabled }`
+ *    → the spec's `ViewSharing` (`{ type }`) — #2890 scope A step 5. `aria.live`
+ *    survives untouched: it has no spec counterpart.
  *  - `filters` → `filter` (#2890 scope A step 4). A key rename only: BOTH keys
  *    carry an ObjectQL FilterNode array (`[['stage','=','won']]`) everywhere in
  *    objectui — every consumer passes the value straight to `$filter`. The spec
@@ -140,11 +162,15 @@ export function normalizeListViewSchema<T>(schema: T): T {
   const foldFilter = Array.isArray(legacyFilters);
   const legacyFlags = Object.keys(SHOW_FLAG_TO_USER_ACTION).filter((k) => typeof s[k] === 'boolean');
   const foldDescription = typeof s.showDescription === 'boolean';
+  const aria = isRecord(s.aria) ? s.aria : undefined;
+  const foldAria = !!aria && Object.keys(ARIA_KEY_ALIASES).some((k) => aria[k] !== undefined);
+  const sharing = isRecord(s.sharing) ? s.sharing : undefined;
+  const foldSharing = !!sharing && (sharing.visibility !== undefined || sharing.enabled !== undefined);
   const viewType = s.viewType;
   const defaultViewKind = !viewType || viewType === 'list';
   if (
     !foldColumns && !foldRowHeight && !foldFilter && !legacyFlags.length &&
-    !foldDescription && !defaultViewKind
+    !foldDescription && !foldAria && !foldSharing && !defaultViewKind
   ) {
     return schema;
   }
@@ -183,6 +209,35 @@ export function normalizeListViewSchema<T>(schema: T): T {
     delete next.showDescription;
     next.appearance = appearance;
   }
+  if (foldAria && aria) {
+    const nextAria: Record<string, unknown> = { ...aria };
+    for (const [legacy, canonical] of Object.entries(ARIA_KEY_ALIASES)) {
+      if (nextAria[canonical] === undefined && aria[legacy] !== undefined) {
+        nextAria[canonical] = aria[legacy];
+      }
+      delete nextAria[legacy];
+    }
+    next.aria = nextAria;
+  }
+  if (foldSharing && sharing) {
+    const nextSharing: Record<string, unknown> = { ...sharing };
+    if (nextSharing.type === undefined) {
+      const visibility = typeof sharing.visibility === 'string' ? sharing.visibility : undefined;
+      // `enabled: true` with no audience is under-specified legacy input. It
+      // used to render the share badge titled "private", so it maps to
+      // `personal` — preserving what the user saw rather than adopting the
+      // spec's `collaborative` default and silently relabeling the badge.
+      const resolved = visibility
+        ? VISIBILITY_TO_SHARING_TYPE[visibility]
+        : sharing.enabled === true
+          ? 'personal'
+          : undefined;
+      if (resolved) nextSharing.type = resolved;
+    }
+    delete nextSharing.visibility;
+    delete nextSharing.enabled;
+    next.sharing = nextSharing;
+  }
   if (defaultViewKind) next.viewType = 'grid';
   return next as T;
 }

packages/plugin-list/src/ListView.tsx

@@ -1744,10 +1744,10 @@ export const ListView = React.forwardRef<ListViewHandle, ListViewProps>(({
     <div
       ref={pullRef}
       className={cn('flex flex-col h-full bg-background relative min-w-0 overflow-hidden', className)}
-      {...(schema.aria?.label ? { 'aria-label': schema.aria.label } : {})}
-      {...(schema.aria?.describedBy ? { 'aria-describedby': schema.aria.describedBy } : {})}
+      {...(schema.aria?.ariaLabel ? { 'aria-label': schema.aria.ariaLabel as string } : {})}
+      {...(schema.aria?.ariaDescribedBy ? { 'aria-describedby': schema.aria.ariaDescribedBy } : {})}
       {...(schema.aria?.live ? { 'aria-live': schema.aria.live } : {})}
-      role="region"
+      role={schema.aria?.role ?? 'region'}
       aria-busy={loading || undefined}
       data-state={loading ? 'loading' : 'idle'}
     >
@@ -2242,12 +2242,12 @@ export const ListView = React.forwardRef<ListViewHandle, ListViewProps>(({
           )}
 
           {/* Share — supports both ObjectUI visibility model and spec personal/collaborative model */}
-          {(schema.sharing?.enabled || schema.sharing?.type) && (
+          {schema.sharing?.type && (
             <Button
               variant="ghost"
               size="sm"
               className="h-7 px-2 text-muted-foreground hover:text-primary text-xs transition-colors duration-150"
-              title={`Sharing: ${schema.sharing?.visibility || schema.sharing?.type || 'private'}`}
+              title={`Sharing: ${schema.sharing.type}`}
               data-testid="share-button"
             >
               <Share2 className="h-3.5 w-3.5 mr-1.5" />
@@ -2271,7 +2271,7 @@ export const ListView = React.forwardRef<ListViewHandle, ListViewProps>(({
 
           {/* --- Separator: Print/Share/Export | Search --- */}
           {(() => {
-            const hasLeftSideItems = schema.allowPrinting || (schema.sharing?.enabled || schema.sharing?.type) || (resolvedExportOptions && exportPermitted);
+            const hasLeftSideItems = schema.allowPrinting || !!schema.sharing?.type || (resolvedExportOptions && exportPermitted);
             return toolbarFlags.showSearch && hasLeftSideItems ? (
               <div className="h-5 w-px bg-border/50 mx-1 shrink-0" />
             ) : null;

packages/plugin-list/src/__tests__/ListView.test.tsx

@@ -584,7 +584,9 @@ describe('ListView', () => {
     renderWithProvider(<ListView schema={schema} />);
     const shareButton = screen.getByTestId('share-button');
     expect(shareButton).toBeInTheDocument();
-    expect(shareButton).toHaveAttribute('title', 'Sharing: team');
+    // #2890: the badge shows the spec's ownership type. The legacy four-value
+    // audience (`team`) collapses onto it — only `private` is personal.
+    expect(shareButton).toHaveAttribute('title', 'Sharing: collaborative');
   });
 
   it('should not render share button when sharing is not enabled', () => {

packages/react/src/spec-bridge/__tests__/P1SpecBridge.test.ts

@@ -340,30 +340,28 @@ describe('P1 SpecBridge Protocol Alignment', () => {
   // P2 Sharing / ExportOptions / Pagination Protocol Alignment
   // ========================================================================
   describe('P2 sharing/exportOptions/pagination alignment', () => {
-    it('should normalize spec sharing { type: personal } to { visibility: private, enabled: true }', () => {
+    // #2890: `sharing` is the spec's `ViewSharing` shape on BOTH sides now, so
+    // the bridge passes it through. It used to downgrade it here — inventing a
+    // legacy `visibility` audience and an `enabled` flag that the renderer then
+    // had to fold back into `type`.
+    it('should pass spec sharing { type: personal } through unchanged', () => {
       const bridge = new SpecBridge();
       const node = bridge.transformListView({
         name: 'personal_view',
         sharing: { type: 'personal', lockedBy: 'admin@example.com' },
       });
 
-      expect(node.sharing).toBeDefined();
-      expect(node.sharing.visibility).toBe('private');
-      expect(node.sharing.enabled).toBe(true);
-      expect(node.sharing.type).toBe('personal');
-      expect(node.sharing.lockedBy).toBe('admin@example.com');
+      expect(node.sharing).toEqual({ type: 'personal', lockedBy: 'admin@example.com' });
     });
 
-    it('should normalize spec sharing { type: collaborative } to { visibility: team, enabled: true }', () => {
+    it('should pass spec sharing { type: collaborative } through unchanged', () => {
       const bridge = new SpecBridge();
       const node = bridge.transformListView({
         name: 'collab_view',
         sharing: { type: 'collaborative' },
       });
 
-      expect(node.sharing.visibility).toBe('team');
-      expect(node.sharing.enabled).toBe(true);
-      expect(node.sharing.type).toBe('collaborative');
+      expect(node.sharing).toEqual({ type: 'collaborative' });
     });
 
     it('should preserve ObjectUI sharing format without overriding', () => {

packages/react/src/spec-bridge/bridges/list-view.ts

@@ -116,17 +116,10 @@ export const bridgeListView: BridgeFn<ListViewSpec> = (
 
   // P1.6 — i18n & ARIA
   if (spec.aria) node.aria = spec.aria;
-  if (spec.sharing) {
-    // Normalize spec sharing format: map type → visibility, set enabled = true
-    const sharing: Record<string, any> = { ...spec.sharing };
-    if (sharing.type && !sharing.visibility) {
-      sharing.visibility = sharing.type === 'collaborative' ? 'team' : 'private';
-    }
-    if (sharing.type && sharing.enabled == null) {
-      sharing.enabled = true;
-    }
-    node.sharing = sharing;
-  }
+  // `sharing` is already the spec's `ViewSharing` shape on both sides (#2890) —
+  // this used to DOWNGRADE it here, inventing a legacy `visibility` audience and
+  // an `enabled` flag that the renderer then had to fold back.
+  if (spec.sharing) node.sharing = spec.sharing;
   if (spec.hiddenFields) node.hiddenFields = spec.hiddenFields;
   if (spec.fieldOrder) node.fieldOrder = spec.fieldOrder;
   if (spec.description) node.description = spec.description;

packages/types/src/zod/objectql.zod.ts

@@ -31,6 +31,7 @@ import {
   SelectionConfigSchema as SpecSelectionConfigSchema,
   PaginationConfigSchema as SpecPaginationConfigSchema,
   UserActionsConfigSchema as SpecUserActionsConfigSchema,
+  AriaPropsSchema as SpecAriaPropsSchema,
 } from '@objectstack/spec/ui';
 import { BaseSchema } from './base.zod.js';
 
@@ -309,7 +310,6 @@ const SpecListViewFields = SpecListViewSchema
     description: true,
     userFilters: true,
     userActions: true,
-    sharing: true,
     aria: true,
     conditionalFormatting: true,
     exportOptions: true,
@@ -456,16 +456,16 @@ export const ListViewSchema = BaseSchema
     userFilters: UserFiltersSchema.optional().describe('User filters configuration (accepts legacy tab shapes)'),
     // Spec `userActions` + the three toolbar toggles it does not model yet (#2890).
     userActions: UserActionsSchema.optional().describe('User action toggles for the view toolbar'),
-    sharing: z.object({
-      visibility: z.enum(['private', 'team', 'organization', 'public']).optional(),
-      enabled: z.boolean().optional(),
-      type: z.enum(['personal', 'collaborative']).optional(),
-      lockedBy: z.string().optional(),
-    }).optional().describe('Sharing configuration'),
-    aria: z.object({
-      label: z.string().optional(),
-      describedBy: z.string().optional(),
-      live: z.enum(['polite', 'assertive', 'off']).optional(),
+    // `sharing` is the spec's `ViewSharingSchema`, imported by reference above.
+    // The legacy `{ visibility, enabled }` pair folds into it at the ListView
+    // boundary (#2890) — see `normalizeListViewSchema`.
+    // ARIA — the spec's `AriaPropsSchema` (`ariaLabel` / `ariaDescribedBy` /
+    // `role`) plus `live`, which has no spec counterpart. The legacy
+    // `{ label, describedBy }` spellings fold into the canonical ones at the
+    // ListView boundary (#2890).
+    aria: SpecAriaPropsSchema.extend({
+      live: z.enum(['polite', 'assertive', 'off']).optional()
+        .describe('aria-live politeness for the list region (objectui-only — promote rather than grow this extension)'),
     }).optional().describe('ARIA attributes'),
     conditionalFormatting: z.array(z.union([
       z.object({