@abuzareal/contour-ui 0.5.0 → 0.6.0

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>
+      }
+    />
+  );
+}

package/examples/recipes/RemoteRecordsTable.tsx

@@ -0,0 +1,256 @@
+"use client";
+import { useCreateAtom, useSelector } from "@tanstack/react-store";
+import {
+  createColumnHelper,
+  functionalUpdate,
+  rowPaginationFeature,
+  rowSortingFeature,
+  tableFeatures,
+  useTable,
+  type PaginationState,
+  type SortingState,
+} from "@tanstack/react-table";
+import { Button, Table, TextField } from "@abuzareal/contour-ui";
+import { useRemoteResource, type Loader } from "./useRemoteResource.js";
+
+export type RecordRow = { id: string; name: string; owner: string };
+export type RecordsQuery = {
+  filter: string;
+  sorting: SortingState;
+  pagination: PaginationState;
+};
+export type RecordsPage = {
+  rows: readonly RecordRow[];
+  total: number;
+  unfilteredTotal: number;
+};
+export type LoadRecords = Loader<RecordsQuery, RecordsPage>;
+const features = tableFeatures({ rowSortingFeature, rowPaginationFeature });
+const column = createColumnHelper<typeof features, RecordRow>();
+const columns = column.columns([
+  column.accessor("name", { header: "Name" }),
+  column.accessor("owner", { header: "Owner" }),
+]);
+
+/** Validate parsed JSON at the application's service boundary before giving it to this recipe. */
+export function parseRecordsPage(
+  value: unknown,
+  pageSize: number,
+): RecordsPage {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    !("rows" in value) ||
+    !Array.isArray(value.rows) ||
+    !("total" in value) ||
+    !("unfilteredTotal" in value)
+  )
+    throw new Error("Invalid records response");
+  const { rows, total, unfilteredTotal } = value;
+  if (
+    typeof total !== "number" ||
+    !Number.isSafeInteger(total) ||
+    total < 0 ||
+    typeof unfilteredTotal !== "number" ||
+    !Number.isSafeInteger(unfilteredTotal) ||
+    unfilteredTotal < total ||
+    rows.length > pageSize ||
+    rows.length > total
+  )
+    throw new Error("Invalid records count");
+  const ids = new Set<string>();
+  const parsed: RecordRow[] = rows.map((row: unknown) => {
+    if (
+      !row ||
+      typeof row !== "object" ||
+      !("id" in row) ||
+      typeof row.id !== "string" ||
+      !row.id ||
+      ids.has(row.id) ||
+      !("name" in row) ||
+      typeof row.name !== "string" ||
+      !("owner" in row) ||
+      typeof row.owner !== "string"
+    )
+      throw new Error("Invalid record");
+    ids.add(row.id);
+    return { id: row.id, name: row.name, owner: row.owner };
+  });
+  return { rows: parsed, total, unfilteredTotal };
+}
+
+/** The service performs sorting/filtering/pagination. This is not local DataTable sorting. */
+export function RemoteRecordsTable({
+  loadRecords,
+}: {
+  loadRecords: LoadRecords;
+}) {
+  const queryAtom = useCreateAtom<RecordsQuery>({
+    filter: "",
+    sorting: [],
+    pagination: { pageIndex: 0, pageSize: 10 },
+  });
+  const query = useSelector(queryAtom);
+  const result = useRemoteResource(query, loadRecords);
+  const page = result.data;
+  const applied = result.appliedQuery;
+  const table = useTable({
+    features,
+    columns,
+    data: page?.rows ?? [],
+    getRowId: (row) => row.id,
+    manualSorting: true,
+    manualPagination: true,
+    rowCount: page?.total ?? 0,
+    state: { sorting: query.sorting, pagination: query.pagination },
+    onSortingChange: (update) =>
+      queryAtom.set((previous) => ({
+        ...previous,
+        sorting: functionalUpdate(update, previous.sorting),
+        pagination: { ...previous.pagination, pageIndex: 0 },
+      })),
+    onPaginationChange: (update) =>
+      queryAtom.set((previous) => ({
+        ...previous,
+        pagination: functionalUpdate(update, previous.pagination),
+      })),
+  });
+  const showingPrevious = !!applied && applied !== query;
+  const canPage =
+    !!page && !result.loading && !result.error && !showingPrevious;
+  return (
+    <section aria-label="Remote records">
+      <TextField
+        label="Filter records"
+        value={query.filter}
+        onChange={(event) =>
+          queryAtom.set((previous) => ({
+            ...previous,
+            filter: event.target.value,
+            pagination: { ...previous.pagination, pageIndex: 0 },
+          }))
+        }
+      />
+      <p role="status">
+        {result.loading
+          ? page
+            ? "Loading requested records; previous results remain below."
+            : "Loading records…"
+          : result.error
+            ? "Requested records are unavailable."
+            : `${page?.total ?? 0} records found.`}
+      </p>
+      {result.error && (
+        <div role="alert">
+          <p>
+            {result.error === "permission"
+              ? "You do not have permission to view these records."
+              : "Records could not be loaded. Previous results have not been replaced."}
+          </p>
+          <Button onClick={result.retry}>Retry records</Button>
+        </div>
+      )}
+      {page && applied && result.error !== "permission" && (
+        <>
+          <p>
+            Displayed results: page {applied.pagination.pageIndex + 1}, filter{" "}
+            {applied.filter ? `“${applied.filter}”` : "none"}, sort{" "}
+            {applied.sorting
+              .map(
+                (sort) =>
+                  `${sort.id} ${sort.desc ? "descending" : "ascending"}`,
+              )
+              .join(", ") || "service default"}
+            .
+            {showingPrevious
+              ? " These are previous results, not the requested result set."
+              : ""}
+          </p>
+          <Table
+            caption="Records returned by the service"
+            aria-busy={result.loading || undefined}
+          >
+            <thead>
+              <tr>
+                {table.getHeaderGroups()[0]?.headers.map((header) => {
+                  const sort = applied.sorting.find(
+                    (sort) => sort.id === header.column.id,
+                  );
+                  return (
+                    <th
+                      scope="col"
+                      key={header.id}
+                      aria-sort={
+                        sort ? (sort.desc ? "descending" : "ascending") : "none"
+                      }
+                    >
+                      <button
+                        type="button"
+                        onClick={header.column.getToggleSortingHandler()}
+                      >
+                        <table.FlexRender header={header} />
+                      </button>
+                    </th>
+                  );
+                })}
+              </tr>
+            </thead>
+            <tbody>
+              {table.getRowModel().rows.map((row) => (
+                <tr key={row.id}>
+                  {row.getAllCells().map((cell) => (
+                    <td key={cell.id}>
+                      <table.FlexRender cell={cell} />
+                    </td>
+                  ))}
+                </tr>
+              ))}
+            </tbody>
+          </Table>
+          {!page.rows.length && (
+            <p>
+              {page.unfilteredTotal === 0
+                ? "No records exist yet."
+                : page.total === 0
+                  ? "No records match this filter."
+                  : "This page no longer exists. Return to the first page."}
+            </p>
+          )}
+          <Button
+            disabled={!canPage || query.pagination.pageIndex === 0}
+            onClick={() => table.previousPage()}
+          >
+            Previous page
+          </Button>
+          <Button
+            disabled={
+              !canPage ||
+              (query.pagination.pageIndex + 1) * query.pagination.pageSize >=
+                page.total
+            }
+            onClick={() => table.nextPage()}
+          >
+            Next page
+          </Button>
+          {page.total > 0 && !page.rows.length && (
+            <Button
+              onClick={() =>
+                queryAtom.set((previous) => ({
+                  ...previous,
+                  pagination: { ...previous.pagination, pageIndex: 0 },
+                }))
+              }
+            >
+              First page
+            </Button>
+          )}
+        </>
+      )}
+      <p>
+        This recipe has no selection, bulk actions, virtualization or adjustable
+        density. Add those application contracts before enabling their
+        table-engine features.
+      </p>
+    </section>
+  );
+}