@happyvertical/smrt-fields 0.40.60 → 0.40.62

package/dist/svelte/suggestions.js

@@ -0,0 +1,68 @@
+/**
+ * Structural browser contracts for field-policy suggestion review.
+ *
+ * These types intentionally omit tenant, user, authorization, and field
+ * sensitivity data. Hosts bind methods to authenticated generated clients;
+ * the server derives identity and validates every action.
+ */
+/**
+ * Validate generated custom-action output at the browser boundary. A malformed
+ * response is an error, never an empty queue that could conceal work.
+ */
+export function parsePendingFieldPolicySuggestions(value) {
+    if (!value || typeof value !== 'object') {
+        throw new Error('Unable to load pending field suggestions.');
+    }
+    const candidate = value;
+    const total = candidate.total;
+    if (!Array.isArray(candidate.suggestions) ||
+        typeof total !== 'number' ||
+        !Number.isSafeInteger(total) ||
+        total < 0) {
+        throw new Error('Unable to load pending field suggestions.');
+    }
+    const suggestions = candidate.suggestions.map(parseSuggestion);
+    if (total < suggestions.length) {
+        throw new Error('Unable to load pending field suggestions.');
+    }
+    return { suggestions, total };
+}
+function parseSuggestion(value) {
+    if (!value || typeof value !== 'object') {
+        throw new Error('Unable to load pending field suggestions.');
+    }
+    const candidate = value;
+    if (typeof candidate.id !== 'string' ||
+        typeof candidate.objectRef !== 'string' ||
+        typeof candidate.fieldName !== 'string' ||
+        (candidate.kind !== 'promote' && candidate.kind !== 'default') ||
+        (candidate.proposedValue !== null &&
+            typeof candidate.proposedValue !== 'string') ||
+        !isRecord(candidate.evidence) ||
+        (candidate.status !== undefined && candidate.status !== 'pending')) {
+        throw new Error('Unable to load pending field suggestions.');
+    }
+    return {
+        id: candidate.id,
+        objectRef: candidate.objectRef,
+        fieldName: candidate.fieldName,
+        kind: candidate.kind,
+        proposedValue: candidate.proposedValue,
+        evidence: candidate.evidence,
+    };
+}
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+/** Human-readable evidence without assuming a server-side evidence schema. */
+export function fieldPolicySuggestionEvidence(suggestion) {
+    const summary = suggestion.evidence.summary;
+    if (typeof summary === 'string' && summary.trim())
+        return summary;
+    const distinctUsers = suggestion.evidence.distinctUsers;
+    const setCount = suggestion.evidence.setCount;
+    if (typeof distinctUsers === 'number' && typeof setCount === 'number') {
+        return `${distinctUsers} users set this field ${setCount} times.`;
+    }
+    return 'Based on recent organization field usage.';
+}

package/dist/svelte/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Shared types for the field-policy Svelte primitives.
+ */
+/**
+ * Props for the PolicyField headless snippet escape hatch — all the data a
+ * fully custom renderer needs.
+ */
+export interface PolicyFieldSnippetProps {
+    id: string;
+    helpId: string;
+    visible: boolean;
+    label: string | null;
+    help: string | null;
+    defaultValue: unknown;
+    required: boolean;
+    /** Resolved visibility tier from the policy. */
+    tier: 'basic' | 'advanced' | 'hidden';
+}
+/**
+ * Browser-safe subset of a generated SMRT web field definition. This mirrors
+ * the `@smrt/web` wire contract without making the reusable Svelte package
+ * depend on an application's generated virtual module.
+ */
+export interface ObjectFormFieldDefinition {
+    /**
+     * The persisted public wire types emitted by generated web collections.
+     * There is deliberately no `select` wire type: applications render
+     * select-like controls by registering a field-specific renderer for a text
+     * (or other persisted) wire field.
+     */
+    type: ObjectFormWireType;
+    required?: boolean;
+    default?: unknown;
+    description?: string;
+    ui?: {
+        basic?: boolean;
+        group?: string;
+        order?: number;
+        locked?: boolean;
+    };
+}
+/** Browser-observable scalar types emitted by a generated web collection. */
+export type ObjectFormWireType = 'text' | 'integer' | 'decimal' | 'boolean' | 'datetime' | 'json' | 'foreignKey' | 'crossPackageRef';
+/** Structural subset of a generated `SmrtWebCollectionDefinition`. */
+export interface ObjectFormCollectionDefinition {
+    /** Canonical qualified model identity, never a simple class name. */
+    objectRef: string;
+    /** Browser-safe generated field definitions. */
+    fields: Readonly<Record<string, ObjectFormFieldDefinition>>;
+}
+/** Generated custom-action client shape, intentionally independent of smrt-web. */
+export interface ObjectFormPolicyClient {
+    resolveBatch(input: {
+        objectRefs: string[];
+    }): Promise<unknown>;
+}
+/** Resolved definition and policy consumed by `ObjectForm`. */
+export interface ObjectFormResolvedSource {
+    definition: ObjectFormCollectionDefinition;
+    policy: import('../types.js').ResolvedObjectFieldPolicy;
+}
+/**
+ * Per-app source contract. The source owns generated definitions and the
+ * app's custom-action transport; ObjectForm never imports a client runtime.
+ */
+export interface ObjectFormSource {
+    load(objectRef: string): Promise<ObjectFormResolvedSource>;
+}
+/** A field selected from the safe web-definition × resolved-policy overlap. */
+export interface ObjectFormField {
+    name: string;
+    definition: ObjectFormFieldDefinition;
+    group: string | null;
+    order: number | null;
+}
+/** Props shared by built-in and app-registered ObjectForm input renderers. */
+export interface FieldInputProps {
+    id: string;
+    name: string;
+    /** Resolved human-facing label for controls whose native name is absent. */
+    label?: string | null;
+    field: ObjectFormField;
+    value: unknown;
+    required: boolean;
+    disabled: boolean;
+    onvaluechange: (value: unknown) => void;
+    /** Reports parser validity to the host form/editor. */
+    onvaliditychange?: (valid: boolean) => void;
+}
+/** Data exposed to an ObjectForm per-field snippet override. */
+export interface ObjectFormFieldSnippetProps {
+    id: string;
+    helpId: string;
+    field: ObjectFormField;
+    value: unknown;
+    required: boolean;
+    disabled: boolean;
+    setValue(value: unknown): void;
+    setValidity(valid: boolean): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/svelte/types.d.ts.map

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

package/dist/svelte/types.js

@@ -0,0 +1,4 @@
+/**
+ * Shared types for the field-policy Svelte primitives.
+ */
+export {};

package/dist/svelte/usage-capture.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Browser-safe usage capture primitives for the field-policy learning loop.
+ *
+ * Hosts own the authenticated transport. This module deliberately carries no
+ * tenant, user, permission, or field-sensitivity information: the server
+ * derives all of that from its ambient context and live object registry.
+ */
+/** One submitted field value sent to the host's usage transport. */
+export interface FieldUsageEntry {
+    objectRef: string;
+    fieldName: string;
+    value?: unknown;
+    /** Optional value-less hint; normal ObjectForm capture sends the value. */
+    matchedDefault?: boolean;
+}
+/** Resolved default metadata used only for a value-less count signal. */
+export interface FieldUsageDefault {
+    hasDefault: boolean;
+    defaultValue: unknown;
+}
+/**
+ * Structural host transport for the counters collection's batched action.
+ * A reporter must never be allowed to affect a successful form submission.
+ */
+export interface FieldUsageReporter {
+    reportUsage(input: {
+        entries: readonly FieldUsageEntry[];
+    }): unknown;
+}
+export interface CollectFieldUsageEntriesOptions {
+    objectRef: string;
+    values: Readonly<Record<string, unknown>>;
+    /**
+     * Rendered field names and their persisted browser wire type. The type is
+     * used only to minimize value transit — it is never a sensitivity or
+     * authorization decision.
+     */
+    fields?: Readonly<Record<string, FieldUsageWireType>>;
+    /**
+     * Resolved defaults for rendered fields. For count-only values, a matching
+     * default is sent as a positive hint so the server does not treat it as a
+     * deviation. Absent or non-matching defaults deliberately send no hint.
+     */
+    defaults?: Readonly<Record<string, FieldUsageDefault>>;
+}
+export type FieldUsageWireType = 'text' | 'integer' | 'decimal' | 'boolean' | 'datetime' | 'json' | 'foreignKey' | 'crossPackageRef';
+/** Values may transit only for bounded, identifier-like wire types. */
+export declare function canCaptureFieldUsageValue(type: FieldUsageWireType | undefined): boolean;
+/**
+ * Collect every non-blank submitted field, including values matching a
+ * resolved default. Values transit only for bounded boolean/reference fields;
+ * free text, numbers, dates, and JSON emit count-only signals. Capturing only
+ * deviations would make the default's dominance denominator disappear. The
+ * server still derives eligibility, sensitivity, and every aggregate.
+ */
+export declare function collectFieldUsageEntries(options: CollectFieldUsageEntriesOptions): FieldUsageEntry[];
+/** Zero and false are submissions; only absent/null/empty-string values are not. */
+export declare function isBlankFieldValue(value: unknown): boolean;
+/** JSON-safe equality for the count-only default-match hint. */
+export declare function fieldUsageValuesEqual(left: unknown, right: unknown): boolean;
+/** Fire-and-forget by design: metrics transport failures never reject submit. */
+export declare function reportFieldUsage(reporter: FieldUsageReporter | undefined, entries: readonly FieldUsageEntry[]): void;
+//# sourceMappingURL=usage-capture.d.ts.map

package/dist/svelte/usage-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-capture.d.ts","sourceRoot":"","sources":["../../src/svelte/usage-capture.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,oEAAoE;AACpE,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,2EAA2E;IAC3E,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,SAAS,eAAe,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC;CACtE;AAED,MAAM,WAAW,+BAA+B;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1C;;;;OAIG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC;IACtD;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC;CACxD;AAED,MAAM,MAAM,kBAAkB,GAC1B,MAAM,GACN,SAAS,GACT,SAAS,GACT,SAAS,GACT,UAAU,GACV,MAAM,GACN,YAAY,GACZ,iBAAiB,CAAC;AAEtB,uEAAuE;AACvE,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,kBAAkB,GAAG,SAAS,GACnC,OAAO,CAIT;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,+BAA+B,GACvC,eAAe,EAAE,CAyBnB;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEzD;AAED,gEAAgE;AAChE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAO5E;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,kBAAkB,GAAG,SAAS,EACxC,OAAO,EAAE,SAAS,eAAe,EAAE,GAClC,IAAI,CASN"}

package/dist/svelte/usage-capture.js

@@ -0,0 +1,61 @@
+/** Values may transit only for bounded, identifier-like wire types. */
+export function canCaptureFieldUsageValue(type) {
+    return (type === 'boolean' || type === 'foreignKey' || type === 'crossPackageRef');
+}
+/**
+ * Collect every non-blank submitted field, including values matching a
+ * resolved default. Values transit only for bounded boolean/reference fields;
+ * free text, numbers, dates, and JSON emit count-only signals. Capturing only
+ * deviations would make the default's dominance denominator disappear. The
+ * server still derives eligibility, sensitivity, and every aggregate.
+ */
+export function collectFieldUsageEntries(options) {
+    const fields = options.fields ??
+        Object.fromEntries(Object.keys(options.values).map((fieldName) => [fieldName, undefined]));
+    const entries = [];
+    for (const [fieldName, type] of Object.entries(fields)) {
+        const value = options.values[fieldName];
+        if (isBlankFieldValue(value))
+            continue;
+        if (canCaptureFieldUsageValue(type)) {
+            entries.push({ objectRef: options.objectRef, fieldName, value });
+            continue;
+        }
+        const fieldDefault = options.defaults?.[fieldName];
+        entries.push({
+            objectRef: options.objectRef,
+            fieldName,
+            ...(fieldDefault?.hasDefault &&
+                fieldUsageValuesEqual(value, fieldDefault.defaultValue)
+                ? { matchedDefault: true }
+                : {}),
+        });
+    }
+    return entries;
+}
+/** Zero and false are submissions; only absent/null/empty-string values are not. */
+export function isBlankFieldValue(value) {
+    return value === undefined || value === null || value === '';
+}
+/** JSON-safe equality for the count-only default-match hint. */
+export function fieldUsageValuesEqual(left, right) {
+    if (left === right)
+        return true;
+    try {
+        return JSON.stringify(left) === JSON.stringify(right);
+    }
+    catch {
+        return false;
+    }
+}
+/** Fire-and-forget by design: metrics transport failures never reject submit. */
+export function reportFieldUsage(reporter, entries) {
+    if (!reporter || entries.length === 0)
+        return;
+    try {
+        void Promise.resolve(reporter.reportUsage({ entries })).catch(() => undefined);
+    }
+    catch {
+        // A synchronous host adapter failure is non-fatal by the same contract.
+    }
+}