@object-ui/fields 13.1.0 → 13.2.0

package/dist/widgets/CapabilityMultiSelectField.d.ts

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+import { FieldWidgetProps } from './types';
+/**
+ * Parse the stored value into the selected capability-name list. The canonical
+ * storage is a JSON-string array; we also tolerate an already-parsed array (in
+ * case a caller hands us the parsed value) and a bare comma-separated string
+ * (legacy/hand-authored) so no selection is silently dropped.
+ */
+export declare function parseCapabilityNames(value: unknown): string[];
+export declare function CapabilityMultiSelectField({ value, onChange, readonly, className, ...props }: FieldWidgetProps<string | string[]>): React.JSX.Element;
+export default CapabilityMultiSelectField;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/fields",
-  "version": "13.1.0",
+  "version": "13.2.0",
   "description": "Field renderers and registry for Object UI",
   "license": "MIT",
   "type": "module",
@@ -30,12 +30,12 @@
     "rehype-sanitize": "^6.0.0",
     "remark-gfm": "^4.0.1",
     "tailwind-merge": "^3.6.0",
-    "@object-ui/components": "13.1.0",
-    "@object-ui/core": "13.1.0",
-    "@object-ui/i18n": "13.1.0",
-    "@object-ui/providers": "13.1.0",
-    "@object-ui/react": "13.1.0",
-    "@object-ui/types": "13.1.0"
+    "@object-ui/components": "13.2.0",
+    "@object-ui/core": "13.2.0",
+    "@object-ui/i18n": "13.2.0",
+    "@object-ui/providers": "13.2.0",
+    "@object-ui/react": "13.2.0",
+    "@object-ui/types": "13.2.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

package/src/index.tsx

@@ -179,6 +179,7 @@ import { CurrencyField } from './widgets/CurrencyField';
 import { TextAreaField } from './widgets/TextAreaField';
 import { RichTextField } from './widgets/RichTextField';
 import { LookupField } from './widgets/LookupField';
+import { CapabilityMultiSelectField } from './widgets/CapabilityMultiSelectField';
 import { DateTimeField } from './widgets/DateTimeField';
 import { TimeField } from './widgets/TimeField';
 import { PercentField } from './widgets/PercentField';
@@ -2152,6 +2153,12 @@ export function registerFields() {
   // display widget remains the default for { type: 'html', content }.
   ComponentRegistry.register('html', createFieldRenderer(RichTextField), { namespace: 'field', skipFallback: true });
   ComponentRegistry.register('lookup', createFieldRenderer(LookupField), { namespace: 'field' });
+  // Capability multi-select (ADR-0056 P2) — reached only via the field
+  // `widget: 'capability-multiselect'` hint (see MetadataProvider), never a bare
+  // field type. Registered WITHOUT createFieldRenderer: it is a fully-controlled
+  // widget (value/onChange from RHF), so the wrapper's extra label + local value
+  // buffer would only duplicate the form's FormLabel and desync the value.
+  ComponentRegistry.register('capability-multiselect', CapabilityMultiSelectField, { namespace: 'field', skipFallback: true });
   // master_detail = child-side FK lookup (single value, typically required). See
   // fieldWidgetMap above for rationale.
   ComponentRegistry.register('master_detail', createFieldRenderer(LookupField), { namespace: 'field' });
@@ -2212,6 +2219,7 @@ export * from './widgets/PasswordField';
 export * from './widgets/TextAreaField';
 export * from './widgets/RichTextField';
 export * from './widgets/LookupField';
+export * from './widgets/CapabilityMultiSelectField';
 export * from './widgets/RecordPickerDialog';
 export * from './widgets/FileField';
 export * from './widgets/ImageField';

package/src/widgets/CapabilityMultiSelectField.test.tsx

@@ -0,0 +1,143 @@
+/**
+ * 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.
+ */
+
+/**
+ * CapabilityMultiSelectField (ADR-0056 P2, epic #2398).
+ *
+ * Proves the two properties P2 depends on:
+ *  1. the stored value parses tolerantly into a capability-name list, and
+ *  2. every edit emits a JSON-**string** array of names — byte-equivalent to
+ *     the `sys_permission_set.system_permissions` textarea storage, so the
+ *     round-trip through the picker never changes the on-disk shape.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import React from 'react';
+import { render, screen, fireEvent } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { CapabilityMultiSelectField, parseCapabilityNames } from './CapabilityMultiSelectField';
+
+describe('parseCapabilityNames', () => {
+  it('parses the canonical JSON-string array', () => {
+    expect(parseCapabilityNames('["setup.access","studio.access"]')).toEqual([
+      'setup.access',
+      'studio.access',
+    ]);
+  });
+
+  it('treats empty / null / undefined as no selection', () => {
+    expect(parseCapabilityNames('')).toEqual([]);
+    expect(parseCapabilityNames('   ')).toEqual([]);
+    expect(parseCapabilityNames(null)).toEqual([]);
+    expect(parseCapabilityNames(undefined)).toEqual([]);
+    expect(parseCapabilityNames('[]')).toEqual([]);
+  });
+
+  it('tolerates an already-parsed array', () => {
+    expect(parseCapabilityNames(['a', 'b'])).toEqual(['a', 'b']);
+  });
+
+  it('falls back to comma-splitting a non-JSON legacy string', () => {
+    expect(parseCapabilityNames('setup.access, studio.access')).toEqual([
+      'setup.access',
+      'studio.access',
+    ]);
+  });
+});
+
+const CAPS = [
+  { name: 'manage_users', label: 'Manage Users', description: 'Manage users', scope: 'platform', active: true },
+  { name: 'studio.access', label: 'Studio Access', description: 'Enter Studio', scope: 'platform', active: true },
+  { name: 'manage_org_users', label: 'Manage Org Users', description: 'Org members', scope: 'org', active: true },
+];
+
+function mockDataSource(rows = CAPS) {
+  return { find: vi.fn().mockResolvedValue({ data: rows }) } as any;
+}
+
+describe('CapabilityMultiSelectField', () => {
+  it('renders capabilities grouped by scope with human labels', async () => {
+    render(
+      <CapabilityMultiSelectField
+        value={'["studio.access"]'}
+        onChange={vi.fn()}
+        field={{ name: 'system_permissions' } as any}
+        dataSource={mockDataSource()}
+      />,
+    );
+    // group headers
+    expect(await screen.findByText('Platform')).toBeInTheDocument();
+    expect(screen.getByText('Organization')).toBeInTheDocument();
+    // labels, not raw names
+    expect(screen.getByRole('button', { name: 'Studio Access' })).toHaveAttribute('aria-pressed', 'true');
+    expect(screen.getByRole('button', { name: 'Manage Users' })).toHaveAttribute('aria-pressed', 'false');
+  });
+
+  it('emits a JSON-string array when a capability is toggled on', async () => {
+    const onChange = vi.fn();
+    render(
+      <CapabilityMultiSelectField
+        value={'["studio.access"]'}
+        onChange={onChange}
+        field={{ name: 'system_permissions' } as any}
+        dataSource={mockDataSource()}
+      />,
+    );
+    fireEvent.click(await screen.findByRole('button', { name: 'Manage Users' }));
+    expect(onChange).toHaveBeenCalledTimes(1);
+    const emitted = onChange.mock.calls[0][0];
+    // The emitted value must be a JSON *string* (not a raw array), byte-equal
+    // to the textarea storage contract.
+    expect(typeof emitted).toBe('string');
+    expect(JSON.parse(emitted)).toEqual(['studio.access', 'manage_users']);
+  });
+
+  it('removes a capability (and keeps emitting a JSON string) when toggled off', async () => {
+    const onChange = vi.fn();
+    render(
+      <CapabilityMultiSelectField
+        value={'["studio.access","manage_users"]'}
+        onChange={onChange}
+        field={{ name: 'system_permissions' } as any}
+        dataSource={mockDataSource()}
+      />,
+    );
+    fireEvent.click(await screen.findByRole('button', { name: 'Studio Access' }));
+    const emitted = onChange.mock.calls[0][0];
+    expect(typeof emitted).toBe('string');
+    expect(JSON.parse(emitted)).toEqual(['manage_users']);
+  });
+
+  it('preserves an unknown/legacy selected name not in the registry', async () => {
+    render(
+      <CapabilityMultiSelectField
+        value={'["studio.access","legacy.custom"]'}
+        onChange={vi.fn()}
+        field={{ name: 'system_permissions' } as any}
+        dataSource={mockDataSource()}
+      />,
+    );
+    // The unknown name still renders as a (selected) chip so it is not dropped.
+    const legacy = await screen.findByRole('button', { name: 'legacy.custom' });
+    expect(legacy).toHaveAttribute('aria-pressed', 'true');
+  });
+
+  it('renders selected labels as read-only badges when readonly', async () => {
+    render(
+      <CapabilityMultiSelectField
+        value={'["studio.access"]'}
+        onChange={vi.fn()}
+        field={{ name: 'system_permissions' } as any}
+        dataSource={mockDataSource()}
+        readonly
+      />,
+    );
+    // No toggle buttons in readonly mode.
+    expect(await screen.findByText('Studio Access')).toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: 'Manage Users' })).not.toBeInTheDocument();
+  });
+});

package/src/widgets/CapabilityMultiSelectField.tsx

@@ -0,0 +1,204 @@
+import React from 'react';
+import { Badge, EmptyValue, cn } from '@object-ui/components';
+import { SchemaRendererContext } from '@object-ui/react';
+import type { DataSource, QueryParams } from '@object-ui/types';
+import { FieldWidgetProps } from './types';
+
+/**
+ * CapabilityMultiSelectField — structured picker for a permission set's
+ * `system_permissions` (ADR-0056 / epic #2398, phase P2).
+ *
+ * `sys_permission_set.system_permissions` is framework-declared as a
+ * `Field.textarea` that stores a **JSON-serialized array of capability names**
+ * (e.g. `["setup.access","studio.access"]`; `security-plugin.ts` writes
+ * `JSON.stringify(...)` and reads `parseJson(...)`). Editing that as raw JSON is
+ * the anti-pattern ADR-0056 removes. This widget renders the same value as a
+ * multi-select over the live `sys_capability` registry — grouped by scope,
+ * labelled, with the capability description on hover — while round-tripping the
+ * stored value **byte-for-byte** as a JSON string of names.
+ *
+ * Reached via the field `widget: 'capability-multiselect'` hint (stamped onto
+ * the object metadata in MetadataProvider), registered in the field registry as
+ * `field:capability-multiselect`.
+ */
+
+interface Capability {
+  name: string;
+  label?: string;
+  description?: string;
+  scope?: string;
+  active?: boolean;
+}
+
+/**
+ * Parse the stored value into the selected capability-name list. The canonical
+ * storage is a JSON-string array; we also tolerate an already-parsed array (in
+ * case a caller hands us the parsed value) and a bare comma-separated string
+ * (legacy/hand-authored) so no selection is silently dropped.
+ */
+export function parseCapabilityNames(value: unknown): string[] {
+  if (Array.isArray(value)) return value.map((v) => String(v)).filter(Boolean);
+  if (typeof value === 'string') {
+    const s = value.trim();
+    if (!s) return [];
+    try {
+      const parsed = JSON.parse(s);
+      if (Array.isArray(parsed)) return parsed.map((v) => String(v)).filter(Boolean);
+      // A JSON scalar (unexpected) — treat as a single name.
+      return [String(parsed)].filter(Boolean);
+    } catch {
+      // Not JSON — fall back to comma-splitting so legacy values survive.
+      return s.split(',').map((x) => x.trim()).filter(Boolean);
+    }
+  }
+  return [];
+}
+
+/** Scope → group header. Order is intentional (platform powers first). */
+const SCOPE_ORDER = ['platform', 'org', 'other'] as const;
+const SCOPE_LABEL: Record<string, string> = {
+  platform: 'Platform',
+  org: 'Organization',
+  other: 'Other',
+};
+
+export function CapabilityMultiSelectField({
+  value,
+  onChange,
+  readonly,
+  className,
+  ...props
+}: FieldWidgetProps<string | string[]>) {
+  const ctx = React.useContext(SchemaRendererContext);
+  const dataSource: DataSource | null =
+    (props as any).dataSource ?? (ctx as any)?.dataSource ?? null;
+  const disabled = (props as any).disabled as boolean | undefined;
+
+  const [caps, setCaps] = React.useState<Capability[] | null>(null);
+
+  const selected = React.useMemo(() => parseCapabilityNames(value), [value]);
+
+  // Load the live capability registry (active only). Mirrors LookupField's
+  // context-dataSource access — createFieldRenderer does not forward the
+  // dataSource prop, so the SchemaRenderer context is the reliable source.
+  React.useEffect(() => {
+    if (!dataSource || typeof (dataSource as any).find !== 'function') return;
+    let cancelled = false;
+    (async () => {
+      try {
+        const res = await dataSource.find('sys_capability', {
+          $filter: { active: true },
+          $top: 500,
+        } as QueryParams);
+        const rows: Capability[] =
+          (res as any)?.data ?? (res as any)?.records ?? (Array.isArray(res) ? res : []);
+        if (!cancelled) setCaps(Array.isArray(rows) ? rows : []);
+      } catch {
+        if (!cancelled) setCaps([]);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [dataSource]);
+
+  // Emit as a JSON string so the value round-trips byte-equivalent to the
+  // `system_permissions` textarea's `JSON.stringify(string[])` storage.
+  const emit = React.useCallback(
+    (names: string[]) => onChange(JSON.stringify(names) as any),
+    [onChange],
+  );
+
+  // Union of the fetched registry and any *selected* names not present in it
+  // (unknown / legacy / package-owned-inactive), so no current grant is hidden
+  // or dropped. Unknown names land in the "other" group.
+  const byName = React.useMemo(() => {
+    const map = new Map<string, Capability>();
+    for (const c of caps ?? []) if (c?.name) map.set(c.name, c);
+    for (const n of selected) if (!map.has(n)) map.set(n, { name: n, label: n, scope: 'other' });
+    return map;
+  }, [caps, selected]);
+
+  const labelFor = (name: string) => byName.get(name)?.label || name;
+
+  // Group options by scope for the editable grid. Computed BEFORE the readonly
+  // early-return so the hook order stays stable regardless of `readonly`.
+  const groups = React.useMemo(() => {
+    const buckets = new Map<string, Capability[]>();
+    for (const c of byName.values()) {
+      const key = (SCOPE_ORDER as readonly string[]).includes(c.scope as string)
+        ? (c.scope as string)
+        : 'other';
+      const list = buckets.get(key) ?? [];
+      list.push(c);
+      buckets.set(key, list);
+    }
+    return SCOPE_ORDER.filter((s) => buckets.has(s)).map((s) => ({
+      scope: s,
+      label: SCOPE_LABEL[s] ?? s,
+      items: (buckets.get(s) ?? []).sort((a, b) =>
+        (a.label || a.name).localeCompare(b.label || b.name),
+      ),
+    }));
+  }, [byName]);
+
+  if (readonly) {
+    if (selected.length === 0) return <EmptyValue />;
+    return (
+      <div className="flex flex-wrap gap-1">
+        {selected.map((name) => (
+          <Badge key={name} variant="outline" title={byName.get(name)?.description}>
+            {labelFor(name)}
+          </Badge>
+        ))}
+      </div>
+    );
+  }
+
+  const toggle = (name: string) => {
+    const next = selected.includes(name)
+      ? selected.filter((x) => x !== name)
+      : [...selected, name];
+    emit(next);
+  };
+
+  return (
+    <div className={cn('flex flex-col gap-3', className)}>
+      {caps === null && groups.length === 0 && (
+        <span className="text-sm text-muted-foreground">Loading capabilities…</span>
+      )}
+      {groups.map((group) => (
+        <div key={group.scope} className="flex flex-col gap-1.5">
+          <div className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+            {group.label}
+          </div>
+          <div className="flex flex-wrap gap-1.5">
+            {group.items.map((cap) => {
+              const active = selected.includes(cap.name);
+              return (
+                <button
+                  type="button"
+                  key={cap.name}
+                  onClick={() => toggle(cap.name)}
+                  disabled={disabled}
+                  aria-pressed={active}
+                  title={cap.description || undefined}
+                  className={cn(
+                    'rounded-full border px-3 py-1 text-sm transition-colors disabled:opacity-50',
+                    active
+                      ? 'border-primary bg-primary text-primary-foreground'
+                      : 'border-input bg-background text-foreground hover:bg-accent',
+                  )}
+                >
+                  {cap.label || cap.name}
+                </button>
+              );
+            })}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+export default CapabilityMultiSelectField;