@happyvertical/smrt-fields 0.40.60 → 0.40.62

package/dist/svelte/components/FieldPolicyProvider.svelte

@@ -0,0 +1,89 @@
+<script lang="ts">
+/**
+ * FieldPolicyProvider — the form-level entry point for policy-driven forms.
+ *
+ * Receives a resolved {@link ResolvedObjectFieldPolicy} **as props** (SSR
+ * `initialData` or a client fetch by the app). Owns mode state (`basic`/
+ * `advanced`) and publishes the reactive context consumed by `PolicyField`,
+ * `ModeSwitch`, `AdvancedFields`, and `FormHelp`.
+ *
+ * No `smrt-web` import in the core primitive — an optional `./web` adapter can
+ * wire live invalidation for apps that want it; this component is policy-source
+ * agnostic.
+ *
+ * SSR seeding: props seed `$state` via `untrack()` so the first render reflects
+ * the request, with a client-only `$effect` resync — the same pattern as
+ * ThemeProvider (`smrt-ui/src/themes/ThemeProvider.svelte:53-70`).
+ */
+
+import type { Snippet } from 'svelte';
+import { untrack } from 'svelte';
+import type {
+  ResolvedFieldPolicy,
+  ResolvedObjectFieldPolicy,
+} from '../../types.js';
+import {
+  type FieldPolicyContextValue,
+  type FieldPolicyMode,
+  FieldPolicyModeStore,
+  setFieldPolicyContext,
+} from '../context.svelte.js';
+
+export interface Props {
+  /**
+   * Pre-resolved field policy for the object. Pass the output of
+   * `resolveFieldPolicy()` (server-side) or the `resolveBatch` endpoint
+   * response (client-side).
+   */
+  policy: ResolvedObjectFieldPolicy;
+  /** Initial display mode — 'basic' hides advanced-tier fields. */
+  mode?: FieldPolicyMode;
+  /** Children rendered inside the provider. */
+  children?: Snippet;
+}
+
+let { policy, mode: modeProp = 'basic', children }: Props = $props();
+
+// --- Reactive mode state (owned by the provider component) ---
+// Using a class with $state fields: Svelte 5 tracks class field reactivity
+// correctly across the context boundary (the class instance is the reactive
+// root, not a component closure variable).
+// Seed via untrack() so the first SSR/client render reflects the requested
+// mode; the $effect below resyncs later prop changes (ThemeProvider precedent).
+const modeStore = new FieldPolicyModeStore(untrack(() => modeProp));
+
+$effect(() => {
+  modeStore.set(modeProp);
+});
+
+// --- Resolved field lookup (reactive over policy prop changes) ---
+function getField(fieldName: string): ResolvedFieldPolicy | undefined {
+  return policy.fields[fieldName];
+}
+
+// --- Advanced field count for the disclosure label ---
+const advancedFieldCount = $derived.by(() => {
+  let count = 0;
+  for (const field of Object.values(policy.fields)) {
+    if (field.visibility === 'advanced') {
+      count++;
+    }
+  }
+  return count;
+});
+
+const context: FieldPolicyContextValue = {
+  get policy() {
+    return policy;
+  },
+  mode: modeStore,
+  getField,
+  get advancedFieldCount() {
+    return advancedFieldCount;
+  },
+};
+
+setFieldPolicyContext(context);
+</script>
+
+{@render children?.()}

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

@@ -0,0 +1,35 @@
+/**
+ * FieldPolicyProvider — the form-level entry point for policy-driven forms.
+ *
+ * Receives a resolved {@link ResolvedObjectFieldPolicy} **as props** (SSR
+ * `initialData` or a client fetch by the app). Owns mode state (`basic`/
+ * `advanced`) and publishes the reactive context consumed by `PolicyField`,
+ * `ModeSwitch`, `AdvancedFields`, and `FormHelp`.
+ *
+ * No `smrt-web` import in the core primitive — an optional `./web` adapter can
+ * wire live invalidation for apps that want it; this component is policy-source
+ * agnostic.
+ *
+ * SSR seeding: props seed `$state` via `untrack()` so the first render reflects
+ * the request, with a client-only `$effect` resync — the same pattern as
+ * ThemeProvider (`smrt-ui/src/themes/ThemeProvider.svelte:53-70`).
+ */
+import type { Snippet } from 'svelte';
+import type { ResolvedObjectFieldPolicy } from '../../types.js';
+import { type FieldPolicyMode } from '../context.svelte.js';
+export interface Props {
+    /**
+     * Pre-resolved field policy for the object. Pass the output of
+     * `resolveFieldPolicy()` (server-side) or the `resolveBatch` endpoint
+     * response (client-side).
+     */
+    policy: ResolvedObjectFieldPolicy;
+    /** Initial display mode — 'basic' hides advanced-tier fields. */
+    mode?: FieldPolicyMode;
+    /** Children rendered inside the provider. */
+    children?: Snippet;
+}
+declare const FieldPolicyProvider: import("svelte").Component<Props, {}, "">;
+type FieldPolicyProvider = ReturnType<typeof FieldPolicyProvider>;
+export default FieldPolicyProvider;
+//# sourceMappingURL=FieldPolicyProvider.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FieldPolicyProvider.svelte.d.ts","sourceRoot":"","sources":["../../../src/svelte/components/FieldPolicyProvider.svelte.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,KAAK,EAEV,yBAAyB,EAC1B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAEL,KAAK,eAAe,EAGrB,MAAM,sBAAsB,CAAC;AAG9B,MAAM,WAAW,KAAK;IACpB;;;;OAIG;IACH,MAAM,EAAE,yBAAyB,CAAC;IAClC,iEAAiE;IACjE,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AA0DD,QAAA,MAAM,mBAAmB,2CAAwC,CAAC;AAClE,KAAK,mBAAmB,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAClE,eAAe,mBAAmB,CAAC"}

package/dist/svelte/components/FieldPolicySuggestionQueue.svelte

@@ -0,0 +1,135 @@
+<script lang="ts">
+/** Accessible, host-transport-neutral review queue for pending suggestions. */
+import { Button } from '@happyvertical/smrt-ui/ui';
+import {
+  type FieldPolicySuggestion,
+  type FieldPolicySuggestionAdapter,
+  fieldPolicySuggestionEvidence,
+  parsePendingFieldPolicySuggestions,
+} from '../suggestions.js';
+
+export interface FieldPolicySuggestionQueueProps {
+  adapter: FieldPolicySuggestionAdapter;
+  objectRefs?: readonly string[];
+  heading?: string;
+  onchanged?: () => void;
+}
+
+let {
+  adapter,
+  objectRefs,
+  heading = 'Pending field suggestions',
+  onchanged,
+}: FieldPolicySuggestionQueueProps = $props();
+
+let suggestions = $state<FieldPolicySuggestion[]>([]);
+let total = $state(0);
+let loading = $state(false);
+let busyId = $state<string | null>(null);
+let error = $state<string | null>(null);
+let generation = 0;
+
+async function load(): Promise<void> {
+  const token = ++generation;
+  loading = true;
+  error = null;
+  try {
+    const result = parsePendingFieldPolicySuggestions(
+      await adapter.pendingSuggestions(
+        objectRefs?.length ? { objectRefs } : undefined,
+      ),
+    );
+    if (token !== generation) return;
+    suggestions = result.suggestions;
+    total = result.total;
+  } catch (cause) {
+    if (token !== generation) return;
+    suggestions = [];
+    total = 0;
+    error =
+      cause instanceof Error
+        ? cause.message
+        : 'Unable to load pending field suggestions.';
+  } finally {
+    if (token === generation) loading = false;
+  }
+}
+
+async function decide(
+  suggestion: FieldPolicySuggestion,
+  decision: 'approve' | 'dismiss',
+): Promise<void> {
+  if (busyId) return;
+  busyId = suggestion.id;
+  error = null;
+  try {
+    if (decision === 'approve') {
+      await adapter.acceptSuggestion({ id: suggestion.id });
+    } else {
+      await adapter.dismissSuggestion({ id: suggestion.id });
+    }
+    await load();
+    onchanged?.();
+  } catch (cause) {
+    error =
+      cause instanceof Error
+        ? cause.message
+        : 'Unable to update this field suggestion.';
+  } finally {
+    busyId = null;
+  }
+}
+
+$effect(() => {
+  adapter;
+  objectRefs;
+  void load();
+});
+
+function description(suggestion: FieldPolicySuggestion): string {
+  return suggestion.kind === 'promote'
+    ? `Promote ${suggestion.fieldName} to the basic form.`
+    : `Set an organization default for ${suggestion.fieldName}.`;
+}
+</script>
+
+<section class="field-policy-suggestion-queue" aria-label={heading}>
+  <header>
+    <h2>{heading}</h2>
+    {#if !loading}<span class="field-policy-suggestion-queue__count">{total}</span>{/if}
+  </header>
+  {#if loading}
+    <p role="status" aria-live="polite">Loading pending suggestions…</p>
+  {:else if error}
+    <p role="alert">{error}</p>
+  {:else if suggestions.length === 0}
+    <p>No pending field suggestions.</p>
+  {:else}
+    <ul>
+      {#each suggestions as suggestion (suggestion.id)}
+        <li>
+          <article>
+            <h3>{suggestion.objectRef} · {suggestion.fieldName}</h3>
+            <p>{description(suggestion)}</p>
+            <p>{fieldPolicySuggestionEvidence(suggestion)}</p>
+            <div class="field-policy-suggestion-queue__actions">
+              <Button type="button" disabled={busyId !== null} onclick={() => decide(suggestion, 'approve')}>Approve</Button>
+              <Button type="button" variant="ghost" disabled={busyId !== null} onclick={() => decide(suggestion, 'dismiss')}>Dismiss</Button>
+            </div>
+          </article>
+        </li>
+      {/each}
+    </ul>
+  {/if}
+</section>
+
+<style>
+  .field-policy-suggestion-queue { display: grid; gap: var(--smrt-spacing-3, 0.75rem); }
+  .field-policy-suggestion-queue header { align-items: center; display: flex; gap: var(--smrt-spacing-2, 0.5rem); }
+  .field-policy-suggestion-queue h2, .field-policy-suggestion-queue h3 { margin: 0; }
+  .field-policy-suggestion-queue__count { border-radius: 999px; background: var(--smrt-color-secondary-container, #e8def8); min-inline-size: 1.5rem; padding: 0.125rem 0.4rem; text-align: center; }
+  .field-policy-suggestion-queue ul { display: grid; gap: var(--smrt-spacing-3, 0.75rem); list-style: none; margin: 0; padding: 0; }
+  .field-policy-suggestion-queue article { border: 1px solid var(--smrt-color-outline-variant, currentColor); border-radius: var(--smrt-radius-small, 0.25rem); display: grid; gap: var(--smrt-spacing-2, 0.5rem); padding: var(--smrt-spacing-3, 0.75rem); }
+  .field-policy-suggestion-queue article p { margin: 0; }
+  .field-policy-suggestion-queue__actions { display: flex; flex-wrap: wrap; gap: var(--smrt-spacing-2, 0.5rem); }
+</style>

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

@@ -0,0 +1,11 @@
+import { type FieldPolicySuggestionAdapter } from '../suggestions.js';
+export interface FieldPolicySuggestionQueueProps {
+    adapter: FieldPolicySuggestionAdapter;
+    objectRefs?: readonly string[];
+    heading?: string;
+    onchanged?: () => void;
+}
+declare const FieldPolicySuggestionQueue: import("svelte").Component<FieldPolicySuggestionQueueProps, {}, "">;
+type FieldPolicySuggestionQueue = ReturnType<typeof FieldPolicySuggestionQueue>;
+export default FieldPolicySuggestionQueue;
+//# sourceMappingURL=FieldPolicySuggestionQueue.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FieldPolicySuggestionQueue.svelte.d.ts","sourceRoot":"","sources":["../../../src/svelte/components/FieldPolicySuggestionQueue.svelte.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,KAAK,4BAA4B,EAGlC,MAAM,mBAAmB,CAAC;AAG3B,MAAM,WAAW,+BAA+B;IAC9C,OAAO,EAAE,4BAA4B,CAAC;IACtC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAuHD,QAAA,MAAM,0BAA0B,qEAAwC,CAAC;AACzE,KAAK,0BAA0B,GAAG,UAAU,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAChF,eAAe,0BAA0B,CAAC"}

package/dist/svelte/components/FormHelp.svelte

@@ -0,0 +1,157 @@
+<script lang="ts">
+/**
+ * FormHelp — a `?` affordance assembling the object description + per-field
+ * glossary from the manifest (org-overridden text where present).
+ *
+ * Renders a button toggling a details/summary panel listing every visible
+ * field's label and help text — matching PolicyField visibility, so
+ * advanced-tier entries only appear while the provider mode is `advanced` —
+ * plus the object description if provided. The data comes entirely from the
+ * resolved policy — no separate fetch needed.
+ *
+ * Must be used inside a FieldPolicyProvider.
+ */
+import { getFieldPolicyContext } from '../context.svelte.js';
+
+export interface Props {
+  /**
+   * Object-level description (e.g. the SmrtObject class `description`). When
+   * provided, it appears at the top of the help panel.
+   */
+  objectDescription?: string;
+  /** Label for the toggle button. */
+  label?: string;
+  /** Additional class. */
+  class?: string;
+}
+
+let {
+  objectDescription,
+  label = 'Help',
+  class: className = '',
+}: Props = $props();
+
+const context = getFieldPolicyContext();
+
+// Build the glossary: one entry per field that has help text AND is visible
+// in the current mode (advanced-tier entries disappear in basic mode,
+// matching PolicyField visibility), ordered by the resolved `order` when
+// available, then by insertion order.
+const glossary = $derived.by(() => {
+  const entries: Array<{
+    label: string;
+    help: string;
+    order: number;
+  }> = [];
+
+  const mode = context.mode.current;
+  for (const field of Object.values(context.policy.fields)) {
+    if (field.visibility === 'hidden') continue;
+    if (field.visibility === 'advanced' && mode !== 'advanced') continue;
+    const labelText = field.label ?? field.fieldName;
+    if (field.help) {
+      entries.push({
+        label: labelText,
+        help: field.help,
+        order: field.order ?? Number.MAX_SAFE_INTEGER,
+      });
+    }
+  }
+
+  // Stable sort by resolved order
+  entries.sort((a, b) => a.order - b.order);
+  return entries;
+});
+</script>
+
+<details class="form-help {className}">
+  <summary class="form-help__toggle">
+    <span class="form-help__icon" aria-hidden="true">?</span>
+    <span class="form-help__label">{label}</span>
+  </summary>
+  <div class="form-help__panel">
+    {#if objectDescription}
+      <p class="form-help__description">{objectDescription}</p>
+    {/if}
+    {#if glossary.length > 0}
+      <dl class="form-help__glossary">
+        {#each glossary as entry}
+          <dt class="form-help__term">{entry.label}</dt>
+          <dd class="form-help__definition">{entry.help}</dd>
+        {/each}
+      </dl>
+    {:else}
+      <p class="form-help__empty">No field help available.</p>
+    {/if}
+  </div>
+</details>
+
+<style>
+  .form-help {
+    display: inline-block;
+  }
+
+  .form-help__toggle {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--smrt-spacing-1, 0.25rem);
+    cursor: pointer;
+    list-style: none;
+    font: var(--smrt-typography-label-medium-font, inherit);
+    color: var(--smrt-color-on-surface-variant, currentColor);
+  }
+
+  .form-help__toggle::-webkit-details-marker {
+    display: none;
+  }
+
+  .form-help__toggle:focus-visible {
+    outline: 2px solid var(--smrt-color-primary, #6750a4);
+    outline-offset: 2px;
+    border-radius: 4px;
+  }
+
+  .form-help__icon {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 1.25em;
+    height: 1.25em;
+    border-radius: 50%;
+    border: 1px solid currentColor;
+    font: var(--smrt-typography-label-small-font, inherit);
+    line-height: 1;
+  }
+
+  .form-help__panel {
+    padding: var(--smrt-spacing-3, 0.75rem) 0;
+    color: var(--smrt-color-on-surface, currentColor);
+  }
+
+  .form-help__description {
+    margin: 0 0 var(--smrt-spacing-2, 0.5rem);
+    font: var(--smrt-typography-body-medium-font, inherit);
+  }
+
+  .form-help__glossary {
+    margin: 0;
+    display: grid;
+    gap: var(--smrt-spacing-1, 0.25rem);
+  }
+
+  .form-help__term {
+    font: var(--smrt-typography-label-medium-font, inherit);
+    font-weight: 600;
+  }
+
+  .form-help__definition {
+    margin: 0 0 var(--smrt-spacing-2, 0.5rem);
+    font: var(--smrt-typography-body-small-font, inherit);
+    color: var(--smrt-color-on-surface-variant, currentColor);
+  }
+
+  .form-help__empty {
+    font: var(--smrt-typography-body-small-font, inherit);
+    color: var(--smrt-color-on-surface-variant, currentColor);
+  }
+</style>

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

@@ -0,0 +1,15 @@
+export interface Props {
+    /**
+     * Object-level description (e.g. the SmrtObject class `description`). When
+     * provided, it appears at the top of the help panel.
+     */
+    objectDescription?: string;
+    /** Label for the toggle button. */
+    label?: string;
+    /** Additional class. */
+    class?: string;
+}
+declare const FormHelp: import("svelte").Component<Props, {}, "">;
+type FormHelp = ReturnType<typeof FormHelp>;
+export default FormHelp;
+//# sourceMappingURL=FormHelp.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FormHelp.svelte.d.ts","sourceRoot":"","sources":["../../../src/svelte/components/FormHelp.svelte.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,KAAK;IACpB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mCAAmC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAuED,QAAA,MAAM,QAAQ,2CAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}

package/dist/svelte/components/ModeSwitch.svelte

@@ -0,0 +1,47 @@
+<script lang="ts">
+/**
+ * ModeSwitch — a Basic/Advanced toggle built on SegmentedControl.
+ *
+ * An optional composition for PolicyField-wrapped forms. Reads and writes the
+ * provider's reactive mode state. Must be used inside a FieldPolicyProvider.
+ *
+ * Uses `@happyvertical/smrt-ui/forms`'s SegmentedControl (exported from there,
+ * not `./ui` — see the plan-review addendum in #2048).
+ */
+
+import type { SegmentedControlOption } from '@happyvertical/smrt-ui/forms';
+import { SegmentedControl } from '@happyvertical/smrt-ui/forms';
+import { getFieldPolicyContext } from '../context.svelte.js';
+
+export interface Props {
+  /** Accessible label for the segmented control. */
+  label?: string;
+  /** Additional class. */
+  class?: string;
+}
+
+let { label = 'View mode', class: className = '' }: Props = $props();
+
+const context = getFieldPolicyContext();
+
+const options: SegmentedControlOption[] = [
+  { value: 'basic', label: 'Basic' },
+  { value: 'advanced', label: 'Advanced' },
+];
+
+function onValueChange(value: string | number): void {
+  // Validate before setting — SegmentedControl hands back `string | number`,
+  // and a stray value must never corrupt the mode state.
+  if (value === 'basic' || value === 'advanced') {
+    context.mode.set(value);
+  }
+}
+</script>
+
+<SegmentedControl
+  {options}
+  {label}
+  value={context.mode.current}
+  onvaluechange={onValueChange}
+  class={className}
+/>

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

@@ -0,0 +1,10 @@
+export interface Props {
+    /** Accessible label for the segmented control. */
+    label?: string;
+    /** Additional class. */
+    class?: string;
+}
+declare const ModeSwitch: import("svelte").Component<Props, {}, "">;
+type ModeSwitch = ReturnType<typeof ModeSwitch>;
+export default ModeSwitch;
+//# sourceMappingURL=ModeSwitch.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ModeSwitch.svelte.d.ts","sourceRoot":"","sources":["../../../src/svelte/components/ModeSwitch.svelte.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,KAAK;IACpB,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA+BD,QAAA,MAAM,UAAU,2CAAwC,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}