@abuzareal/contour-ui 0.5.0 → 0.6.1

package/examples/onboarding/SettingsForm.jsx

@@ -0,0 +1,30 @@
+// Generated from SettingsForm.tsx by scripts/build-onboarding.mjs.
+import { useRef, useState } from "react";
+import { Button, Checkbox, Combobox, TextField } from "@abuzareal/contour-ui";
+const options = [
+    { value: "atlas", label: "Atlas" },
+    { value: "field", label: "Field notes" },
+];
+/** Local inspection only. Validate and authorize real submissions on the server. */
+export default function SettingsForm() {
+    const [payload, setPayload] = useState("");
+    const name = useRef(null);
+    return (<section aria-label="Settings example">
+      <h2>Project settings</h2>
+      <p>This form inspects local values; it does not save them.</p>
+      <form onSubmit={(event) => {
+            event.preventDefault();
+            setPayload(JSON.stringify(Object.fromEntries(new FormData(event.currentTarget))));
+        }} onReset={() => setPayload("")}>
+        <TextField ref={name} label="Name" name="name" defaultValue="Ada" required/>
+        <Combobox label="Project" name="project" options={options} defaultValue="atlas" required/>
+        <Checkbox label="Allow updates" name="updates" defaultChecked/>
+        <Button type="submit">Inspect values</Button>
+        <Button type="reset" variant="secondary">
+          Reset form
+        </Button>
+      </form>
+      <output aria-label="Form values">{payload}</output>
+      <Button onClick={() => name.current?.focus()}>Focus name</Button>
+    </section>);
+}

package/examples/onboarding/SettingsForm.tsx

@@ -0,0 +1,50 @@
+import { useRef, useState } from "react";
+import { Button, Checkbox, Combobox, TextField } from "@abuzareal/contour-ui";
+const options = [
+  { value: "atlas", label: "Atlas" },
+  { value: "field", label: "Field notes" },
+];
+/** Local inspection only. Validate and authorize real submissions on the server. */
+export default function SettingsForm() {
+  const [payload, setPayload] = useState("");
+  const name = useRef<HTMLInputElement>(null);
+  return (
+    <section aria-label="Settings example">
+      <h2>Project settings</h2>
+      <p>This form inspects local values; it does not save them.</p>
+      <form
+        onSubmit={(event) => {
+          event.preventDefault();
+          setPayload(
+            JSON.stringify(
+              Object.fromEntries(new FormData(event.currentTarget)),
+            ),
+          );
+        }}
+        onReset={() => setPayload("")}
+      >
+        <TextField
+          ref={name}
+          label="Name"
+          name="name"
+          defaultValue="Ada"
+          required
+        />
+        <Combobox
+          label="Project"
+          name="project"
+          options={options}
+          defaultValue="atlas"
+          required
+        />
+        <Checkbox label="Allow updates" name="updates" defaultChecked />
+        <Button type="submit">Inspect values</Button>
+        <Button type="reset" variant="secondary">
+          Reset form
+        </Button>
+      </form>
+      <output aria-label="Form values">{payload}</output>
+      <Button onClick={() => name.current?.focus()}>Focus name</Button>
+    </section>
+  );
+}

package/examples/optional/LazyScene.tsx

@@ -0,0 +1,78 @@
+"use client";
+import { lazy, Suspense, useState } from "react";
+import {
+  Button,
+  SceneBoundary,
+  useMotionPreference,
+} from "@abuzareal/contour-ui";
+import "./optional.css";
+const Sculpture = lazy(() =>
+  import("@abuzareal/contour-ui/three").then((module) => ({
+    default: module.Sculpture,
+  })),
+);
+export function LazyScene() {
+  const [loaded, setLoaded] = useState(false),
+    [paused, setPaused] = useState(false);
+  const reducedMotion = useMotionPreference();
+  return (
+    <figure>
+      <div className="recipe-scene-visual">
+        <div
+          className="recipe-scene-fallback"
+          role="img"
+          aria-label="Three interlocking sculptural links"
+        >
+          <svg aria-hidden="true" viewBox="0 0 300 180">
+            <g fill="none" stroke="currentColor" strokeWidth="16">
+              <ellipse
+                cx="95"
+                cy="78"
+                rx="52"
+                ry="29"
+                transform="rotate(-25 95 78)"
+              />
+              <ellipse
+                cx="165"
+                cy="95"
+                rx="52"
+                ry="29"
+                transform="rotate(25 165 95)"
+              />
+              <ellipse
+                cx="215"
+                cy="62"
+                rx="40"
+                ry="25"
+                transform="rotate(-35 215 62)"
+              />
+            </g>
+          </svg>
+        </div>
+        {loaded && (
+          <div className="recipe-scene-layer" aria-hidden="true">
+            <SceneBoundary>
+              <Suspense fallback={null}>
+                <Sculpture motionEnabled={!paused && !reducedMotion} />
+              </Suspense>
+            </SceneBoundary>
+          </div>
+        )}
+      </div>
+      <figcaption>
+        Three linked forms. The static study remains available if 3D cannot
+        load.
+      </figcaption>
+      <Button onClick={() => setLoaded(true)} disabled={loaded}>
+        Load 3D study
+      </Button>
+      <button
+        type="button"
+        aria-pressed={paused}
+        onClick={() => setPaused((value) => !value)}
+      >
+        Pause motion
+      </button>
+    </figure>
+  );
+}

package/examples/optional/OptionalSmoothScroll.tsx

@@ -0,0 +1,25 @@
+"use client";
+import { lazy, Suspense, useState } from "react";
+import { useMotionPreference } from "@abuzareal/contour-ui";
+const SmoothScrollOwner = lazy(() => import("./SmoothScrollOwner.js"));
+/** Mount at most one owner for the page; ordinary native scrolling works before opt-in. */
+export function OptionalSmoothScroll() {
+  const [enabled, setEnabled] = useState(false);
+  const reducedMotion = useMotionPreference();
+  return (
+    <>
+      <button
+        type="button"
+        aria-pressed={enabled}
+        onClick={() => setEnabled((value) => !value)}
+      >
+        Smooth scrolling
+      </button>
+      {enabled && !reducedMotion && (
+        <Suspense fallback={null}>
+          <SmoothScrollOwner enabled />
+        </Suspense>
+      )}
+    </>
+  );
+}

package/examples/optional/SmoothScrollOwner.tsx

@@ -0,0 +1,7 @@
+"use client";
+import { useSmoothScroll } from "@abuzareal/contour-ui/scroll";
+import "lenis/dist/lenis.css";
+export default function SmoothScrollOwner({ enabled }: { enabled: boolean }) {
+  useSmoothScroll(enabled);
+  return null;
+}

package/examples/optional/optional.css

@@ -0,0 +1,25 @@
+.recipe-scene-visual {
+  position: relative;
+  block-size: 18rem;
+  overflow: hidden;
+}
+.recipe-scene-fallback,
+.recipe-scene-layer {
+  position: absolute;
+  inset: 0;
+}
+.recipe-scene-fallback {
+  display: grid;
+  place-items: center;
+}
+.recipe-scene-fallback svg {
+  inline-size: min(100%, 24rem);
+  block-size: 100%;
+}
+.recipe-scene-layer .contour-sculpture-canvas {
+  position: absolute;
+  inset: 0;
+}
+.recipe-scene-visual:has([data-state="ready"]) .recipe-scene-fallback {
+  visibility: hidden;
+}

package/examples/recipes/AsyncProjectPicker.tsx

@@ -0,0 +1,82 @@
+"use client";
+import { useCallback, useMemo, useState } from "react";
+import { Combobox, type ComboboxOption } from "@abuzareal/contour-ui";
+import { useRemoteResource, type Loader } from "./useRemoteResource.js";
+
+export type ProjectSearch = Loader<string, readonly ComboboxOption[]>;
+export type AsyncProjectPickerProps = {
+  /** Stable function: validate response IDs/labels before resolving. */
+  searchProjects: ProjectSearch;
+  initialProject?: ComboboxOption;
+  onProjectChange?: (project: ComboboxOption | null) => void;
+};
+
+/** Copy this into the application; fetching and selected-record retention are not library features. */
+export function AsyncProjectPicker({
+  searchProjects,
+  initialProject,
+  onProjectChange,
+}: AsyncProjectPickerProps) {
+  const [query, setQuery] = useState(initialProject?.label ?? "");
+  const [selected, setSelected] = useState<ComboboxOption | null>(
+    initialProject ?? null,
+  );
+  const search = useCallback(
+    async (text: string, signal: AbortSignal) => {
+      const matches = await searchProjects(text, signal);
+      if (!signal.aborted)
+        setSelected((previous) =>
+          previous
+            ? (matches.find((option) => option.value === previous.value) ??
+              previous)
+            : null,
+        );
+      return matches;
+    },
+    [searchProjects],
+  );
+  const result = useRemoteResource(query, search);
+  // Never display the previous query's rows as if they matched this query.
+  const matches = useMemo(
+    () =>
+      !result.loading && !result.error && result.appliedQuery === query
+        ? (result.data ?? [])
+        : [],
+    [result.loading, result.error, result.appliedQuery, result.data, query],
+  );
+  // Bounded retention: keep the current result set and one selected record, not an unbounded cache.
+  const options = useMemo(
+    () =>
+      selected && !matches.some((option) => option.value === selected.value)
+        ? [...matches, selected]
+        : matches,
+    [matches, selected],
+  );
+  return (
+    <Combobox
+      label="Project"
+      name="project"
+      required
+      options={options}
+      filteredOptions={matches}
+      value={selected?.value ?? null}
+      onValueChange={(value) => {
+        const next = options.find((option) => option.value === value) ?? null;
+        setSelected(next);
+        onProjectChange?.(next);
+      }}
+      inputValue={query}
+      onInputValueChange={setQuery}
+      loading={result.loading}
+      searchError={
+        result.error === "permission"
+          ? "You do not have permission to search projects."
+          : result.error
+            ? "Projects could not be loaded. Try again."
+            : undefined
+      }
+      onRetry={result.retry}
+      hint="Choose a project from the results. Typed text is not a submitted project."
+    />
+  );
+}

package/examples/recipes/DeleteProjectConfirmation.tsx

@@ -0,0 +1,97 @@
+"use client";
+import { useEffect, useRef, useState } from "react";
+import { Button, Dialog } from "@abuzareal/contour-ui";
+
+export type DeleteProjectConfirmationProps = {
+  project: { id: string; name: string };
+  /** Resolve only after server confirmation. Authorization/idempotency belong on the server. */
+  deleteProject: (id: string, signal: AbortSignal) => Promise<void>;
+  onDeleted?: (id: string) => void;
+};
+
+/** Native Dialog composition; no AlertDialog export or simulated successful deletion. */
+export function DeleteProjectConfirmation(
+  props: DeleteProjectConfirmationProps,
+) {
+  // Target identity owns the whole interaction; changing projects cannot reuse a pending confirmation.
+  return <ProjectDeletion key={props.project.id} {...props} />;
+}
+
+function ProjectDeletion({
+  project,
+  deleteProject,
+  onDeleted,
+}: DeleteProjectConfirmationProps) {
+  const [open, setOpen] = useState(false),
+    [pending, setPending] = useState(false),
+    [error, setError] = useState("");
+  const cancel = useRef<HTMLButtonElement>(null);
+  const active = useRef<AbortController | null>(null);
+  // A changed target or unmount invalidates the old operation, even if its transport ignores abort.
+  useEffect(() => {
+    return () => {
+      active.current?.abort();
+      active.current = null;
+    };
+  }, [project.id]);
+  const dismiss = () => {
+    active.current?.abort();
+    active.current = null;
+    setPending(false);
+    setOpen(false);
+    setError("");
+  };
+  const remove = async () => {
+    if (active.current) return;
+    const controller = new AbortController();
+    active.current = controller;
+    setPending(true);
+    setError("");
+    try {
+      await deleteProject(project.id, controller.signal);
+    } catch {
+      if (controller.signal.aborted || active.current !== controller) return;
+      active.current = null;
+      setPending(false);
+      setError(
+        "The deletion could not be confirmed. Check the project before retrying.",
+      );
+      return;
+    }
+    if (controller.signal.aborted || active.current !== controller) return;
+    active.current = null;
+    setPending(false);
+    setOpen(false);
+    onDeleted?.(project.id);
+  };
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>Delete {project.name}</Button>
+      <Dialog
+        title={`Delete ${project.name}?`}
+        open={open}
+        onClose={dismiss}
+        initialFocus={cancel}
+        description="Deleting this project permanently removes its saved settings. This action cannot be undone."
+        closeButtonProps={{ "aria-label": "Cancel deletion" }}
+        footer={
+          <>
+            <Button ref={cancel} variant="secondary" onClick={dismiss}>
+              Keep project
+            </Button>
+            <Button disabled={pending} onClick={() => void remove()}>
+              {pending ? "Deleting…" : "Permanently delete project"}
+            </Button>
+          </>
+        }
+      >
+        <p role="status">
+          {pending
+            ? "Waiting for server confirmation. Closing stops waiting; the server may still complete the deletion."
+            : "No action is taken until you confirm."}
+        </p>
+        {error && <p role="alert">{error}</p>}
+      </Dialog>
+    </>
+  );
+}

package/examples/recipes/InputCompositions.tsx

@@ -0,0 +1,49 @@
+"use client";
+import { useRef, useState } from "react";
+import { TextField } from "@abuzareal/contour-ui";
+
+/** Native number behavior is sufficient for a bounded integer quantity, not locale-aware money. */
+export function QuantityField() {
+  return (
+    <TextField
+      leadingIcon={<span aria-hidden="true">#</span>}
+      label="Seats"
+      name="seats"
+      type="number"
+      min={1}
+      max={100}
+      step={1}
+      defaultValue={1}
+      trailing={<span aria-hidden="true">seats</span>}
+      hint="Whole number, 1–100 seats."
+    />
+  );
+}
+
+/** Keep the same native input mounted so form identity and password-manager hooks survive toggling. */
+export function PasswordField() {
+  const [visible, setVisible] = useState(false);
+  const input = useRef<HTMLInputElement>(null);
+  return (
+    <TextField
+      ref={input}
+      label="Password"
+      name="password"
+      type={visible ? "text" : "password"}
+      autoComplete="current-password"
+      trailing={
+        <button
+          type="button"
+          aria-label="Show password"
+          aria-pressed={visible}
+          onClick={() => {
+            setVisible((previous) => !previous);
+            input.current?.focus();
+          }}
+        >
+          {visible ? "Hide" : "Show"}
+        </button>
+      }
+    />
+  );
+}