@abuzareal/contour-ui 0.4.0 → 0.6.0

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/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.0 Combobox issue](https://github.com/abuzareal/contour-ui/issues/new?template=bug_report.yml&title=Combobox%200.6.0%3A%20&component=Combobox&version=0.6.0)
+
+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.0",
+    "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.0, 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.

package/examples/starters/next/app/Demo.tsx

@@ -0,0 +1,65 @@
+"use client";
+import { useRef, useState } from "react";
+import Link from "next/link";
+import {
+  Button,
+  Combobox,
+  Dialog,
+  TextField,
+  ThemeToggle,
+  buttonClassName,
+} from "@abuzareal/contour-ui";
+const projects = [
+  { value: "atlas", label: "Atlas" },
+  { value: "field", label: "Field notes" },
+];
+export default function Demo() {
+  const [open, setOpen] = useState(false),
+    [payload, setPayload] = useState("");
+  const name = useRef<HTMLInputElement>(null);
+  return (
+    <>
+      <p>This form inspects local values. It does not save data.</p>
+      <ThemeToggle animate={false} />
+      <form
+        onSubmit={(event) => {
+          event.preventDefault();
+          setPayload(
+            JSON.stringify(
+              Object.fromEntries(new FormData(event.currentTarget)),
+            ),
+          );
+        }}
+      >
+        <TextField
+          ref={name}
+          label="Name"
+          name="name"
+          defaultValue="Ada"
+          required
+        />
+        <Combobox
+          label="Project"
+          name="project"
+          options={projects}
+          defaultValue="atlas"
+          required
+        />
+        <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>
+      <Button onClick={() => setOpen(true)}>Open dialog</Button>
+      <Dialog open={open} onClose={() => setOpen(false)} title="Starter dialog">
+        <p>Try Tab, Escape and focus return.</p>
+        <Button onClick={() => setOpen(false)}>Done</Button>
+      </Dialog>
+      <Link href="/next-page" className={buttonClassName("secondary")}>
+        Next page
+      </Link>
+    </>
+  );
+}

package/examples/starters/next/app/layout.tsx

@@ -0,0 +1,25 @@
+import { headers } from "next/headers";
+import { themeBootstrapScript } from "@abuzareal/contour-ui/theme-bootstrap";
+import "@abuzareal/contour-ui/scoped.css";
+import "./style.css";
+export const dynamic = "force-dynamic";
+export const metadata = { title: "Contour Next starter" };
+export default async function Layout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const nonce = (await headers()).get("x-nonce") ?? undefined;
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <meta name="theme-color" content="#f2f3ee" />
+        <script
+          nonce={nonce}
+          dangerouslySetInnerHTML={{ __html: themeBootstrapScript }}
+        />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}

package/examples/starters/next/app/next-page/page.tsx

@@ -0,0 +1,9 @@
+import Link from "next/link";
+export default function NextPage() {
+  return (
+    <main>
+      <h1>Next page</h1>
+      <Link href="/">Return to starter</Link>
+    </main>
+  );
+}

package/examples/starters/next/app/page.tsx

@@ -0,0 +1,11 @@
+import { safeHref } from "@abuzareal/contour-ui";
+import Demo from "./Demo";
+export default function Page() {
+  return (
+    <main className="contour-root starter">
+      <h1>Contour Next starter</h1>
+      <p>Server helper result: {safeHref("/next-page")}</p>
+      <Demo />
+    </main>
+  );
+}

package/examples/starters/next/app/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/starters/next/next-env.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />

package/examples/starters/next/next.config.mjs

@@ -0,0 +1 @@
+export default { experimental: { cpus: 2 } };

package/examples/starters/next/package.json

@@ -0,0 +1,27 @@
+{
+  "private": true,
+  "type": "module",
+  "version": "0.0.0",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "name": "contour-next-starter",
+  "scripts": {
+    "dev": "next dev --webpack",
+    "build": "next build --webpack",
+    "typecheck": "tsc --noEmit",
+    "start": "next start"
+  },
+  "dependencies": {
+    "@abuzareal/contour-ui": "0.6.0",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "next": "16.4.0"
+  },
+  "devDependencies": {
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@types/node": "26.6.5",
+    "typescript": "7.0.2"
+  }
+}

package/examples/starters/next/proxy.ts

@@ -0,0 +1,16 @@
+import { NextResponse, type NextRequest } from "next/server";
+export function proxy(request: NextRequest) {
+  const nonce = Buffer.from(crypto.randomUUID()).toString("base64");
+  const development =
+    process.env.NODE_ENV === "development" ? " 'unsafe-eval'" : "";
+  const policy = `default-src 'self'; script-src 'self' 'nonce-${nonce}' 'strict-dynamic'${development}; style-src 'self' 'unsafe-inline'; font-src 'self'; img-src 'self' data:; connect-src 'self'; object-src 'none'; base-uri 'none'; frame-ancestors 'none'`;
+  const headers = new Headers(request.headers);
+  headers.set("x-nonce", nonce);
+  headers.set("Content-Security-Policy", policy);
+  const response = NextResponse.next({ request: { headers } });
+  response.headers.set("Content-Security-Policy", policy);
+  return response;
+}
+export const config = {
+  matcher: ["/((?!api|_next/static|_next/image|favicon.svg).*)"],
+};

package/examples/starters/next/tsconfig.json

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

package/examples/starters/vite/README.md

@@ -0,0 +1,16 @@
+# Contour + Vite
+
+Copy this folder into a new directory. Node 22.12 or newer is required. Direct dependencies are pinned; `npm install` creates the application's own lockfile. Commit that lockfile and use `npm ci` for later installs.
+
+```sh
+npm install --strict-peer-deps
+npm run dev
+npm run build
+npm run preview
+```
+
+Uses Contour 0.6.0, React/React DOM 18.3.1, TypeScript 5.9.3 and Vite 8.3.2. No aliases, workspace links, optional peers, font download, private catalogue or provider are required. Scoped CSS includes tokens and component families without the legacy global reset. The application owns the small body/layout stylesheet. Optional branded fonts: import `@abuzareal/contour-ui/fonts-latin.css` once.
+
+The Vite config inserts the exact released theme bootstrap before the application, with a calculated CSP script hash. Keep the placeholder in index.html; recalculate through the build after upgrades. Script execution is restricted; style attributes are allowed because popup positioning and some components use inline styles. Extend connect-src intentionally for your service/development socket. An HTTP CSP header may replace this meta policy if it contains the same hash. See the package GETTING-STARTED.md for embedded themes and optional features.
+
+Run against the registry after the release is published. Release candidates are tested with the verified npm archive in a disposable copy; an unpublished candidate version will not install from npm yet.

package/examples/starters/vite/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/starters/vite/package.json

@@ -0,0 +1,27 @@
+{
+  "private": true,
+  "type": "module",
+  "version": "0.0.0",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "name": "contour-vite-starter",
+  "scripts": {
+    "dev": "vite",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc --noEmit && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@abuzareal/contour-ui": "0.6.0",
+    "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/starters/vite/src/main.tsx

@@ -0,0 +1,81 @@
+import { StrictMode, useRef, useState } from "react";
+import { createRoot } from "react-dom/client";
+import {
+  Button,
+  Combobox,
+  Dialog,
+  TextField,
+  ThemeToggle,
+  buttonClassName,
+} from "@abuzareal/contour-ui";
+import "@abuzareal/contour-ui/scoped.css";
+import "./style.css";
+const projects = [
+  { value: "atlas", label: "Atlas" },
+  { value: "field", label: "Field notes" },
+];
+function App() {
+  const [open, setOpen] = useState(false),
+    [payload, setPayload] = useState("");
+  const name = useRef<HTMLInputElement>(null);
+  return (
+    <main className="contour-root starter">
+      <h1>Contour starter</h1>
+      <p>This form inspects local values. It does not save data.</p>
+      <ThemeToggle animate={false} />
+      <form
+        onSubmit={(event) => {
+          event.preventDefault();
+          setPayload(
+            JSON.stringify(
+              Object.fromEntries(new FormData(event.currentTarget)),
+            ),
+          );
+        }}
+      >
+        <TextField
+          ref={name}
+          label="Name"
+          name="name"
+          defaultValue="Ada"
+          required
+        />
+        <Combobox
+          label="Project"
+          name="project"
+          options={projects}
+          defaultValue="atlas"
+          required
+        />
+        <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>
+      <Button onClick={() => setOpen(true)}>Open dialog</Button>
+      <Dialog open={open} onClose={() => setOpen(false)} title="Starter dialog">
+        <p>Try Tab, Escape and focus return.</p>
+        <Button onClick={() => setOpen(false)}>Done</Button>
+      </Dialog>
+      <a className={buttonClassName("secondary")} href="#integration">
+        Integration notes
+      </a>
+      <section id="integration">
+        <h2>Application ownership</h2>
+        <p>
+          Add your own router, validation and persistence. No provider is
+          required by the controls above.
+        </p>
+      </section>
+    </main>
+  );
+}
+const root = document.getElementById("root");
+if (!root) throw new Error("Missing root element");
+createRoot(root).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/examples/starters/vite/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/starters/vite/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"]
+}