@abuzareal/contour-ui 0.3.0 → 0.4.0

package/examples/forms/ManualSettingsForm-0.3.0.tsx

@@ -0,0 +1,102 @@
+"use client";
+import { useState } from "react";
+import {
+  Button,
+  RadioGroup,
+  Slider,
+  Switch,
+  TextField,
+} from "@abuzareal/contour-ui";
+import {
+  defaultSettings,
+  readSettings,
+  type FieldErrors,
+  type SaveSettings,
+} from "./settings.js";
+import useSubmission from "./useSubmission.js";
+
+/** Legacy 0.3.0 recipe: these three controls submit through application state. */
+export function ManualSettingsForm({ save }: { save: SaveSettings }) {
+  const [settings, setSettings] = useState(defaultSettings);
+  const [errors, setErrors] = useState<FieldErrors>({});
+  const submission = useSubmission(save);
+  const pending = submission.status === "pending";
+  return (
+    <form
+      noValidate
+      method="post"
+      aria-label="Manual 0.3.0 settings"
+      onReset={() => {
+        submission.cancel();
+        setSettings(defaultSettings);
+        setErrors({});
+      }}
+      onSubmit={async (event) => {
+        event.preventDefault();
+        if (pending) return;
+        const data = new FormData(event.currentTarget);
+        // The generated radio name is not a stable service field; explicitly serialize state.
+        data.set("level", String(settings.level));
+        data.set("contact", settings.contact);
+        if (settings.updates) data.set("updates", "on");
+        else data.delete("updates");
+        const parsed = readSettings(data);
+        setErrors(parsed.errors);
+        if (!parsed.value) {
+          submission.validationFailed();
+          return;
+        }
+        const result = await submission.run(parsed.value);
+        if (result) setErrors(result.fields);
+      }}
+    >
+      <fieldset disabled={pending} aria-busy={pending}>
+        <legend>Notification settings</legend>
+        <TextField
+          name="email"
+          label="Email"
+          type="email"
+          required
+          error={errors.email}
+        />
+        <Switch
+          label="Updates"
+          checked={settings.updates}
+          onChange={(updates) =>
+            setSettings((current) => ({ ...current, updates }))
+          }
+        />
+        <Slider
+          label="Level"
+          value={settings.level}
+          step={5}
+          onChange={(level) =>
+            setSettings((current) => ({ ...current, level }))
+          }
+        />
+        <RadioGroup
+          legend="Contact method"
+          value={settings.contact}
+          onChange={(contact) =>
+            setSettings((current) => ({ ...current, contact }))
+          }
+          options={[
+            { value: "email", label: "Email contact" },
+            { value: "phone", label: "Phone contact" },
+          ]}
+        />
+        <p aria-live="polite">
+          {errors.updates ?? errors.level ?? errors.contact}
+        </p>
+      </fieldset>
+      <p role="status" aria-label="Submission status">
+        {submission.message}
+      </p>
+      <Button type="submit" disabled={pending}>
+        Save settings
+      </Button>
+      <Button type="reset">Reset settings</Button>
+      {pending && <Button onClick={submission.cancel}>Stop waiting</Button>}
+    </form>
+  );
+}

package/examples/forms/NativeSettingsForm.tsx

@@ -0,0 +1,119 @@
+"use client";
+import { useEffect, useRef, useState, type FormEvent } from "react";
+import {
+  Button,
+  RadioGroup,
+  Slider,
+  Switch,
+  TextField,
+} from "@abuzareal/contour-ui";
+import {
+  defaultSettings,
+  readSettings,
+  type FieldErrors,
+  type SaveSettings,
+} from "./settings.js";
+import useSubmission from "./useSubmission.js";
+
+/** Provide a real save adapter. This example never invents a successful response. */
+export function NativeSettingsForm({ save }: { save: SaveSettings }) {
+  const submission = useSubmission(save);
+  const [errors, setErrors] = useState<FieldErrors>({});
+  const email = useRef<HTMLInputElement>(null);
+  const level = useRef<HTMLInputElement>(null);
+  const contact = useRef<HTMLInputElement>(null);
+  const updates = useRef<HTMLButtonElement>(null);
+  const pending = submission.status === "pending";
+  useEffect(() => {
+    if (pending) return;
+    if (errors.email) email.current?.focus();
+    else if (errors.updates) updates.current?.focus();
+    else if (errors.level) level.current?.focus();
+    else if (errors.contact) contact.current?.focus();
+  }, [errors, pending]);
+  const submit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    if (pending) return;
+    const parsed = readSettings(new FormData(event.currentTarget));
+    setErrors(parsed.errors);
+    if (!parsed.value) {
+      submission.validationFailed();
+      return;
+    }
+    const result = await submission.run(parsed.value);
+    if (result) setErrors(result.fields);
+  };
+  return (
+    <form
+      noValidate
+      method="post"
+      onSubmit={submit}
+      onReset={() => {
+        submission.cancel();
+        setErrors({});
+      }}
+      aria-label="Native settings"
+    >
+      <fieldset disabled={pending} aria-busy={pending}>
+        <legend>Notification settings</legend>
+        <TextField
+          ref={email}
+          name="email"
+          maxLength={80}
+          type="email"
+          label="Email"
+          required
+          autoComplete="email"
+          error={errors.email}
+        />
+        <Switch
+          ref={updates}
+          name="updates"
+          label="Updates"
+          defaultChecked={defaultSettings.updates}
+          error={errors.updates}
+        />
+        <Slider
+          ref={level}
+          name="level"
+          label="Level"
+          defaultValue={defaultSettings.level}
+          min={0}
+          max={100}
+          step={5}
+          format={(value) => `${value}%`}
+          error={errors.level}
+        />
+        <RadioGroup
+          name="contact"
+          legend="Contact method"
+          defaultValue={defaultSettings.contact}
+          required
+          error={errors.contact}
+          options={[
+            {
+              value: "email",
+              label: "Email contact",
+              inputProps: { ref: contact },
+            },
+            { value: "phone", label: "Phone contact" },
+          ]}
+        />
+      </fieldset>
+      <p role="status" aria-label="Submission status">
+        {submission.message}
+      </p>
+      <Button type="submit" disabled={pending}>
+        Save settings
+      </Button>
+      <Button type="reset" variant="secondary">
+        Reset settings
+      </Button>
+      {pending && (
+        <Button onClick={submission.cancel} variant="secondary">
+          Stop waiting
+        </Button>
+      )}
+    </form>
+  );
+}

package/examples/forms/settings.ts

@@ -0,0 +1,61 @@
+/** Copy these application contracts with the recipe; adapt them to your real service. */
+export type Settings = {
+  email: string;
+  updates: boolean;
+  level: number;
+  contact: "email" | "phone";
+};
+export type FieldErrors = Partial<Record<keyof Settings, string>>;
+export type SaveResult =
+  { ok: true } | { ok: false; message: string; fields?: FieldErrors };
+export type SaveSettings = (
+  settings: Settings,
+  signal: AbortSignal,
+) => Promise<SaveResult>;
+export const defaultSettings: Settings = {
+  email: "",
+  updates: true,
+  level: 20,
+  contact: "email",
+};
+
+export function readSettings(data: FormData): {
+  value?: Settings;
+  errors: FieldErrors;
+} {
+  const email = data.get("email"),
+    level = data.get("level"),
+    contact = data.get("contact");
+  const errors: FieldErrors = {};
+  if (
+    typeof email !== "string" ||
+    !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email.trim())
+  )
+    errors.email = "Enter a valid email address.";
+  const numeric =
+    typeof level === "string" && level.trim() !== "" ? Number(level) : NaN;
+  if (
+    !Number.isFinite(numeric) ||
+    numeric < 0 ||
+    numeric > 100 ||
+    numeric % 5 !== 0
+  )
+    errors.level = "Choose a level from 0 to 100 in steps of five.";
+  if (contact !== "email" && contact !== "phone")
+    errors.contact = "Choose a contact method.";
+  if (
+    Object.keys(errors).length ||
+    typeof email !== "string" ||
+    (contact !== "email" && contact !== "phone")
+  )
+    return { errors };
+  return {
+    errors,
+    value: {
+      email: email.trim(),
+      updates: data.get("updates") === "on",
+      level: numeric,
+      contact,
+    },
+  };
+}

package/examples/forms/useSubmission.ts

@@ -0,0 +1,77 @@
+"use client";
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { FieldErrors, SaveSettings, Settings } from "./settings.js";
+
+type Submission = {
+  status: "idle" | "pending" | "error" | "success";
+  message: string;
+  fields: FieldErrors;
+};
+const ready: Submission = { status: "idle", message: "", fields: {} };
+
+/** Application example: the injected adapter confirms success; cancellation cannot undo server work. */
+export default function useSubmission(save: SaveSettings) {
+  const active = useRef<AbortController | null>(null);
+  const [submission, setSubmission] = useState(ready);
+  useEffect(
+    () => () => {
+      active.current?.abort();
+      active.current = null;
+    },
+    [],
+  );
+  const cancel = useCallback(() => {
+    const wasPending = active.current !== null;
+    active.current?.abort();
+    active.current = null;
+    setSubmission({
+      ...ready,
+      message: wasPending
+        ? "Stopped waiting for the response. The server may still finish this request."
+        : "",
+    });
+  }, []);
+  const validationFailed = useCallback(() => {
+    if (!active.current)
+      setSubmission({
+        ...ready,
+        status: "error",
+        message: "Check the highlighted fields.",
+      });
+  }, []);
+  const run = async (settings: Settings) => {
+    if (active.current) return null;
+    const operation = new AbortController();
+    active.current = operation;
+    setSubmission({
+      status: "pending",
+      message: "Saving settings…",
+      fields: {},
+    });
+    try {
+      const result = await save(settings, operation.signal);
+      if (active.current !== operation || operation.signal.aborted) return null;
+      const next: Submission = result.ok
+        ? { status: "success", message: "Settings saved.", fields: {} }
+        : {
+            status: "error",
+            message: result.message,
+            fields: result.fields ?? {},
+          };
+      setSubmission(next);
+      return next;
+    } catch {
+      if (active.current !== operation || operation.signal.aborted) return null;
+      const next: Submission = {
+        status: "error",
+        message: "Could not save settings. Try again.",
+        fields: {},
+      };
+      setSubmission(next);
+      return next;
+    } finally {
+      if (active.current === operation) active.current = null;
+    }
+  };
+  return { ...submission, run, cancel, validationFailed };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abuzareal/contour-ui",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "private": false,
   "description": "Editorial React components, themes, restrained motion, and optional Three.js objects.",
   "type": "module",
@@ -16,7 +16,9 @@
     "NEXTJS.md",
     "CONTRACTS.md",
     "PUBLIC-API.md",
-    "COMPOSITION.md"
+    "COMPOSITION.md",
+    "FORMS.md",
+    "examples/forms"
   ],
   "sideEffects": [
     "**/*.css"
@@ -51,7 +53,7 @@
   "scripts": {
     "build": "node scripts/build.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "lint": "oxlint src --deny-warnings",
+    "lint": "oxlint src examples --deny-warnings",
     "test": "node --test tests/*.test.mjs",
     "test:browser": "node --test tests/*.browser.mjs",
     "check:package": "node scripts/check-package.mjs",
@@ -61,7 +63,8 @@
     "test:compat": "node scripts/test-compat.mjs",
     "test:optional": "node scripts/test-optional-consumer.mjs",
     "test:next": "npm run build && node scripts/test-next.mjs",
-    "verify:release": "node scripts/verify-release.mjs"
+    "verify:release": "node scripts/verify-release.mjs",
+    "test:form-recipes": "node scripts/test-form-recipes.mjs"
   },
   "dependencies": {
     "@fontsource-variable/dm-sans": "^5.3.0",