feat(access): Studio permission matrix — field-level bulk + filter for wide objects (#2600 B4) (#2651)

os-zhuang · claude · web-flow · commit d121cb3d549f · 2026-07-18T13:19:22.000+08:00
Expanding an object with many fields (the field_zoo pain) meant toggling two
checkboxes per field, one at a time — the object row had read/all/none
shortcuts but the field sub-table had none.

- FieldsSubTable gains a field filter (name/label, shown once an object has
  more than ~6 fields) and Read-all / Write-all / Clear shortcuts that act over
  the currently VISIBLE (filtered) fields, so you can narrow then bulk-apply.
- New parent `bulkSetFields(object, action, fieldNames)`: `readable` sets read
  only, `writable` grants R+W, `clear` drops the overrides back to default.
- A visible/total count keeps the filter honest.

Read-only packages still hide the bulk actions (writable-gated); the per-field
checkboxes and their aria-labels are unchanged.

Adds PermissionMatrixEditor.fieldBulk.test.tsx (write-all, filter-scoped bulk,
clear-to-default).

Co-authored-by: Jack Zhuang &lt;277994282+os-zhuang@users.noreply.github.com&gt;
Co-authored-by: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;
diff --git a/packages/app-shell/src/views/metadata-admin/PermissionMatrixEditor.fieldBulk.test.tsx b/packages/app-shell/src/views/metadata-admin/PermissionMatrixEditor.fieldBulk.test.tsx
@@ -0,0 +1,109 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * objectui#2600 B4 — field-level bulk + filter. Expanding a wide object used to
+ * mean toggling two checkboxes per field, one field at a time. The sub-table
+ * now carries a field filter and Read-all / Write-all / Clear shortcuts that
+ * act over the VISIBLE (filtered) fields — mirroring the per-object row.
+ */
+
+import '@testing-library/jest-dom/vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { MemoryRouter } from 'react-router-dom';
+
+let clientImpl: any;
+
+vi.mock('./useMetadata', () => ({
+  useMetadataClient: () => clientImpl,
+  useMetadataTypes: () => ({
+    loading: false,
+    error: null,
+    entries: [{ type: 'permission', label: 'Permission', allowOrgOverride: true }],
+  }),
+}));
+
+import { PermissionMatrixEditPage } from './PermissionMatrixEditor';
+
+afterEach(cleanup);
+
+// Eight fields → wide enough that the filter shows (threshold is > 6).
+const FIELDS = ['amount', 'email', 'name', 'owner', 'phone', 'region', 'revenue', 'status'];
+
+function makeClient() {
+  return {
+    layered: async () => ({
+      effective: { name: 'sales_perms', label: 'Sales', objects: { a_account: { allowRead: true } }, fields: {} },
+      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: FIELDS.map((name) => ({ name })) } : null,
+    save: async (_t: string, _n: string, payload: Record<string, unknown>) => payload,
+  } as any;
+}
+
+async function renderExpanded() {
+  clientImpl = makeClient();
+  render(
+    <MemoryRouter>
+      <PermissionMatrixEditPage type="permission" name="sales_perms" packageId="app.a" />
+    </MemoryRouter>,
+  );
+  // Expand the object row, then wait for its fields to load.
+  fireEvent.click(await screen.findByRole('button', { name: /a_account/ }));
+  await screen.findByLabelText('a_account.email readable');
+}
+
+describe('PermissionMatrixEditPage — field-level bulk + filter (objectui#2600 B4)', () => {
+  it('Write all grants read+write to every visible field', async () => {
+    await renderExpanded();
+
+    expect(screen.getByLabelText('a_account.email editable')).not.toBeChecked();
+    fireEvent.click(screen.getByRole('button', { name: 'Write all' }));
+
+    for (const f of FIELDS) {
+      expect(screen.getByLabelText(`a_account.${f} readable`)).toBeChecked();
+      expect(screen.getByLabelText(`a_account.${f} editable`)).toBeChecked();
+    }
+  });
+
+  it('the filter narrows the field set and bulk acts only on what is visible', async () => {
+    await renderExpanded();
+
+    // Grant write to everyone first.
+    fireEvent.click(screen.getByRole('button', { name: 'Write all' }));
+    expect(screen.getByLabelText('a_account.email editable')).toBeChecked();
+
+    // Filter to just the "re*" fields — region + revenue.
+    fireEvent.change(screen.getByLabelText('Filter fields…'), { target: { value: 're' } });
+    expect(screen.getByLabelText('a_account.region readable')).toBeInTheDocument();
+    expect(screen.getByLabelText('a_account.revenue readable')).toBeInTheDocument();
+    expect(screen.queryByLabelText('a_account.email readable')).toBeNull();
+    expect(screen.getByText('2 / 8')).toBeInTheDocument();
+
+    // Read-all now only revokes write on the visible (filtered) fields.
+    fireEvent.click(screen.getByRole('button', { name: 'Read all' }));
+    expect(screen.getByLabelText('a_account.region editable')).not.toBeChecked();
+    expect(screen.getByLabelText('a_account.region readable')).toBeChecked();
+
+    // Clearing the filter reveals the untouched fields still holding write.
+    fireEvent.change(screen.getByLabelText('Filter fields…'), { target: { value: '' } });
+    expect(screen.getByLabelText('a_account.email editable')).toBeChecked();
+  });
+
+  it('Clear drops the overrides so fields fall back to the read-only default', async () => {
+    await renderExpanded();
+
+    fireEvent.click(screen.getByRole('button', { name: 'Write all' }));
+    expect(screen.getByLabelText('a_account.name editable')).toBeChecked();
+
+    fireEvent.click(screen.getByRole('button', { name: 'Clear' }));
+    // Default field posture: readable, not editable.
+    expect(screen.getByLabelText('a_account.name readable')).toBeChecked();
+    expect(screen.getByLabelText('a_account.name editable')).not.toBeChecked();
+  });
+});
diff --git a/packages/app-shell/src/views/metadata-admin/PermissionMatrixEditor.tsx b/packages/app-shell/src/views/metadata-admin/PermissionMatrixEditor.tsx
@@ -513,6 +513,24 @@ export function PermissionMatrixEditPage({ type, name, packageId, onDraftSaved,
     });
   }
 
+  // objectui#2600 B4 — field-level bulk over the fields currently VISIBLE in the
+  // sub-table (i.e. after the field filter), mirroring the per-object row's
+  // read/all/none shortcuts. `readable` sets read-only, `writable` grants R+W,
+  // `clear` drops the explicit overrides so those fields fall back to default.
+  function bulkSetFields(objectName: string, action: 'readable' | 'writable' | 'clear', fieldNames: string[]) {
+    if (fieldNames.length === 0) return;
+    setDraft((prev) => {
+      const fields = { ...(prev.fields ?? {}) };
+      for (const fieldName of fieldNames) {
+        const key = `${objectName}.${fieldName}`;
+        if (action === 'clear') delete fields[key];
+        else if (action === 'readable') fields[key] = { readable: true, editable: false };
+        else fields[key] = { readable: true, editable: true };
+      }
+      return { ...prev, fields };
+    });
+  }
+
   /**
    * Re-narrow a freshly-read full permission set to this package's slice for
    * display. No-op at environment scope (no `packageId`).
@@ -815,6 +833,7 @@ export function PermissionMatrixEditPage({ type, name, packageId, onDraftSaved,
             onObjectPerm={updateObjectPerm}
             onFieldPerm={updateFieldPerm}
             onBulkSet={bulkSetObject}
+            onFieldBulk={bulkSetFields}
             onOpenOwd={onOpenOwd}
           />
           {/* Advanced facets (ADR-0056 P3) — RLS / tab visibility / delegated
@@ -909,6 +928,8 @@ interface PermissionTableProps {
   onObjectPerm: (objectName: string, action: keyof ObjectPerm, value: boolean) => void;
   onFieldPerm: (objectName: string, fieldName: string, action: keyof FieldPerm, value: boolean) => void;
   onBulkSet: (objectName: string, action: 'all' | 'none' | 'crud' | 'read') => void;
+  /** objectui#2600 B4 — field-level bulk over the filtered field set. */
+  onFieldBulk: (objectName: string, action: 'readable' | 'writable' | 'clear', fieldNames: string[]) => void;
   /** objectui#2505 — when set, the OWD badge links to the package OWD overview. */
   onOpenOwd?: (objectName: string) => void;
 }
@@ -925,6 +946,7 @@ function PermissionTable({
   onObjectPerm,
   onFieldPerm,
   onBulkSet,
+  onFieldBulk,
   onOpenOwd,
 }: PermissionTableProps) {
   return (
@@ -1078,6 +1100,7 @@ function PermissionTable({
                       writable={writable}
                       t={t}
                       onFieldPerm={onFieldPerm}
+                      onFieldBulk={onFieldBulk}
                     />
                   </td>
                 </tr>
@@ -1097,14 +1120,19 @@ function FieldsSubTable({
   writable,
   t,
   onFieldPerm,
+  onFieldBulk,
 }: {
   objectName: string;
   fields: FieldSummary[] | undefined;
   fieldsState: Record<string, FieldPerm>;
   writable: boolean;
   t: (key: string) => string;
   onFieldPerm: (objectName: string, fieldName: string, action: keyof FieldPerm, value: boolean) => void;
+  onFieldBulk: (objectName: string, action: 'readable' | 'writable' | 'clear', fieldNames: string[]) => void;
 }) {
+  // objectui#2600 B4 — filter fields and bulk-apply over the visible set, so
+  // wide objects (dozens of fields) aren't two-checkboxes-at-a-time tedious.
+  const [fieldFilter, setFieldFilter] = React.useState('');
   if (!fields) {
     return (
       <div className="text-xs text-muted-foreground flex items-center gap-2">
@@ -1115,47 +1143,105 @@ function FieldsSubTable({
   if (fields.length === 0) {
     return <div className="text-xs text-muted-foreground">{t('perm.field.empty')}</div>;
   }
+  const q = fieldFilter.trim().toLowerCase();
+  const visible = q
+    ? fields.filter((f) => f.name.toLowerCase().includes(q) || (f.label ?? '').toLowerCase().includes(q))
+    : fields;
+  const visibleNames = visible.map((f) => f.name);
   return (
-    <table className="w-full text-xs">
-      <thead>
-        <tr className="text-muted-foreground">
-          <th className="text-left py-1 font-medium">{t('perm.field.col.name')}</th>
-          <th className="px-2 py-1 font-medium w-16 text-center" title={t('perm.field.read')}>{t('perm.field.read')}</th>
-          <th className="px-2 py-1 font-medium w-16 text-center" title={t('perm.field.edit')}>{t('perm.field.edit')}</th>
-        </tr>
-      </thead>
-      <tbody>
-        {fields.map((f) => {
-          const key = `${objectName}.${f.name}`;
-          const cur = fieldsState[key] ?? { readable: true, editable: false };
-          return (
-            <tr key={f.name} className="border-t border-muted">
-              <td className="py-1">
-                {f.label ?? f.name}
-                {f.label && (
-                  <span className="ml-1 text-muted-foreground">({f.name})</span>
-                )}
-              </td>
-              <td className="px-2 py-1 text-center">
-                <Checkbox
-                  checked={!!cur.readable}
-                  disabled={!writable}
-                  onCheckedChange={(v) => onFieldPerm(objectName, f.name, 'readable', !!v)}
-                  aria-label={`${objectName}.${f.name} readable`}
-                />
-              </td>
-              <td className="px-2 py-1 text-center">
-                <Checkbox
-                  checked={!!cur.editable}
-                  disabled={!writable}
-                  onCheckedChange={(v) => onFieldPerm(objectName, f.name, 'editable', !!v)}
-                  aria-label={`${objectName}.${f.name} editable`}
-                />
-              </td>
+    <div className="space-y-2">
+      {/* Field toolbar (B4): filter + bulk over the visible field set. The
+          filter only appears once one-by-one would actually hurt. */}
+      <div className="flex flex-wrap items-center gap-2">
+        {fields.length > 6 && (
+          <Input
+            value={fieldFilter}
+            onChange={(e) => setFieldFilter(e.target.value)}
+            placeholder={t('perm.field.filter')}
+            aria-label={t('perm.field.filter')}
+            className="h-7 w-44 text-xs"
+          />
+        )}
+        {writable && (
+          <div className="flex items-center gap-1">
+            <Button
+              variant="ghost"
+              size="sm"
+              className="h-6 px-1.5 text-xs"
+              disabled={visibleNames.length === 0}
+              onClick={() => onFieldBulk(objectName, 'readable', visibleNames)}
+            >
+              {t('perm.field.bulk.readable')}
+            </Button>
+            <Button
+              variant="ghost"
+              size="sm"
+              className="h-6 px-1.5 text-xs"
+              disabled={visibleNames.length === 0}
+              onClick={() => onFieldBulk(objectName, 'writable', visibleNames)}
+            >
+              {t('perm.field.bulk.writable')}
+            </Button>
+            <Button
+              variant="ghost"
+              size="sm"
+              className="h-6 px-1.5 text-xs"
+              disabled={visibleNames.length === 0}
+              onClick={() => onFieldBulk(objectName, 'clear', visibleNames)}
+            >
+              {t('perm.field.bulk.clear')}
+            </Button>
+          </div>
+        )}
+        <span className="ml-auto text-[11px] text-muted-foreground">
+          {visible.length} / {fields.length}
+        </span>
+      </div>
+      {visible.length === 0 ? (
+        <div className="text-xs text-muted-foreground">{t('perm.field.filterEmpty')}</div>
+      ) : (
+        <table className="w-full text-xs">
+          <thead>
+            <tr className="text-muted-foreground">
+              <th className="text-left py-1 font-medium">{t('perm.field.col.name')}</th>
+              <th className="px-2 py-1 font-medium w-16 text-center" title={t('perm.field.read')}>{t('perm.field.read')}</th>
+              <th className="px-2 py-1 font-medium w-16 text-center" title={t('perm.field.edit')}>{t('perm.field.edit')}</th>
             </tr>
-          );
-        })}
-      </tbody>
-    </table>
+          </thead>
+          <tbody>
+            {visible.map((f) => {
+              const key = `${objectName}.${f.name}`;
+              const cur = fieldsState[key] ?? { readable: true, editable: false };
+              return (
+                <tr key={f.name} className="border-t border-muted">
+                  <td className="py-1">
+                    {f.label ?? f.name}
+                    {f.label && (
+                      <span className="ml-1 text-muted-foreground">({f.name})</span>
+                    )}
+                  </td>
+                  <td className="px-2 py-1 text-center">
+                    <Checkbox
+                      checked={!!cur.readable}
+                      disabled={!writable}
+                      onCheckedChange={(v) => onFieldPerm(objectName, f.name, 'readable', !!v)}
+                      aria-label={`${objectName}.${f.name} readable`}
+                    />
+                  </td>
+                  <td className="px-2 py-1 text-center">
+                    <Checkbox
+                      checked={!!cur.editable}
+                      disabled={!writable}
+                      onCheckedChange={(v) => onFieldPerm(objectName, f.name, 'editable', !!v)}
+                      aria-label={`${objectName}.${f.name} editable`}
+                    />
+                  </td>
+                </tr>
+              );
+            })}
+          </tbody>
+        </table>
+      )}
+    </div>
   );
 }
diff --git a/packages/app-shell/src/views/metadata-admin/i18n.ts b/packages/app-shell/src/views/metadata-admin/i18n.ts
@@ -777,6 +777,11 @@ const ENGINE_STRINGS_EN: Record<string, string> = {
   'perm.badge.default': 'Default for new users',
   'perm.field.loading': 'Loading fields…',
   'perm.field.empty': 'No fields registered for this object.',
+  'perm.field.filter': 'Filter fields…',
+  'perm.field.filterEmpty': 'No fields match the filter.',
+  'perm.field.bulk.readable': 'Read all',
+  'perm.field.bulk.writable': 'Write all',
+  'perm.field.bulk.clear': 'Clear',
   'perm.field.col.name': 'Field',
   'perm.field.read': 'Read',
   'perm.field.edit': 'Edit',
@@ -2137,6 +2142,11 @@ const ENGINE_STRINGS_ZH: Record<string, string> = {
   'perm.badge.default': '新用户默认',
   'perm.field.loading': '加载字段中…',
   'perm.field.empty': '该对象未注册字段。',
+  'perm.field.filter': '筛选字段…',
+  'perm.field.filterEmpty': '没有匹配的字段。',
+  'perm.field.bulk.readable': '全部可读',
+  'perm.field.bulk.writable': '全部可写',
+  'perm.field.bulk.clear': '清空',
   'perm.field.col.name': '字段',
   'perm.field.read': '读',
   'perm.field.edit': '改',
