@ilha/store 0.1.3 → 0.2.0

package/README.md

@@ -2,6 +2,8 @@
 
 A zustand-shaped reactive store for [Ilha](https://github.com/ilhajs/ilha) islands. Backed by [alien-signals](https://github.com/stackblitz/alien-signals) — the same engine that powers `ilha` core state — for shared global state that lives outside any single island.
 
+Includes a `/form` subpath with unopinionated, type-safe form helpers built on [Standard Schema](https://standardschema.dev) — works with Zod, Valibot, ArkType, or any compatible library.
+
 ---
 
 ## Installation
@@ -12,6 +14,19 @@ bun add @ilha/store
 
 ---
 
+## When to Use
+
+`ilha` state is **island-local** — signals are scoped to a single component instance. Use `@ilha/store` when you need state that is:
+
+- **Shared across multiple islands** — e.g. a cart, auth session, or theme
+- **Updated from outside an island** — e.g. from a WebSocket handler or a global event bus
+- **Persisted or derived globally** — e.g. synced to `localStorage` via a `subscribe` listener
+- **Form state** — pair `createStore` with `@ilha/store/form` helpers for typed validation, error mapping, and submission handling
+
+For state that only one island reads and writes, prefer `ilha`'s built-in `.state()`.
+
+---
+
 ## Quick Start
 
 ```ts
@@ -25,18 +40,6 @@ store.getState(); // → { count: 1 }
 
 ---
 
-## When to Use
-
-`ilha` state is **island-local** — signals are scoped to a single component instance. Use `@ilha/store` when you need state that is:
-
-- **Shared across multiple islands** — e.g. a cart, auth session, or theme
-- **Updated from outside an island** — e.g. from a WebSocket handler or a global event bus
-- **Persisted or derived globally** — e.g. synced to `localStorage` via a `subscribe` listener
-
-For state that only one island reads and writes, prefer `ilha`'s built-in `.state()`.
-
----
-
 ## API
 
 ### `createStore(initialState, actions?)`
@@ -132,7 +135,7 @@ const unsub = store.subscribe(
 Reactively renders a store-driven HTML string into a DOM element whenever state changes. The render function may return a plain string or an `html\`\`` tagged template.
 
 ```ts
-import { html } from "@ilha/store";
+import { html } from "ilha";
 
 const unsub = store.bind(
   document.getElementById("counter")!,
@@ -161,8 +164,8 @@ store.bind(
 The most common pattern is reading the store inside an island's `.effect()` and calling `store.subscribe()` to drive reactive re-renders:
 
 ```ts
-import { createStore, html } from "@ilha/store";
-import ilha from "ilha";
+import { createStore } from "@ilha/store";
+import ilha, { html } from "ilha";
 
 export const cartStore = createStore({ items: [] as string[] }, (set, get) => ({
   add(item: string) {
@@ -192,6 +195,116 @@ export const CartIsland = ilha
 
 ---
 
+## Forms — `@ilha/store/form`
+
+Three small helpers for building typed, validated forms with any [Standard Schema](https://standardschema.dev)-compatible library. They are **unopinionated** — you compose them with `createStore` however you like; nothing is imposed about your form's state shape.
+
+```ts
+import { extractFormData, validateWithSchema, issuesToErrors } from "@ilha/store/form";
+```
+
+### `extractFormData(source)`
+
+Turns an `HTMLFormElement` (or a `FormData` instance) into a plain object. Handles the `string` vs `string[]` dance correctly: single fields stay scalar, repeated keys (checkbox groups, multi-selects) collapse to arrays. File inputs pass through as `File` values.
+
+```ts
+const data = extractFormData(event.target as HTMLFormElement);
+// → { email: "ada@example.com", role: ["admin", "editor"] }
+```
+
+### `validateWithSchema(schema, data)`
+
+Runs a Standard Schema synchronously and returns a discriminated union — **never throws**.
+
+```ts
+const result = validateWithSchema(SignInSchema, data);
+if (result.ok) {
+  result.data; // ← fully typed schema output
+} else {
+  result.issues; // ← ReadonlyArray<StandardSchemaV1.Issue>
+}
+```
+
+If your schema has async refinements (e.g. server-side uniqueness checks), use `validateWithSchemaAsync` instead — same return shape, always returns a `Promise`.
+
+### `issuesToErrors(issues)`
+
+Flattens Standard Schema issues into a per-field error map keyed by dot-separated path. Form-level errors (issues with no path) land under the `""` key.
+
+```ts
+issuesToErrors([
+  { message: "Required", path: ["email"] },
+  { message: "Invalid", path: ["user", "email"] },
+]);
+// → { email: ["Required"], "user.email": ["Invalid"] }
+```
+
+---
+
+### Full example — contact form
+
+```ts
+import { createStore } from "@ilha/store";
+import { extractFormData, validateWithSchema, issuesToErrors } from "@ilha/store/form";
+import type { FormErrors } from "@ilha/store/form";
+import ilha, { html } from "ilha";
+import { z } from "zod";
+
+const ContactSchema = z.object({
+  name: z.string().min(1, "Name is required"),
+  email: z.email("Invalid email"),
+  message: z.string().min(10, "Message must be at least 10 characters"),
+});
+
+const formStore = createStore({ errors: {} as FormErrors }, (set) => ({
+  submit(event: SubmitEvent) {
+    const result = validateWithSchema(
+      ContactSchema,
+      extractFormData(event.target as HTMLFormElement),
+    );
+    if (result.ok) {
+      console.log("submitting:", result.data);
+      set({ errors: {} });
+    } else {
+      set({ errors: issuesToErrors(result.issues) });
+    }
+  },
+}));
+
+export default ilha
+  .on("form@submit", ({ event }) => {
+    event.preventDefault();
+    formStore.getState().submit(event);
+  })
+  .render(() => {
+    const errors = formStore.getState().errors;
+    return html`
+      <form>
+        <label>
+          Name
+          <input name="name" />
+          ${errors.name ? html`<p role="alert">${errors.name.join(", ")}</p>` : ""}
+        </label>
+        <label>
+          Email
+          <input name="email" type="email" />
+          ${errors.email ? html`<p role="alert">${errors.email.join(", ")}</p>` : ""}
+        </label>
+        <label>
+          Message
+          <textarea name="message"></textarea>
+          ${errors.message ? html`<p role="alert">${errors.message.join(", ")}</p>` : ""}
+        </label>
+        <button type="submit">Send</button>
+      </form>
+    `;
+  });
+```
+
+The store holds errors, the schema drives types, and `extractFormData` + `validateWithSchema` + `issuesToErrors` form a straight pipeline from DOM to error state.
+
+---
+
 ## TypeScript
 
 Key exported types:
@@ -206,6 +319,12 @@ import type {
   RenderResult, // string | RawHtml
   Unsub, // () => void
 } from "@ilha/store";
+
+import type {
+  StandardSchemaV1, // the Standard Schema spec interface
+  FormResult, // discriminated union: { ok: true, data } | { ok: false, issues }
+  FormErrors, // Record<string, string[]>
+} from "@ilha/store/form";
 ```
 
 ---

package/dist/form.d.ts

@@ -0,0 +1,102 @@
+//#region src/form.d.ts
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+  interface Props<Input = unknown, Output = Input> {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+    readonly types?: Types<Input, Output> | undefined;
+  }
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+  interface SuccessResult<Output> {
+    readonly value: Output;
+    readonly issues?: undefined;
+  }
+  interface FailureResult {
+    readonly issues: ReadonlyArray<Issue>;
+  }
+  interface Issue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+  interface PathSegment {
+    readonly key: PropertyKey;
+  }
+  interface Types<Input, Output> {
+    readonly input: Input;
+    readonly output: Output;
+  }
+  type InferInput<S extends StandardSchemaV1> = NonNullable<S["~standard"]["types"]>["input"];
+  type InferOutput<S extends StandardSchemaV1> = NonNullable<S["~standard"]["types"]>["output"];
+}
+/**
+ * Discriminated union result from validating form values.
+ * Never throws — validation failures are returned as data.
+ */
+type FormResult<T> = {
+  ok: true;
+  data: T;
+} | {
+  ok: false;
+  issues: ReadonlyArray<StandardSchemaV1.Issue>;
+};
+/**
+ * Per-field error map. Keys are dot-separated field paths matching the
+ * schema's issue path (e.g. `"user.email"`). Values are arrays of messages
+ * so multiple failing rules on a single field are all surfaced.
+ */
+type FormErrors = Record<string, string[]>;
+/**
+ * Extract a plain object from a `<form>` element or `FormData` instance.
+ * Duplicate keys (checkbox groups, `<select multiple>`) collapse to a
+ * `FormDataEntryValue[]`; single keys stay as `FormDataEntryValue`. File
+ * inputs are preserved as `File` values — pass them straight through to
+ * your schema.
+ *
+ * @example
+ * ilha.on("form@submit", ({ event }) => {
+ *   event.preventDefault();
+ *   const data = extractFormData(event.target as HTMLFormElement);
+ *   const result = validateWithSchema(SignInSchema, data);
+ *   // ...
+ * });
+ */
+declare function extractFormData(source: HTMLFormElement | FormData): Record<string, unknown>;
+/**
+ * Run a Standard Schema synchronously and return a discriminated union.
+ * Never throws. If the schema returns a Promise (i.e. it has async refinements),
+ * a warning is logged and a failure result is returned — pair it with an
+ * async schema by awaiting `schema["~standard"].validate(...)` directly instead.
+ *
+ * Compatible with Zod, Valibot, ArkType, and any other Standard Schema library.
+ *
+ * @example
+ * const result = validateWithSchema(SignInSchema, extractFormData(form));
+ * if (result.ok) {
+ *   formStore.setState({ data: result.data, errors: {} });
+ * } else {
+ *   formStore.setState({ errors: issuesToErrors(result.issues) });
+ * }
+ */
+declare function validateWithSchema<S extends StandardSchemaV1>(schema: S, data: unknown): FormResult<StandardSchemaV1.InferOutput<S>>;
+/**
+ * Async variant of {@link validateWithSchema}. Always returns a Promise,
+ * supports both sync and async schemas. Use this when your schema has
+ * async refinements (e.g. uniqueness checks against a server).
+ */
+declare function validateWithSchemaAsync<S extends StandardSchemaV1>(schema: S, data: unknown): Promise<FormResult<StandardSchemaV1.InferOutput<S>>>;
+/**
+ * Flatten Standard Schema issues into a per-field error map keyed by
+ * dot-separated path. Issues without a path are grouped under the empty
+ * string key — useful for form-level errors.
+ *
+ * @example
+ * // issues: [{ message: "Invalid email", path: ["email"] }]
+ * issuesToErrors(issues);
+ * // => { email: ["Invalid email"] }
+ */
+declare function issuesToErrors(issues: ReadonlyArray<StandardSchemaV1.Issue>): FormErrors;
+//#endregion
+export { FormErrors, FormResult, StandardSchemaV1, extractFormData, issuesToErrors, validateWithSchema, validateWithSchemaAsync };

package/dist/form.js

@@ -0,0 +1,117 @@
+//#region src/form.ts
+/**
+* Extract a plain object from a `<form>` element or `FormData` instance.
+* Duplicate keys (checkbox groups, `<select multiple>`) collapse to a
+* `FormDataEntryValue[]`; single keys stay as `FormDataEntryValue`. File
+* inputs are preserved as `File` values — pass them straight through to
+* your schema.
+*
+* @example
+* ilha.on("form@submit", ({ event }) => {
+*   event.preventDefault();
+*   const data = extractFormData(event.target as HTMLFormElement);
+*   const result = validateWithSchema(SignInSchema, data);
+*   // ...
+* });
+*/
+function extractFormData(source) {
+	const data = source instanceof FormData ? source : new FormData(source);
+	const result = Object.create(null);
+	for (const key of new Set(data.keys())) {
+		const values = data.getAll(key);
+		result[key] = values.length === 1 ? values[0] : values;
+	}
+	return result;
+}
+/**
+* Run a Standard Schema synchronously and return a discriminated union.
+* Never throws. If the schema returns a Promise (i.e. it has async refinements),
+* a warning is logged and a failure result is returned — pair it with an
+* async schema by awaiting `schema["~standard"].validate(...)` directly instead.
+*
+* Compatible with Zod, Valibot, ArkType, and any other Standard Schema library.
+*
+* @example
+* const result = validateWithSchema(SignInSchema, extractFormData(form));
+* if (result.ok) {
+*   formStore.setState({ data: result.data, errors: {} });
+* } else {
+*   formStore.setState({ errors: issuesToErrors(result.issues) });
+* }
+*/
+function validateWithSchema(schema, data) {
+	let result;
+	try {
+		result = schema["~standard"].validate(data);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : "Schema validation threw: " + String(error);
+		console.warn("[@ilha/store/form] Schema validation threw an exception:", message);
+		return {
+			ok: false,
+			issues: [{ message }]
+		};
+	}
+	if (result instanceof Promise) {
+		console.warn("[@ilha/store/form] Schema validation returned a Promise. validateWithSchema is synchronous — use validateWithSchemaAsync or call schema['~standard'].validate(...) directly for async schemas.");
+		result.catch(() => {});
+		return {
+			ok: false,
+			issues: [{ message: "Async schema validation is not supported by validateWithSchema." }]
+		};
+	}
+	if (result.issues !== void 0) return {
+		ok: false,
+		issues: result.issues
+	};
+	return {
+		ok: true,
+		data: result.value
+	};
+}
+/**
+* Async variant of {@link validateWithSchema}. Always returns a Promise,
+* supports both sync and async schemas. Use this when your schema has
+* async refinements (e.g. uniqueness checks against a server).
+*/
+async function validateWithSchemaAsync(schema, data) {
+	let result;
+	try {
+		result = await schema["~standard"].validate(data);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : "Schema validation threw: " + String(error);
+		console.warn("[@ilha/store/form] Schema validation threw an exception:", message);
+		return {
+			ok: false,
+			issues: [{ message }]
+		};
+	}
+	if (result.issues !== void 0) return {
+		ok: false,
+		issues: result.issues
+	};
+	return {
+		ok: true,
+		data: result.value
+	};
+}
+/**
+* Flatten Standard Schema issues into a per-field error map keyed by
+* dot-separated path. Issues without a path are grouped under the empty
+* string key — useful for form-level errors.
+*
+* @example
+* // issues: [{ message: "Invalid email", path: ["email"] }]
+* issuesToErrors(issues);
+* // => { email: ["Invalid email"] }
+*/
+function issuesToErrors(issues) {
+	const errors = Object.create(null);
+	for (const issue of issues) {
+		const path = issue.path?.map((p) => typeof p === "object" ? String(p.key) : String(p)).join(".") ?? "";
+		if (!errors[path]) errors[path] = [];
+		errors[path].push(issue.message);
+	}
+	return errors;
+}
+//#endregion
+export { extractFormData, issuesToErrors, validateWithSchema, validateWithSchemaAsync };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ilha/store",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Typed store.",
   "license": "MIT",
   "author": "Ryuz <ryuzer@proton.me>",
@@ -16,6 +16,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./form": {
+      "types": "./dist/form.d.ts",
+      "import": "./dist/form.js"
     }
   },
   "scripts": {
@@ -25,7 +29,7 @@
   },
   "dependencies": {
     "alien-signals": "3.1.2",
-    "ilha": "0.3.0"
+    "ilha": "0.3.1"
   },
   "devDependencies": {
     "zod": "^4.3.6"