feat(access): Studio permission matrix — collapse identity + zero-grant capabilities so the matrix hits the first screen (#2600 B1) (#2649)

The Access pillar is called "Permission Matrix", but the editor opened with
a name/label form plus the capability picker's option chips, pushing the
matrix below the fold. Two low-frequency, high-chrome sections now start
collapsed:

- Identity (name/label) collapses to a one-line summary (label · provenance ·
  default/read-only badges) and expands on click. The api-name already lives
  in the PageShell breadcrumb, so the summary carries the human label only.
- System capabilities: a zero-grant WRITABLE set rendered every option as an
  outline chip, which read as already-owned. It now shows an explicit
  "none granted · add" affordance; granted sets and read-only sets keep the
  inline picker as before.

Read-only packages, the dirty/guard contracts (#2588/#2606), the history
sheet and breadcrumb (#2599) are all unaffected. Adds
PermissionMatrixEditor.basics.test.tsx and updates the settle points of the
existing matrix/guard suites (identity is now summary text, not an input).

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/PermissionMatrixEditor.badge.test.tsx

@@ -47,8 +47,9 @@ async function renderWith(extra: Record<string, unknown>) {
       <PermissionMatrixEditPage type="permission" name="sales_perms" />
     </MemoryRouter>,
   );
-  // Wait for the load to settle (the label input renders after the fetch).
-  await screen.findByDisplayValue('Sales');
+  // Wait for the load to settle. The identity strip is collapsed by default
+  // (objectui#2600 B1), so the label shows as summary text, not an input.
+  await screen.findByText('Sales');
 }
 
 describe('PermissionMatrixEditPage — provenance tri-state badge (A4 framework#2920)', () => {

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

@@ -0,0 +1,99 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * objectui#2600 B1 — "first screen sees the matrix". The pillar is called the
+ * Permission Matrix, so the low-frequency identity form (name / label) and the
+ * capability picker must NOT push the matrix below the fold:
+ *   - the identity strip collapses to a one-line summary and expands on click;
+ *   - a zero-grant writable set shows an explicit "none granted · add"
+ *     affordance instead of the picker's option chips (which read as owned).
+ */
+
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render, screen, cleanup, fireEvent } from '@testing-library/react';
+import { MemoryRouter } from 'react-router-dom';
+
+function makeClient(set: Record<string, unknown>) {
+  return {
+    layered: async () => ({ effective: set, code: null, overlay: null, overlayScope: null }),
+    getDraft: async () => null,
+    list: async (type: string) => (type === 'object' ? [{ item: { name: 'a_account' } }] : []),
+    get: async (type: string) => (type === 'object' ? { fields: [] } : null),
+    save: async (_t: string, _n: string, payload: Record<string, unknown>) => payload,
+  } as any;
+}
+
+let clientImpl: any;
+
+vi.mock('./useMetadata', () => ({
+  useMetadataClient: () => clientImpl,
+  useMetadataTypes: () => ({
+    loading: false,
+    error: null,
+    entries: [{ type: 'permission', label: 'Permission', allowOrgOverride: true }],
+  }),
+}));
+vi.mock('./AssignedUsersSection', () => ({ AssignedUsersSection: () => null }));
+// Stub the capability picker so the B1 collapse logic is isolated from the
+// live sys_capability registry read.
+vi.mock('@object-ui/fields', () => ({
+  CapabilityMultiSelectField: () => <div data-testid="cap-picker" />,
+  parseCapabilityNames: (v: unknown) => (typeof v === 'string' ? JSON.parse(v) : []),
+}));
+
+import { PermissionMatrixEditPage } from './PermissionMatrixEditor';
+
+afterEach(cleanup);
+
+async function renderSet(extra: Record<string, unknown> = {}) {
+  clientImpl = makeClient({
+    name: 'sales_perms',
+    label: 'Sales',
+    isProfile: false,
+    objects: {},
+    fields: {},
+    ...extra,
+  });
+  render(
+    <MemoryRouter>
+      <PermissionMatrixEditPage type="permission" name="sales_perms" />
+    </MemoryRouter>,
+  );
+  await screen.findByText('Sales');
+}
+
+describe('PermissionMatrixEditPage — B1 first-screen collapse (objectui#2600)', () => {
+  it('collapses the identity form by default and expands on click', async () => {
+    await renderSet();
+
+    // Name/label are summary text, not editable inputs, on first paint.
+    expect(screen.queryByDisplayValue('sales_perms')).toBeNull();
+    expect(screen.queryByDisplayValue('Sales')).toBeNull();
+    expect(screen.getByText('Sales')).toBeInTheDocument();
+
+    // Clicking the summary strip (labelled "Sales") reveals the inputs.
+    fireEvent.click(screen.getByRole('button', { name: /Sales/ }));
+    expect(screen.getByDisplayValue('sales_perms')).toBeInTheDocument();
+    expect(screen.getByDisplayValue('Sales')).toBeInTheDocument();
+  });
+
+  it('collapses zero-grant capabilities to a "none · add" affordance', async () => {
+    await renderSet({ systemPermissions: [] });
+
+    // The option-chip picker is hidden; an explicit none-granted line shows.
+    expect(screen.queryByTestId('cap-picker')).toBeNull();
+    const add = screen.getByRole('button', { name: /Add capability/i });
+    expect(add).toBeInTheDocument();
+
+    // Opting in reveals the picker.
+    fireEvent.click(add);
+    expect(screen.getByTestId('cap-picker')).toBeInTheDocument();
+  });
+
+  it('keeps the picker inline when the set already grants capabilities', async () => {
+    await renderSet({ systemPermissions: ['studio.access'] });
+    // Non-empty grants must remain visible without an extra click.
+    expect(screen.getByTestId('cap-picker')).toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: /Add capability/i })).toBeNull();
+  });
+});

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

@@ -71,7 +71,9 @@ async function renderMatrix(embedded: boolean) {
       />
     </MemoryRouter>,
   );
-  await screen.findByDisplayValue('Sales');
+  // Identity strip is collapsed by default (objectui#2600 B1) — the label is
+  // summary text, not an input, until the strip is expanded.
+  await screen.findByText('Sales');
 }
 
 describe('PermissionMatrixEditPage — embedded mode (Studio Access pillar)', () => {

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

@@ -114,7 +114,10 @@ describe('PermissionMatrixEditPage — read-only package gate (host readOnly)',
       expect(within(row).getByRole('button', { name })).toBeDisabled();
     }
 
-    // Identity inputs are locked too.
+    // Identity inputs collapse by default (objectui#2600 B1) — expand the
+    // strip (summary shows the label "Sales"), then confirm they are locked
+    // too in a read-only package.
+    fireEvent.click(screen.getByRole('button', { name: /Sales/ }));
     expect(screen.getByDisplayValue('sales_perms')).toBeDisabled();
     expect(screen.getByDisplayValue('Sales')).toBeDisabled();
 

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

@@ -248,6 +248,12 @@ export function PermissionMatrixEditPage({ type, name, packageId, onDraftSaved,
   >(null);
   const [filter, setFilter] = React.useState('');
   const [showOnlyEnabled, setShowOnlyEnabled] = React.useState(false);
+  // objectui#2600 B1 — the pillar is called "Permission Matrix", so the matrix
+  // must reach the first screen. Name/label change rarely and the capability
+  // picker floods the top with option chips even at zero grants, so both start
+  // collapsed to a one-line summary and the user opts in to edit them.
+  const [basicsOpen, setBasicsOpen] = React.useState(false);
+  const [capsOpen, setCapsOpen] = React.useState(false);
   // Embedded-mode History sheet (see `embedded` prop doc).
   const [historyOpen, setHistoryOpen] = React.useState(false);
   // All permission-set api-names — the admin-scope editor's assignable
@@ -648,58 +654,76 @@ export function PermissionMatrixEditPage({ type, name, packageId, onDraftSaved,
           </div>
         )}
 
-        {/* Header strip — name / label / provenance + default badges */}
-        <div className="px-6 py-3 border-b bg-muted/30 flex flex-wrap items-end gap-4">
-          <div className="space-y-1">
-            <Label htmlFor="perm-name" className="text-xs">{t('perm.field.name')}</Label>
-            <Input
-              id="perm-name"
-              value={draft.name}
-              disabled={!writable}
-              onChange={(e) => setDraft((p) => ({ ...p, name: e.target.value }))}
-              className="h-8 w-56"
-            />
-          </div>
-          <div className="space-y-1">
-            <Label htmlFor="perm-label" className="text-xs">{t('perm.field.label')}</Label>
-            <Input
-              id="perm-label"
-              value={draft.label ?? ''}
-              disabled={!writable}
-              onChange={(e) => setDraft((p) => ({ ...p, label: e.target.value }))}
-              className="h-8 w-72"
-            />
-          </div>
-          {/* ADR-0090 D2: the profile toggle is gone. What matters instead is
-              WHO OWNS the set (provenance, ADR-0086 D3) and whether it is the
-              package's suggested default (ADR-0090 D5). */}
-          <div className="flex items-center gap-1.5 pb-1">
+        {/* Identity summary — collapsible (objectui#2600 B1). Name/label change
+            rarely, so the strip collapses to a one-line summary and the matrix
+            reaches the first screen; the row toggles the editable inputs open. */}
+        <div className="border-b bg-muted/30">
+          <button
+            type="button"
+            onClick={() => setBasicsOpen((o) => !o)}
+            aria-expanded={basicsOpen}
+            className="w-full px-6 py-2.5 flex items-center gap-2 text-left hover:bg-muted/50 transition-colors"
+          >
+            {basicsOpen ? (
+              <ChevronDown className="h-4 w-4 shrink-0 text-muted-foreground" />
+            ) : (
+              <ChevronRight className="h-4 w-4 shrink-0 text-muted-foreground" />
+            )}
+            {/* The api-name already sits in the PageShell breadcrumb (font-mono),
+                so the summary carries the human label — no need to repeat it. */}
+            <span className="font-medium truncate">{draft.label || draft.name}</span>
             {/* [A4 framework#2920] Provenance tri-state — platform / package /
-                admin(custom) — mirrors the unified sys_* `managed_by` vocab so
-                the Studio matrix and the Setup record page read the same. */}
-            <Badge variant="outline" className="text-[10px]">
+                admin(custom) — mirrors the unified sys_* `managed_by` vocab. */}
+            <Badge variant="outline" className="text-[10px] shrink-0">
               {draft.managedBy === 'platform'
                 ? t('perm.badge.platform')
                 : draft.managedBy === 'package' || packageId
                   ? t('perm.badge.package')
                   : t('perm.badge.custom')}
             </Badge>
             {!!draft.isDefault && (
-              <Badge variant="secondary" className="text-[10px]">{t('perm.badge.default')}</Badge>
+              <Badge variant="secondary" className="text-[10px] shrink-0">{t('perm.badge.default')}</Badge>
             )}
-          </div>
-          {!writable && (
-            // Same badge slot, two distinct reasons: a read-only PACKAGE
-            // (host gate — mirror the top-bar wording so the screen is not
-            // self-contradictory) vs. metadata writes disabled environment-
-            // wide (type gate).
-            <Badge
-              variant="secondary"
-              className="ml-auto"
-              title={readOnly ? t('engine.studio.pkg.readonlyHint') : undefined}
-            >
-              {readOnly ? t('engine.studio.pkg.readonly') : t('perm.readOnly')}
-            </Badge>
+            {writable && (
+              <span className="text-xs text-muted-foreground shrink-0">{t('perm.basics.editHint')}</span>
+            )}
+            {!writable && (
+              // Same badge slot, two distinct reasons: a read-only PACKAGE
+              // (host gate — mirror the top-bar wording so the screen is not
+              // self-contradictory) vs. metadata writes disabled environment-
+              // wide (type gate).
+              <Badge
+                variant="secondary"
+                className="ml-auto shrink-0"
+                title={readOnly ? t('engine.studio.pkg.readonlyHint') : undefined}
+              >
+                {readOnly ? t('engine.studio.pkg.readonly') : t('perm.readOnly')}
+              </Badge>
+            )}
+          </button>
+          {basicsOpen && (
+            <div className="px-6 pb-3 flex flex-wrap items-end gap-4">
+              <div className="space-y-1">
+                <Label htmlFor="perm-name" className="text-xs">{t('perm.field.name')}</Label>
+                <Input
+                  id="perm-name"
+                  value={draft.name}
+                  disabled={!writable}
+                  onChange={(e) => setDraft((p) => ({ ...p, name: e.target.value }))}
+                  className="h-8 w-56"
+                />
+              </div>
+              <div className="space-y-1">
+                <Label htmlFor="perm-label" className="text-xs">{t('perm.field.label')}</Label>
+                <Input
+                  id="perm-label"
+                  value={draft.label ?? ''}
+                  disabled={!writable}
+                  onChange={(e) => setDraft((p) => ({ ...p, label: e.target.value }))}
+                  className="h-8 w-72"
+                />
+              </div>
+            </div>
           )}
         </div>
 
@@ -709,21 +733,40 @@ export function PermissionMatrixEditPage({ type, name, packageId, onDraftSaved,
             as PermissionSetDraft.systemPermissions (string[]); the picker
             round-trips via a JSON string, so parse back into the array the
             draft model uses. Persisted by the whole-record Save at env scope. */}
-        <div className="px-6 py-3 border-b">
-          <Label className="text-xs">{t('perm.field.systemCapabilities')}</Label>
-          <p className="text-xs text-muted-foreground mt-0.5 mb-2">
-            {t('perm.field.systemCapabilitiesHelp')}
-          </p>
-          <CapabilityMultiSelectField
-            value={JSON.stringify(draft.systemPermissions ?? [])}
-            onChange={(v: unknown) =>
-              setDraft((p) => ({ ...p, systemPermissions: parseCapabilityNames(v) }))
-            }
-            field={{ name: 'system_permissions' } as any}
-            dataSource={adapter as any}
-            readonly={!writable}
-          />
-        </div>
+        {writable && (draft.systemPermissions ?? []).length === 0 && !capsOpen ? (
+          // objectui#2600 B1 — zero-grant writable sets used to render the full
+          // picker's option chips, which read as already-owned capabilities.
+          // Collapse to an explicit "none granted · add" affordance instead.
+          <div className="px-6 py-2.5 border-b flex items-center gap-2 text-xs">
+            <Label className="text-xs text-muted-foreground">{t('perm.field.systemCapabilities')}</Label>
+            <span className="text-muted-foreground">·</span>
+            <span className="text-muted-foreground">{t('perm.cap.none')}</span>
+            <Button
+              variant="ghost"
+              size="sm"
+              className="h-6 px-2 text-xs"
+              onClick={() => setCapsOpen(true)}
+            >
+              + {t('perm.cap.add')}
+            </Button>
+          </div>
+        ) : (
+          <div className="px-6 py-3 border-b">
+            <Label className="text-xs">{t('perm.field.systemCapabilities')}</Label>
+            <p className="text-xs text-muted-foreground mt-0.5 mb-2">
+              {t('perm.field.systemCapabilitiesHelp')}
+            </p>
+            <CapabilityMultiSelectField
+              value={JSON.stringify(draft.systemPermissions ?? [])}
+              onChange={(v: unknown) =>
+                setDraft((p) => ({ ...p, systemPermissions: parseCapabilityNames(v) }))
+              }
+              field={{ name: 'system_permissions' } as any}
+              dataSource={adapter as any}
+              readonly={!writable}
+            />
+          </div>
+        )}
 
         {/* Filter bar */}
         <div className="px-6 py-3 border-b flex items-center gap-3">

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

@@ -768,6 +768,9 @@ const ENGINE_STRINGS_EN: Record<string, string> = {
   'perm.filter.empty': 'No objects match the filter.',
   'perm.field.name': 'Name',
   'perm.field.label': 'Label',
+  'perm.basics.editHint': 'Edit name / label',
+  'perm.cap.none': 'No system capabilities',
+  'perm.cap.add': 'Add capability',
   'perm.badge.platform': 'Platform',
   'perm.badge.package': 'Package',
   'perm.badge.custom': 'Custom',
@@ -2124,6 +2127,9 @@ const ENGINE_STRINGS_ZH: Record<string, string> = {
   'perm.filter.empty': '没有匹配的对象。',
   'perm.field.name': '名称',
   'perm.field.label': '标签',
+  'perm.basics.editHint': '编辑名称 / 标签',
+  'perm.cap.none': '无附加系统能力',
+  'perm.cap.add': '添加能力',
   'perm.badge.platform': '平台内置',
   'perm.badge.package': '包内置',
   'perm.badge.custom': '本环境自定义',