feat(access): Studio Explain panel — package-scoped object dropdown instead of free-text api-name (#2600 B2) (#2650)

The "why can this user access?" panel asked for the object as free text, with
a placeholder (`crm_lead`) that isn't even in the package — so it invited typos
and named a non-existent object. The Access pillar already knows its package,
which has only ~20 objects.

- AccessExplainPanel takes an optional `packageId`; when set it loads that
  package's objects (same `list('object', {packageId})` the matrix uses) and
  renders the object field as a `<select>` of `label (api-name)`.
- Free-text input stays as a graceful fallback when unscoped or the list fails.
- Placeholder no longer names a non-existent object.
- StudioDesignSurface passes `packageId` to the panel.

The Explain button was already correctly disabled (opacity-50) until an object
is chosen; the dropdown makes choosing one a clear affordance.

Adds dropdown + fallback coverage to AccessExplainPanel.test.tsx.

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

Author: os-zhuang

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

@@ -12,16 +12,22 @@
 
 import '@testing-library/jest-dom/vitest';
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { cleanup, fireEvent, render, screen, waitFor, within } from '@testing-library/react';
 
 const fetchSpy = vi.fn();
+// objectui#2600 B2 — package object list backing the object dropdown; a
+// `mock`-prefixed name so vitest allows the hoisted factory to close over it.
+let mockObjectList: Array<Record<string, unknown>> = [];
 
 vi.mock('@object-ui/auth', () => ({
   createAuthenticatedFetch: () => fetchSpy,
 }));
 vi.mock('@object-ui/react', () => ({
   useAdapter: () => ({ find: vi.fn(async () => []) }),
 }));
+vi.mock('./useMetadata', () => ({
+  useMetadataClient: () => ({ list: async () => mockObjectList }),
+}));
 // The user picker has its own coverage; a stub keeps this suite focused on
 // the explain round-trip.
 vi.mock('@object-ui/fields', () => ({
@@ -33,6 +39,7 @@ import { AccessExplainPanel, type ExplainDecision } from './AccessExplainPanel';
 afterEach(() => {
   cleanup();
   fetchSpy.mockReset();
+  mockObjectList = [];
 });
 
 const DECISION: ExplainDecision = {
@@ -181,4 +188,36 @@ describe('AccessExplainPanel (ADR-0090 D6)', () => {
     expect(screen.getByRole('alert').textContent).toMatch(/manage_users|delegated admin scope/i);
     expect(screen.queryByTestId('explain-verdict')).not.toBeInTheDocument();
   });
+
+  // objectui#2600 B2 — with a package scope, the object field becomes a
+  // dropdown of the package's objects instead of a free-text api-name input.
+  it('renders a package-scoped object dropdown when packageId is set', async () => {
+    mockObjectList = [
+      { item: { name: 'showcase_account', label: 'Account' } },
+      { item: { name: 'showcase_task' } },
+    ];
+    render(<AccessExplainPanel open onOpenChange={() => {}} packageId="com.example.showcase" />);
+
+    // The object field swaps from a free-text input to a <select> once loaded.
+    await waitFor(() => expect(screen.getByLabelText('Object').tagName).toBe('SELECT'));
+    const objectField = screen.getByLabelText('Object');
+    expect(within(objectField).getByRole('option', { name: 'Account (showcase_account)' })).toBeInTheDocument();
+    expect(within(objectField).getByRole('option', { name: 'showcase_task' })).toBeInTheDocument();
+    // The misleading free-text placeholder example is gone.
+    expect(screen.queryByPlaceholderText(/crm_lead/)).toBeNull();
+
+    // Selecting an object and explaining posts that object.
+    fetchSpy.mockResolvedValue(jsonResponse(200, DECISION));
+    fireEvent.change(objectField, { target: { value: 'showcase_account' } });
+    fireEvent.click(screen.getByRole('button', { name: /explain$/i }));
+    await waitFor(() => expect(fetchSpy).toHaveBeenCalled());
+    const body = JSON.parse(String((fetchSpy.mock.calls[0]?.[1] as any)?.body ?? '{}'));
+    expect(body.object).toBe('showcase_account');
+  });
+
+  // Unscoped (no packageId) keeps the free-text input as a fallback.
+  it('falls back to a free-text object input without a package scope', async () => {
+    renderPanel();
+    expect(screen.getByLabelText('Object').tagName).toBe('INPUT');
+  });
 });

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

@@ -51,6 +51,7 @@ import {
   XCircle,
 } from 'lucide-react';
 import { t, tFormat, useMetadataLocale } from './i18n';
+import { useMetadataClient } from './useMetadata';
 
 /** Mirrors `ExplainOperationSchema` in `@objectstack/spec/security`. */
 const OPERATIONS = ['read', 'create', 'update', 'delete', 'transfer', 'restore', 'purge'] as const;
@@ -159,13 +160,50 @@ export interface AccessExplainPanelProps {
   onOpenChange: (open: boolean) => void;
   /** Optional prefill for the object input (e.g. from the matrix). */
   defaultObject?: string;
+  /**
+   * objectui#2600 B2 — the package this panel is scoped to. When set, the
+   * object field becomes a dropdown of the package's objects (only ~20 exist)
+   * instead of a free-text api-name input whose example never resolves.
+   */
+  packageId?: string;
 }
 
-export function AccessExplainPanel({ open, onOpenChange, defaultObject }: AccessExplainPanelProps): React.ReactElement {
+export function AccessExplainPanel({ open, onOpenChange, defaultObject, packageId }: AccessExplainPanelProps): React.ReactElement {
   const locale = useMetadataLocale();
   const adapter = useAdapter() as any;
+  const client = useMetadataClient();
   const authFetch = React.useMemo(() => createAuthenticatedFetch(), []);
 
+  // objectui#2600 B2 — package object list backing the object dropdown. `null`
+  // until loaded (or when unscoped / load fails), which keeps the free-text
+  // input as a graceful fallback.
+  const [objectOptions, setObjectOptions] = React.useState<Array<{ name: string; label?: string }> | null>(null);
+  React.useEffect(() => {
+    if (!open || !packageId) {
+      setObjectOptions(null);
+      return;
+    }
+    let cancelled = false;
+    void (async () => {
+      try {
+        const rows = (await client.list<any>('object', { packageId })) as any[];
+        const opts = (rows ?? [])
+          .map((row) => {
+            const item = row?.item ?? row;
+            return { name: String(item?.name ?? ''), label: item?.label as string | undefined };
+          })
+          .filter((o) => !!o.name)
+          .sort((a, b) => a.name.localeCompare(b.name));
+        if (!cancelled) setObjectOptions(opts);
+      } catch {
+        if (!cancelled) setObjectOptions(null);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [open, packageId, client]);
+
   const [objectName, setObjectName] = React.useState(defaultObject ?? '');
   const [operation, setOperation] = React.useState<ExplainOperation>('read');
   const [user, setUser] = React.useState<{ id: string; label: string } | null>(null);
@@ -281,13 +319,32 @@ export function AccessExplainPanel({ open, onOpenChange, defaultObject }: Access
               <label htmlFor="explain-object" className="text-xs font-medium text-muted-foreground">
                 {t('engine.studio.access.explain.object', locale)}
               </label>
-              <Input
-                id="explain-object"
-                value={objectName}
-                onChange={(e) => setObjectName(e.target.value)}
-                placeholder={t('engine.studio.access.explain.objectPlaceholder', locale)}
-                className="h-8 text-xs"
-              />
+              {objectOptions && objectOptions.length > 0 ? (
+                // objectui#2600 B2 — package-scoped dropdown: the object must be
+                // one of this package's ~20 objects, so free-text (with an
+                // example that isn't even in the package) only invites typos.
+                <select
+                  id="explain-object"
+                  value={objectName}
+                  onChange={(e) => setObjectName(e.target.value)}
+                  className="h-8 w-full rounded-md border bg-background px-2 text-xs outline-none focus:ring-1 focus:ring-primary"
+                >
+                  <option value="">{t('engine.studio.access.explain.objectSelect', locale)}</option>
+                  {objectOptions.map((o) => (
+                    <option key={o.name} value={o.name}>
+                      {o.label && o.label !== o.name ? `${o.label} (${o.name})` : o.name}
+                    </option>
+                  ))}
+                </select>
+              ) : (
+                <Input
+                  id="explain-object"
+                  value={objectName}
+                  onChange={(e) => setObjectName(e.target.value)}
+                  placeholder={t('engine.studio.access.explain.objectPlaceholder', locale)}
+                  className="h-8 text-xs"
+                />
+              )}
             </div>
             <div className="w-32 shrink-0 space-y-1">
               <label htmlFor="explain-operation" className="text-xs font-medium text-muted-foreground">

packages/app-shell/src/views/metadata-admin/i18n.ts

@@ -1423,7 +1423,8 @@ const ENGINE_STRINGS_EN: Record<string, string> = {
   'engine.studio.access.explain.clearUser': 'Reset to me',
   'engine.studio.access.explain.pickUserTitle': 'Select the user to explain',
   'engine.studio.access.explain.object': 'Object',
-  'engine.studio.access.explain.objectPlaceholder': 'Object name (e.g. crm_lead)',
+  'engine.studio.access.explain.objectPlaceholder': 'Object api-name',
+  'engine.studio.access.explain.objectSelect': 'Select an object…',
   'engine.studio.access.explain.operation': 'Operation',
   'engine.studio.access.explain.run': 'Explain',
   'engine.studio.access.explain.running': 'Explaining…',
@@ -2777,7 +2778,8 @@ const ENGINE_STRINGS_ZH: Record<string, string> = {
   'engine.studio.access.explain.clearUser': '重置为我',
   'engine.studio.access.explain.pickUserTitle': '选择要解释的用户',
   'engine.studio.access.explain.object': '对象',
-  'engine.studio.access.explain.objectPlaceholder': '对象名(如:crm_lead)',
+  'engine.studio.access.explain.objectPlaceholder': '对象 API 名称',
+  'engine.studio.access.explain.objectSelect': '选择对象…',
   'engine.studio.access.explain.operation': '操作',
   'engine.studio.access.explain.run': '解释',
   'engine.studio.access.explain.running': '解释中…',

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

@@ -3583,7 +3583,7 @@ export function AccessPillar({
         </main>
       </div>
 
-      <AccessExplainPanel open={explainOpen} onOpenChange={setExplainOpen} />
+      <AccessExplainPanel open={explainOpen} onOpenChange={setExplainOpen} packageId={packageId} />
 
       <CreateItemDialog
         open={creating}