@happyvertical/smrt-svelte 0.55.7 → 0.55.9

package/dist/components/overview/WidgetOptionsForm.svelte

@@ -0,0 +1,193 @@
+<script lang="ts">
+/**
+ * WidgetOptionsForm - edits one widget's options (#3727). A widget's options
+ * are plain fields, so this reads like the generated record forms: smrt-ui
+ * form controls driven by the option field descriptors (label, help,
+ * required, type), with the same save/cancel bar. It validates through the
+ * widget's schema (via `onsave`) and shows each problem beside its field.
+ */
+import { Alert } from '@happyvertical/smrt-ui/feedback';
+import {
+  Checkbox,
+  Form,
+  FormActionBar,
+  FormGroup,
+  Input,
+  Select,
+  Textarea,
+} from '@happyvertical/smrt-ui/forms';
+import { useI18n } from '@happyvertical/smrt-ui/i18n';
+import { Button } from '@happyvertical/smrt-ui/ui';
+import { untrack } from 'svelte';
+import { M } from '../../i18n/strings.overview.js';
+import type { WidgetOptionsFormProps } from './grid-types.js';
+import type { OverviewOptions, WidgetOptionField } from './types.js';
+
+let { definition, initial, models, onsave, oncancel }: WidgetOptionsFormProps =
+  $props();
+
+const { t } = useI18n();
+
+const fields = $derived(definition.options);
+
+function seed(): {
+  text: Record<string, string>;
+  flags: Record<string, boolean>;
+} {
+  const text: Record<string, string> = {};
+  const flags: Record<string, boolean> = {};
+  for (const field of definition.options) {
+    const value = initial[field.key];
+    if (field.type === 'boolean') flags[field.key] = value === true;
+    else
+      text[field.key] =
+        value === undefined || value === null ? '' : String(value);
+  }
+  return { text, flags };
+}
+
+const seeded = untrack(seed);
+let text = $state<Record<string, string>>(seeded.text);
+let flags = $state<Record<string, boolean>>(seeded.flags);
+let issues = $state<Record<string, string>>({});
+let failed = $state(false);
+
+function toOptions(): OverviewOptions {
+  const options: OverviewOptions = {};
+  for (const field of fields) {
+    if (field.type === 'boolean') {
+      options[field.key] = flags[field.key] === true;
+      continue;
+    }
+    const raw = text[field.key] ?? '';
+    if (field.type === 'markdown') {
+      options[field.key] = raw;
+    } else if (raw.trim() === '') {
+    } else if (field.type === 'integer' || field.type === 'number') {
+      // NaN is not a primitive option: it fails validation as an invalid type.
+      options[field.key] = Number(raw);
+    } else {
+      options[field.key] = raw.trim();
+    }
+  }
+  return options;
+}
+
+const ISSUE_TEXT: Record<string, string> = {
+  required: M['ui.overview.issue_required'],
+  invalid_type: M['ui.overview.issue_invalid_type'],
+  too_long: M['ui.overview.issue_too_long'],
+  out_of_range: M['ui.overview.issue_out_of_range'],
+  not_in_choices: M['ui.overview.issue_not_in_choices'],
+  invalid_format: M['ui.overview.issue_invalid_format'],
+  not_allowed: M['ui.overview.issue_not_allowed'],
+  unknown_option: M['ui.overview.issue_unknown_option'],
+};
+
+function issueText(code: string): string {
+  return t(ISSUE_TEXT[code] ?? M['ui.overview.issue_invalid_type']);
+}
+
+function submit(): void {
+  const options = toOptions();
+  const problems = onsave(options);
+  if (problems === null) return;
+  const next: Record<string, string> = {};
+  for (const problem of problems) {
+    next[problem.key] ??= issueText(problem.code);
+  }
+  issues = next;
+  failed = true;
+}
+
+const label = (field: WidgetOptionField): string => t(field.label);
+const hint = (field: WidgetOptionField): string | undefined =>
+  field.help ? t(field.help) : undefined;
+const optionalChoice = (field: WidgetOptionField): boolean =>
+  !field.required && (field.default === undefined || field.default === null);
+const modelValues = $derived(
+  new Set((models ?? []).map((model) => model.value)),
+);
+</script>
+
+<Form onsubmit={submit} novalidate>
+  {#if failed}
+    <Alert variant="error">{t(M['ui.overview.options_failed'])}</Alert>
+  {/if}
+  {#if fields.length === 0}
+    <p class="smrt-widget-form__none">{t(M['ui.overview.options_none'])}</p>
+  {/if}
+  {#each fields as field (field.key)}
+    {#if field.type === 'boolean'}
+      <div class="smrt-widget-form__check">
+        <Checkbox
+          name={field.key}
+          label={label(field)}
+          bind:checked={() => flags[field.key] === true, (v) => (flags[field.key] = v)}
+        />
+        {#if hint(field)}<small class="smrt-widget-form__hint">{hint(field)}</small>{/if}
+        {#if issues[field.key]}<small class="smrt-widget-form__error" role="alert">{issues[field.key]}</small>{/if}
+      </div>
+    {:else}
+      <FormGroup label={label(field)} hint={hint(field)} error={issues[field.key]} required={field.required}>
+        {#if field.type === 'markdown'}
+          <Textarea
+            name={field.key}
+            rows={6}
+            bind:value={() => text[field.key] ?? '', (v) => (text[field.key] = v)}
+          />
+        {:else if field.type === 'enum'}
+          <Select
+            name={field.key}
+            bind:value={() => text[field.key] ?? '', (v) => (text[field.key] = v)}
+          >
+            {#if optionalChoice(field)}
+              <option value="">{t(M['ui.overview.options_choose'])}</option>
+            {/if}
+            {#each field.choices ?? [] as choice (choice.value)}
+              <option value={choice.value}>{t(choice.label)}</option>
+            {/each}
+          </Select>
+        {:else if field.type === 'model' && models && models.length > 0}
+          <Select
+            name={field.key}
+            bind:value={() => text[field.key] ?? '', (v) => (text[field.key] = v)}
+          >
+            <option value="">{t(M['ui.overview.options_choose'])}</option>
+            {#if text[field.key] && !modelValues.has(text[field.key])}
+              <option value={text[field.key]}>{text[field.key]}</option>
+            {/if}
+            {#each models as model (model.value)}
+              <option value={model.value}>{model.label}</option>
+            {/each}
+          </Select>
+        {:else}
+          <Input
+            name={field.key}
+            type={field.type === 'integer' || field.type === 'number' ? 'number' : 'text'}
+            step={field.type === 'integer' ? '1' : field.type === 'number' ? 'any' : undefined}
+            min={field.min}
+            max={field.max}
+            maxlength={field.type === 'text' ? (field.maxLength ?? 200) : undefined}
+            bind:value={() => text[field.key] ?? '', (v) => (text[field.key] = String(v))}
+          />
+        {/if}
+      </FormGroup>
+    {/if}
+  {/each}
+  <FormActionBar>
+    <Button type="button" variant="ghost" onclick={oncancel}>
+      {t(M['ui.overview.options_cancel'])}
+    </Button>
+    <Button type="submit" variant="primary">
+      {t(M['ui.overview.options_save'])}
+    </Button>
+  </FormActionBar>
+</Form>
+
+<style>
+  .smrt-widget-form__check { display: flex; flex-direction: column; gap: var(--smrt-spacing-1); }
+  .smrt-widget-form__hint { color: var(--smrt-color-on-surface-variant); }
+  .smrt-widget-form__error { color: var(--smrt-color-error); }
+  .smrt-widget-form__none { margin: 0; color: var(--smrt-color-on-surface-variant); }
+</style>

package/dist/components/overview/WidgetOptionsForm.svelte.d.ts

@@ -0,0 +1,5 @@
+import type { WidgetOptionsFormProps } from './grid-types.js';
+declare const WidgetOptionsForm: import("svelte").Component<WidgetOptionsFormProps, {}, "">;
+type WidgetOptionsForm = ReturnType<typeof WidgetOptionsForm>;
+export default WidgetOptionsForm;
+//# sourceMappingURL=WidgetOptionsForm.svelte.d.ts.map

package/dist/components/overview/WidgetOptionsForm.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WidgetOptionsForm.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/overview/WidgetOptionsForm.svelte.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AA8J9D,QAAA,MAAM,iBAAiB,4DAAwC,CAAC;AAChE,KAAK,iBAAiB,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAC9D,eAAe,iBAAiB,CAAC"}

package/dist/components/overview/controller.svelte.d.ts

@@ -0,0 +1,92 @@
+import { type WidgetRegistry } from './registry.js';
+import type { LoadedOverview, LoadedWidgetErrorCode, OverviewDefinition, OverviewDocument, OverviewIssue, OverviewOptions, OverviewOverride, OverviewWidget, RegisteredWidget, WidgetOptionIssue, WidgetStatus } from './types.js';
+/** Where one widget's data stands. */
+export interface OverviewWidgetEntry {
+    status: WidgetStatus;
+    data?: unknown;
+    error?: LoadedWidgetErrorCode;
+}
+export type OverviewOpResult = {
+    ok: true;
+    id: string;
+} | {
+    ok: false;
+    reason: 'not_allowed' | 'unknown_widget' | 'unknown_type' | 'invalid_options' | 'limit' | 'unchanged';
+    issues?: WidgetOptionIssue[];
+};
+export interface OverviewControllerOptions {
+    definition: OverviewDefinition;
+    /** Defaults to the shared registry. */
+    registry?: WidgetRegistry;
+    /**
+     * The stored override (untrusted JSON; `null` for none). When given the host
+     * is the single source of truth and must feed edits back through it.
+     */
+    override?: () => unknown;
+    /** Receives the canonical override after each edit; `null` = defaults. */
+    onchange?: (override: OverviewOverride | null) => void | Promise<void>;
+    /** Whether the viewer may customize (default true). Hosts derive it from roles. */
+    canCustomize?: () => boolean;
+    /** Data the page's server load already produced; seeds the entries. */
+    loaded?: LoadedOverview | (() => LoadedOverview | undefined);
+    /**
+     * Loads one widget's data after an add or an options change. The host runs
+     * the widget's `load` where its data lives: a remote function or endpoint in
+     * production, the in-browser source in the planner. Must return JSON data.
+     */
+    loadWidget?: (widget: OverviewWidget, signal: AbortSignal) => Promise<unknown>;
+}
+export declare class OverviewController {
+    #private;
+    constructor(options: OverviewControllerOptions);
+    get definition(): OverviewDefinition;
+    get registry(): WidgetRegistry;
+    /** The sanitized document to render. */
+    get document(): OverviewDocument;
+    /** The sanitized defaults. */
+    get base(): OverviewDocument;
+    /** The canonical override currently applied; `null` when on defaults. */
+    get override(): OverviewOverride | null;
+    /** What was dropped or reported while resolving. */
+    get issues(): readonly OverviewIssue[];
+    /** True when the viewer has changed anything from the defaults. */
+    get customized(): boolean;
+    get canCustomize(): boolean;
+    /** Whether another widget fits under the cap. */
+    get full(): boolean;
+    /** Registered widget types this overview allows, in registration order. */
+    get addable(): RegisteredWidget[];
+    /** Data state of a widget (loading while a load is outstanding). */
+    entry(widget: OverviewWidget): OverviewWidgetEntry;
+    /** Add a widget of `type` at the end, with the given (or default) options. */
+    add(type: string, options?: OverviewOptions): OverviewOpResult;
+    remove(id: string): OverviewOpResult;
+    /** Move a widget so it sits at `toIndex` once it is taken out of the list. */
+    move(id: string, toIndex: number): OverviewOpResult;
+    /** Set a widget's column span (clamped to the widget's range). */
+    resize(id: string, span: number): OverviewOpResult;
+    /** Replace a widget's options after validating them against its schema. */
+    setOptions(id: string, options: OverviewOptions): OverviewOpResult;
+    /** Put one widget back to its default (or remove it when it is not one). */
+    resetWidget(id: string): OverviewOpResult;
+    /** Drop every customization; the overview returns to its defaults. */
+    reset(): OverviewOpResult;
+    /**
+     * Replace the override wholesale (an assistant's Undo restores the previous
+     * value). The value is parsed and sanitized like any stored override.
+     */
+    restore(override: unknown): OverviewOpResult;
+    /** Re-run a widget's load (after an error). */
+    reload(id: string): void;
+    /**
+     * Request data for every widget the entries do not cover. Call from an
+     * effect when the document can change outside the controller (a host-owned
+     * override). Never called during server render.
+     */
+    sync(): void;
+    /** Abort outstanding loads (call when the owning component is destroyed). */
+    destroy(): void;
+}
+/** Create a controller; call during component initialization. */
+export declare function createOverview(options: OverviewControllerOptions): OverviewController;
+//# sourceMappingURL=controller.svelte.d.ts.map

package/dist/components/overview/controller.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/overview/controller.svelte.ts"],"names":[],"mappings":"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"}

package/dist/components/overview/controller.svelte.js

@@ -0,0 +1,336 @@
+/**
+ * The overview controller (#3727): the host-owned, reactive state of one
+ * customizable overview. It follows the `ShellLayout` controller pattern:
+ * persistence belongs to the host, which stores the sparse override and
+ * feeds it back (`override`), and is told about every edit (`onchange`);
+ * with no `override` getter the controller keeps the value in memory.
+ *
+ * Every user operation (and, later, every assistant operation) is a method
+ * here. They validate through the same pure model the server uses, so a
+ * client edit can never produce a document the server would reject.
+ */
+import { untrack } from 'svelte';
+import { diffOverview, isEmptyOverride, nextWidgetId, parseOverviewOverride, resolveOverview, sanitizeOverview, } from './model.js';
+import { defaultWidgetRegistry } from './registry.js';
+import { defaultWidgetOptions, validateWidgetOptions } from './schema.js';
+function optionsKey(widget) {
+    return JSON.stringify([widget.type, widget.version ?? 1, widget.options]);
+}
+export class OverviewController {
+    #options;
+    #registry;
+    #local = $state.raw(null);
+    #entries = $state.raw({});
+    #pending = new Map();
+    #resolved = $derived.by(() => resolveOverview(this.#options.definition, this.#options.override ? this.#options.override() : this.#local, this.#registry));
+    constructor(options) {
+        this.#options = options;
+        this.#registry = options.registry ?? defaultWidgetRegistry;
+        const loaded = typeof options.loaded === 'function' ? options.loaded() : options.loaded;
+        if (loaded)
+            this.#seed(loaded);
+    }
+    #seed(loaded) {
+        const entries = {};
+        for (const widget of loaded.widgets) {
+            entries[widget.id] = {
+                key: optionsKey(widget),
+                status: widget.status,
+                data: widget.data,
+                error: widget.error?.code,
+            };
+        }
+        this.#entries = entries;
+    }
+    get definition() {
+        return this.#options.definition;
+    }
+    get registry() {
+        return this.#registry;
+    }
+    /** The sanitized document to render. */
+    get document() {
+        return this.#resolved.document;
+    }
+    /** The sanitized defaults. */
+    get base() {
+        return this.#resolved.base;
+    }
+    /** The canonical override currently applied; `null` when on defaults. */
+    get override() {
+        return diffOverview(this.#resolved.base, this.#resolved.document);
+    }
+    /** What was dropped or reported while resolving. */
+    get issues() {
+        return this.#resolved.issues;
+    }
+    /** True when the viewer has changed anything from the defaults. */
+    get customized() {
+        return !isEmptyOverride(this.override);
+    }
+    get canCustomize() {
+        return this.#options.canCustomize ? this.#options.canCustomize() : true;
+    }
+    /** Whether another widget fits under the cap. */
+    get full() {
+        const cap = this.#options.definition.maxWidgets ?? 24;
+        return this.document.widgets.length >= cap;
+    }
+    /** Registered widget types this overview allows, in registration order. */
+    get addable() {
+        const { allowed, id } = this.#options.definition;
+        return this.#registry
+            .list()
+            .filter((def) => (!allowed || allowed.includes(def.type)) &&
+            (!def.allowedIn || def.allowedIn.includes(id)));
+    }
+    /** Data state of a widget (loading while a load is outstanding). */
+    entry(widget) {
+        const entry = this.#entries[widget.id];
+        if (entry && entry.key === optionsKey(widget))
+            return entry;
+        return { status: this.#options.loadWidget ? 'loading' : 'ready' };
+    }
+    #models() {
+        return this.#options.definition.models;
+    }
+    #gate() {
+        return this.canCustomize ? null : { ok: false, reason: 'not_allowed' };
+    }
+    #commit(next, id) {
+        const sanitized = sanitizeOverview(next, {
+            registry: this.#registry,
+            definition: this.#options.definition,
+        });
+        const override = diffOverview(this.#resolved.base, sanitized.document);
+        if (sameJson(override, this.override)) {
+            return { ok: false, reason: 'unchanged' };
+        }
+        if (!this.#options.override)
+            this.#local = override;
+        void this.#options.onchange?.(override);
+        // The derived document reflects a host-owned override only after the host
+        // feeds it back, so sync against what was just committed.
+        this.#syncWidgets(sanitized.document.widgets);
+        return { ok: true, id };
+    }
+    #reserved() {
+        const override = this.override;
+        return [
+            ...this.#resolved.base.widgets.map((widget) => widget.id),
+            ...this.document.widgets.map((widget) => widget.id),
+            ...(override?.removed ?? []),
+            ...(override?.added ?? []).map((widget) => widget.id),
+        ];
+    }
+    /** Add a widget of `type` at the end, with the given (or default) options. */
+    add(type, options = {}) {
+        const denied = this.#gate();
+        if (denied)
+            return denied;
+        const def = this.addable.find((candidate) => candidate.type === type);
+        if (!def)
+            return { ok: false, reason: 'unknown_type' };
+        if (this.full)
+            return { ok: false, reason: 'limit' };
+        const checked = validateWidgetOptions(def.options, { ...defaultWidgetOptions(def.options), ...options }, { models: this.#models() });
+        if (!checked.ok) {
+            return { ok: false, reason: 'invalid_options', issues: checked.issues };
+        }
+        const id = nextWidgetId(this.#reserved());
+        return this.#commit({
+            widgets: [
+                ...this.document.widgets,
+                {
+                    id,
+                    type,
+                    span: def.defaultSpan,
+                    options: checked.options,
+                    version: def.version,
+                },
+            ],
+        }, id);
+    }
+    #find(id) {
+        return this.document.widgets.find((widget) => widget.id === id);
+    }
+    remove(id) {
+        const denied = this.#gate();
+        if (denied)
+            return denied;
+        if (!this.#find(id))
+            return { ok: false, reason: 'unknown_widget' };
+        return this.#commit({ widgets: this.document.widgets.filter((widget) => widget.id !== id) }, id);
+    }
+    /** Move a widget so it sits at `toIndex` once it is taken out of the list. */
+    move(id, toIndex) {
+        const denied = this.#gate();
+        if (denied)
+            return denied;
+        const widget = this.#find(id);
+        if (!widget)
+            return { ok: false, reason: 'unknown_widget' };
+        const rest = this.document.widgets.filter((entry) => entry.id !== id);
+        const index = Math.max(0, Math.min(toIndex, rest.length));
+        rest.splice(index, 0, widget);
+        return this.#commit({ widgets: rest }, id);
+    }
+    /** Set a widget's column span (clamped to the widget's range). */
+    resize(id, span) {
+        const denied = this.#gate();
+        if (denied)
+            return denied;
+        const widget = this.#find(id);
+        if (!widget)
+            return { ok: false, reason: 'unknown_widget' };
+        return this.#commit({
+            widgets: this.document.widgets.map((entry) => entry.id === id ? { ...entry, span: Math.round(span) } : entry),
+        }, id);
+    }
+    /** Replace a widget's options after validating them against its schema. */
+    setOptions(id, options) {
+        const denied = this.#gate();
+        if (denied)
+            return denied;
+        const widget = this.#find(id);
+        const def = widget ? this.#registry.get(widget.type) : undefined;
+        if (!widget || !def)
+            return { ok: false, reason: 'unknown_widget' };
+        const checked = validateWidgetOptions(def.options, options, {
+            models: this.#models(),
+        });
+        if (!checked.ok) {
+            return { ok: false, reason: 'invalid_options', issues: checked.issues };
+        }
+        return this.#commit({
+            widgets: this.document.widgets.map((entry) => entry.id === id
+                ? { ...entry, options: checked.options, version: def.version }
+                : entry),
+        }, id);
+    }
+    /** Put one widget back to its default (or remove it when it is not one). */
+    resetWidget(id) {
+        const denied = this.#gate();
+        if (denied)
+            return denied;
+        const original = this.#resolved.base.widgets.find((widget) => widget.id === id);
+        if (!original)
+            return this.remove(id);
+        return this.#commit({
+            widgets: this.document.widgets.some((widget) => widget.id === id)
+                ? this.document.widgets.map((widget) => widget.id === id ? { ...original } : widget)
+                : [...this.document.widgets, { ...original }],
+        }, id);
+    }
+    /** Drop every customization; the overview returns to its defaults. */
+    reset() {
+        const denied = this.#gate();
+        if (denied)
+            return denied;
+        if (!this.customized)
+            return { ok: false, reason: 'unchanged' };
+        if (!this.#options.override)
+            this.#local = null;
+        void this.#options.onchange?.(null);
+        this.#syncWidgets(this.#resolved.base.widgets);
+        return { ok: true, id: '' };
+    }
+    /**
+     * Replace the override wholesale (an assistant's Undo restores the previous
+     * value). The value is parsed and sanitized like any stored override.
+     */
+    restore(override) {
+        const denied = this.#gate();
+        if (denied)
+            return denied;
+        const { override: parsed } = parseOverviewOverride(override);
+        const next = resolveOverview(this.#options.definition, parsed, this.#registry);
+        const canonical = diffOverview(next.base, next.document);
+        if (sameJson(canonical, this.override)) {
+            return { ok: false, reason: 'unchanged' };
+        }
+        if (!this.#options.override)
+            this.#local = canonical;
+        void this.#options.onchange?.(canonical);
+        this.#syncWidgets(next.document.widgets);
+        return { ok: true, id: '' };
+    }
+    /** Re-run a widget's load (after an error). */
+    reload(id) {
+        const widget = this.#find(id);
+        if (!widget)
+            return;
+        this.#request(widget);
+    }
+    /**
+     * Request data for every widget the entries do not cover. Call from an
+     * effect when the document can change outside the controller (a host-owned
+     * override). Never called during server render.
+     */
+    sync() {
+        this.#syncWidgets(this.document.widgets);
+    }
+    #syncWidgets(widgets) {
+        untrack(() => {
+            const live = new Set(widgets.map((widget) => widget.id));
+            const kept = {};
+            for (const [id, entry] of Object.entries(this.#entries)) {
+                if (live.has(id))
+                    kept[id] = entry;
+            }
+            for (const [id, controller] of this.#pending) {
+                if (!live.has(id)) {
+                    controller.abort();
+                    this.#pending.delete(id);
+                }
+            }
+            this.#entries = kept;
+            if (!this.#options.loadWidget)
+                return;
+            for (const widget of widgets) {
+                const entry = this.#entries[widget.id];
+                if (!entry || entry.key !== optionsKey(widget))
+                    this.#request(widget);
+            }
+        });
+    }
+    #request(widget) {
+        const load = this.#options.loadWidget;
+        if (!load)
+            return;
+        const key = optionsKey(widget);
+        this.#pending.get(widget.id)?.abort();
+        const controller = new AbortController();
+        this.#pending.set(widget.id, controller);
+        this.#entries = {
+            ...this.#entries,
+            [widget.id]: { key, status: 'loading' },
+        };
+        const settle = (entry) => {
+            if (controller.signal.aborted)
+                return;
+            if (this.#pending.get(widget.id) === controller) {
+                this.#pending.delete(widget.id);
+            }
+            if (this.#entries[widget.id]?.key !== key)
+                return;
+            this.#entries = { ...this.#entries, [widget.id]: { key, ...entry } };
+        };
+        Promise.resolve()
+            .then(() => controller.signal.aborted ? undefined : load(widget, controller.signal))
+            .then((data) => settle({ status: 'ready', data }), () => settle({ status: 'error', error: 'load_failed' }));
+    }
+    /** Abort outstanding loads (call when the owning component is destroyed). */
+    destroy() {
+        for (const controller of this.#pending.values())
+            controller.abort();
+        this.#pending.clear();
+    }
+}
+function sameJson(a, b) {
+    return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+}
+/** Create a controller; call during component initialization. */
+export function createOverview(options) {
+    return new OverviewController(options);
+}

package/dist/components/overview/format.d.ts

@@ -0,0 +1,13 @@
+export type WidgetValueFormat = 'integer' | 'decimal' | 'percent' | 'money';
+export interface FormatWidgetValueOptions {
+    format?: WidgetValueFormat;
+    /** ISO 4217 code for `money` (default USD). */
+    currency?: string;
+    locale: string;
+}
+/**
+ * Format a metric value. `money` takes integer minor units, `percent` takes a
+ * fraction (0.25 is 25%). Non-finite input renders as an en dash.
+ */
+export declare function formatWidgetValue(value: unknown, { format, currency, locale }: FormatWidgetValueOptions): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/components/overview/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../src/components/overview/format.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAE5E,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAYD;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,EAAE,MAAkB,EAAE,QAAgB,EAAE,MAAM,EAAE,EAAE,wBAAwB,GACzE,MAAM,CA4BR"}