@privaty/ui-forms 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Privaty
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,2 @@
+Privaty UI
+Copyright 2026 Privaty

package/README.md

@@ -0,0 +1,107 @@
+# @privaty/ui-forms
+
+Form components built on **SvelteKit remote functions** (experimental):
+`Form` wraps a `form(schema, handler)` instance, inputs bind to its fields,
+and a small `FormState` layer adds the display semantics Kit doesn't ship —
+value-based dirty tracking, touch-gated error display, submit gating.
+
+```bash
+pnpm add @privaty/ui @privaty/ui-forms
+```
+
+> Requires `@privaty/ui` as a **peerDependency** at the same lockstep version
+> (single instance — Symbol-keyed contexts), `@sveltejs/kit` with
+> `experimental.remoteFunctions` + `compilerOptions.experimental.async`, and
+> Tailwind v4 (`@source` the package, see the core README).
+
+## Quickstart
+
+```svelte
+<script>
+  import Form from "@privaty/ui-forms/form.svelte";
+  import TextInput from "@privaty/ui-forms/inputs/text-input.svelte";
+  import Submit from "@privaty/ui-forms/components/submit.svelte";
+  import FormError from "@privaty/ui-forms/components/form-error.svelte";
+  import { createItem } from "./data.remote";
+  import { createItemSchema } from "./schema";
+</script>
+
+<Form form={createItem} schema={createItemSchema}>
+  <TextInput field={createItem.fields.name} label="Name" required />
+  <FormError />
+  <Submit />
+</Form>
+```
+
+Inputs: `TextInput` (text/email/password/search/url/tel), `TextareaInput`,
+`NumberInput`, `DateInput` (date/month/week/time/datetime-local — one
+component, all string-valued), `SelectInput`, `CheckboxInput`. Plus
+`Submit`, `Reset`, `FormError`. Icon-style Submit/Reset: pass children; the
+label stays as the accessible name.
+
+## The validation model
+
+- **With `schema`** (a Standard Schema, e.g. valibot): validation runs
+  client-side via Kit's `preflight` — immediately on input, and on submit.
+  Kit swallows invalid submits before the enhance callback runs; the Form's
+  own submit listener still opens the error gates, so a rejected click shows
+  its issues.
+- **Without `schema`**: every validation is a server round-trip — typing is
+  debounced (`validationDebounce`, default 400 ms), submits validate
+  server-side. Transform schemas (Output ≠ Input) are accepted.
+- Issues per field appear once the field is touched or a submit was
+  attempted; `FormError` shows path-less issues and submit failures
+  (`labels.form.generalError`).
+- **Server issues** (a rejected submission, a server validation round-trip)
+  are persisted by Kit through every client-side validation pass — no edit
+  can refresh them, only another round-trip. The Form handles both
+  consequences: a schema'd resubmission is never gated on them (the
+  submission re-judges them authoritatively), and while they linger, input
+  revalidation escalates to full validation — client schema first, then the
+  server round-trip that replaces the whole issue set — debounced like
+  schema-less typing. Rules that depend on server data (a cross-field cap, a
+  uniqueness check) therefore belong in the **server schema** (an async check
+  is fine) if they should refresh live while the user edits; issues raised in
+  the _handler_ (`invalid()`) clear optimistically on the next round-trip and
+  are re-judged at submit.
+
+## Schema recipes (the footguns)
+
+```ts
+// Checkboxes: unchecked submits NOTHING — the schema supplies the false.
+inStock: v.optional(v.boolean(), false),
+
+// Placeholder selects: the disabled placeholder is skipped by submission —
+// default "" so YOUR message fires instead of a raw missing-key error.
+category: v.pipe(v.optional(v.string(), ""), v.picklist(categories, "required")),
+
+// Month inputs submit "YYYY-MM"; empty submits "".
+availableFrom: v.pipe(v.string(), v.nonEmpty("required"), v.regex(/^\d{4}-\d{2}$/, "invalid-month")),
+```
+
+## Rules learned the hard way
+
+- **Never disable controls while submitting** — disabled controls are
+  excluded from `FormData`, and Kit reads live form data mid-submission. The
+  inputs lock via `readonly` / pointer+keyboard locks instead. Keep that
+  contract in custom inputs.
+- **Queries: `await getItems()` bare.** `query().current` never
+  server-renders (hard-coded `undefined` on the server), and a
+  `<svelte:boundary>` with a `pending` snippet makes the server render the
+  snippet INSTEAD of the children. Await, no pending boundary.
+- Required/optional markers follow the majority rule (the minority gets
+  marked) and wait for `FormState.settled` — they cannot be SSR'd with
+  self-registering fields.
+- No-JS submissions are out of scope for v1 (Submit renders its gate state
+  into SSR HTML).
+- Browser support: Firefox has no `type="month"`/`"week"` pickers (falls
+  back to a text input) — a library-owned cross-browser date picker is
+  planned post-v1.
+
+## Testing
+
+`testing/fakes.svelte.ts` ships Kit-faithful fakes: `fakeRemoteForm`
+preflight-gates its enhance callback like Kit does, and the field fakes'
+`edit()` stores raw DOM values (`"5"`, `"on"`) while `set()` stores typed
+ones — mirroring Kit's mid-edit behavior so dirty-tracking tests mean
+something.

package/dist/components/form-error.svelte

@@ -0,0 +1,49 @@
+<!-- @component
+Form-level error list — must render inside a <Form> (throws otherwise).
+Shows the configured `labels.form.generalError` line when a submission threw,
+plus every validation issue without a path (e.g. from `invalid("...")` in the
+handler), translated through the configured `resolveMessage`; field-level
+issues render at their inputs instead. Renders nothing while there are no
+messages.
+-->
+<script lang="ts">
+  import { cn } from "@privaty/ui/cn.js";
+  import { getUiConfig } from "@privaty/ui/config/context.js";
+  import { getFormContext } from "../context";
+
+  interface Props {
+    /** Extra classes for the <ul> element. */
+    class?: string;
+  }
+
+  const { class: classes }: Props = $props();
+
+  const { form, state } = getFormContext();
+  const config = getUiConfig();
+
+  const messages = $derived.by(() => {
+    const collected: string[] = [];
+
+    if (state.submitError !== undefined)
+      collected.push(config.labels.form.generalError);
+
+    // Form-level issues (e.g. from `invalid("...")` in the handler) carry no
+    // path; field-level issues render at their fields instead.
+    for (const issue of form.fields.allIssues() ?? []) {
+      if (!issue.path?.length) collected.push(config.resolveMessage(issue));
+    }
+
+    return collected;
+  });
+</script>
+
+{#if messages.length}
+  <ul
+    class={cn("text-sm text-red-700 dark:text-red-500", classes)}
+    role="alert"
+  >
+    {#each messages as message, index (index)}
+      <li>{message}</li>
+    {/each}
+  </ul>
+{/if}

package/dist/components/form-error.svelte.d.ts

@@ -0,0 +1,15 @@
+interface Props {
+    /** Extra classes for the <ul> element. */
+    class?: string;
+}
+/**
+ * Form-level error list — must render inside a <Form> (throws otherwise).
+ * Shows the configured `labels.form.generalError` line when a submission threw,
+ * plus every validation issue without a path (e.g. from `invalid("...")` in the
+ * handler), translated through the configured `resolveMessage`; field-level
+ * issues render at their inputs instead. Renders nothing while there are no
+ * messages.
+ */
+declare const FormError: import("svelte").Component<Props, {}, "">;
+type FormError = ReturnType<typeof FormError>;
+export default FormError;

package/dist/components/reset.svelte

@@ -0,0 +1,49 @@
+<!-- @component
+Reset button — must render inside a <Form> (throws otherwise). Disabled
+while the form is pristine or submitting; clicking fires a native reset,
+which the Form's onreset handler turns into a full state reset (initial
+values restored, issues and error gates cleared).
+-->
+<script lang="ts">
+  import Button from "@privaty/ui/components/button.svelte";
+  import { getUiConfig } from "@privaty/ui/config/context.js";
+  import { getFormContext } from "../context";
+
+  import type { Snippet } from "svelte";
+
+  interface Props {
+    /** Button label — defaults to the configured `labels.form.reset`. */
+    label?: string;
+
+    /** Extra classes for the button. */
+    class?: string;
+
+    /** Icon-style content rendered instead of the label text — the label
+     * stays as the accessible name (sr-only + tooltip). */
+    children?: Snippet;
+  }
+
+  const { label, class: classes, children }: Props = $props();
+
+  const { state } = getFormContext();
+  const config = getUiConfig();
+
+  const resolvedLabel = $derived(label ?? config.labels.form.reset);
+</script>
+
+<!-- Nothing to reset while pristine; the native reset event triggers
+     FormState.reset() via the Form component's onreset handler. -->
+<Button
+  type="reset"
+  variant="secondary"
+  disabled={!state.isDirty || state.isSubmitting}
+  title={children ? resolvedLabel : undefined}
+  class={classes}
+>
+  {#if children}
+    {@render children()}
+    <span class="sr-only">{resolvedLabel}</span>
+  {:else}
+    {resolvedLabel}
+  {/if}
+</Button>

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

@@ -0,0 +1,19 @@
+import type { Snippet } from "svelte";
+interface Props {
+    /** Button label — defaults to the configured `labels.form.reset`. */
+    label?: string;
+    /** Extra classes for the button. */
+    class?: string;
+    /** Icon-style content rendered instead of the label text — the label
+     * stays as the accessible name (sr-only + tooltip). */
+    children?: Snippet;
+}
+/**
+ * Reset button — must render inside a <Form> (throws otherwise). Disabled
+ * while the form is pristine or submitting; clicking fires a native reset,
+ * which the Form's onreset handler turns into a full state reset (initial
+ * values restored, issues and error gates cleared).
+ */
+declare const Reset: import("svelte").Component<Props, {}, "">;
+type Reset = ReturnType<typeof Reset>;
+export default Reset;

package/dist/components/submit.svelte

@@ -0,0 +1,82 @@
+<!-- @component
+Submit button — must render inside a <Form> (throws otherwise). Disabled
+per `disabledUntil` (default "dirty-and-valid") and always while submitting,
+when it shows a spinner, sets aria-busy, and swaps to `submittingLabel` when
+one is given.
+-->
+<script lang="ts">
+  import { cn } from "@privaty/ui/cn.js";
+  import Button from "@privaty/ui/components/button.svelte";
+  import Spinner from "@privaty/ui/components/spinner.svelte";
+  import { getUiConfig } from "@privaty/ui/config/context.js";
+  import type { Snippet } from "svelte";
+  import { getFormContext } from "../context";
+
+  interface Props {
+    /** Button label — defaults to the configured `labels.form.submit`. */
+    label?: string;
+    /** Label shown next to the spinner while submitting. Without it only the
+     * spinner is visible and the label stays as the sr-only accessible name. */
+    submittingLabel?: string;
+
+    /** Validity gate: "dirty-and-valid" (default) disables the button until
+     * the form is both dirty and issue-free, "valid" only requires issue-free,
+     * "none" removes the gate. The button is always disabled while submitting
+     * regardless. */
+    disabledUntil?: "dirty-and-valid" | "valid" | "none";
+
+    /** Extra classes for the button. */
+    class?: string;
+
+    /** Icon-style content rendered instead of the label text — the label
+     * stays as the accessible name (sr-only + tooltip). */
+    children?: Snippet;
+  }
+
+  const {
+    label,
+    submittingLabel,
+
+    disabledUntil = "dirty-and-valid",
+
+    class: classes,
+
+    children,
+  }: Props = $props();
+
+  const { state } = getFormContext();
+  const config = getUiConfig();
+
+  const resolvedLabel = $derived(label ?? config.labels.form.submit);
+
+  const gateBlocked = $derived(
+    disabledUntil === "dirty-and-valid"
+      ? !state.isDirty || !state.isValid
+      : disabledUntil === "valid"
+        ? !state.isValid
+        : false,
+  );
+</script>
+
+<Button
+  type="submit"
+  disabled={gateBlocked || state.isSubmitting}
+  aria-busy={state.isSubmitting}
+  title={children ? resolvedLabel : undefined}
+  class={cn("inline-flex items-center justify-center gap-2", classes)}
+>
+  {#if state.isSubmitting}
+    <Spinner />
+    {#if submittingLabel}
+      {submittingLabel}
+    {:else}
+      <!-- Keep the accessible name when only the spinner is visible. -->
+      <span class="sr-only">{resolvedLabel}</span>
+    {/if}
+  {:else if children}
+    {@render children()}
+    <span class="sr-only">{resolvedLabel}</span>
+  {:else}
+    {resolvedLabel}
+  {/if}
+</Button>

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

@@ -0,0 +1,27 @@
+import type { Snippet } from "svelte";
+interface Props {
+    /** Button label — defaults to the configured `labels.form.submit`. */
+    label?: string;
+    /** Label shown next to the spinner while submitting. Without it only the
+     * spinner is visible and the label stays as the sr-only accessible name. */
+    submittingLabel?: string;
+    /** Validity gate: "dirty-and-valid" (default) disables the button until
+     * the form is both dirty and issue-free, "valid" only requires issue-free,
+     * "none" removes the gate. The button is always disabled while submitting
+     * regardless. */
+    disabledUntil?: "dirty-and-valid" | "valid" | "none";
+    /** Extra classes for the button. */
+    class?: string;
+    /** Icon-style content rendered instead of the label text — the label
+     * stays as the accessible name (sr-only + tooltip). */
+    children?: Snippet;
+}
+/**
+ * Submit button — must render inside a <Form> (throws otherwise). Disabled
+ * per `disabledUntil` (default "dirty-and-valid") and always while submitting,
+ * when it shows a spinner, sets aria-busy, and swaps to `submittingLabel` when
+ * one is given.
+ */
+declare const Submit: import("svelte").Component<Props, {}, "">;
+type Submit = ReturnType<typeof Submit>;
+export default Submit;

package/dist/context.d.ts

@@ -0,0 +1,23 @@
+import type { FormState } from "./form-state.svelte";
+import type { ValidatableForm } from "./types/form";
+/** What a <Form> shares with its descendants. */
+interface FormContext {
+    /** The enhanced remote form instance (the preflighted one when the Form
+     * was given a schema). */
+    form: ValidatableForm;
+    /** The form's client-side display state — dirty/touched tracking and
+     * error-display gating. */
+    state: FormState;
+}
+/**
+ * Shares a form instance and its FormState with descendant components. Called
+ * by <Form>; must run during component init. A custom form wrapper can call
+ * it to host this library's inputs and buttons.
+ */
+declare function setFormContext(context: FormContext): void;
+/**
+ * Returns the nearest enclosing <Form>'s context. Must be called during
+ * component init; throws when no ancestor has set the form context.
+ */
+declare function getFormContext(): FormContext;
+export { getFormContext, setFormContext };

package/dist/context.js

@@ -0,0 +1,21 @@
+import { getContext, setContext } from "svelte";
+const formContextKey = Symbol("privaty-ui-form-context");
+/**
+ * Shares a form instance and its FormState with descendant components. Called
+ * by <Form>; must run during component init. A custom form wrapper can call
+ * it to host this library's inputs and buttons.
+ */
+function setFormContext(context) {
+    setContext(formContextKey, context);
+}
+/**
+ * Returns the nearest enclosing <Form>'s context. Must be called during
+ * component init; throws when no ancestor has set the form context.
+ */
+function getFormContext() {
+    const context = getContext(formContextKey);
+    if (!context)
+        throw new Error("FormContext: form components must be used inside a <Form>");
+    return context;
+}
+export { getFormContext, setFormContext };