@abuzareal/contour-ui 0.5.0 → 0.6.1

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

package/examples/recipes/useRemoteResource.ts

@@ -0,0 +1,81 @@
+"use client";
+import { useEffect, useRef, useState } from "react";
+
+/** The application maps its service failures; never display raw server exceptions. */
+export class RecipeServiceError extends Error {
+  constructor(public readonly kind: "permission" | "service") {
+    super(kind);
+  }
+}
+export type Loader<Query, Data> = (
+  query: Query,
+  signal: AbortSignal,
+) => Promise<Data>;
+
+/** Application-owned fetching. The old snapshot stays labelled; obsolete work cannot commit. */
+export function useRemoteResource<Query, Data>(
+  query: Query,
+  load: Loader<Query, Data>,
+) {
+  const [attempt, setAttempt] = useState(0);
+  const sequence = useRef(0);
+  const [state, setState] = useState<{
+    requested: Query | null;
+    loader: Loader<Query, Data> | null;
+    attempt: number;
+    applied: Query | null;
+    data: Data | null;
+    error: "permission" | "service" | null;
+  }>({
+    requested: null,
+    loader: null,
+    attempt: -1,
+    applied: null,
+    data: null,
+    error: null,
+  });
+  useEffect(() => {
+    const controller = new AbortController();
+    const revision = ++sequence.current;
+    void (async () => {
+      try {
+        const data = await load(query, controller.signal);
+        if (controller.signal.aborted || sequence.current !== revision) return;
+        setState({
+          requested: query,
+          loader: load,
+          attempt,
+          applied: query,
+          data,
+          error: null,
+        });
+      } catch (error) {
+        if (controller.signal.aborted || sequence.current !== revision) return;
+        const kind =
+          error instanceof RecipeServiceError ? error.kind : "service";
+        setState((previous) => ({
+          ...previous,
+          requested: query,
+          loader: load,
+          attempt,
+          error: kind,
+          // A denied snapshot must not reappear while a later query is pending.
+          data: kind === "permission" ? null : previous.data,
+          applied: kind === "permission" ? null : previous.applied,
+        }));
+      }
+    })();
+    return () => controller.abort();
+  }, [query, load, attempt]);
+  const current =
+    state.requested === query &&
+    state.loader === load &&
+    state.attempt === attempt;
+  return {
+    data: state.data,
+    appliedQuery: state.applied,
+    loading: !current,
+    error: current ? state.error : null,
+    retry: () => setAttempt((n) => n + 1),
+  };
+}

package/examples/reference/HookExamples.tsx

@@ -0,0 +1,146 @@
+import { useRef, useState } from "react";
+import {
+  Button,
+  TextField,
+  ThemeScope,
+  ToastProvider,
+  useClipboardCopy,
+  useDismiss,
+  useIdleTrigger,
+  useMotionPreference,
+  useTheme,
+  useToast,
+  type Theme,
+} from "@abuzareal/contour-ui";
+export function ClipboardExample() {
+  const { copy, status } = useClipboardCopy(
+    "Public synthetic project reference",
+  );
+  return (
+    <section aria-label="Clipboard example">
+      <Button onClick={() => void copy()}>Copy reference</Button>
+      <p role="status">
+        {status === "error"
+          ? "Copy failed. You can try again."
+          : status === "copied"
+            ? "Copied."
+            : status === "copying"
+              ? "Copying…"
+              : "Ready to copy."}
+      </p>
+    </section>
+  );
+}
+export function MotionExample() {
+  const reduced = useMotionPreference();
+  const [paused, setPaused] = useState(false);
+  return (
+    <section aria-label="Motion preference">
+      <Button
+        aria-pressed={paused}
+        onClick={() => setPaused((value) => !value)}
+      >
+        Pause optional motion
+      </Button>
+      <p>Optional animation is {!reduced && !paused ? "allowed" : "paused"}.</p>
+      <p>
+        This example owns no animation loop; a scene must consume this combined
+        policy.
+      </p>
+    </section>
+  );
+}
+export function DismissExample() {
+  const [open, setOpen] = useState(false);
+  const panel = useRef<HTMLDivElement>(null),
+    trigger = useRef<HTMLButtonElement>(null);
+  useDismiss(
+    panel,
+    open,
+    (reason) => {
+      setOpen(false);
+      if (reason === "escape") trigger.current?.focus();
+    },
+    { branches: [trigger] },
+  );
+  return (
+    <section aria-label="Custom nonmodal dismissal">
+      <Button
+        ref={trigger}
+        aria-expanded={open}
+        aria-controls="example-help"
+        onClick={() => setOpen((value) => !value)}
+      >
+        Toggle custom help
+      </Button>
+      {open && (
+        <div
+          id="example-help"
+          ref={panel}
+          role="region"
+          aria-label="Custom help"
+        >
+          <p>This nonmodal example does not trap or move focus.</p>
+          <TextField label="Local note" />
+        </div>
+      )}
+    </section>
+  );
+}
+export function IdleExample() {
+  const [enabled, setEnabled] = useState(false);
+  const ready = useIdleTrigger(enabled);
+  return (
+    <section aria-label="Idle signal">
+      <Button onClick={() => setEnabled(true)}>Request idle signal</Button>
+      <p role="status">
+        {ready
+          ? "Idle signal received; no work was loaded."
+          : enabled
+            ? "Waiting for idle signal…"
+            : "Not requested."}
+      </p>
+    </section>
+  );
+}
+function ThemeAction() {
+  const { theme, toggle } = useTheme(false);
+  return (
+    <Button
+      aria-pressed={theme === "dark"}
+      onClick={(event) => toggle(event.currentTarget)}
+    >
+      Dark embedded theme
+    </Button>
+  );
+}
+export function ScopedThemeExample() {
+  const [theme, setTheme] = useState<Theme>("light");
+  return (
+    <ThemeScope theme={theme} onThemeChange={setTheme}>
+      <ThemeAction />
+    </ThemeScope>
+  );
+}
+function ToastAction() {
+  const toast = useToast();
+  return (
+    <Button
+      onClick={() =>
+        toast.show({
+          title: "Notification example",
+          message: "This local example sends and saves nothing.",
+        })
+      }
+    >
+      Show example notification
+    </Button>
+  );
+}
+export function ToastExample() {
+  return (
+    <ToastProvider>
+      <ToastAction />
+    </ToastProvider>
+  );
+}

package/examples/reproduction/README.md

@@ -0,0 +1,9 @@
+# Minimal component / overlay / form reproduction
+
+Copy this folder alone into an empty directory. Run npm install --strict-peer-deps, npm run build and npm run preview. Versions are pinned in package.json; commit the generated lockfile. There are no workspace aliases or private catalogue dependencies. Use npm ci once your application lockfile exists.
+
+Keep a failing interaction in src/main.tsx and remove unrelated UI. Include installed Contour/React/browser versions, expected/actual behavior, keyboard steps, theme, viewport and the smallest input data. Replace names and service URLs with synthetic data; never include credentials, customer records or private repository links. A public repository or sandbox can use this standalone folder.
+
+[Report a Contour 0.6.1 Combobox issue](https://github.com/abuzareal/contour-ui/issues/new?template=bug_report.yml&title=Combobox%200.6.1%3A%20&component=Combobox&version=0.6.1)
+
+Candidate versions need the package to be published before registry installation; the maintainer tests the same source against the packed candidate first.

package/examples/reproduction/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <meta name="theme-color" content="#f2f3ee" />
+    <!-- theme-bootstrap -->
+    <title>Contour starter</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/examples/reproduction/package.json

@@ -0,0 +1,27 @@
+{
+  "private": true,
+  "type": "module",
+  "version": "0.0.0",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "name": "contour-bug-reproduction",
+  "scripts": {
+    "dev": "vite",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc --noEmit && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@abuzareal/contour-ui": "0.6.1",
+    "react": "18.3.1",
+    "react-dom": "18.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "18.3.31",
+    "@types/react-dom": "18.3.7",
+    "@types/node": "26.6.5",
+    "typescript": "5.9.3",
+    "vite": "8.3.2"
+  }
+}

package/examples/reproduction/src/main.tsx

@@ -0,0 +1,33 @@
+import { useState } from "react";
+import { createRoot } from "react-dom/client";
+import { Button, Combobox, Dialog, Popover } from "@abuzareal/contour-ui";
+import "@abuzareal/contour-ui/scoped.css";
+import "./style.css";
+const options = [
+  { value: "one", label: "One" },
+  { value: "two", label: "Two", disabled: true },
+];
+function Reproduction() {
+  const [open, setOpen] = useState(false);
+  return (
+    <main className="contour-root starter">
+      <h1>Contour reproduction</h1>
+      <p>
+        Contour 0.6.0, React/React DOM 18.3.1. Replace only the smallest
+        relevant case. No real user data.
+      </p>
+      <Button onClick={() => setOpen(true)}>Open dialog</Button>
+      <Dialog open={open} onClose={() => setOpen(false)} title="Reproduction">
+        <Popover trigger="Open popover" title="Nested layer">
+          <form onSubmit={(event) => event.preventDefault()}>
+            <Combobox label="Choice" name="choice" options={options} required />
+            <Button type="reset">Reset</Button>
+          </form>
+        </Popover>
+      </Dialog>
+    </main>
+  );
+}
+const element = document.getElementById("root");
+if (!element) throw new Error("Missing root");
+createRoot(element).render(<Reproduction />);

package/examples/reproduction/src/style.css

@@ -0,0 +1,19 @@
+body {
+  margin: 0;
+  background: var(--contour-bg);
+  color: var(--contour-fg);
+}
+.starter {
+  max-width: 42rem;
+  margin: 0 auto;
+  padding: 2rem 1rem;
+  display: grid;
+  gap: 1.25rem;
+}
+.starter form {
+  display: grid;
+  gap: 1rem;
+}
+.starter output {
+  overflow-wrap: anywhere;
+}

package/examples/reproduction/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["DOM", "DOM.Iterable", "ES2022"],
+    "strict": true,
+    "skipLibCheck": false,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "isolatedModules": true
+  },
+  "include": ["**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/examples/reproduction/vite.config.ts

@@ -0,0 +1,19 @@
+import { createHash } from "node:crypto";
+import { defineConfig } from "vite";
+import { themeBootstrapScript } from "@abuzareal/contour-ui/theme-bootstrap";
+const hash = createHash("sha256").update(themeBootstrapScript).digest("base64");
+export default defineConfig({
+  plugins: [
+    {
+      name: "contour-theme-bootstrap",
+      transformIndexHtml(html) {
+        // Hash the exact bytes inserted here; no inline handler or unsafe-eval allowance.
+        const policy = `default-src 'self'; script-src 'self' 'sha256-${hash}'; style-src 'self' 'unsafe-inline'; font-src 'self'; img-src 'self' data:; connect-src 'self'; object-src 'none'; base-uri 'none'`;
+        return html.replace(
+          "<!-- theme-bootstrap -->",
+          `<meta http-equiv="Content-Security-Policy" content="${policy}"><script>${themeBootstrapScript}</script>`,
+        );
+      },
+    },
+  ],
+});

package/examples/starters/next/README.md

@@ -0,0 +1,18 @@
+# Contour + Next App Router
+
+Copy this directory. Use Node 22.12 or newer, then:
+
+```sh
+npm install --strict-peer-deps
+npm run dev
+npm run build
+npm start
+```
+
+Direct versions: Contour 0.6.1, Next 16.4.0, React/React DOM 19.3.0, TypeScript 7.0.2; webpack explicitly selected. Commit the generated application lockfile and use npm ci afterward. There are no workspace aliases, optional Three/Lenis peers, fonts or required providers. To opt into branded fonts, import `@abuzareal/contour-ui/fonts-latin.css` in app/layout.tsx. Root CSS and route composition belong to the application.
+
+layout.tsx and the page are server components. Demo.tsx owns client state, refs and handlers. The pure theme-bootstrap subpath is server-safe; before-paint script changes only the root theme attribute and theme-color. The root's suppressHydrationWarning is narrowly for this attribute, not a workaround for arbitrary mismatches.
+
+proxy.ts generates a new nonce on every document request, forwards the CSP and nonce to Next and returns the CSP header. The dynamic layout reads that nonce so both bootstrap and framework scripts are authorized. This deliberately requires server rendering; static export/cached shared nonces are not supported. Inline styles remain allowed for library geometry. Production script policy has no unsafe-eval; development adds it for the bundler. Configure additional service origins explicitly. See [Next's CSP guide](https://nextjs.org/docs/app/guides/content-security-policy).
+
+This folder establishes the named App Router/webpack pair only. Turbopack, Pages Router and Next Lenis are unverified. Optional lazy Three is covered separately by the library's optional fixture, not installed here. A release candidate uses an archive only in disposable validation copies; the exact registry installation requires the published release.