@happyvertical/smrt-fields 0.40.61 → 0.40.63

package/dist/svelte/__tests__/ObjectForm.test.js

@@ -254,6 +254,137 @@ describe('ObjectForm component', () => {
         await userEvent.click(submit);
         expect(onsubmit).toHaveBeenCalledTimes(1);
     });
+    it('reports only after a synchronous host persistence acknowledgement', async () => {
+        const onsubmit = vi.fn(() => true);
+        const reportUsage = vi.fn(() => {
+            throw new Error('metrics unavailable');
+        });
+        render(ObjectFormActionsFixture, {
+            props: { fields, policy, onsubmit, usageReporter: { reportUsage } },
+        });
+        await userEvent.type(screen.getByRole('textbox', { name: 'Name' }), 'Deluxe');
+        await userEvent.click(screen.getByRole('button', { name: 'Save product' }));
+        expect(onsubmit).toHaveBeenCalledTimes(1);
+        expect(reportUsage).toHaveBeenCalledWith({
+            entries: [{ objectRef: '@test:Product', fieldName: 'name' }],
+        });
+        const metadata = screen.getByRole('textbox', {
+            name: 'Metadata',
+        });
+        metadata.value = '{not json}';
+        await fireEvent.input(metadata);
+        await userEvent.click(screen.getByRole('button', { name: 'Save product' }));
+        expect(reportUsage).toHaveBeenCalledTimes(1);
+    });
+    it('reports after an asynchronous host persistence acknowledgement', async () => {
+        const onsubmit = vi.fn(async () => true);
+        const reportUsage = vi.fn();
+        render(ObjectFormActionsFixture, {
+            props: { fields, policy, onsubmit, usageReporter: { reportUsage } },
+        });
+        await userEvent.type(screen.getByRole('textbox', { name: 'Name' }), 'Deluxe');
+        await userEvent.click(screen.getByRole('button', { name: 'Save product' }));
+        await vi.waitFor(() => expect(reportUsage).toHaveBeenCalledTimes(1));
+    });
+    it('reports the submitted values when a successful create clears its bound record', async () => {
+        const reportUsage = vi.fn();
+        render(ObjectFormActionsFixture, {
+            props: {
+                fields,
+                policy,
+                onsubmit: async () => true,
+                usageReporter: { reportUsage },
+                resetAfterSuccessfulSubmit: true,
+            },
+        });
+        await userEvent.type(screen.getByRole('textbox', { name: 'Name' }), 'Deluxe');
+        await userEvent.click(screen.getByRole('button', { name: 'Save product' }));
+        await vi.waitFor(() => expect(reportUsage).toHaveBeenCalledWith({
+            entries: [{ objectRef: '@test:Product', fieldName: 'name' }],
+        }));
+    });
+    it('keeps named void and Promise<void> persistence handlers compatible without treating either as success', async () => {
+        function legacyVoidHandler(_event) { }
+        async function legacyAsyncVoidHandler(_event) { }
+        const handlers = [
+            legacyVoidHandler,
+            legacyAsyncVoidHandler,
+        ];
+        for (const onsubmit of handlers) {
+            const reportUsage = vi.fn();
+            const view = render(ObjectFormActionsFixture, {
+                props: { fields, policy, onsubmit, usageReporter: { reportUsage } },
+            });
+            await userEvent.type(screen.getByRole('textbox', { name: 'Name' }), 'Deluxe');
+            await userEvent.click(screen.getByRole('button', { name: 'Save product' }));
+            await Promise.resolve();
+            expect(reportUsage).not.toHaveBeenCalled();
+            view.unmount();
+        }
+    });
+    it('marks a count-only text default as matched after persistence', async () => {
+        const policyWithTextDefault = {
+            ...policy,
+            fields: {
+                ...policy.fields,
+                name: {
+                    ...policy.fields.name,
+                    hasDefault: true,
+                    defaultValue: 'Default product name',
+                },
+            },
+        };
+        const reportUsage = vi.fn();
+        render(ObjectFormActionsFixture, {
+            props: {
+                fields,
+                policy: policyWithTextDefault,
+                onsubmit: () => true,
+                usageReporter: { reportUsage },
+            },
+        });
+        await tick();
+        await userEvent.click(screen.getByRole('button', { name: 'Save product' }));
+        expect(reportUsage).toHaveBeenCalledWith({
+            entries: [
+                {
+                    objectRef: '@test:Product',
+                    fieldName: 'name',
+                    matchedDefault: true,
+                },
+            ],
+        });
+    });
+    it('does not report when the host cancels, omits success, rejects, or local validation fails', async () => {
+        let attempt = 0;
+        const onsubmit = vi.fn(async () => {
+            attempt++;
+            if (attempt === 1)
+                return undefined;
+            if (attempt === 2)
+                return false;
+            throw new Error('persistence failed');
+        });
+        const reportUsage = vi.fn();
+        render(ObjectFormActionsFixture, {
+            props: { fields, policy, onsubmit, usageReporter: { reportUsage } },
+        });
+        await userEvent.type(screen.getByRole('textbox', { name: 'Name' }), 'Deluxe');
+        const submit = screen.getByRole('button', { name: 'Save product' });
+        await userEvent.click(submit);
+        await userEvent.click(submit);
+        await userEvent.click(submit);
+        await vi.waitFor(() => expect(onsubmit).toHaveBeenCalledTimes(3));
+        expect(reportUsage).not.toHaveBeenCalled();
+        const metadata = screen.getByRole('textbox', {
+            name: 'Metadata',
+        });
+        metadata.value = '{not json}';
+        await fireEvent.input(metadata);
+        await userEvent.click(submit);
+        expect(onsubmit).toHaveBeenCalledTimes(3);
+        expect(reportUsage).not.toHaveBeenCalled();
+    });
     it('is axe-clean for its generated basic form', async () => {
         const { container } = render(ObjectFormFixture, {
             props: { fields, policy },

package/dist/svelte/__tests__/UsageLearning.test.js

@@ -0,0 +1,140 @@
+// @vitest-environment jsdom
+import { expectNoA11yViolations, render, screen, userEvent, } from '@happyvertical/smrt-vitest/svelte';
+import { describe, expect, it, vi } from 'vitest';
+import FieldPolicySuggestionQueue from '../components/FieldPolicySuggestionQueue.svelte';
+import { parsePendingFieldPolicySuggestions, } from '../suggestions.js';
+import { collectFieldUsageEntries, reportFieldUsage, } from '../usage-capture.js';
+import SuggestionGearFixture from './fixtures/SuggestionGearFixture.svelte';
+const pending = {
+    suggestions: [
+        {
+            id: 'suggestion-1',
+            objectRef: '@test:Widget',
+            fieldName: 'status',
+            kind: 'promote',
+            proposedValue: null,
+            evidence: { summary: '6 users set this field 12 times.' },
+            status: 'pending',
+        },
+    ],
+    total: 1,
+};
+function suggestionAdapter() {
+    return {
+        pendingSuggestions: vi.fn(async () => pending),
+        acceptSuggestion: vi.fn(async () => undefined),
+        dismissSuggestion: vi.fn(async () => undefined),
+    };
+}
+const editorAdapter = {
+    load: async () => ({
+        capabilities: { manage: true, personalize: false },
+        personalLowerDefaultUsable: {},
+        policy: { objectRef: '@test:Widget', fields: {}, layers: {} },
+        rows: { app: [], tenant: [], user: [] },
+    }),
+    create: async () => undefined,
+    update: async () => undefined,
+    delete: async () => undefined,
+};
+describe('field usage capture', () => {
+    it('keeps free-form values out of browser telemetry while retaining count signals', () => {
+        expect(collectFieldUsageEntries({
+            objectRef: '@test:Widget',
+            fields: {
+                title: 'text',
+                enabled: 'boolean',
+                count: 'integer',
+                ownerId: 'foreignKey',
+                metadata: 'json',
+            },
+            values: {
+                title: 'A title',
+                enabled: false,
+                count: 0,
+                ownerId: '4f552b7e-88a4-499a-9ce4-6a88bec3b439',
+                metadata: { email: 'member@example.test' },
+                omitted: 'not rendered',
+            },
+            defaults: {
+                title: { hasDefault: true, defaultValue: 'A title' },
+                count: { hasDefault: true, defaultValue: 1 },
+                metadata: {
+                    hasDefault: true,
+                    defaultValue: { email: 'member@example.test' },
+                },
+            },
+        })).toEqual([
+            {
+                objectRef: '@test:Widget',
+                fieldName: 'title',
+                matchedDefault: true,
+            },
+            { objectRef: '@test:Widget', fieldName: 'enabled', value: false },
+            { objectRef: '@test:Widget', fieldName: 'count' },
+            {
+                objectRef: '@test:Widget',
+                fieldName: 'ownerId',
+                value: '4f552b7e-88a4-499a-9ce4-6a88bec3b439',
+            },
+            {
+                objectRef: '@test:Widget',
+                fieldName: 'metadata',
+                matchedDefault: true,
+            },
+        ]);
+    });
+    it('contains synchronous and asynchronous reporter failures outside the submit path', async () => {
+        const sync = {
+            reportUsage: () => {
+                throw new Error('offline');
+            },
+        };
+        const rejected = {
+            reportUsage: async () => {
+                throw new Error('offline');
+            },
+        };
+        expect(() => reportFieldUsage(sync, [
+            { objectRef: '@test:Widget', fieldName: 'title' },
+        ])).not.toThrow();
+        expect(() => reportFieldUsage(rejected, [
+            { objectRef: '@test:Widget', fieldName: 'title' },
+        ])).not.toThrow();
+        await Promise.resolve();
+    });
+});
+describe('field policy suggestion review', () => {
+    it('fails closed for malformed generated-action output', () => {
+        expect(() => parsePendingFieldPolicySuggestions({ suggestions: [], total: '1' })).toThrow(/Unable to load pending/i);
+        expect(() => parsePendingFieldPolicySuggestions({
+            suggestions: [{ id: 'missing fields' }],
+            total: 1,
+        })).toThrow(/Unable to load pending/i);
+    });
+    it('renders an accessible reviewed queue and refreshes after approve or dismiss', async () => {
+        const adapter = suggestionAdapter();
+        const { container } = render(FieldPolicySuggestionQueue, {
+            props: { adapter, objectRefs: ['@test:Widget'] },
+        });
+        await vi.waitFor(() => expect(screen.getByText(/6 users set/i)).toBeVisible());
+        expect(screen.getByRole('heading', { name: 'Pending field suggestions' })).toBeVisible();
+        await userEvent.click(screen.getByRole('button', { name: 'Approve' }));
+        await vi.waitFor(() => expect(adapter.acceptSuggestion).toHaveBeenCalledWith({
+            id: 'suggestion-1',
+        }));
+        expect(adapter.pendingSuggestions).toHaveBeenCalledWith({
+            objectRefs: ['@test:Widget'],
+        });
+        await expectNoA11yViolations(container);
+    });
+    it('announces a pending-suggestion count on the policy gear without exposing suggestion details', async () => {
+        render(SuggestionGearFixture, {
+            props: { adapter: editorAdapter, suggestionAdapter: suggestionAdapter() },
+        });
+        await vi.waitFor(() => expect(screen.getByRole('button', {
+            name: 'Field settings, 1 pending suggestion',
+        })).toBeVisible());
+        expect(screen.getByText('1')).toHaveAttribute('aria-hidden', 'true');
+    });
+});

package/dist/svelte/__tests__/fixtures/ObjectFormActionsFixture.svelte

@@ -1,19 +1,36 @@
 <script lang="ts">
 import type { ResolvedObjectFieldPolicy } from '../../../types.js';
-import ObjectForm from '../../components/ObjectForm.svelte';
+import ObjectForm, {
+  type ObjectFormProps,
+} from '../../components/ObjectForm.svelte';
 import type { ObjectFormFieldDefinition } from '../../types.js';
+import type { FieldUsageReporter } from '../../usage-capture.js';
 
 interface Props {
   fields: Record<string, ObjectFormFieldDefinition>;
   policy: ResolvedObjectFieldPolicy;
-  onsubmit: (event: SubmitEvent) => void;
+  onsubmit: NonNullable<ObjectFormProps['onsubmit']>;
+  usageReporter?: FieldUsageReporter;
+  resetAfterSuccessfulSubmit?: boolean;
 }
 
-let { fields, policy, onsubmit }: Props = $props();
+let {
+  fields,
+  policy,
+  onsubmit,
+  usageReporter,
+  resetAfterSuccessfulSubmit = false,
+}: Props = $props();
 let record = $state<Record<string, unknown>>({});
+
+async function submit(event: SubmitEvent): Promise<boolean | undefined> {
+  const result = await onsubmit(event);
+  if (result === true && resetAfterSuccessfulSubmit) record = {};
+  return result === true ? true : undefined;
+}
 </script>
 
-<ObjectForm objectRef={policy.objectRef} {fields} {policy} bind:value={record} {onsubmit}>
+<ObjectForm objectRef={policy.objectRef} {fields} {policy} bind:value={record} onsubmit={submit} {usageReporter}>
   {#snippet actions()}
     <button type="submit">Save product</button>
   {/snippet}

package/dist/svelte/__tests__/fixtures/ObjectFormActionsFixture.svelte.d.ts

@@ -1,9 +1,13 @@
 import type { ResolvedObjectFieldPolicy } from '../../../types.js';
+import { type ObjectFormProps } from '../../components/ObjectForm.svelte';
 import type { ObjectFormFieldDefinition } from '../../types.js';
+import type { FieldUsageReporter } from '../../usage-capture.js';
 interface Props {
     fields: Record<string, ObjectFormFieldDefinition>;
     policy: ResolvedObjectFieldPolicy;
-    onsubmit: (event: SubmitEvent) => void;
+    onsubmit: NonNullable<ObjectFormProps['onsubmit']>;
+    usageReporter?: FieldUsageReporter;
+    resetAfterSuccessfulSubmit?: boolean;
 }
 declare const ObjectFormActionsFixture: import("svelte").Component<Props, {}, "">;
 type ObjectFormActionsFixture = ReturnType<typeof ObjectFormActionsFixture>;

package/dist/svelte/__tests__/fixtures/ObjectFormActionsFixture.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ObjectFormActionsFixture.svelte.d.ts","sourceRoot":"","sources":["../../../../src/svelte/__tests__/fixtures/ObjectFormActionsFixture.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAEnE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAGhE,UAAU,KAAK;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;IAClD,MAAM,EAAE,yBAAyB,CAAC;IAClC,QAAQ,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;CACxC;AAmBD,QAAA,MAAM,wBAAwB,2CAAwC,CAAC;AACvE,KAAK,wBAAwB,GAAG,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC5E,eAAe,wBAAwB,CAAC"}
+{"version":3,"file":"ObjectFormActionsFixture.svelte.d.ts","sourceRoot":"","sources":["../../../../src/svelte/__tests__/fixtures/ObjectFormActionsFixture.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAmB,EACjB,KAAK,eAAe,EACrB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAGjE,UAAU,KAAK;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;IAClD,MAAM,EAAE,yBAAyB,CAAC;IAClC,QAAQ,EAAE,WAAW,CAAC,eAAe,CAAC,UAAU,CAAC,CAAC,CAAC;IACnD,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,0BAA0B,CAAC,EAAE,OAAO,CAAC;CACtC;AAgCD,QAAA,MAAM,wBAAwB,2CAAwC,CAAC;AACvE,KAAK,wBAAwB,GAAG,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC5E,eAAe,wBAAwB,CAAC"}

package/dist/svelte/__tests__/fixtures/SuggestionGearFixture.svelte

@@ -0,0 +1,23 @@
+<script lang="ts">
+import FieldPolicyGearButton from '../../components/FieldPolicyGearButton.svelte';
+import FieldPolicyGearProvider from '../../components/FieldPolicyGearProvider.svelte';
+import type { FieldPolicyEditorAdapter } from '../../field-policy-editor.js';
+import type { FieldPolicySuggestionAdapter } from '../../suggestions.js';
+
+let {
+  adapter,
+  suggestionAdapter,
+}: {
+  adapter: FieldPolicyEditorAdapter;
+  suggestionAdapter: FieldPolicySuggestionAdapter;
+} = $props();
+</script>
+
+<FieldPolicyGearProvider
+  objectRef="@test:Widget"
+  fields={{ title: { type: 'text' } }}
+  {adapter}
+  {suggestionAdapter}
+>
+  <FieldPolicyGearButton />
+</FieldPolicyGearProvider>

package/dist/svelte/__tests__/fixtures/SuggestionGearFixture.svelte.d.ts

@@ -0,0 +1,10 @@
+import type { FieldPolicyEditorAdapter } from '../../field-policy-editor.js';
+import type { FieldPolicySuggestionAdapter } from '../../suggestions.js';
+type $$ComponentProps = {
+    adapter: FieldPolicyEditorAdapter;
+    suggestionAdapter: FieldPolicySuggestionAdapter;
+};
+declare const SuggestionGearFixture: import("svelte").Component<$$ComponentProps, {}, "">;
+type SuggestionGearFixture = ReturnType<typeof SuggestionGearFixture>;
+export default SuggestionGearFixture;
+//# sourceMappingURL=SuggestionGearFixture.svelte.d.ts.map

package/dist/svelte/__tests__/fixtures/SuggestionGearFixture.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SuggestionGearFixture.svelte.d.ts","sourceRoot":"","sources":["../../../../src/svelte/__tests__/fixtures/SuggestionGearFixture.svelte.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAC7E,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAC;AAExE,KAAK,gBAAgB,GAAI;IACxB,OAAO,EAAE,wBAAwB,CAAC;IAClC,iBAAiB,EAAE,4BAA4B,CAAC;CACjD,CAAC;AAmBF,QAAA,MAAM,qBAAqB,sDAAwC,CAAC;AACpE,KAAK,qBAAqB,GAAG,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACtE,eAAe,qBAAqB,CAAC"}

package/dist/svelte/__tests__/playground.test.js

@@ -0,0 +1,66 @@
+// @vitest-environment jsdom
+/**
+ * Playground smoke tests (#2272).
+ *
+ * Registering `@happyvertical/smrt-fields/playground` publishes EVERY entry in
+ * the module, and `PlaygroundHost` mounts the selected one bare — no
+ * `<svelte:boundary>` around it. So a preview that throws on mount is not a
+ * contained failure the host can route around; a host cannot offer the sound
+ * entry without also offering one that breaks the page.
+ *
+ * That is exactly how #2272 shipped: the `Policy-Driven Form` preview rendered
+ * `<FormHelp>` outside its `<FieldPolicyProvider>`, and no unit test could see
+ * it, because `FormHelp`'s own tests always mount it through a provider
+ * fixture — they exercise the component's contract, never the preview's
+ * composition.
+ *
+ * These tests therefore load and MOUNT every exported entry the way
+ * `PlaygroundHost` does — one mount per declared mode, with the entry props and
+ * mode props merged (`PlaygroundHost.svelte`). Nothing wraps the component, so
+ * a preview that needs an ancestor provider must supply its own.
+ *
+ * Structural types below: this package must not depend on
+ * `@happyvertical/smrt-playground`, so the module shape is asserted, not
+ * imported.
+ */
+import { cleanup, render } from '@happyvertical/smrt-vitest/svelte';
+import { afterEach, describe, expect, it } from 'vitest';
+import playground from '../playground.js';
+const entries = playground.entries;
+afterEach(() => {
+    cleanup();
+});
+describe('smrt-fields playground module', () => {
+    it('publishes the field-policy previews', () => {
+        expect(playground.packageName).toBe('@happyvertical/smrt-fields');
+        expect(entries.map((entry) => entry.id)).toEqual([
+            'policy-form',
+            'object-form',
+        ]);
+        for (const entry of entries) {
+            expect(entry.loadComponent).toEqual(expect.any(Function));
+            expect(entry.modes).toHaveProperty('mock');
+        }
+    });
+    // One case per entry/mode so a failure names the broken preview.
+    for (const entry of entries) {
+        for (const [mode, config] of Object.entries(entry.modes ?? {})) {
+            it(`mounts the "${entry.title}" preview in ${mode} mode`, async () => {
+                const loaded = await entry.loadComponent();
+                const component = typeof loaded === 'function'
+                    ? loaded
+                    : loaded.default;
+                expect(component).toEqual(expect.any(Function));
+                // Mirror PlaygroundHost: entry props, then mode props. Nothing else.
+                const props = {
+                    ...(entry.props ?? {}),
+                    ...(config === true ? {} : (config.props ?? {})),
+                };
+                const { container } = render(component, {
+                    props: props,
+                });
+                expect(container.textContent?.trim()).not.toBe('');
+            });
+        }
+    }
+});

package/dist/svelte/components/FieldPolicyControlPanel.svelte

@@ -29,7 +29,9 @@ import {
   orgRowIdsForObject,
   prunableDriftRows,
 } from '../settings-catalog.js';
+import type { FieldPolicySuggestionAdapter } from '../suggestions.js';
 import FieldPolicyEditor from './FieldPolicyEditor.svelte';
+import FieldPolicySuggestionQueue from './FieldPolicySuggestionQueue.svelte';
 
 export interface FieldPolicyCatalogComponentProps {
   page: FieldPolicySettingsCatalogPage;
@@ -48,6 +50,8 @@ export interface FieldPolicyControlPanelProps {
   heading?: string;
   onchanged?: () => void;
   confirmAction?: (message: string) => boolean | Promise<boolean>;
+  /** Optional reviewed-suggestion queue transport. */
+  suggestionAdapter?: FieldPolicySuggestionAdapter;
 }
 
 let {
@@ -59,6 +63,7 @@ let {
   heading = 'Field settings',
   onchanged,
   confirmAction,
+  suggestionAdapter,
 }: FieldPolicyControlPanelProps = $props();
 
 // Before client effects run (including SSR), render the server snapshot.
@@ -70,6 +75,7 @@ let loadingEditor = $state(false);
 let busy = $state(false);
 let error = $state<string | null>(null);
 let generation = 0;
+let auditGeneration = 0;
 
 const Catalog = $derived(catalog);
 const visibleAudit = $derived(audit ?? data.audit);
@@ -83,6 +89,9 @@ const preservedParams = $derived(fieldPolicyCatalogPreservedParams(data));
 
 $effect(() => {
   data;
+  // A prop snapshot supersedes every in-flight mutation refresh. Without this
+  // invalidation, an older response can overwrite newer SSR/navigation data.
+  auditGeneration++;
   audit = data.audit;
   editorState = null;
   editorOpen = false;
@@ -114,11 +123,15 @@ async function loadEditor(): Promise<void> {
 }
 
 async function refreshAudit(): Promise<boolean> {
+  const token = ++auditGeneration;
   const refs = auditObjectRefs(data.page);
   try {
-    audit = await adapter.loadAudit({ ...refs, includeDrift: true });
+    const refreshed = await adapter.loadAudit({ ...refs, includeDrift: true });
+    if (token !== auditGeneration) return false;
+    audit = refreshed;
     return true;
   } catch (cause) {
+    if (token !== auditGeneration) return false;
     error =
       cause instanceof Error
         ? cause.message
@@ -195,6 +208,13 @@ function valueText(cell: FieldPolicyLayerCell): string {
     return String(cell.defaultValue);
   }
 }
+
+async function suggestionChanged(): Promise<void> {
+  if (await refreshAudit()) {
+    await loadEditor();
+    onchanged?.();
+  }
+}
 </script>
 
 {#if canManage}
@@ -234,6 +254,13 @@ function valueText(cell: FieldPolicyLayerCell): string {
         onmutated={editorMutated}
       />
     {/if}
+    {#if suggestionAdapter}
+      <FieldPolicySuggestionQueue
+        adapter={suggestionAdapter}
+        objectRefs={auditObjectRefs(data.page).objectRefs}
+        onchanged={suggestionChanged}
+      />
+    {/if}
     {#if prunableDriftRows(visibleAudit).length}
       <section class="field-policy-control-panel__drift" aria-label="Manifest drift">
         <h2>Manifest drift</h2>

package/dist/svelte/components/FieldPolicyControlPanel.svelte.d.ts

@@ -1,6 +1,7 @@
 import type { Component, Snippet } from 'svelte';
 import type { FieldPolicyDetailItem, FieldPolicySettingsCatalogData, FieldPolicySettingsCatalogPage } from '../../settings-catalog.js';
 import { type FieldPolicyControlPanelAdapter } from '../settings-catalog.js';
+import type { FieldPolicySuggestionAdapter } from '../suggestions.js';
 export interface FieldPolicyCatalogComponentProps {
     page: FieldPolicySettingsCatalogPage;
     baseUrl: string;
@@ -19,6 +20,8 @@ export interface FieldPolicyControlPanelProps {
     heading?: string;
     onchanged?: () => void;
     confirmAction?: (message: string) => boolean | Promise<boolean>;
+    /** Optional reviewed-suggestion queue transport. */
+    suggestionAdapter?: FieldPolicySuggestionAdapter;
 }
 declare const FieldPolicyControlPanel: Component<FieldPolicyControlPanelProps, {}, "">;
 type FieldPolicyControlPanel = ReturnType<typeof FieldPolicyControlPanel>;

package/dist/svelte/components/FieldPolicyControlPanel.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FieldPolicyControlPanel.svelte.d.ts","sourceRoot":"","sources":["../../../src/svelte/components/FieldPolicyControlPanel.svelte.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,KAAK,EACV,qBAAqB,EACrB,8BAA8B,EAC9B,8BAA8B,EAC/B,MAAM,2BAA2B,CAAC;AASnC,OAAO,EAGL,KAAK,8BAA8B,EAMpC,MAAM,wBAAwB,CAAC;AAIhC,MAAM,WAAW,gCAAgC;IAC/C,IAAI,EAAE,8BAA8B,CAAC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC,CAAC;QAAE,IAAI,EAAE,qBAAqB,CAAA;KAAE,CAAC,CAAC,CAAC;IACnD,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,8BAA8B,CAAC;IACrC,OAAO,EAAE,8BAA8B,CAAC;IACxC,OAAO,EAAE,SAAS,CAAC,gCAAgC,CAAC,CAAC;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjE;AAiND,QAAA,MAAM,uBAAuB,iDAAwC,CAAC;AACtE,KAAK,uBAAuB,GAAG,UAAU,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAC1E,eAAe,uBAAuB,CAAC"}
+{"version":3,"file":"FieldPolicyControlPanel.svelte.d.ts","sourceRoot":"","sources":["../../../src/svelte/components/FieldPolicyControlPanel.svelte.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,KAAK,EACV,qBAAqB,EACrB,8BAA8B,EAC9B,8BAA8B,EAC/B,MAAM,2BAA2B,CAAC;AASnC,OAAO,EAGL,KAAK,8BAA8B,EAMpC,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,mBAAmB,CAAC;AAKtE,MAAM,WAAW,gCAAgC;IAC/C,IAAI,EAAE,8BAA8B,CAAC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC,CAAC;QAAE,IAAI,EAAE,qBAAqB,CAAA;KAAE,CAAC,CAAC,CAAC;IACnD,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,8BAA8B,CAAC;IACrC,OAAO,EAAE,8BAA8B,CAAC;IACxC,OAAO,EAAE,SAAS,CAAC,gCAAgC,CAAC,CAAC;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAChE,oDAAoD;IACpD,iBAAiB,CAAC,EAAE,4BAA4B,CAAC;CAClD;AAsOD,QAAA,MAAM,uBAAuB,iDAAwC,CAAC;AACtE,KAAK,uBAAuB,GAAG,UAAU,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAC1E,eAAe,uBAAuB,CAAC"}

package/dist/svelte/components/FieldPolicyGearButton.svelte

@@ -10,8 +10,15 @@ const gear = getFieldPolicyGearContext();
 </script>
 
 {#if gear.canEdit}
-  <Button type="button" variant="ghost" class={className} aria-haspopup="dialog" onclick={() => gear.show()}>
+  <Button type="button" variant="ghost" class={className} aria-haspopup="dialog" aria-label={gear.pendingSuggestionCount > 0 ? `${label}, ${gear.pendingSuggestionCount} pending suggestion${gear.pendingSuggestionCount === 1 ? '' : 's'}` : label} onclick={() => gear.show()}>
     <span aria-hidden="true">⚙</span>
     <span>{label}</span>
+    {#if gear.pendingSuggestionCount > 0}
+      <span class="field-policy-gear-button__badge" aria-hidden="true">{gear.pendingSuggestionCount}</span>
+    {/if}
   </Button>
 {/if}
+
+<style>
+  .field-policy-gear-button__badge { border-radius: 999px; background: var(--smrt-color-secondary-container, #e8def8); min-inline-size: 1.25rem; padding-inline: 0.25rem; text-align: center; }
+</style>

package/dist/svelte/components/FieldPolicyGearButton.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FieldPolicyGearButton.svelte.d.ts","sourceRoot":"","sources":["../../../src/svelte/components/FieldPolicyGearButton.svelte.ts"],"names":[],"mappings":"AAMC,KAAK,gBAAgB,GAAI;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAqB7D,QAAA,MAAM,qBAAqB,sDAAwC,CAAC;AACpE,KAAK,qBAAqB,GAAG,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACtE,eAAe,qBAAqB,CAAC"}
+{"version":3,"file":"FieldPolicyGearButton.svelte.d.ts","sourceRoot":"","sources":["../../../src/svelte/components/FieldPolicyGearButton.svelte.ts"],"names":[],"mappings":"AAMC,KAAK,gBAAgB,GAAI;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AA0B7D,QAAA,MAAM,qBAAqB,sDAAwC,CAAC;AACpE,KAAK,qBAAqB,GAAG,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACtE,eAAe,qBAAqB,CAAC"}

package/dist/svelte/components/FieldPolicyGearProvider.svelte

@@ -12,6 +12,10 @@ import {
   setFieldPolicyGearContext,
 } from '../gear-context.svelte.js';
 import type { FieldInputRegistry } from '../input-registry.js';
+import {
+  type FieldPolicySuggestionAdapter,
+  parsePendingFieldPolicySuggestions,
+} from '../suggestions.js';
 import type { ObjectFormFieldDefinition } from '../types.js';
 import FieldPolicyEditor from './FieldPolicyEditor.svelte';
 
@@ -22,6 +26,8 @@ interface Props {
   inputRegistry?: FieldInputRegistry;
   /** Hosts in an app-wide context pass app; tenant hosts retain the default. */
   organizationScope?: FieldPolicyOrganizationScope;
+  /** Optional reviewed-suggestion transport for the gear badge. */
+  suggestionAdapter?: FieldPolicySuggestionAdapter;
   children?: Snippet;
 }
 
@@ -31,6 +37,7 @@ let {
   adapter,
   inputRegistry,
   organizationScope = 'tenant',
+  suggestionAdapter,
   children,
 }: Props = $props();
 
@@ -38,6 +45,7 @@ let editorState = $state<FieldPolicyEditorState | null>(null);
 let error = $state<string | null>(null);
 let open = $state(false);
 let loading = $state(false);
+let pendingSuggestionCount = $state(0);
 
 const controller: FieldPolicyGearController = {
   get state() {
@@ -55,6 +63,9 @@ const controller: FieldPolicyGearController = {
       (editorState.capabilities.manage || editorState.capabilities.personalize)
     );
   },
+  get pendingSuggestionCount() {
+    return pendingSuggestionCount;
+  },
   show() {
     if (this.canEdit) open = true;
   },
@@ -104,16 +115,39 @@ async function reload(generation = ++loadGeneration): Promise<void> {
   }
 }
 
+async function reloadPendingSuggestions(
+  generation = ++suggestionGeneration,
+): Promise<void> {
+  if (!suggestionAdapter) {
+    pendingSuggestionCount = 0;
+    return;
+  }
+  try {
+    const result = parsePendingFieldPolicySuggestions(
+      await suggestionAdapter.pendingSuggestions({ objectRefs: [objectRef] }),
+    );
+    if (generation === suggestionGeneration) {
+      pendingSuggestionCount = result.total;
+    }
+  } catch {
+    // A metrics/read failure must not suppress ordinary policy editing.
+    if (generation === suggestionGeneration) pendingSuggestionCount = 0;
+  }
+}
+
 let loadGeneration = 0;
+let suggestionGeneration = 0;
 $effect(() => {
   const generation = ++loadGeneration;
   editorState = null;
   error = null;
   open = false;
   void reload(generation);
+  void reloadPendingSuggestions();
   return () => {
     // A delayed transport response must never repopulate a prior object.
     if (loadGeneration === generation) loadGeneration++;
+    suggestionGeneration++;
   };
 });
 </script>