@emmorts/formsnap 0.0.0-stage → 2.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Hunter Johnston <https://github.com/huntabyte>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,116 @@
-# Temporary Holding Version
+# Formsnap
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The goal of this library is to make working with the already incredible [sveltekit-superforms](https://github.com/ciscoheat/sveltekit-superforms) even more pleasant, by wrapping it with accessible form components.
+
+## Installation
+
+```bash
+npm i formsnap sveltekit-superforms <your-schema-library>
+```
+
+## Usage
+
+You'll handle the initial Superforms setup just as you normally would, where you define a schema and return the form from your load function.
+
+#### 1. Define a Zod schema
+
+```ts
+// schemas.ts
+import { z } from "zod";
+export const settingsFormSchema = z.object({
+	email: z.string().email(),
+	bio: z.string().max(250).optional(),
+	marketingEmails: z.boolean().default(true),
+	language: z.enum(["en", "es", "fr"]).default(["en"]),
+	theme: z.enum(["light", "dark"]).default(["light"]),
+});
+```
+
+#### 2. Return the form from your load function
+
+```ts
+// +page.server.ts
+import { superValidate } from "sveltekit-superforms";
+import { zod } from "sveltekit-superforms/adapters";
+import type { PageServerLoad } from "./$types";
+import { settingsFormSchema } from "./schemas";
+
+export const load: PageServerLoad = async () => {
+	return {
+		form: await superValidate(zod(settingsFormSchema)),
+	};
+};
+```
+
+#### 3. Construct the form in your page
+
+```svelte
+<script lang="ts">
+	import { Field, Label, FieldErrors, Control, Description, Fieldset, Legend } from "formsnap";
+	import { settingsFormSchema } from "./schemas";
+	import { superForm } from "sveltekit-superforms";
+	import { zodClient } from "sveltekit-superforms/adapters";
+
+	export let data;
+
+	const form = superForm(data.form, {
+		validators: zodClient(settingsFormSchema),
+	});
+
+	const { form: formData, enhance } = form;
+</script>
+
+<form method="POST" use:enhance>
+	<Field {form} name="email">
+		<Control let:attrs>
+			<Label>Email</Label>
+			<input type="email" {...attrs} bind:value={$formData.email} />
+		</Control>
+		<Description>We'll provide critical updates about your account via email.</Description>
+		<FieldErrors />
+	</Field>
+
+	<Field {form} name="bio">
+		<Control let:attrs>
+			<Label>Bio</Label>
+			<textarea bind:value={$formData.bio} {...attrs} />
+		</Control>
+		<FieldErrors />
+	</Field>
+
+	<Field {form} name="language">
+		<Control let:attrs>
+			<Label>Language</Label>
+			<select {...attrs} bind:value={$formData.language}>
+				<option value="en">English</option>
+				<option value="es">Spanish</option>
+				<option value="fr">French</option>
+			</select>
+		</Control>
+		<FieldErrors />
+	</Field>
+
+	<Field {form} name="marketingEmails">
+		<Control let:attrs>
+			<Label>Receive marketing emails from us</Label>
+			<input type="checkbox" {...attrs} bind:checked={$formData.marketingEmails} />
+		</Control>
+		<FieldErrors />
+	</Field>
+
+	<Fieldset {form} name="theme">
+		<Legend>Select your theme</Legend>
+		{#each ["light", "dark"] as theme}
+			<Control let:attrs>
+				<input {...attrs} type="radio" bind:group={$formData.theme} value={theme} />
+				<Label>{theme}</Label>
+			</Control>
+		{/each}
+		<FieldErrors />
+	</Fieldset>
+
+	<button type="submit">Submit</button>
+</form>
+```
+
+Check out [Formsnap.dev](https://formsnap.dev) for more documentation.

package/dist/attrs.types.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Attributes provided via the props snippet prop of the
+ * [Control](https://formsnap.dev/docs/components/control) component to
+ * spread onto the form control element.
+ *
+ * @category Control
+ *
+ * @see {@link https://formsnap.dev/docs/components/control Control Documentation}
+ */
+export type ControlAttrs = {
+    /** The name of the control used for form submission. */
+    name: string;
+    /** The ID of the control, used for label association. */
+    id: string;
+    /** Present when a validation error exists on the field. */
+    "data-fs-error": string | undefined;
+    /** Present when description or validation exists. */
+    "aria-describedby": string | undefined;
+    /** Present when a validation error exists on the field. */
+    "aria-invalid": "true" | undefined;
+    /** Present when the field is required. */
+    "aria-required": "true" | undefined;
+    /**
+     * Used for selection during styling or otherwise
+     * @see {@link https://formsnap.dev/docs/styling Styling Documentation}
+     */
+    "data-fs-control": string;
+};
+/**
+ * Attributes provided via the `child` snippet props of the
+ * [Label](https://formsnap.dev/docs/components/label) component to spread onto the label element.
+ */
+export type LabelAttrs = {
+    /** The ID of the control, used for label association. */
+    for: string;
+    /** Present when a validation error exists on the field. */
+    "data-fs-error": string | undefined;
+    /**
+     * Used for selection during styling or otherwise
+     * @see {@link https://formsnap.dev/docs/styling Styling Documentation}
+     */
+    "data-fs-label": string;
+    /** Any additional props provided to the `<Form.Label />` component */
+    [key: string]: any;
+};
+/**
+ * Attributes provided via the `child` snippet props to spread onto the field error
+ * container element.
+ */
+export type FieldErrorsAttrs = {
+    /** The ID of the validation element, used to describe the control. */
+    id: string;
+    /** Present when a validation error exists on the field. */
+    "data-fs-error": string | undefined;
+    /**
+     * Used for selection during styling or otherwise
+     * @see {@link https://formsnap.dev/docs/styling Styling Documentation}
+     */
+    "data-fs-field-errors": string;
+    /** Notifies screen readers when a validation error occurs */
+    "aria-live": "assertive" | "polite";
+    /** Any additional props provided to `<Form.Validation />` */
+    [key: string]: any;
+};
+/**
+ * Attributes provided via the snippet props to be spread onto the individual error elements.
+ */
+export type ErrorAttrs = {
+    /**
+     * Used for selection during styling or otherwise
+     * @see {@link https://formsnap.dev/docs/styling Styling Documentation}
+     */
+    "data-fs-field-error": string;
+    /** Present when a validation error exists on the field. */
+    "data-fs-error": string | undefined;
+};
+/**
+ * Attributes provided via the {@link LegendSlotProps legendAttrs} slot prop of
+ * the [Legend](https://formsnap.dev/docs/components/legend) component to be spread
+ * onto the legend element when used with the {@link LegendProps asChild} prop.
+ *
+ * @category Legend
+ *
+ * @see {@link https://formsnap.dev/docs/composition/aschild asChild Documentation}
+ * @see {@link https://formsnap.dev/docs/components/legend Legend Documentation}
+ */
+export type LegendAttrs = {
+    /**
+     * Used for selection during styling or otherwise
+     * @see {@link https://formsnap.dev/docs/styling Styling Documentation}
+     */
+    "data-fs-legend": string;
+    /** Present when a validation error exists on the field. */
+    "data-fs-error": string | undefined;
+    [key: string]: any;
+};
+/**
+ * Attributes provided via the {@link DescriptionSlotProps descriptionAttrs} slot prop
+ * of the [Description](https://formsnap.dev/docs/components/description) component to be
+ * spread onto the description element when used with the {@link DescriptionProps asChild} prop.
+ *
+ * @category Description
+ *
+ * @see {@link https://formsnap.dev/docs/composition/aschild asChild Documentation}
+ * @see {@link https://formsnap.dev/docs/components/description Description Documentation}
+ */
+export type DescriptionAttrs = {
+    /** The ID of the description element, used to describe the control. */
+    id: string;
+    /**
+     * Used for selection during styling or otherwise
+     * @see {@link https://formsnap.dev/docs/styling Styling Documentation}
+     */
+    "data-fs-description": string;
+    /** Present when a validation error exists on the field. */
+    "data-fs-error": string | undefined;
+    [key: string]: any;
+};
+/**
+ * Attributes provided via the {@link FieldsetSlotProps props} snippet prop
+ * of the [Fieldset](https://formsnap.dev/docs/components/fieldset) component to be
+ * spread onto the `<fieldset>` element when used with the {@link FieldsetProps child} snippet.
+ *
+ * @category Fieldset
+ *
+ * @see {@link https://formsnap.dev/docs/composition/aschild asChild Documentation}
+ * @see {@link https://formsnap.dev/docs/components/fieldset Fieldset Documentation}
+ */
+export type FieldsetAttrs = {
+    /**
+     * Used for selection during styling or otherwise
+     * @see {@link https://formsnap.dev/docs/styling Styling Documentation}
+     */
+    "data-fs-fieldset": string;
+    /** Present when a validation error exists on the field. */
+    "data-fs-error": string | undefined;
+    [key: string]: any;
+};

package/dist/attrs.types.js

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

package/dist/components/control.svelte

@@ -0,0 +1,34 @@
+<script lang="ts">
+	import { box } from "svelte-toolbelt";
+	import type { ControlProps } from "./types.js";
+	import { useId } from "../internal/utils/index.js";
+	import { useControl } from "../formsnap.svelte.js";
+
+	let { id = useId(), children }: ControlProps = $props();
+
+	const controlState = useControl({
+		id: box.with(() => id),
+	});
+</script>
+
+<!--
+@component
+## Control
+Associates a [Label](https://formsnap.dev/docs/components/label) with and provides necessary attributes for a form control.
+
+- [Control Documentation](https://formsnap.dev/docs/components/label)
+
+@example
+```svelte
+<Control>
+  {#snippet children({ props })}
+	<Label>Name</Label>
+	<input type="text" {...props} bind:value={$formData.name} />
+   {/snippet}
+</Control>
+```
+
+### Snippet Props
+- `props` - A spreadable object of attributes that must be applied to the form control element.
+-->
+{@render children?.({ props: controlState.props })}

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

@@ -0,0 +1,22 @@
+import type { ControlProps } from "./types.js";
+/**
+ * ## Control
+ * Associates a [Label](https://formsnap.dev/docs/components/label) with and provides necessary attributes for a form control.
+ *
+ * - [Control Documentation](https://formsnap.dev/docs/components/label)
+ *
+ * @example
+ * ```svelte
+ * <Control>
+ *  {#snippet children({ props })}
+ * <Label>Name</Label>
+ * <input type="text" {...props} bind:value={$formData.name} />
+ *   {/snippet}
+ * </Control>
+ * ```
+ *
+ * ### Snippet Props
+ * - `props` - A spreadable object of attributes that must be applied to the form control element.
+ */
+declare const Control: import("svelte").Component<ControlProps, {}, "">;
+export default Control;

package/dist/components/description.svelte

@@ -0,0 +1,40 @@
+<script lang="ts">
+	import { box, mergeProps } from "svelte-toolbelt";
+	import type { DescriptionProps } from "./types.js";
+	import { useId } from "../internal/utils/index.js";
+	import { useDescription } from "../formsnap.svelte.js";
+
+	let {
+		id = useId(),
+		ref = $bindable(null),
+		children,
+		child,
+		...restProps
+	}: DescriptionProps = $props();
+
+	const descriptionState = useDescription({
+		id: box.with(() => id),
+		ref: box.with(
+			() => ref,
+			(v) => (ref = v)
+		),
+	});
+
+	const mergedProps = $derived(mergeProps(restProps, descriptionState.props));
+</script>
+
+<!--
+@component
+## Description
+A component that provides additional context for a field and is associated with the control using the `aria-describedby` attribute.
+
+- [Description Documentation](https://formsnap.dev/docs/components/description)
+-->
+
+{#if child}
+	{@render child({ props: mergedProps })}
+{:else}
+	<div {...mergedProps}>
+		{@render children?.()}
+	</div>
+{/if}

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

@@ -0,0 +1,9 @@
+import type { DescriptionProps } from "./types.js";
+/**
+ * ## Description
+ * A component that provides additional context for a field and is associated with the control using the `aria-describedby` attribute.
+ *
+ * - [Description Documentation](https://formsnap.dev/docs/components/description)
+ */
+declare const Description: import("svelte").Component<DescriptionProps, {}, "ref">;
+export default Description;

package/dist/components/element-field.svelte

@@ -0,0 +1,37 @@
+<script lang="ts" module>
+	import type { FormPathLeaves as _FormPathLeaves } from "sveltekit-superforms";
+	type T = unknown;
+	type U = unknown;
+</script>
+
+<script lang="ts" generics="T extends Record<string, unknown>, U extends _FormPathLeaves<T>">
+	import { box } from "svelte-toolbelt";
+	import type { ElementFieldProps } from "./types.js";
+	import { useElementField } from "../formsnap.svelte.js";
+
+	let { form, name, children }: ElementFieldProps<T, U> = $props();
+
+	const elementFieldState = useElementField({
+		form: box.with(() => form),
+		name: box.with(() => name),
+	});
+</script>
+
+<!--
+@component
+## ElementField
+A component that provides the necessary context for a form field that represents a single element in an array.
+
+- [ElementField Documentation](https://formsnap.dev/docs/components/element-field)
+
+### Snippet Props
+- `value` - The value of the field.
+- `errors` - The errors of the field.
+- `tainted` - The tainted state of the field.
+- `constraints` - The constraints of the field.
+
+@param {SuperForm} form - The form object.
+@param {FormPathLeaves<T>} name - The name and index of the field. For example, `urls[0]`.
+-->
+
+{@render children?.(elementFieldState.snippetProps)}

package/dist/components/element-field.svelte.d.ts

@@ -0,0 +1,34 @@
+import type { FormPathLeaves as _FormPathLeaves } from "sveltekit-superforms";
+import type { ElementFieldProps } from "./types.js";
+declare class __sveltets_Render<T extends Record<string, unknown>, U extends _FormPathLeaves<T>> {
+    props(): ElementFieldProps<T, U>;
+    events(): {};
+    slots(): {};
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T extends Record<string, unknown>, U extends _FormPathLeaves<T>>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T, U>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T, U>['props']>, ReturnType<__sveltets_Render<T, U>['events']>, ReturnType<__sveltets_Render<T, U>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T, U>['bindings']>;
+    } & ReturnType<__sveltets_Render<T, U>['exports']>;
+    <T extends Record<string, unknown>, U extends _FormPathLeaves<T>>(internal: unknown, props: ReturnType<__sveltets_Render<T, U>['props']> & {}): ReturnType<__sveltets_Render<T, U>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any, any>['bindings']>;
+}
+/**
+ * ## ElementField
+ * A component that provides the necessary context for a form field that represents a single element in an array.
+ *
+ * - [ElementField Documentation](https://formsnap.dev/docs/components/element-field)
+ *
+ * ### Snippet Props
+ * - `value` - The value of the field.
+ * - `errors` - The errors of the field.
+ * - `tainted` - The tainted state of the field.
+ * - `constraints` - The constraints of the field.
+ *
+ * @param {SuperForm} form - The form object.
+ * @param {FormPathLeaves<T>} name - The name and index of the field. For example, `urls[0]`.
+ */
+declare const ElementField: $$IsomorphicComponent;
+type ElementField<T extends Record<string, unknown>, U extends _FormPathLeaves<T>> = InstanceType<typeof ElementField<T, U>>;
+export default ElementField;

package/dist/components/field-errors.svelte

@@ -0,0 +1,55 @@
+<script lang="ts">
+	import { box, mergeProps } from "svelte-toolbelt";
+	import type { FieldErrorsProps } from "./types.js";
+	import { useId } from "../internal/utils/index.js";
+	import { useFieldErrors } from "../formsnap.svelte.js";
+
+	let {
+		id = useId(),
+		ref = $bindable(null),
+		children,
+		child,
+		...restProps
+	}: FieldErrorsProps = $props();
+
+	const fieldErrorsState = useFieldErrors({
+		id: box.with(() => id),
+		ref: box.with(
+			() => ref,
+			(v) => (ref = v)
+		),
+	});
+
+	const mergedProps = $derived(mergeProps(restProps, fieldErrorsState.fieldErrorsProps));
+</script>
+
+<!--
+@component
+## FieldErrors
+A component that renders the container for validation errors for a [Field](https://formsnap.dev/docs/components/field), [Fieldset](https://formsnap.dev/docs/components/fieldset), or [ElementField](https://formsnap.dev/docs/components/element-field).
+
+- [FieldErrors Documentation](https://formsnap.dev/docs/components/field-errors)
+
+### Snippet Props
+- `errors` - An array of errors for the associated field.
+- `fieldErrorsAttrs` - A spreadable object of attributes for the container element if `child` snippet is used.
+- `errorAttrs` - A spreadable object of attributes for the individual error elements if `child` snippet is used.
+
+@param {string} [id] - The id of the field errors container.
+-->
+{#if child}
+	{@render child({
+		props: mergedProps,
+		...fieldErrorsState.snippetProps,
+	})}
+{:else}
+	<div {...mergedProps}>
+		{#if children}
+			{@render children(fieldErrorsState.snippetProps)}
+		{:else}
+			{#each fieldErrorsState.field.errors as error}
+				<div {...fieldErrorsState.errorProps}>{error}</div>
+			{/each}
+		{/if}
+	</div>
+{/if}

package/dist/components/field-errors.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { FieldErrorsProps } from "./types.js";
+/**
+ * ## FieldErrors
+ * A component that renders the container for validation errors for a [Field](https://formsnap.dev/docs/components/field), [Fieldset](https://formsnap.dev/docs/components/fieldset), or [ElementField](https://formsnap.dev/docs/components/element-field).
+ *
+ * - [FieldErrors Documentation](https://formsnap.dev/docs/components/field-errors)
+ *
+ * ### Snippet Props
+ * - `errors` - An array of errors for the associated field.
+ * - `fieldErrorsAttrs` - A spreadable object of attributes for the container element if `child` snippet is used.
+ * - `errorAttrs` - A spreadable object of attributes for the individual error elements if `child` snippet is used.
+ *
+ * @param {string} [id] - The id of the field errors container.
+ */
+declare const FieldErrors: import("svelte").Component<FieldErrorsProps, {}, "ref">;
+export default FieldErrors;

package/dist/components/field.svelte

@@ -0,0 +1,37 @@
+<script lang="ts" module>
+	import type { FormPath as _FormPath } from "sveltekit-superforms";
+	type T = unknown;
+	type U = unknown;
+</script>
+
+<script lang="ts" generics="T extends Record<string, unknown>, U extends _FormPath<T>">
+	import { box } from "svelte-toolbelt";
+	import type { FieldProps } from "./types.js";
+	import { useField } from "../formsnap.svelte.js";
+
+	let { form, name, children }: FieldProps<T, U> = $props();
+
+	const fieldState = useField({
+		form: box.with(() => form),
+		name: box.with(() => name),
+	});
+</script>
+
+<!--
+@component
+## Field
+A component that provides the necessary context for a form field.
+
+- [Field Documentation](https://formsnap.dev/docs/components/field)
+
+### Snippet Props
+- `value` - The value of the field.
+- `errors` - The errors of the field.
+- `tainted` - The tainted state of the field.
+- `constraints` - The constraints of the field.
+
+@param {SuperForm} form - The form object.
+@param {FormPath<T>} name - The name of the field.
+-->
+
+{@render children?.(fieldState.snippetProps)}

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

@@ -0,0 +1,34 @@
+import type { FormPath as _FormPath } from "sveltekit-superforms";
+import type { FieldProps } from "./types.js";
+declare class __sveltets_Render<T extends Record<string, unknown>, U extends _FormPath<T>> {
+    props(): FieldProps<T, U>;
+    events(): {};
+    slots(): {};
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T extends Record<string, unknown>, U extends _FormPath<T>>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T, U>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T, U>['props']>, ReturnType<__sveltets_Render<T, U>['events']>, ReturnType<__sveltets_Render<T, U>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T, U>['bindings']>;
+    } & ReturnType<__sveltets_Render<T, U>['exports']>;
+    <T extends Record<string, unknown>, U extends _FormPath<T>>(internal: unknown, props: ReturnType<__sveltets_Render<T, U>['props']> & {}): ReturnType<__sveltets_Render<T, U>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any, any>['bindings']>;
+}
+/**
+ * ## Field
+ * A component that provides the necessary context for a form field.
+ *
+ * - [Field Documentation](https://formsnap.dev/docs/components/field)
+ *
+ * ### Snippet Props
+ * - `value` - The value of the field.
+ * - `errors` - The errors of the field.
+ * - `tainted` - The tainted state of the field.
+ * - `constraints` - The constraints of the field.
+ *
+ * @param {SuperForm} form - The form object.
+ * @param {FormPath<T>} name - The name of the field.
+ */
+declare const Field: $$IsomorphicComponent;
+type Field<T extends Record<string, unknown>, U extends _FormPath<T>> = InstanceType<typeof Field<T, U>>;
+export default Field;