@privaty/ui-forms 0.1.0

package/dist/testing/fakes.svelte.js

@@ -0,0 +1,346 @@
+import { createAttachmentKey } from "svelte/attachments";
+/**
+ * Minimal `ValidatableForm` fake for FormState-level tests. `computeIssues`
+ * runs on every `validate()` call and its result becomes the issue set that
+ * `fields.allIssues()` exposes (default: always valid). State is reactive —
+ * effects re-run on `setIssues`/`setPending`.
+ */
+function fakeForm(computeIssues = () => undefined) {
+    let issues = $state(undefined);
+    let pending = $state(0);
+    const validateCalls = [];
+    const form = {
+        validate: (validateOptions) => {
+            validateCalls.push(validateOptions);
+            issues = computeIssues();
+        },
+        fields: { allIssues: () => issues },
+        get pending() {
+            return pending;
+        },
+    };
+    return {
+        /** The fake form — pass it where a `ValidatableForm` is expected. */
+        form,
+        /** Arguments of every `validate()` call, in order. */
+        validateCalls,
+        /** Replaces the issue set directly, bypassing `validate()`. */
+        setIssues: (next) => {
+            issues = next;
+        },
+        /** Sets the form's `pending` submission count. */
+        setPending: (next) => {
+            pending = next;
+        },
+    };
+}
+/**
+ * Structural `TextField` fake for TextInput/TextareaInput tests. `as()`
+ * returns plain spreadable attributes (no attachment); value and issues are
+ * reactive state. Pass `options.issues` to seed the field with issues.
+ */
+function fakeTextField(name, options = {}) {
+    let value = $state(undefined);
+    let issues = $state(options.issues);
+    const field = {
+        as: (type, initialValue) => ({
+            name,
+            type,
+            value: initialValue,
+        }),
+        issues: () => issues,
+        value: () => value,
+        set: (next) => {
+            value = next;
+        },
+    };
+    return {
+        /** The fake field — pass it as the input component's `field` prop. */
+        field,
+        /** Simulates USER typing (string fields store the same value `set()`
+         * would — no raw/typed split here). */
+        edit: (next) => {
+            value = next;
+        },
+        /** Replaces the field's issue set. */
+        setIssues: (next) => {
+            issues = next;
+        },
+    };
+}
+/**
+ * Structural `DateField` fake for DateInput tests. The whole date family
+ * (date, month, week, time, datetime-local) carries ISO-style string values,
+ * so one fake covers all five. Same shape and reactivity as `fakeTextField`.
+ */
+function fakeDateField(name, options = {}) {
+    let value = $state(undefined);
+    let issues = $state(options.issues);
+    const field = {
+        as: (type, initialValue) => ({
+            name,
+            type,
+            value: initialValue,
+        }),
+        issues: () => issues,
+        value: () => value,
+        set: (next) => {
+            value = next;
+        },
+    };
+    return {
+        /** The fake field — pass it as the input component's `field` prop. */
+        field,
+        /** Simulates USER input — an ISO-style string, same as `set()` would
+         * store. */
+        edit: (next) => {
+            value = next;
+        },
+        /** Replaces the field's issue set. */
+        setIssues: (next) => {
+            issues = next;
+        },
+    };
+}
+/**
+ * Structural `NumberField` fake for NumberInput tests. Mirrors Kit's mid-edit
+ * behavior: `edit()` stores the raw DOM string a user's typing would produce,
+ * while `set()` stores the typed number — the distinction is what makes
+ * dirty-tracking tests meaningful.
+ */
+function fakeNumberField(name, options = {}) {
+    // Kit stores raw DOM strings mid-edit; set() stores typed values.
+    let value = $state(undefined);
+    let issues = $state(options.issues);
+    const field = {
+        as: (type, initialValue) => ({
+            name,
+            type,
+            value: initialValue,
+        }),
+        issues: () => issues,
+        value: () => value,
+        set: (next) => {
+            value = next;
+        },
+    };
+    return {
+        /** The fake field — pass it as the input component's `field` prop. */
+        field,
+        /** Simulates USER typing: stores the raw DOM string, like Kit does. */
+        edit: (next) => {
+            value = next === undefined ? "" : String(next);
+        },
+        /** Replaces the field's issue set. */
+        setIssues: (next) => {
+            issues = next;
+        },
+    };
+}
+/**
+ * Structural `SelectField` fake for SelectInput tests. Same shape and
+ * reactivity as `fakeTextField` — select values are plain strings on both
+ * the DOM and typed sides.
+ */
+function fakeSelectField(name, options = {}) {
+    let value = $state(undefined);
+    let issues = $state(options.issues);
+    const field = {
+        as: (type, initialValue) => ({
+            name,
+            value: initialValue,
+        }),
+        issues: () => issues,
+        value: () => value,
+        set: (next) => {
+            value = next;
+        },
+    };
+    return {
+        /** The fake field — pass it as the input component's `field` prop. */
+        field,
+        /** Simulates the USER choosing an option: stores its string value. */
+        edit: (next) => {
+            value = next;
+        },
+        /** Replaces the field's issue set. */
+        setIssues: (next) => {
+            issues = next;
+        },
+    };
+}
+/**
+ * Structural `CheckboxField` fake for CheckboxInput tests. Like Kit's
+ * `as("checkbox", seed)`, the returned attributes expose `checked` and
+ * `defaultChecked` getters (the latter is what makes native reset restore
+ * the seed). `edit()` stores the raw DOM value ("on"/null) while `set()`
+ * stores the typed boolean — mirroring Kit's mid-edit behavior.
+ */
+function fakeCheckboxField(name, options = {}) {
+    // Kit stores the raw DOM value mid-edit: "on" checked, null unchecked.
+    let value = $state(undefined);
+    let issues = $state(options.issues);
+    const field = {
+        as: (type, initialValue) => ({
+            name,
+            type,
+            get checked() {
+                if (value === undefined)
+                    return initialValue ?? false;
+                return value === true || value === "on";
+            },
+            get defaultChecked() {
+                return initialValue;
+            },
+        }),
+        issues: () => issues,
+        value: () => value,
+        set: (next) => {
+            value = next;
+        },
+    };
+    return {
+        /** The fake field — pass it as the input component's `field` prop. */
+        field,
+        /** Simulates a USER toggle: raw DOM value, like Kit's input listener. */
+        edit: (next) => {
+            value = next ? "on" : null;
+        },
+        /** Replaces the field's issue set. */
+        setIssues: (next) => {
+            issues = next;
+        },
+    };
+}
+/**
+ * A full-surface fake of a SvelteKit remote form for testing the Form
+ * component: `enhance` returns spreadable attributes whose attachment
+ * intercepts native submits (like Kit's does), so tests drive real buttons.
+ */
+function fakeRemoteForm(options = {}) {
+    let issues = $state(undefined);
+    let pending = $state(0);
+    const validateCalls = [];
+    const preflightCalls = [];
+    const validateGates = [];
+    let submitCount = 0;
+    const pathName = (issue) => (issue.path ?? []).join(".");
+    async function validate(validateOptions) {
+        validateCalls.push(validateOptions);
+        if (options.gateValidate) {
+            await new Promise((resolve) => validateGates.push(resolve));
+        }
+        const computed = (options.onValidate?.(validateOptions) ?? []).map((issue) => ({
+            ...issue,
+            server: validateOptions?.preflightOnly !== true,
+        }));
+        if (validateOptions?.preflightOnly) {
+            // Kit's merge: server issues persist through client-side validation
+            // unless a client issue lands on the same path — nothing else can
+            // refresh them (merge_with_server_issues, next.25).
+            const clientNames = computed.map(pathName);
+            issues = [
+                ...(issues ?? []).filter((issue) => issue.server && !clientNames.includes(pathName(issue))),
+                ...computed,
+            ];
+        }
+        else {
+            // Full validation ends in a server round-trip whose result replaces
+            // the entire issue set. (Kit short-circuits on client-schema failures
+            // first — the fake folds both stages into onValidate.)
+            issues = computed;
+        }
+    }
+    function makeEnhanceInstance(node) {
+        return {
+            element: node,
+            submit: async () => {
+                submitCount += 1;
+                pending += 1;
+                try {
+                    const succeeded = await (options.onSubmit
+                        ? options.onSubmit()
+                        : true);
+                    // Kit derives success from the response's issue set: a success
+                    // clears it, a rejection replaces it with the server's issues.
+                    if (succeeded) {
+                        issues = [];
+                    }
+                    else if (options.serverIssues) {
+                        issues = options.serverIssues.map((issue) => ({
+                            ...issue,
+                            server: true,
+                        }));
+                    }
+                    return succeeded;
+                }
+                finally {
+                    pending -= 1;
+                }
+            },
+        };
+    }
+    const form = {
+        method: "POST",
+        action: "?/fake",
+        preflight: (schema) => {
+            preflightCalls.push(schema);
+            return form;
+        },
+        enhance: (callback) => ({
+            method: "POST",
+            action: "?/fake",
+            [createAttachmentKey()]: (node) => {
+                const onSubmit = (event) => {
+                    event.preventDefault();
+                    void (async () => {
+                        // Kit runs preflight BEFORE the enhance callback and swallows
+                        // the submit entirely when the schema rejects — mirror that
+                        // whenever a schema was registered via preflight(). Only CLIENT
+                        // issues block: persisted server issues pass through, because
+                        // the submission itself is what re-judges them.
+                        if (preflightCalls.length > 0) {
+                            await validate({ all: true, preflightOnly: true });
+                            if ((issues ?? []).some((issue) => !issue.server))
+                                return;
+                        }
+                        await callback(makeEnhanceInstance(node));
+                    })();
+                };
+                node.addEventListener("submit", onSubmit);
+                return () => node.removeEventListener("submit", onSubmit);
+            },
+        }),
+        validate,
+        get result() {
+            return options.result;
+        },
+        get pending() {
+            return pending;
+        },
+        fields: {
+            // Kit's allIssues() strips issues down to { path, message } — the
+            // server flag never reaches the library.
+            allIssues: () => issues?.map(({ message, path }) => ({ message, path })),
+        },
+    };
+    return {
+        /** The fake remote form — pass it as the Form component's form. */
+        form,
+        /** Arguments of every `validate()` call, in order. */
+        validateCalls,
+        /** Schemas passed to `preflight()`, in order. */
+        preflightCalls,
+        /** Number of enhance submissions started so far. */
+        submitCount: () => submitCount,
+        /** Resolves the oldest still-gated `validate()` — pairs with the
+         * `gateValidate` option. */
+        releaseValidate: () => validateGates.shift()?.(),
+        /** Installs server-flagged issues directly — models the SSR-restored
+         * issue set of a rejected no-JS submission. */
+        setServerIssues: (next) => {
+            issues = next.map((issue) => ({ ...issue, server: true }));
+        },
+    };
+}
+export { fakeCheckboxField, fakeDateField, fakeForm, fakeNumberField, fakeRemoteForm, fakeSelectField, fakeTextField, };

package/dist/types/field.d.ts

@@ -0,0 +1,156 @@
+import type { InputType } from "@privaty/ui/components/types.js";
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { HTMLInputAttributes, HTMLSelectAttributes } from "svelte/elements";
+/**
+ * What an input hands to FormState.register, so the form can compute
+ * dirtiness, pick the majority-aware required/optional marker, and restore
+ * values on reset.
+ */
+interface FieldRegistration {
+    /** The field's form name — must be unique within the form (register throws
+     * on a duplicate). */
+    name: string;
+    /** The typed seed the field started from — the reference value for the
+     * dirty comparison and the value reset restores. */
+    initialValue: unknown;
+    /** Whether the field is required — feeds the majority-aware
+     * required/optional markers. */
+    required: boolean;
+    /** Reads the field's current value from the remote form. `undefined` means
+     * Kit tracks no value yet, in which case initialValue stands in. */
+    getValue: () => unknown;
+    /** Writes a value back into the remote form field — reset uses it to
+     * restore initialValue. */
+    setValue: (value: unknown) => void;
+    /** Maps raw field values onto the initialValue's domain before dirty
+     * comparison — Kit stores raw DOM strings mid-edit ("5", "on") while
+     * registrations hold typed seeds (5, true). */
+    normalize: (value: unknown) => unknown;
+}
+/** The `type` values a text-family field can render as. */
+type TextFieldType = Extract<InputType, "text" | "email" | "password" | "search" | "url" | "tel">;
+/** The attribute bag TextField.as() returns — spread onto the <input>. */
+type TextFieldAttributes = Omit<HTMLInputAttributes, "type"> & {
+    name: string;
+    type?: TextFieldType;
+};
+/**
+ * The slice of a SvelteKit remote form string field that TextInput needs.
+ * Structural on purpose: tests can pass a fake, and a client-only adapter can
+ * satisfy it later. Declared with method syntax — methods are checked
+ * bivariantly, which lets Kit's generic `as(...)` (a union of narrow tuples)
+ * satisfy this widened signature.
+ */
+interface TextField {
+    /**
+     * Returns the spreadable attribute bag for the <input>, optionally seeding
+     * an initial value. A single signature over a tuple union mirrors Kit's
+     * exact-arity AsArgs: seeded and unseeded are distinct call shapes (never
+     * an optional parameter), while a single signature keeps Kit's generic
+     * return narrowed by inference (overloads would compare against every
+     * field-type branch).
+     */
+    as(...args: [type: TextFieldType] | [type: TextFieldType, initialValue: string]): TextFieldAttributes;
+    /** Validation issues belonging to this field, if any. */
+    issues(): readonly StandardSchemaV1.Issue[] | undefined;
+    /** The field's current value, or undefined when Kit tracks none. */
+    value(): string | undefined;
+    /** Writes a value into the field — reset uses it to restore the seed. */
+    set(value: string): void;
+}
+/** The `type` values a date-family field can render as. */
+type DateFieldType = Extract<InputType, "date" | "datetime-local" | "month" | "time" | "week">;
+/** The attribute bag DateField.as() returns — spread onto the <input>. */
+type DateFieldAttributes = Omit<HTMLInputAttributes, "type"> & {
+    name: string;
+    type?: DateFieldType;
+};
+/**
+ * The slice of a SvelteKit remote form date-family field that DateInput
+ * needs. The whole family — date, month, week, time, datetime-local —
+ * carries ISO-style string values, so one slice covers all five. Same
+ * structural/method-syntax reasoning as TextField.
+ */
+interface DateField {
+    /** Returns the spreadable attribute bag for the <input>, optionally seeding
+     * an initial value — same tuple-union reasoning as TextField.as. */
+    as(...args: [type: DateFieldType] | [type: DateFieldType, initialValue: string]): DateFieldAttributes;
+    /** Validation issues belonging to this field, if any. */
+    issues(): readonly StandardSchemaV1.Issue[] | undefined;
+    /** The field's current ISO-style value, or undefined when Kit tracks none. */
+    value(): string | undefined;
+    /** Writes a value into the field — reset uses it to restore the seed. */
+    set(value: string): void;
+}
+/** The attribute bag NumberField.as() returns — spread onto the <input>. */
+type NumberFieldAttributes = Omit<HTMLInputAttributes, "type"> & {
+    name: string;
+    type?: "number";
+};
+/**
+ * The slice of a SvelteKit remote form number field that NumberInput needs.
+ * Same structural/method-syntax reasoning as TextField.
+ */
+interface NumberField {
+    /** Returns the spreadable attribute bag for the <input>, optionally seeding
+     * an initial value — same tuple-union reasoning as TextField.as. */
+    as(...args: [type: "number"] | [type: "number", initialValue: number]): NumberFieldAttributes;
+    /** Validation issues belonging to this field, if any. */
+    issues(): readonly StandardSchemaV1.Issue[] | undefined;
+    /** The field's current value, or undefined when Kit tracks none. Raw DOM
+     * strings appear mid-edit — Kit only coerces at submit/reset. */
+    value(): number | string | undefined;
+    /** Writes a number into the field — reset uses it to restore the seed. */
+    set(value: number): void;
+}
+/** The attribute bag SelectField.as() returns — spread onto the <select>. */
+type SelectFieldAttributes = Omit<HTMLSelectAttributes, "class" | "multiple"> & {
+    name: string;
+};
+/**
+ * The slice of a SvelteKit remote form select field that SelectInput needs.
+ * Same structural/method-syntax reasoning as TextField.
+ */
+interface SelectField {
+    /** Returns the spreadable attribute bag for the <select>, optionally
+     * seeding an initial value — same tuple-union reasoning as TextField.as. */
+    as(...args: [type: "select"] | [type: "select", initialValue: string]): SelectFieldAttributes;
+    /** Validation issues belonging to this field, if any. */
+    issues(): readonly StandardSchemaV1.Issue[] | undefined;
+    /** The field's current value, or undefined when Kit tracks none. */
+    value(): string | undefined;
+    /**
+     * Typed `never` on purpose: picklist schemas make Kit type `set()` over the
+     * field's literal union, which this slice cannot know. `never` is assignable
+     * to every union parameter (contravariance), and the library only ever
+     * passes back values the field itself produced.
+     */
+    set: (value: never) => void;
+}
+/** The attribute bag CheckboxField.as() returns — spread onto the <input>. */
+type CheckboxFieldAttributes = Omit<HTMLInputAttributes, "type"> & {
+    name: string;
+    type?: "checkbox";
+};
+/**
+ * The slice of a SvelteKit remote form boolean field that CheckboxInput
+ * needs. Same structural/method-syntax reasoning as TextField. The seeded
+ * call shape matters: Kit's as("checkbox", seed) provides `checked` AND a
+ * `defaultChecked` getter, which is what makes native reset restore the
+ * seed — never add a separate defaultChecked attribute on top (Kit defines
+ * its getter non-configurably; SSR crashes redefining it).
+ */
+interface CheckboxField {
+    /** Returns the spreadable attribute bag for the <input>, optionally seeding
+     * an initial value — same tuple-union reasoning as TextField.as. */
+    as(...args: [type: "checkbox"] | [type: "checkbox", initialValue: boolean]): CheckboxFieldAttributes;
+    /** Validation issues belonging to this field, if any. */
+    issues(): readonly StandardSchemaV1.Issue[] | undefined;
+    /** The field's current value, or undefined when Kit tracks none. Mid-edit,
+     * Kit stores the raw DOM value ("on") or null for unchecked — coercion to
+     * boolean only happens at submit/reset. */
+    value(): boolean | string | null | undefined;
+    /** Writes a boolean into the field — reset uses it to restore the seed. */
+    set: (value: boolean) => void;
+}
+export type { CheckboxField, CheckboxFieldAttributes, DateField, DateFieldAttributes, DateFieldType, FieldRegistration, NumberField, NumberFieldAttributes, SelectField, SelectFieldAttributes, TextField, TextFieldAttributes, TextFieldType, };

package/dist/types/field.js

@@ -0,0 +1 @@
+export {};

package/dist/types/form.d.ts

@@ -0,0 +1,27 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+/**
+ * The slice of a SvelteKit remote form that FormState needs. Structural on
+ * purpose: tests can pass a fake, and a client-only adapter can satisfy it later.
+ */
+interface ValidatableForm {
+    /**
+     * Kit's programmatic validation. `all: true` also surfaces issues on fields
+     * not yet edited and blurred; `preflightOnly: true` runs only the
+     * client-side preflight schema (no server round-trip). Typed `unknown`
+     * rather than `Promise<void>` so a fake may return synchronously — callers
+     * wrap the result in Promise.resolve.
+     */
+    validate: (options?: {
+        all?: boolean;
+        preflightOnly?: boolean;
+    }) => unknown;
+    /** Root issue accessor: validation issues for the whole form — form-level
+     * (path-less) and field-level alike — if any. */
+    fields: {
+        allIssues: () => readonly StandardSchemaV1.Issue[] | undefined;
+    };
+    /** The number of pending submissions — isSubmitting derives from it being
+     * greater than zero. */
+    readonly pending: number;
+}
+export type { ValidatableForm };

package/dist/types/form.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@privaty/ui-forms",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/privaty-io/ui.git",
+    "directory": "packages/ui-forms"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "NOTICE"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./*": {
+      "svelte": "./dist/*",
+      "default": "./dist/*"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@sveltejs/kit": "^3.0.0-next.0",
+    "svelte": "^5.0.0",
+    "@privaty/ui": "^0.1.0"
+  },
+  "dependencies": {
+    "@standard-schema/spec": "^1.1.0"
+  },
+  "devDependencies": {
+    "@sveltejs/kit": "next",
+    "@sveltejs/package": "^2.5.8",
+    "eslint": "^10.9.1",
+    "svelte": "^5.56.10",
+    "svelte-check": "^4.7.6",
+    "typescript": "^6.0.3",
+    "@config/typescript": "0.0.0",
+    "@privaty/ui": "0.1.0",
+    "@config/eslint": "0.0.0"
+  },
+  "scripts": {
+    "check": "svelte-check --tsconfig ./tsconfig.json",
+    "build": "svelte-package && find dist \\( -name '*.test.*' -o -name '*.fixture.*' \\) -delete",
+    "lint": "eslint ."
+  }
+}