fix(plugin-detail): quick_actions 读 aria 契约拼写,并撤下不存在的 actionNames 回退承诺 (#4663) (#5133)

同一组件的两处生产侧缺陷,objectstack#8744 测量该 renderer 读点时发现。

一、aria 读点双向落空。工具条只读 `schema.aria?.label` —— 恰是
`@objectstack/spec` 的 `AriaPropsSchema` 唯一拒绝的拼写:在那个封闭形上
`label` 是 alias 条目(指向 `ariaLabel` 的改名指示),存在意义是给出更好的
拒绝消息,从不被接受(实测:`safeParse({ label })` 返回 unrecognized_keys
并点名 `label`,`safeParse({ ariaLabel })` 通过)。于是 spec-valid 的
`aria: { ariaLabel: … }` 到达 renderer 后无人读取,内建 "Quick actions"
每次都赢;而 renderer 认的拼写,作者一写文档就被契约拒收。
`SchemaRenderer` 的通用 ARIA 通道也不是出口:它读扁平 `schema.ariaLabel`
并以组件 prop 注入 `aria-label`,而本 renderer 的 `splitDesigner` 连同其他
非 designer prop 一并丢弃。

读点改为 `(aria.ariaLabel ?? aria.label) || 'Quick actions'`:legacy 一腿
仅为契约封闭前的存量文档保留,两者同现时 canonical 赢。两半都照本仓既有的
同键惯例 —— `normalizeListViewSchema` 的 aria fold 仅在 canonical 为
`undefined` 时才搬运 legacy 键(故 `ariaLabel: ''` 遮蔽陈旧的 `label`),
而 `ListView` 自身读点把空串视为「没有可访问名」;因 `role="toolbar"` 必须
有名字,此处「没有名字」落到内建兜底,而非 ListView 的省略属性。

二、`actionNames` 注册描述承诺了不存在的回退(「else every action declared
for the object at this location」)。实测:无 `actionNames` 且宿主不传
`actions` 时 `namesToResolve` 为空、`needsLookup` 为 false、对象元数据从不
被查询、渲染虚线占位符。注册 `inputs` 是发布面(序列化进
`sdui.manifest.json` 与 JSX 授权类型,Studio 据此教作者),该承诺已流入工具
链 —— objectstack#8744 的派发提示逐字引用了它。按分诊口径改句子:实现该回退
属能力扩张,另立卡。回归测试驱动一个「有货」的元数据 provider,证明对象上已
声明的 action 确实不会被拉进来(并附控制用例证明同一套接线在有名字时照常
交付)。

Fixes #4663

Co-authored-by: Claude <noreply@anthropic.com>

Author: yinlianghui

.changeset/quick-actions-aria-label-and-actionnames-description-4663.md

@@ -0,0 +1,45 @@
+---
+'@object-ui/plugin-detail': patch
+---
+
+`record:quick_actions` reads the toolbar's accessible name under the spelling the ARIA contract accepts, and stops advertising an action fallback it never had.
+
+Two producer-side defects in the same component (objectui#4663), found while
+objectstack#8744 measured this renderer's read points.
+
+**The `aria` read point was dead in both directions.** The toolbar read
+`schema.aria?.label` and nothing else — the ONE spelling `@objectstack/spec`'s
+`AriaPropsSchema` refuses. On that closed shape `label` is an ALIAS ENTRY: a
+rename prescription pointing at `ariaLabel`, there to produce a better rejection
+message, never accepted (measured: `safeParse({ label })` returns
+`unrecognized_keys` naming `label`, while `safeParse({ ariaLabel })` passes). So
+a spec-valid `aria: { ariaLabel: 'Account actions' }` reached the renderer and
+was read by nothing — the built-in "Quick actions" default won every time — and
+the spelling that did work was one no author can write without the contract
+rejecting the document. `SchemaRenderer`'s generic ARIA channel was no escape
+hatch either: it reads the FLAT `schema.ariaLabel` and injects `aria-label` as a
+component prop, which this renderer drops along with every other non-designer
+prop.
+
+The read is now `(aria.ariaLabel ?? aria.label) || 'Quick actions'`. The legacy
+leg is back-compat only, for documents stored before the contract closed;
+canonical wins when both are present. Both halves follow how the repo already
+handles this key: `normalizeListViewSchema`'s aria fold copies the legacy key
+across only when the canonical one is `undefined` (so a declared `ariaLabel: ''`
+shadows a stale `label`), and `ListView`'s own read point treats an empty string
+as no accessible name at all — which here resolves to the built-in default,
+since `role="toolbar"` needs a name.
+
+**The `actionNames` description promised a fallback that exists on no path.** It
+read "(else every action declared for the object at this location)". Measured:
+with no `actionNames` and no host-supplied `actions`, `namesToResolve` is empty,
+`needsLookup` is false, the object metadata is never queried, and the bar renders
+its dashed placeholder. The registry `inputs` are published — they are serialized
+into `sdui.manifest.json` and the JSX authoring types, and Studio teaches authors
+from them — so the promise reached tooling; objectstack#8744's dispatch prompt
+quoted it verbatim as a declared input. Per the triage ruling the sentence is
+what changes: implementing the fallback would be a behaviour expansion and needs
+its own card. No runtime behaviour changes with it, and a regression test now
+drives a LOADED metadata provider to prove the object's declared actions really
+are not pulled in (with a control proving the same wiring delivers them the
+moment a name asks).

packages/plugin-detail/src/__tests__/recordQuickActionsInputs.actionNamesFallback.test.tsx

@@ -0,0 +1,127 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * `record:quick_actions` — the registered `actionNames` description describes
+ * what the renderer does (objectui#4663).
+ *
+ * The registry `inputs` ARE the published authoring surface: `gen-manifest.ts`
+ * serializes them into `sdui.manifest.json` and the JSX authoring types, and
+ * Studio tooling teaches authors from these sentences. The `actionNames`
+ * description promised a fallback that exists on no path —
+ *
+ *   > 'Action names to expose, in order (else every action declared for the
+ *   >  object at this location)'
+ *
+ * — and it was believed: objectstack#8744's dispatch prompt quoted it verbatim
+ * as a declared input, and this is the clause that failed verification there.
+ *
+ * The measured chain, which the first two cases drive for real rather than
+ * restate: no `actionNames` and no host `actions` → `namesToResolve` is empty →
+ * `needsLookup` is false → the object metadata is NEVER queried → `actions` is
+ * `[]` → the dashed placeholder renders. Per the triage ruling on #4663 the
+ * fallback is a behaviour EXPANSION and is not being implemented here, so the
+ * sentence is what changes; these cases are what stops it drifting back into a
+ * promise.
+ *
+ * The metadata provider below is deliberately LOADED — it declares an action at
+ * this very location — so "the bar stayed empty" cannot be an artefact of a
+ * provider that had nothing to give. The control case proves the same wiring
+ * delivers that action the moment a name asks for it.
+ */
+
+import * as React from 'react';
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { ComponentRegistry } from '@object-ui/core';
+import { MetadataCtx, RecordContextProvider } from '@object-ui/react';
+import type { MetadataContextValue } from '@object-ui/react';
+import { RecordQuickActionsRenderer } from '../renderers/record-quick-actions';
+import '../index';
+
+/** Declared on the object, at the location this bar renders by default. */
+const APPROVE = {
+  name: 'approve',
+  label: 'Approve',
+  type: 'script',
+  locations: ['record_header'],
+};
+
+const OBJECT_META = { name: 'crm_account', actions: [APPROVE] };
+
+const getItem = vi.fn(async (type: string, name: string) =>
+  type === 'object' && name === 'crm_account' ? OBJECT_META : null,
+);
+
+/**
+ * A hand-rolled context value, held at MODULE level on purpose: `getItem` is an
+ * effect dependency of `useMetadataItem`, so a value rebuilt per render spins
+ * that hook forever (the loop `NO_METADATA_PROVIDER` was frozen to fix).
+ */
+const METADATA: MetadataContextValue = {
+  apps: [],
+  objects: [OBJECT_META] as any,
+  dashboards: [],
+  reports: [],
+  pages: [],
+  loading: false,
+  error: null,
+  refresh: async () => {},
+  invalidate: () => {},
+  ensureType: async () => [],
+  getItem: getItem as unknown as MetadataContextValue['getItem'],
+  getItemsByType: () => [],
+  getTypeStatus: () => 'ready' as const,
+};
+
+function mount(schema: Record<string, unknown>) {
+  return render(
+    <MetadataCtx.Provider value={METADATA}>
+      <RecordContextProvider objectName="crm_account" recordId="rec-1" data={{ id: 'rec-1' }}>
+        <RecordQuickActionsRenderer schema={schema as any} />
+      </RecordContextProvider>
+    </MetadataCtx.Provider>,
+  );
+}
+
+const actionNamesInput = () =>
+  (ComponentRegistry.getConfig('record:quick_actions')?.inputs ?? []).find(
+    (i) => i.name === 'actionNames',
+  );
+
+beforeEach(() => getItem.mockClear());
+
+describe('record:quick_actions — `actionNames` description vs measured behaviour (objectui#4663)', () => {
+  it('with no `actionNames` and no host `actions`, the object\'s declared actions are NOT pulled in', async () => {
+    mount({});
+
+    // The bar's empty state, not the object's action.
+    expect(await screen.findByText(/no actions configured/i)).toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: 'Approve' })).not.toBeInTheDocument();
+    // …and the reason: nothing ever asked the metadata layer. This is the exact
+    // step the promised "else every action declared for the object" fallback
+    // would have had to take.
+    expect(getItem).not.toHaveBeenCalled();
+  });
+
+  it('names the actions and the same wiring resolves them (control)', async () => {
+    mount({ actionNames: ['approve'] });
+
+    expect(await screen.findByRole('button', { name: 'Approve' })).toBeInTheDocument();
+    expect(getItem).toHaveBeenCalledWith('object', 'crm_account');
+  });
+
+  it('the published description does not promise the fallback the renderer lacks', () => {
+    const description = actionNamesInput()?.description ?? '';
+    expect(description).not.toBe('');
+    // The removed claim, named exactly as it was published.
+    expect(description).not.toMatch(/every action declared/i);
+    // …replaced by the measured outcome of case 1, so an author reading the
+    // manifest learns what actually happens when the input is left off.
+    expect(description).toMatch(/empty placeholder/i);
+  });
+});

packages/plugin-detail/src/index.tsx

@@ -537,7 +537,17 @@ ComponentRegistry.register('quick_actions', RecordQuickActionsRenderer, {
   label: 'Quick Actions',
   icon: 'Zap',
   inputs: [
-    { name: 'actionNames', type: 'array', label: 'Actions', description: 'Action names to expose, in order (else every action declared for the object at this location)' },
+    // Describes what the renderer does, not what it might do (objectui#4663).
+    // This sentence used to end "(else every action declared for the object at
+    // this location)" — a fallback that exists on no path: with no names and no
+    // host-supplied `actions`, `needsLookup` is false, the object metadata is
+    // never queried, and the bar renders its placeholder. The registry `inputs`
+    // are the published surface (`gen-manifest.ts` serializes them into
+    // `sdui.manifest.json` and the JSX authoring types), so the promise was
+    // taught to authors and to tooling — objectstack#8744 quoted it verbatim.
+    // Implementing the fallback would be a behaviour expansion and needs its own
+    // card; pinned by `recordQuickActionsInputs.actionNamesFallback.test.tsx`.
+    { name: 'actionNames', type: 'array', label: 'Actions', description: 'Action names to expose, in order — resolved from the actions declared on the object. With no names (and no host-supplied actions) nothing is looked up and the bar renders its empty placeholder' },
     { name: 'requiredPermissions', type: 'array', label: 'Required Permissions', description: 'Hide the whole bar unless the user holds these permissions' },
     // Derived from the spec's own vocabulary rather than restated — #3019.
     { name: 'location', type: 'enum', label: 'Location', enum: [...ACTION_LOCATIONS], defaultValue: 'record_header', description: 'Which declared action location this bar renders' },

packages/plugin-detail/src/renderers/__tests__/record-quick-actions.ariaLabel.test.tsx

@@ -0,0 +1,128 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * `record:quick_actions` — the toolbar's accessible name is read under the
+ * spelling the platform ARIA contract actually accepts (objectui#4663).
+ *
+ * The bar used to read `schema.aria?.label` and nothing else. That is the ONE
+ * spelling `@objectstack/spec`'s `AriaPropsSchema` refuses: `label` is an ALIAS
+ * ENTRY on that closed shape, i.e. a rename prescription pointing at
+ * `ariaLabel`, so it exists to produce a better rejection message — never to be
+ * accepted. The two halves compounded into a dead read point:
+ *
+ *   - the spec-valid `aria: { ariaLabel: '…' }` reached the renderer and was
+ *     read by nothing (the built-in "Quick actions" default won every time);
+ *   - the spelling the renderer honoured is the one an author cannot write
+ *     without the contract rejecting the document.
+ *
+ * `SchemaRenderer`'s generic ARIA channel is no escape hatch here: it reads the
+ * FLAT `schema.ariaLabel` off the hoisted node and injects `aria-label` as a
+ * component PROP, and this renderer drops every prop that is not a designer key
+ * (`splitDesigner` keeps `data-obj-id` / `data-obj-type` / `style` and discards
+ * the rest). The nested bag read below is the only live path for an authored
+ * name on this surface.
+ *
+ * The spec half is measured, not asserted from memory — the last case parses
+ * both spellings through the installed `AriaPropsSchema` so "the contract
+ * refuses `label`" stays a fact this file checks rather than a claim it repeats.
+ */
+
+import * as React from 'react';
+import { describe, it, expect } from 'vitest';
+import { render, screen, cleanup } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { RecordContextProvider } from '@object-ui/react';
+import { AriaPropsSchema } from '@objectstack/spec/ui';
+import { RecordQuickActionsRenderer } from '../record-quick-actions';
+
+/**
+ * One visible action, so the toolbar element (and its `aria-label`) renders at
+ * all — with no visible action the bar short-circuits to its dashed placeholder,
+ * which carries no toolbar role.
+ */
+const ACT = { name: 'act', label: 'Act', type: 'script', locations: ['record_header'] };
+
+function mount(aria?: Record<string, unknown>) {
+  return render(
+    <RecordContextProvider objectName="crm_account" recordId="rec-1" data={{ id: 'rec-1' }}>
+      <RecordQuickActionsRenderer schema={{ actions: [ACT], ...(aria ? { aria } : {}) } as any} />
+    </RecordContextProvider>,
+  );
+}
+
+const toolbarName = () => screen.getByRole('toolbar').getAttribute('aria-label');
+
+describe('record:quick_actions — toolbar accessible name (objectui#4663)', () => {
+  it('reads the contract spelling `aria.ariaLabel`', () => {
+    mount({ ariaLabel: 'Account actions' });
+    expect(toolbarName()).toBe('Account actions');
+  });
+
+  it('still honours the legacy `aria.label` stored documents carry', () => {
+    // Back-compat only. `AriaPropsSchema` refuses this spelling (last case), so
+    // nothing newly authored can reach here — it exists for documents written
+    // before the contract closed, mirroring the fold `normalizeListViewSchema`
+    // applies at the ListView boundary (`ARIA_KEY_ALIASES`, objectui#2890).
+    mount({ label: 'Legacy name' });
+    expect(toolbarName()).toBe('Legacy name');
+  });
+
+  it('prefers the canonical spelling when a document carries both', () => {
+    mount({ ariaLabel: 'Canonical', label: 'Legacy' });
+    expect(toolbarName()).toBe('Canonical');
+  });
+
+  it('falls back to the built-in name when neither spelling is authored', () => {
+    mount();
+    expect(toolbarName()).toBe('Quick actions');
+  });
+
+  /**
+   * Empty-string semantics, pinned because this is exactly where `??` and `||`
+   * part company and the choice is deliberate (objectui#4663).
+   *
+   * Both halves follow the repo's existing handling of THIS key:
+   *
+   *   - canonical-vs-legacy uses `??`, matching `normalizeListViewSchema`'s aria
+   *     fold, which copies the legacy key across only when the canonical one is
+   *     `undefined` — a declared `ariaLabel: ''` shadows the legacy key there,
+   *     and does here;
+   *   - the built-in default is truthiness-gated, matching `ListView`'s own read
+   *     point (`schema.aria?.ariaLabel ? {'aria-label': …} : {}`), which treats
+   *     an empty string as no accessible name at all. `role="toolbar"` needs a
+   *     name, so the equivalent here is the built-in default rather than
+   *     ListView's "omit the attribute".
+   */
+  it('treats an authored empty string as no name — the built-in default wins', () => {
+    mount({ ariaLabel: '' });
+    expect(toolbarName()).toBe('Quick actions');
+    cleanup();
+
+    // …and the empty canonical value still shadows the legacy key, rather than
+    // letting a stale legacy name resurface under a document that has been
+    // migrated to the contract spelling.
+    mount({ ariaLabel: '', label: 'Legacy' });
+    expect(toolbarName()).toBe('Quick actions');
+  });
+
+  it('the platform contract really accepts `ariaLabel` and refuses `label`', () => {
+    // The premise the read order above rests on, measured against the installed
+    // spec instead of restated. If a future spec ever accepts `label`, this
+    // fails and the legacy leg's justification (back-compat only, never an
+    // authoring surface) has to be revisited.
+    expect(AriaPropsSchema.safeParse({ ariaLabel: 'Account actions' }).success).toBe(true);
+
+    const legacy = AriaPropsSchema.safeParse({ label: 'Account actions' });
+    expect(legacy.success).toBe(false);
+    // Asserted as an envelope — the code AND the key it names — so a rejection
+    // of something else could not satisfy it.
+    expect(legacy.error?.issues.map((i) => i.code)).toContain('unrecognized_keys');
+    expect(
+      legacy.error?.issues.flatMap((i) => (i as unknown as { keys?: string[] }).keys ?? []),
+    ).toContain('label');
+  });
+});

packages/plugin-detail/src/renderers/record-quick-actions.tsx

@@ -35,7 +35,13 @@ export interface RecordQuickActionsRendererProps {
     align?: 'start' | 'center' | 'end';
     size?: 'sm' | 'default' | 'lg';
     variant?: 'default' | 'secondary' | 'outline' | 'ghost' | 'destructive' | 'link';
-    aria?: { label?: string };
+    /**
+     * Accessible name for the toolbar. `ariaLabel` is the spelling
+     * `@objectstack/spec`'s `AriaPropsSchema` accepts; `label` is that shape's
+     * alias entry — refused on parse — and is kept here as a back-compat read
+     * for documents written before the contract closed (objectui#4663).
+     */
+    aria?: { ariaLabel?: string; label?: string };
     properties?: Record<string, any>;
     [k: string]: any;
   };
@@ -164,6 +170,36 @@ export const RecordQuickActionsRenderer: React.FC<RecordQuickActionsRendererProp
   // (the `inline` flag is set by PageHeader's first-class `actions` prop).
   const inlineWithHeader = location === 'record_header' && !schema.inline;
 
+  /**
+   * The toolbar's accessible name, read under the spelling the platform ARIA
+   * contract actually accepts (objectui#4663).
+   *
+   * This line used to read `aria.label` and nothing else — the ONE spelling
+   * `@objectstack/spec`'s `AriaPropsSchema` refuses. `label` is that closed
+   * shape's ALIAS ENTRY, a rename prescription pointing at `ariaLabel`, so it
+   * exists to produce a better rejection message and is never accepted. The
+   * result was a dead read point in both directions: a spec-valid
+   * `aria: { ariaLabel: … }` was discarded, and the spelling honoured was one no
+   * author can write without the contract rejecting the document.
+   *
+   * `SchemaRenderer`'s generic ARIA channel does not cover this: it reads the
+   * FLAT `schema.ariaLabel` and injects `aria-label` as a component PROP, which
+   * `splitDesigner` above drops with every other non-designer prop. The nested
+   * bag is the live path here.
+   *
+   * `??` between the two spellings, `||` for the built-in default — both halves
+   * follow how this repo already handles this key:
+   *
+   *   - `normalizeListViewSchema`'s aria fold (`ARIA_KEY_ALIASES`, objectui#2890)
+   *     copies the legacy key onto the canonical one only when the canonical is
+   *     `undefined`, so a declared `ariaLabel: ''` shadows a stale `label` there
+   *     — and does here;
+   *   - `ListView`'s own read point treats an empty string as no accessible name
+   *     at all. `role="toolbar"` needs a name, so "no name" resolves to the
+   *     built-in default here rather than to ListView's omitted attribute.
+   */
+  const ariaLabel = (schema.aria?.ariaLabel ?? schema.aria?.label) || 'Quick actions';
+
   return (
     <div
       className={cn(
@@ -173,7 +209,7 @@ export const RecordQuickActionsRenderer: React.FC<RecordQuickActionsRendererProp
         className,
       )}
       role="toolbar"
-      aria-label={schema.aria?.label || 'Quick actions'}
+      aria-label={ariaLabel}
       {...designer}
     >
       {visibleActions.map((action, idx) => (