@abuzareal/contour-ui 0.3.0 → 0.5.0

package/examples/forms/HookFormSettingsForm.tsx

@@ -0,0 +1,176 @@
+"use client";
+import { useEffect } from "react";
+import { Controller, useForm } from "react-hook-form";
+import {
+  Button,
+  RadioGroup,
+  Slider,
+  Switch,
+  TextField,
+} from "@abuzareal/contour-ui";
+import {
+  defaultSettings,
+  type SaveSettings,
+  type Settings,
+} from "./settings.js";
+import useSubmission from "./useSubmission.js";
+
+/** RHF is an application dependency. Native fields register; value callbacks use Controller. */
+export function HookFormSettingsForm({ save }: { save: SaveSettings }) {
+  const {
+    register,
+    control,
+    handleSubmit,
+    reset,
+    setError,
+    setFocus,
+    formState: { errors },
+  } = useForm<Settings>({ defaultValues: defaultSettings });
+  const submission = useSubmission(save);
+  const pending = submission.status === "pending";
+  useEffect(() => {
+    if (pending) return;
+    for (const key of ["email", "updates", "level", "contact"] as const) {
+      if (errors[key]) {
+        setFocus(key);
+        break;
+      }
+    }
+  }, [errors, pending, setFocus]);
+  const submit = handleSubmit(async (values) => {
+    if (pending) return;
+    const result = await submission.run({
+      ...values,
+      email: values.email.trim(),
+    });
+    if (result) {
+      for (const key of ["email", "updates", "level", "contact"] as const) {
+        const message = result.fields[key];
+        if (message)
+          setError(key, { type: "server", message }, { shouldFocus: false });
+      }
+    }
+  }, submission.validationFailed);
+  return (
+    <form
+      noValidate
+      method="post"
+      aria-label="Hook Form settings"
+      onSubmit={submit}
+    >
+      <fieldset disabled={pending} aria-busy={pending}>
+        <legend>Notification settings</legend>
+        <TextField
+          maxLength={80}
+          type="email"
+          label="Email"
+          required
+          autoComplete="email"
+          error={errors.email?.message}
+          {...register("email", {
+            required: "Enter an email address.",
+            validate: (value) =>
+              /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value.trim()) ||
+              "Enter a valid email address.",
+          })}
+        />
+        <Controller
+          control={control}
+          name="updates"
+          render={({ field }) => (
+            <Switch
+              ref={field.ref}
+              name={field.name}
+              label="Updates"
+              checked={field.value}
+              onChange={field.onChange}
+              onBlur={field.onBlur}
+              error={errors.updates?.message}
+            />
+          )}
+        />
+        <Controller
+          control={control}
+          name="level"
+          rules={{
+            validate: (value) =>
+              (Number.isFinite(value) && value % 5 === 0) ||
+              "Use steps of five.",
+            min: { value: 0, message: "Choose at least zero." },
+            max: { value: 100, message: "Choose at most 100." },
+          }}
+          render={({ field }) => (
+            <Slider
+              ref={field.ref}
+              name={field.name}
+              label="Level"
+              value={field.value}
+              onChange={field.onChange}
+              onBlur={field.onBlur}
+              min={0}
+              max={100}
+              step={5}
+              format={(value) => `${value}%`}
+              error={errors.level?.message}
+            />
+          )}
+        />
+        <Controller
+          control={control}
+          name="contact"
+          rules={{
+            validate: (value) =>
+              value === "email" ||
+              value === "phone" ||
+              "Choose a contact method.",
+          }}
+          render={({ field }) => (
+            <RadioGroup
+              name={field.name}
+              legend="Contact method"
+              value={field.value}
+              onChange={field.onChange}
+              required
+              error={errors.contact?.message}
+              options={[
+                {
+                  value: "email",
+                  label: "Email contact",
+                  inputProps: { ref: field.ref, onBlur: field.onBlur },
+                },
+                {
+                  value: "phone",
+                  label: "Phone contact",
+                  inputProps: { onBlur: field.onBlur },
+                },
+              ]}
+            />
+          )}
+        />
+      </fieldset>
+      <p role="status" aria-label="Submission status">
+        {submission.message}
+      </p>
+      <Button type="submit" disabled={pending}>
+        Save settings
+      </Button>
+      <Button
+        type="button"
+        variant="secondary"
+        onClick={(event) => {
+          submission.cancel();
+          // Native reset synchronizes registered counters/auto-resize; RHF resets its own state.
+          event.currentTarget.form?.reset();
+          reset(defaultSettings);
+        }}
+      >
+        Reset settings
+      </Button>
+      {pending && (
+        <Button onClick={submission.cancel} variant="secondary">
+          Stop waiting
+        </Button>
+      )}
+    </form>
+  );
+}

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.5.0",
   "private": false,
   "description": "Editorial React components, themes, restrained motion, and optional Three.js objects.",
   "type": "module",
@@ -16,7 +16,12 @@
     "NEXTJS.md",
     "CONTRACTS.md",
     "PUBLIC-API.md",
-    "COMPOSITION.md"
+    "COMPOSITION.md",
+    "FORMS.md",
+    "examples/forms",
+    "OVERLAYS.md",
+    "STYLING.md",
+    "SIZE.md"
   ],
   "sideEffects": [
     "**/*.css"
@@ -46,24 +51,42 @@
     "./reset.css": "./dist/reset.css",
     "./tokens.css": "./dist/tokens.css",
     "./fonts.css": "./dist/fonts.css",
-    "./fonts-latin.css": "./dist/fonts-latin.css"
+    "./fonts-latin.css": "./dist/fonts-latin.css",
+    "./scoped.css": "./dist/scoped.css",
+    "./scoped-tokens.css": "./dist/scoped-tokens.css",
+    "./minimal-reset.css": "./dist/minimal-reset.css",
+    "./tokens.json": "./dist/tokens.json",
+    "./actions.css": "./dist/actions.css",
+    "./forms.css": "./dist/forms.css",
+    "./navigation.css": "./dist/navigation.css",
+    "./data-display.css": "./dist/data-display.css",
+    "./feedback.css": "./dist/feedback.css",
+    "./overlays.css": "./dist/overlays.css",
+    "./effects.css": "./dist/effects.css"
   },
   "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",
-    "validate": "npm run typecheck && npm run lint && npm run build && npm test && npm run test:browser && npm run check:package",
+    "validate": "npm run check:styles && npm run typecheck && npm run lint && npm run build && npm test && npm run test:browser && npm run check:package",
     "prepublishOnly": "node scripts/verify-release.mjs",
     "test:consumer": "node scripts/test-consumer.mjs",
     "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",
+    "build:styles": "node scripts/build-styles.mjs",
+    "measure:size": "node scripts/measure-size.mjs",
+    "check:size": "node scripts/measure-size.mjs --check",
+    "check:api-docs": "node scripts/check-api-docs.mjs",
+    "check:styles": "node scripts/build-styles.mjs --check"
   },
   "dependencies": {
+    "@floating-ui/dom": "1.8.0",
     "@fontsource-variable/dm-sans": "^5.3.0",
     "@fontsource-variable/space-grotesk": "^5.3.0",
     "@fontsource/dm-mono": "^5.3.0",
@@ -92,6 +115,7 @@
     "jsdom": "^30.1.2",
     "lenis": "^1.3.26",
     "oxlint": "^1.81.0",
+    "postcss": "8.5.29",
     "react": "18.3.1",
     "react-dom": "18.3.1",
     "three": "^0.186.1",