@samuel-charpentier/sform 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Samuel Charpentier
+
+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

@@ -0,0 +1,405 @@
+# Sform
+
+A type-safe form library for **Svelte 5** with **SvelteKit remote functions**.
+
+## Features
+
+- ✅ **Type-safe** - Discriminated union types for each input type
+- ✅ **Preflight validation** - All errors shown on submit, not one at a time
+- ✅ **Validate modes** - `blur`, `change`, or `submit`
+- ✅ **Password toggle** - Eye icon to show/hide password
+- ✅ **Masked inputs** - Phone, credit card, SSN formatting
+- ✅ **Range slider** - With optional value display
+- ✅ **Toggle switch** - Modern on/off control
+- ✅ **Toggle options** - Segmented control for mutually exclusive options
+- ✅ **Stateful button** - Shows pending state during submission
+
+## Requirements
+
+- Svelte 5
+- SvelteKit with `remoteFunctions: true` in config
+- Valibot for schema validation
+
+## Installation
+
+```bash
+npm install
+```
+
+Enable remote functions in `svelte.config.js`:
+
+```javascript
+export default {
+	kit: {
+		experimental: {
+			remoteFunctions: true
+		}
+	}
+};
+```
+
+## Quick Start
+
+### 1. Create a Remote Form
+
+Create a `.remote.ts` file with your form schema and handler:
+
+```typescript
+// src/routes/auth.remote.ts
+import * as v from 'valibot';
+import { form } from '@sveltejs/kit/remote';
+
+const loginSchema = v.object({
+	username: v.pipe(v.string(), v.minLength(3, 'Username must be at least 3 characters')),
+	_password: v.pipe(v.string(), v.minLength(8, 'Password must be at least 8 characters'))
+});
+
+export const login = form(loginSchema, async ({ username, _password }) => {
+	// Your authentication logic here
+	return { success: true, message: 'Welcome!' };
+});
+```
+
+### 2. Create Your Form Component
+
+```svelte
+<script lang="ts">
+	import { Sform, Sfield, Sbutton } from '$lib';
+	import { login } from './auth.remote.ts';
+</script>
+
+<Sform form={login} validateOn="blur">
+	<Sfield name="username" type="text" label="Username" />
+	<Sfield name="_password" type="password" label="Password" />
+
+	<Sbutton label="Login" />
+</Sform>
+```
+
+## Components
+
+### `<Sform>`
+
+Wrapper component that provides form context to all child fields.
+
+```svelte
+<Sform form={remoteForm} validateOn="blur" class="my-form">
+	<!-- Sfield components here -->
+</Sform>
+```
+
+| Prop         | Type                             | Default     | Description                          |
+| ------------ | -------------------------------- | ----------- | ------------------------------------ |
+| `form`       | `RemoteForm`                     | required    | Remote form object from `form()` API |
+| `validateOn` | `'blur' \| 'change' \| 'submit'` | `'blur'`    | When to validate and show errors     |
+| `class`      | `string`                         | `undefined` | CSS class for form element           |
+
+**Validate Modes:**
+
+- `blur` - Validate and show errors after leaving field (default)
+- `change` - Validate and show errors as soon as value changes
+- `submit` - Validate and show all errors only after submit attempt
+
+### `<Sfield>`
+
+Smart field component with type-safe props based on input type.
+
+#### Common Props (all types)
+
+| Prop          | Type                      | Default     | Description                    |
+| ------------- | ------------------------- | ----------- | ------------------------------ |
+| `name`        | `string`                  | required    | Field name (must match schema) |
+| `type`        | `InputType`               | required    | Input type                     |
+| `label`       | `string`                  | `undefined` | Field label                    |
+| `placeholder` | `string`                  | `undefined` | Placeholder text               |
+| `disabled`    | `boolean`                 | `false`     | Disable the field              |
+| `readonly`    | `boolean`                 | `false`     | Make field readonly            |
+| `validateOn`  | `ValidateOn`              | inherited   | Override form validateOn       |
+| `class`       | `SfieldClasses \| string` | `undefined` | CSS classes                    |
+
+#### Text Inputs
+
+```svelte
+<Sfield name="email" type="email" label="Email" placeholder="you@example.com" />
+<Sfield name="search" type="search" label="Search" />
+<Sfield name="phone" type="tel" label="Phone" />
+<Sfield name="website" type="url" label="Website" />
+```
+
+Supported text types: `text`, `email`, `tel`, `url`, `search`, `date`, `datetime-local`, `time`, `month`, `week`, `color`, `file`, `hidden`
+
+#### Password Input
+
+```svelte
+<Sfield name="_password" type="password" label="Password" />
+<Sfield name="_password" type="password" label="Password" showToggle={false} />
+```
+
+| Prop         | Type      | Default | Description                        |
+| ------------ | --------- | ------- | ---------------------------------- |
+| `showToggle` | `boolean` | `true`  | Show eye icon to toggle visibility |
+
+#### Number Input
+
+```svelte
+<Sfield name="age" type="number" label="Age" min={0} max={150} step={1} />
+```
+
+| Prop   | Type               | Default     | Description    |
+| ------ | ------------------ | ----------- | -------------- |
+| `min`  | `number \| string` | `undefined` | Minimum value  |
+| `max`  | `number \| string` | `undefined` | Maximum value  |
+| `step` | `number \| string` | `undefined` | Step increment |
+
+#### Textarea
+
+```svelte
+<Sfield name="bio" type="textarea" label="Bio" placeholder="Tell us about yourself" />
+```
+
+#### Select
+
+```svelte
+<Sfield
+	name="country"
+	type="select"
+	label="Country"
+	options={[
+		{ value: 'us', label: 'United States' },
+		{ value: 'uk', label: 'United Kingdom' },
+		{ value: 'ca', label: 'Canada' }
+	]}
+/>
+```
+
+| Prop      | Type                         | Default  | Description    |
+| --------- | ---------------------------- | -------- | -------------- |
+| `options` | `SelectOption[] \| string[]` | required | Select options |
+
+#### Checkbox
+
+```svelte
+<Sfield name="subscribe" type="checkbox" label="Subscribe to newsletter" />
+```
+
+#### Radio
+
+```svelte
+<Sfield
+	name="plan"
+	type="radio"
+	label="Plan"
+	options={[
+		{ value: 'free', label: 'Free' },
+		{ value: 'pro', label: 'Pro' },
+		{ value: 'enterprise', label: 'Enterprise' }
+	]}
+/>
+```
+
+| Prop      | Type                         | Default     | Description              |
+| --------- | ---------------------------- | ----------- | ------------------------ |
+| `options` | `SelectOption[] \| string[]` | `undefined` | Radio options for groups |
+
+#### Range
+
+```svelte
+<Sfield name="volume" type="range" label="Volume" min={0} max={100} step={5} showValue />
+```
+
+| Prop          | Type                        | Default     | Description            |
+| ------------- | --------------------------- | ----------- | ---------------------- |
+| `min`         | `number \| string`          | `0`         | Minimum value          |
+| `max`         | `number \| string`          | `100`       | Maximum value          |
+| `step`        | `number \| string`          | `1`         | Step increment         |
+| `showValue`   | `boolean`                   | `false`     | Show current value     |
+| `formatValue` | `(value: number) => string` | `undefined` | Format displayed value |
+
+#### Toggle
+
+```svelte
+<Sfield name="notifications" type="toggle" label="Enable Notifications" />
+<Sfield name="darkMode" type="toggle" label="Theme" onLabel="Dark" offLabel="Light" />
+```
+
+| Prop             | Type     | Default     | Description          |
+| ---------------- | -------- | ----------- | -------------------- |
+| `onLabel`        | `string` | `undefined` | Label when on        |
+| `offLabel`       | `string` | `undefined` | Label when off       |
+| `checkedValue`   | `string` | `'true'`    | Value when checked   |
+| `uncheckedValue` | `string` | `'false'`   | Value when unchecked |
+
+#### Toggle Options
+
+```svelte
+<Sfield
+	name="theme"
+	type="toggle-options"
+	label="Theme"
+	options={[
+		{ value: 'light', label: 'Light' },
+		{ value: 'dark', label: 'Dark' },
+		{ value: 'auto', label: 'Auto' }
+	]}
+/>
+```
+
+| Prop       | Type                         | Default  | Description               |
+| ---------- | ---------------------------- | -------- | ------------------------- |
+| `options`  | `ToggleOption[] \| string[]` | required | Toggle options            |
+| `multiple` | `boolean`                    | `false`  | Allow multiple selections |
+
+#### Masked Input
+
+```svelte
+<Sfield name="phone" type="masked" label="Phone" mask="(###) ###-####" />
+<Sfield name="creditCard" type="masked" label="Credit Card" mask="#### #### #### ####" />
+<Sfield name="ssn" type="masked" label="SSN" mask="###-##-####" />
+```
+
+| Prop                  | Type      | Default  | Description                      |
+| --------------------- | --------- | -------- | -------------------------------- |
+| `mask`                | `string`  | required | Mask pattern                     |
+| `maskPlaceholder`     | `string`  | `'_'`    | Placeholder character            |
+| `showMaskPlaceholder` | `boolean` | `false`  | Show full mask with placeholders |
+| `storeRaw`            | `boolean` | `true`   | Store unmasked value             |
+
+**Mask Tokens:**
+
+- `#` or `9` - Numeric (0-9)
+- `a` - Alphabetic (a-z, A-Z)
+- `A` - Alphabetic uppercase
+- `*` - Alphanumeric
+
+### `<Sbutton>`
+
+Stateful submit button that reacts to form state.
+
+```svelte
+<Sbutton label="Submit" class="my-button" />
+
+<!-- With custom state snippets -->
+<Sbutton class="submit-btn">
+	{#snippet defaultState(state)}
+		Submit Form
+	{/snippet}
+	{#snippet pendingState(state)}
+		Submitting...
+	{/snippet}
+	{#snippet successState(state)}
+		✓ Success!
+	{/snippet}
+	{#snippet errorState(state)}
+		Fix Errors
+	{/snippet}
+</Sbutton>
+```
+
+| Prop           | Type                              | Default     | Description           |
+| -------------- | --------------------------------- | ----------- | --------------------- |
+| `label`        | `string`                          | `'Submit'`  | Button text           |
+| `buttonType`   | `'submit' \| 'reset' \| 'button'` | `'submit'`  | Button type           |
+| `class`        | `string`                          | `undefined` | CSS class             |
+| `disabled`     | `boolean`                         | `false`     | Disable button        |
+| `defaultState` | `Snippet`                         | `undefined` | Default state snippet |
+| `pendingState` | `Snippet`                         | `undefined` | Pending state snippet |
+| `successState` | `Snippet`                         | `undefined` | Success state snippet |
+| `errorState`   | `Snippet`                         | `undefined` | Error state snippet   |
+
+## Styling
+
+### CSS Classes
+
+Sfield adds these classes automatically:
+
+- `.sform-field` - Wrapper element
+- `.sform-label` - Label element
+- `.sform-input` - Input element
+- `.sform-messages` - Error messages container
+- `.sform-field-error` - Added to wrapper when field has errors
+
+### Custom Classes
+
+```svelte
+<!-- String class applies to wrapper -->
+<Sfield name="email" type="email" class="my-field" />
+
+<!-- Object for granular control -->
+<Sfield
+	name="email"
+	type="email"
+	class={{
+		wrapper: 'field-wrapper',
+		label: 'field-label',
+		input: 'field-input',
+		messages: 'field-errors'
+	}}
+/>
+```
+
+## Validation
+
+Sform uses preflight validation with Valibot schemas. Native browser validation (required, minlength, pattern) is disabled to allow showing all errors at once on submit.
+
+### Schema Example
+
+```typescript
+import * as v from 'valibot';
+
+const signupSchema = v.object({
+	email: v.pipe(v.string(), v.email('Please enter a valid email')),
+	_password: v.pipe(
+		v.string(),
+		v.minLength(8, 'Password must be at least 8 characters'),
+		v.regex(/[A-Z]/, 'Password must contain an uppercase letter'),
+		v.regex(/[0-9]/, 'Password must contain a number')
+	),
+	age: v.pipe(v.number(), v.minValue(18, 'Must be at least 18 years old'))
+});
+```
+
+## Type Safety
+
+Sform uses TypeScript discriminated unions to provide type-safe props for each input type:
+
+```typescript
+// ✅ TypeScript knows 'showToggle' is only valid for password type
+<Sfield name="_password" type="password" showToggle={false} />
+
+// ✅ TypeScript knows 'options' is required for select type
+<Sfield name="country" type="select" options={countries} />
+
+// ✅ TypeScript knows 'min', 'max', 'step' are valid for number type
+<Sfield name="age" type="number" min={0} max={150} />
+
+// ❌ TypeScript error: 'showToggle' doesn't exist on text type
+<Sfield name="username" type="text" showToggle />
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start dev server
+npm run dev
+
+# Run tests
+npm test
+
+# Build library
+npm run package
+```
+
+## License
+
+MIT
+
+Go into the `package.json` and give your package the desired name through the `"name"` option. Also consider adding a `"license"` field and point it to a `LICENSE` file which you can create from a template (one popular option is the [MIT license](https://opensource.org/license/mit/)).
+
+To publish your library to [npm](https://www.npmjs.com):
+
+```sh
+npm publish
+```

package/dist/Sform/Sfield.svelte

@@ -0,0 +1,164 @@
+<script lang="ts">
+	import type {
+		SfieldClasses,
+		RemoteFormField,
+		RemoteFormFieldValue,
+		TypedSfieldProps
+	} from './types.js';
+	import { getSformContext } from './context.svelte.js';
+	import TextInput from './inputs/TextInput.svelte';
+	import NumberInput from './inputs/NumberInput.svelte';
+	import TextareaInput from './inputs/TextareaInput.svelte';
+	import SelectInput from './inputs/SelectInput.svelte';
+	import CheckboxInput from './inputs/CheckboxInput.svelte';
+	import CheckboxGroupInput from './inputs/CheckboxGroupInput.svelte';
+	import RadioInput from './inputs/RadioInput.svelte';
+	import RangeInput from './inputs/RangeInput.svelte';
+	import ToggleInput from './inputs/ToggleInput.svelte';
+	import ToggleOptionsInput from './inputs/ToggleOptionsInput.svelte';
+	import MaskedInput from './inputs/MaskedInput.svelte';
+	import PasswordInput from './inputs/PasswordInput.svelte';
+
+	/**
+	 * Sfield - Type-safe form field component.
+	 *
+	 * The `type` prop is constrained based on the field's value type:
+	 * - string fields: text, email, password, textarea, select, radio, masked, etc.
+	 * - number fields: number, range
+	 * - boolean fields: checkbox, toggle
+	 * - string[] fields: checkbox-group
+	 */
+	let props: TypedSfieldProps<RemoteFormFieldValue> = $props();
+
+	const context = getSformContext();
+
+	// Field is directly passed as a prop
+	const field = $derived(props.field as RemoteFormField<RemoteFormFieldValue>);
+
+	// Derive name from the field - all field types include name in their .as() output
+	const name = $derived(field.as('text').name);
+
+	const classes: SfieldClasses = $derived(
+		typeof props.class === 'string' ? { wrapper: props.class } : (props.class ?? {})
+	);
+
+	const showIssues = $derived(context.shouldDisplayIssues(name, props.validateOn));
+	const issues = $derived(showIssues ? field.issues() : []);
+	const hasIssues = $derived(issues && issues instanceof Array && issues.length > 0);
+
+	function handleBlur() {
+		context.markTouched(name);
+		// Trigger validation with includeUntouched so blur mode shows issues
+		context.triggerValidation();
+	}
+
+	function handleInput() {
+		context.markDirty(name);
+	}
+
+	// Props that Sfield manages internally - these are set by Sfield, not passed from parent
+	const internalPropKeys = [
+		'field',
+		'name',
+		'showIssues',
+		'onblur',
+		'oninput',
+		'labelClass',
+		'class'
+	];
+	// Props that are Sfield-specific and not passed to components
+	const sfieldOnlyPropKeys = ['validateOn', 'hint', 'type'];
+
+	// Passthrough props: everything from parent except internal and sfield-only props
+	// This allows new component props to automatically flow through without updating Sfield
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	const passthroughProps = $derived((): any => {
+		const result: Record<string, unknown> = {};
+		for (const [key, value] of Object.entries(props)) {
+			if (!internalPropKeys.includes(key) && !sfieldOnlyPropKeys.includes(key)) {
+				result[key] = value;
+			}
+		}
+		return result;
+	});
+
+	// Internal props that Sfield computes/manages
+	const internalProps = $derived({
+		field,
+		name,
+		class: hasIssues ? `${classes.input ?? ''} sform-field-error`.trim() : classes.input,
+		labelClass: classes.label,
+		showIssues,
+		onblur: handleBlur,
+		oninput: handleInput
+	});
+
+	// Check input type categories
+	const isTextType = $derived(
+		[
+			'text',
+			'email',
+			'tel',
+			'url',
+			'search',
+			'date',
+			'datetime-local',
+			'time',
+			'month',
+			'week',
+			'color',
+			'hidden',
+			'file'
+		].includes(props.type)
+	);
+</script>
+
+<div class={classes.wrapper}>
+	{#if isTextType}
+		<TextInput
+			{...passthroughProps()}
+			{...internalProps}
+			type={props.type as import('./types.js').TextInputType}
+		/>
+	{:else if props.type === 'password'}
+		<PasswordInput {...passthroughProps()} {...internalProps} />
+	{:else if props.type === 'number'}
+		<NumberInput {...passthroughProps()} {...internalProps} />
+	{:else if props.type === 'textarea'}
+		<TextareaInput {...passthroughProps()} {...internalProps} />
+	{:else if props.type === 'select'}
+		<SelectInput {...passthroughProps()} {...internalProps} />
+	{:else if props.type === 'checkbox'}
+		<CheckboxInput {...passthroughProps()} {...internalProps} />
+	{:else if props.type === 'checkbox-group'}
+		<CheckboxGroupInput {...passthroughProps()} {...internalProps} />
+	{:else if props.type === 'radio'}
+		<RadioInput {...passthroughProps()} {...internalProps} />
+	{:else if props.type === 'range'}
+		<RangeInput {...passthroughProps()} {...internalProps} />
+	{:else if props.type === 'toggle'}
+		<ToggleInput {...passthroughProps()} {...internalProps} />
+	{:else if props.type === 'toggle-options'}
+		<ToggleOptionsInput {...passthroughProps()} {...internalProps} />
+	{:else if props.type === 'masked'}
+		<MaskedInput {...passthroughProps()} {...internalProps} />
+	{/if}
+
+	{#if props.hint}
+		<div class="sform-hint">
+			{#if typeof props.hint === 'string'}
+				{props.hint}
+			{:else}
+				{@render props.hint()}
+			{/if}
+		</div>
+	{/if}
+
+	{#if hasIssues}
+		<div class={classes.messages}>
+			{#each issues as issue, i (i)}
+				<p>{issue.message}</p>
+			{/each}
+		</div>
+	{/if}
+</div>

package/dist/Sform/Sfield.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { RemoteFormFieldValue, TypedSfieldProps } from './types.js';
+declare const Sfield: import("svelte").Component<TypedSfieldProps<RemoteFormFieldValue>, {}, "">;
+type Sfield = ReturnType<typeof Sfield>;
+export default Sfield;

package/dist/Sform/Sform.svelte

@@ -0,0 +1,101 @@
+<script lang="ts" generics="Input extends import('@sveltejs/kit').RemoteFormInput, Output">
+	import type { RemoteFormInstance, ValidateOn, EnhanceCallback } from './types.js';
+	import type { RemoteFormFields } from '@sveltejs/kit';
+	import type { StandardSchemaV1 } from '@standard-schema/spec';
+	import { createSformContext } from './context.svelte.js';
+	import type { HTMLFormAttributes } from 'svelte/elements';
+	import type { Snippet } from 'svelte';
+
+	/**
+	 * Form fields accessor type - provides typed access to all form fields
+	 */
+	type FormFields = RemoteFormFields<Input>;
+
+	let {
+		form,
+		schema,
+		enhance,
+		validateOn = 'blur',
+		class: className,
+		children
+	}: {
+		/** Remote form object from form() API, or the result of form.for(id) */
+		form: RemoteFormInstance<Input, Output>;
+		/** Preflight validation schema (Valibot, Zod, or any StandardSchema) */
+		schema?: StandardSchemaV1<Input, unknown>;
+		/** Enhance callback for custom form submission handling */
+		enhance?: EnhanceCallback<Input>;
+		/** When to validate and show issues: 'blur' (default), 'change', or 'submit' */
+		validateOn?: ValidateOn;
+		/** Form element class */
+		class?: string;
+		/**
+		 * Children snippet receives typed fields for type-safe field access.
+		 * @example
+		 * ```svelte
+		 * <Sform {form}>
+		 *   {#snippet children(fields)}
+		 *     <Sfield field={fields.username} type="text" />
+		 *   {/snippet}
+		 * </Sform>
+		 * ```
+		 */
+		children: Snippet<[FormFields]>;
+	} = $props();
+
+	// Get field names for marking all dirty on submit
+	const getFieldNames = () => {
+		return Object.keys(form.fields).filter((key) => !['value', 'set', 'allIssues'].includes(key));
+	};
+
+	// Trigger validation including untouched fields (for blur mode)
+	const triggerValidation = () => {
+		form.validate({ includeUntouched: true });
+	};
+
+	const context = createSformContext(() => validateOn, getFieldNames, triggerValidation);
+
+	// Apply preflight schema if provided
+	const formWithSchema = $derived(schema ? form.preflight(schema) : form);
+
+	// Apply enhance if provided - returns a minimal object for spreading onto form element
+	const formProps = $derived(enhance ? formWithSchema.enhance(enhance) : formWithSchema);
+
+	// Track previous pending state to detect submission completion
+	let wasPending = $state(false);
+
+	$effect(() => {
+		const isPending = form.pending !== 0;
+		const hasResult = form.result !== undefined;
+		const allIssues =
+			(form.fields as { allIssues?: () => unknown[] | undefined }).allIssues?.() ?? [];
+		const hasNoIssues = allIssues.length === 0;
+
+		// Submission just completed successfully (was pending, now not, has result, no issues)
+		if (wasPending && !isPending && hasResult && hasNoIssues) {
+			context.resetFieldStates();
+		}
+
+		wasPending = isPending;
+	});
+
+	function handleInput() {
+		// Always include untouched to preserve issues on fields that were already validated
+		form.validate({ includeUntouched: true });
+	}
+
+	function handleSubmit() {
+		context.markSubmitted();
+		context.markAllFieldsDirty();
+	}
+</script>
+
+<form
+	{...formProps as unknown as HTMLFormAttributes}
+	class={className}
+	novalidate
+	oninput={handleInput}
+	onsubmit={handleSubmit}
+>
+	{@render (children as Snippet<[FormFields]>)(form.fields)}
+</form>