fix(actions): one placement rule for locations — declare it or it renders nowhere (#3145)

Four renderers each answered "where does an action with no `locations` go?"
differently: action:bar and metadata-admin showed it EVERYWHERE, page:header
showed it on the header, action:group showed it for `undefined` but hid it for
`[]`. ActionEngine, RecordDetailView, DeclaredActionsBar, the related-list
bridge and the environment toolbar all showed it NOWHERE. The same action
appeared or vanished depending on which component drew it — which is how an
aggregate-only bulk action (#3139) minted a list-toolbar button whose dispatch
could only fail.

All of them now share one exported predicate, actionRendersAt(action,
location) in @object-ui/types: an action renders at a location only if it
declares that location. ADR-0078 already listed "an action with no locations"
as a verified inert shape, and buildDefaultPageSchema already documented "must
include locations: ['record_header'] to render".

One named carve-out, now consistent across both bars: host-injected chrome
(systemActions / headerSystemActions) is placed by the host, not authored, so
it is never location-filtered. Selection placement stays declared by a view's
bulkActions / bulkActionDefs.

Authoring side so the stricter rule cannot mint invisible actions: Studio
seeds locations on a new action, the inspector flags an empty placement, and
the false `defaults to ['record_header']` JSDoc is gone.

Closes #3142

Author: os-zhuang

.changeset/action-locations-one-rule.md

@@ -0,0 +1,42 @@
+---
+"@object-ui/types": minor
+"@object-ui/components": minor
+"@object-ui/app-shell": minor
+---
+
+One placement rule for action `locations` (objectui#3142).
+
+**Breaking for metadata**: an action that declares no `locations` (missing key
+or `[]`) no longer renders in a located surface. FROM: omitting `locations`
+made an action appear on the list toolbar, the record header, and every
+metadata-admin toolbar. TO: declare where it belongs —
+`locations: ['record_header']` for the record header, `['list_toolbar']` for
+the list toolbar, and so on. Nothing else changes; actions that already
+declare a location are untouched.
+
+Four renderers each answered "where does an action with no `locations` go?"
+differently — `action:bar` and metadata-admin showed it EVERYWHERE,
+`page:header` showed it on the header, `action:group` showed it for
+`undefined` but hid it for `[]` — while `ActionEngine`, `RecordDetailView`,
+`DeclaredActionsBar`, the related-list bridge and the environment toolbar all
+showed it NOWHERE. The same action therefore appeared or vanished depending on
+which component happened to draw it. All eight now go through one exported
+predicate, `actionRendersAt(action, location)` from `@object-ui/types`: an
+action renders at a location only if it declares that location.
+
+The strict reading is the platform's own — ADR-0078 lists "an `action` with no
+`locations`" as a verified inert shape, and the detail-page synthesizer already
+documented "must include `locations: ['record_header']` to render". The
+leniency contradicted both, and it is what let an aggregate-only bulk action
+(objectui#3139) — one with no single-record placement by construction — mint a
+list-toolbar button whose dispatch could only fail.
+
+Two placements are declared elsewhere and need no `locations`, both unchanged:
+host-injected chrome in the `systemActions` / `headerSystemActions` slot (now
+consistently exempt on `page:header` too, where it used to be filtered), and an
+action named in a view's `bulkActions` / `bulkActionDefs`.
+
+Authoring side: Studio seeds `locations: ['record_header']` on a new action
+instead of minting one that renders nowhere, and the action inspector says so
+when no placement is ticked. The `ActionSchema.locations` JSDoc claimed a
+`['record_header']` default that no renderer ever implemented — corrected.

content/docs/guide/slotted-pages.md

@@ -103,6 +103,35 @@ Delete) as a button row. Up to **`maxVisible`** actions render inline,
 side by side (default **3** on desktop, **`mobileMaxVisible`**, default
 **1**, on mobile); the rest collapse into a `⋯` "More actions" menu.
 
+### Declaring placement
+
+An authored action renders here only if its **`locations`** declares
+`record_header` (inline) or `record_more` (straight into the `⋯` menu).
+There is no default: an action that declares no location renders in **no**
+located surface — not here, not the list toolbar, not the row menu. That
+one rule is shared by every surface that places actions by location
+(`action:bar`, `action:group`, `record:quick_actions`, related lists, the
+metadata-admin toolbars and the action engine), so an action behaves the
+same wherever it is drawn.
+
+```ts
+actions: [
+  { name: 'convert_lead', label: 'Convert', locations: ['record_header'] },
+  { name: 'export_pdf',   label: 'Export',  locations: ['record_more'] },
+]
+```
+
+Two placements come from somewhere other than `locations`, and neither
+needs an entry here:
+
+- **Host chrome** — the Edit / Share / Delete set the host injects is
+  placed by the host, not authored, so it is never location-filtered.
+- **Selection actions** — an action named in a list view's `bulkActions`
+  or `bulkActionDefs` is placed by that declaration. An action that only
+  makes sense over a selection (an aggregate export, say) can therefore
+  declare no `locations` at all and still be reachable from the
+  selection bar.
+
 Which actions claim the inline slots is declared in metadata, using the
 same rules as `action:bar`:
 

packages/app-shell/src/views/metadata-admin/MetadataTypeActions.test.tsx

@@ -43,6 +43,42 @@ beforeEach(() => {
 });
 
 describe('MetadataTypeActions', () => {
+  // [#3142] These actions come off the server's `/meta/types` feed, and this
+  // component used to carry a byte-identical copy of `action:bar`'s lenient
+  // rule — so a type shipping an action with no `locations` got a button on
+  // BOTH the list toolbar and the record header. Placement is declared now,
+  // like everywhere else. Nothing pinned the lenient branch before, which is
+  // how the two copies drifted from the rest of the repo unnoticed.
+  it('renders only actions that declare the requested location', () => {
+    const { container } = render(
+      <MetadataTypeActions
+        location="record_header"
+        recordId="ds1"
+        entry={{
+          actions: [
+            { name: 'here', label: 'Here', type: 'api', target: '/x', locations: ['record_header'] },
+            { name: 'elsewhere', label: 'Elsewhere', type: 'api', target: '/x', locations: ['list_toolbar'] },
+            { name: 'undeclared', label: 'Undeclared', type: 'api', target: '/x' },
+          ],
+        }}
+      />,
+    );
+    expect(screen.getByTitle('Here')).toBeTruthy();
+    expect(screen.queryByTitle('Elsewhere')).toBeNull();
+    expect(screen.queryByTitle('Undeclared')).toBeNull();
+    expect(container.textContent).not.toContain('Undeclared');
+  });
+
+  it('renders nothing when no action declares the requested location', () => {
+    const { container } = render(
+      <MetadataTypeActions
+        location="list_toolbar"
+        entry={{ actions: [{ name: 'undeclared', label: 'Undeclared', type: 'api', target: '/x' }] }}
+      />,
+    );
+    expect(container.firstChild).toBeNull();
+  });
+
   it('runs an api action without params directly (no dialog)', async () => {
     render(
       <MetadataTypeActions

packages/app-shell/src/views/metadata-admin/MetadataTypeActions.tsx

@@ -37,6 +37,7 @@ import { Loader2 } from 'lucide-react';
 import { Button } from '@object-ui/components';
 import { createAuthenticatedFetch } from '@object-ui/auth';
 import type { ActionParamDef } from '@object-ui/core';
+import { actionRendersAt, type ActionLocation } from '@object-ui/types';
 import { getIcon } from '../../utils/getIcon';
 import { ActionParamDialog, type ParamDialogState } from '../ActionParamDialog';
 import { ActionResultDialog, type ResultDialogState } from '../ActionResultDialog';
@@ -74,8 +75,12 @@ function interpolateTarget(
 export interface MetadataTypeActionsProps {
   /** The rich type entry whose `actions` to render. */
   entry?: Pick<RichMetadataTypeEntry, 'actions'> | undefined;
-  /** Which chrome slot is asking — actions are filtered by their `locations`. */
-  location: string;
+  /**
+   * Which chrome slot is asking — actions are filtered by their `locations`.
+   * Typed as the spec vocabulary rather than `string` so a typo cannot quietly
+   * match nothing: both call sites pass a literal, so this costs them nothing.
+   */
+  location: ActionLocation;
   /** Current item name, exposed to actions as `${ctx.recordId}`. */
   recordId?: string;
   /** Called after a successful action when `refreshAfter` is set. */
@@ -93,11 +98,12 @@ export function MetadataTypeActions({ entry, location, recordId, onAfter }: Meta
   const [resultState, setResultState] = React.useState<ResultDialogState>({ open: false });
   const authFetch = React.useMemo(() => createAuthenticatedFetch(), []);
 
+  // Placement is `actionRendersAt`'s call (objectui#3142). These actions come
+  // from the server's `/meta/types` feed, so a type shipping an action with no
+  // `locations` used to get a button on BOTH the list toolbar and the record
+  // header; now it must declare where it belongs, like every other surface.
   const actions = React.useMemo(
-    () =>
-      (entry?.actions ?? []).filter(
-        (a) => !a.locations || a.locations.length === 0 || a.locations.includes(location),
-      ),
+    () => (entry?.actions ?? []).filter((a) => actionRendersAt(a, location)),
     [entry?.actions, location],
   );
 

packages/app-shell/src/views/metadata-admin/inspectors/ActionDefaultInspector.tsx

@@ -406,6 +406,17 @@ export function ActionDefaultInspector({
             <InspectorCheckboxField key={loc.value} label={loc.label} value={locations.includes(loc.value)} onCommit={(v) => toggleLocation(loc.value, v)} disabled={readOnly} />
           ))}
         </div>
+        {/* [#3142] No placement = renders in no located surface. Saying so
+            here is the difference between an author seeing an empty list and
+            an author hunting for a button that was never going to appear.
+            Not an error: a selection-only action is placed by a view's
+            `bulkActions` / `bulkActionDefs` instead, which is legitimate. */}
+        {locations.length === 0 && (
+          <div className="text-[11px] text-destructive">
+            No placement selected — this action will not appear on any record or list surface. Tick a
+            placement above, or place it from a view’s bulk actions.
+          </div>
+        )}
         <div className="grid grid-cols-2 gap-2 pt-1">
           <InspectorSelectField label="Component" value={str('component') || undefined} options={COMPONENT_OPTS} onCommit={(v) => onPatch({ component: v })} disabled={readOnly} />
         </div>

packages/app-shell/src/views/studio-design/ObjectActionsPanel.tsx

@@ -115,11 +115,19 @@ export function ObjectActionsPanel({
     // the user types into the body (same dead-end class as a fresh validation
     // rule needing a placeholder condition). The user configures the rest
     // (behavior/placement/…) in the form on the right.
+    //
+    // `locations` is seeded for the same reason (objectui#3142): an action
+    // that declares no location renders in no located surface, so an unseeded
+    // skeleton would save clean and then be invisible everywhere — the author
+    // would have no button to click and nothing to tell them why. Placement
+    // stays fully editable in the Placement checkboxes; `record_header` is
+    // just the starting point.
     const fresh: ActionItem = {
       name,
       label: t('engine.studio.actions.newLabel', locale),
       type: 'script',
       objectName,
+      locations: ['record_header'],
       body: { language: 'js', source: 'return { ok: true };' },
     };
     onPatch({ actions: [...actions, fresh] });

packages/components/src/__tests__/action-bar.test.tsx

@@ -70,18 +70,30 @@ describe('ActionBar (action:bar)', () => {
       expect(container.textContent).toContain('Both Action');
     });
 
-    it('shows actions without locations when filtering by location', () => {
+    // [#3142] Deliberately INVERTED from "shows actions without locations".
+    // An undeclared placement is not a wildcard: this bar used to show such an
+    // action at every location, while ActionEngine, RecordDetailView,
+    // DeclaredActionsBar and the related-list bridge all showed it at none —
+    // so the same action appeared or vanished with the renderer. `locations`
+    // is the declaration; no declaration, no located placement (ADR-0078 reads
+    // an action with no `locations` as inert for exactly this reason).
+    it('hides an action that declares no locations when filtering by location', () => {
       const { container } = renderComponent({
         type: 'action:bar',
         location: 'record_header',
         actions: [
           { name: 'no_loc', label: 'No Location', type: 'script' },
-          { name: 'has_loc', label: 'Has Location', type: 'script', locations: ['list_toolbar'] },
+          { name: 'empty_loc', label: 'Empty Location', type: 'script', locations: [] },
+          { name: 'other_loc', label: 'Other Location', type: 'script', locations: ['list_toolbar'] },
+          { name: 'here_loc', label: 'Here Location', type: 'script', locations: ['record_header'] },
         ],
       });
-      // Action without locations should show in any location
-      expect(container.textContent).toContain('No Location');
-      expect(container.textContent).not.toContain('Has Location');
+      expect(container.textContent).not.toContain('No Location');
+      // An empty array reads the same as an absent one — the third dialect
+      // (`action:group` hid `[]` but showed `undefined`) is gone too.
+      expect(container.textContent).not.toContain('Empty Location');
+      expect(container.textContent).not.toContain('Other Location');
+      expect(container.textContent).toContain('Here Location');
     });
 
     it('renders all actions when no location filter is set', () => {
@@ -400,8 +412,12 @@ describe('ActionBar (action:bar)', () => {
     const withUser = (user: unknown, props: { actions?: any[]; systemActions?: any[] }) =>
       render(<ActionProvider context={{ user } as any}><Bar {...props} /></ActionProvider>);
 
-    const gated = { name: 'gated', label: 'Bulk Reassign', type: 'api', requiredPermissions: ['manage_users'] };
-    const plain = { name: 'plain', label: 'Export', type: 'api' };
+    // Both fixtures declare the harness's location (#3142): without it the
+    // strict placement filter would drop them before the capability gate ever
+    // ran, and every `not.toContain` below would pass VACUOUSLY — the suite
+    // would keep reporting green while testing nothing.
+    const gated = { name: 'gated', label: 'Bulk Reassign', type: 'api', locations: ['list_toolbar'], requiredPermissions: ['manage_users'] };
+    const plain = { name: 'plain', label: 'Export', type: 'api', locations: ['list_toolbar'] };
 
     it('hides an action whose capability the caller lacks', () => {
       const { container } = withUser({ id: 'u1', systemPermissions: ['setup.access'] }, { actions: [gated, plain] });

packages/components/src/__tests__/action-group.test.tsx

@@ -0,0 +1,69 @@
+/**
+ * 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.
+ */
+
+/**
+ * `action:group` placement (objectui#3142).
+ *
+ * This renderer carried a THIRD reading of `locations`: `!a.locations ||
+ * a.locations.includes(loc)` — an action with `locations: undefined` showed,
+ * while one with `locations: []` was hidden, for no stated reason. Both now
+ * mean the same thing (no declared placement → not rendered here) because both
+ * go through `actionRendersAt`. Nothing pinned this file's behaviour before,
+ * which is how the third dialect survived.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { renderComponent } from './test-utils';
+
+// Action renderers are loaded by the shared vitest setup (see action-bar.test).
+const renderGroup = (schema: Record<string, unknown>) => renderComponent(schema as never);
+
+describe('action:group — placement', () => {
+  it('renders only actions that declare the requested location', () => {
+    renderGroup({
+      type: 'action:group',
+      location: 'list_toolbar',
+      actions: [
+        { name: 'here', label: 'Here', type: 'script', locations: ['list_toolbar'] },
+        { name: 'elsewhere', label: 'Elsewhere', type: 'script', locations: ['record_header'] },
+      ],
+    });
+    expect(screen.getByText('Here')).toBeInTheDocument();
+    expect(screen.queryByText('Elsewhere')).not.toBeInTheDocument();
+  });
+
+  it('treats an undeclared placement the same as an empty one — both hide', () => {
+    renderGroup({
+      type: 'action:group',
+      location: 'list_toolbar',
+      actions: [
+        { name: 'undeclared', label: 'Undeclared', type: 'script' },
+        { name: 'empty', label: 'Empty', type: 'script', locations: [] },
+        { name: 'here', label: 'Here', type: 'script', locations: ['list_toolbar'] },
+      ],
+    });
+    // Pre-#3142 `Undeclared` rendered and `Empty` did not — same key, two answers.
+    expect(screen.queryByText('Undeclared')).not.toBeInTheDocument();
+    expect(screen.queryByText('Empty')).not.toBeInTheDocument();
+    expect(screen.getByText('Here')).toBeInTheDocument();
+  });
+
+  it('renders every action when the group sets no location filter', () => {
+    renderGroup({
+      type: 'action:group',
+      actions: [
+        { name: 'a', label: 'Alpha', type: 'script' },
+        { name: 'b', label: 'Beta', type: 'script', locations: ['record_header'] },
+      ],
+    });
+    expect(screen.getByText('Alpha')).toBeInTheDocument();
+    expect(screen.getByText('Beta')).toBeInTheDocument();
+  });
+});