@abuzareal/contour-ui 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 Changes to the published `@abuzareal/contour-ui` package. Version headings refer to package versions, not catalogue or application versions. Consumer projects pin their own version and update separately.
 
+## Unreleased
+
+No changes recorded.
+
+## 0.2.0
+
+- TextField, TextArea and SelectField expose native refs while retaining React 18/19 compatibility. Caller-supplied aria-invalid is preserved when no component error overrides it.
+- Uncontrolled field counters and textarea height follow native form reset, including external form association and canceled resets. A browser task waits for the native reset default action, and native input keeps counters current when an edit repeats the pre-reset value.
+- Tabs adds activeTabId/onTabChange; Popover and DropdownMenu add open/defaultOpen/onOpenChange. Existing uncontrolled defaults remain.
+- DropdownMenu skips disabled items, opens from ArrowUp/ArrowDown, supports label typeahead and accepts stable item ids.
+- Three stages release resources after partial initialization failure; setup can register disposal immediately. ObjectStudy reflows paused scenes on resize instead of arranging every animation frame.
+- Interactive modules retain client boundaries; ESM export targets also provide a default condition for framework dynamic-module resolution. A pinned packed Next.js App Router fixture checks the candidate. Latin font assets use relative packaged URLs with their licenses for webpack compatibility.
+- Contributor setup and issue/PR templates are portable. Release checks reuse one archive across compatibility consumers and publish that verified archive without rerunning source lifecycle gates.
+
+These changes are absent from 0.1.2. A separate Next.js fixture mode covers lazy Three.js; Lenis, alternate-bundler and wider framework support remain outside these checks.
+
 ## 0.1.2 — 2026-10-07
 
 An optional font-loading entry and clearer setup documentation. Component APIs and runtime dependencies are unchanged from 0.1.1.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,5 @@
+# Code of conduct
+
+Treat contributors and users with respect. Focus criticism on behavior and code. Harassment, discrimination, threats, sharing private information without permission and repeated personal attacks are unacceptable.
+
+Maintainers may remove disruptive material or restrict participation to keep the project usable. Send conduct concerns privately to abuzart1999@gmail.com, including links or evidence you are comfortable sharing. Reports are handled privately where possible; do not publish other people's personal details in issues.

package/CONTRIBUTING.md

@@ -0,0 +1,15 @@
+# Contributing to Contour UI
+
+Contour is a styled React library. The catalogue is a separate application at [contour.abuzr.in](https://contour.abuzr.in/). Domain workflows and product scenes belong in applications; reusable controls, semantic tokens and shared browser lifecycles belong here.
+
+Start with an issue describing the user task, current behavior and a small reproduction. For a new component, describe its stable props, native semantics, keyboard behavior, failure/empty states and why existing exports cannot compose the result. Do not include secrets or private application data. Report security concerns through [SECURITY.md](SECURITY.md).
+
+Use Node 22.12+ or 24+, then `npm ci --ignore-scripts`. Install Chromium once with `npx playwright install chromium`. Run `npm run validate` for types, lint, build, component and browser regressions, and archive checks. Run `npm run test:compat` for packed React 18/19 consumers and source declarations; run `npm run test:next` for the pinned App Router fixture. Compatibility installs need network access. The core fixture must work without Three.js or Lenis. Optional entries have separate consumers.
+
+Keep strict types and validate untrusted data before use. Components own presentation and nearby state; hooks own subscriptions and browser lifecycles; helpers own pure calculations. Use native controls, linked labels/errors, visible focus and explicit button types. Respect reduced motion. Release every listener, timer, observer and GPU resource on unmount and partial initialization failure. Use `onDispose` immediately for resources allocated in a custom stage setup.
+
+For a fix, add a regression that fails for the previous behavior. Use component tests for interaction contracts and real browsers for native dialogs, event timing, layout and GPU integration. Check narrow layouts, long content and both themes. Do not replace browser evidence with jsdom when a browser owns the behavior. Avoid duplicate tests that only restate implementation.
+
+Update the README and Unreleased changelog when public behavior changes. Keep documented APIs consistent with the archive. New APIs need a migration/usage example. Generic CSS class names and the legacy `aa-theme` storage key are existing compatibility constraints; do not rename them silently.
+
+A pull request should name the concrete behavior change, why it helps, which checks passed and any remaining limitation. Review public exports, packed files and dependency changes. No publish, deploy or merge is implied by opening a pull request. Consumers adopt an exact published release with a lockfile update; local source edits do not update them.

package/NEXTJS.md

@@ -0,0 +1,51 @@
+# Next.js App Router integration
+
+This guide describes **Contour 0.2.0**. npm 0.1.2 does not include the client directives, native refs or relative Latin font files described here. Check npm for release availability before installing. The fixture pins Next 16.4.0 with React/React DOM 19.3.0, uses the webpack production build, and consumes an npm archive. It does not establish every Next version, Turbopack, Pages Router, scroll entries or hosting platform. A separate optional mode checks a lazy Three.js scene with SSR disabled and disposal on navigation.
+
+In `app/layout.tsx`, load CSS once:
+
+```tsx
+import "@abuzareal/contour-ui/styles.css";
+import "@abuzareal/contour-ui/fonts-latin.css"; // Optional; use your own fonts if preferred.
+import { themeBootstrapScript } from "@abuzareal/contour-ui/theme-bootstrap";
+
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <script dangerouslySetInnerHTML={{ __html: themeBootstrapScript }} />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+The narrowly scoped hydration suppression handles the root theme attribute changed before hydration; do not use it to hide arbitrary mismatch errors. A restrictive CSP requires a nonce or hash for the bootstrap script. `reset.css` is optional and global; decide whether your host reset already supplies equivalent defaults, visible focus and a `[hidden]` rule.
+
+A client component owns event handlers, state and providers:
+
+```tsx
+"use client";
+import { useState } from "react";
+import { TextField, Button } from "@abuzareal/contour-ui";
+
+export default function SearchForm() {
+  const [query, setQuery] = useState("");
+  return (
+    <form>
+      <TextField
+        label="Search"
+        name="query"
+        value={query}
+        onChange={(event) => setQuery(event.target.value)}
+      />
+      <Button type="submit">Search</Button>
+    </form>
+  );
+}
+```
+
+Provide real submission behavior in the application. Toast consumers need ToastProvider; dialogs need application-owned open/onClose. Keep function props inside client boundaries. A server component can pass serializable props to a package client component or import pure `safeHref`; a client directive does not remove normal server prerendering.
+
+Run `npm run test:next` to rebuild and consume the candidate archive. The fixture checks server imports/prerendering, hydration, CSS/fonts, refs, native resets, dialog dismissal/focus, toast, tabs, theme persistence and client navigation without Three.js/Lenis installed. Run `CONTOUR_NEXT_OPTIONAL=1 node scripts/test-next.mjs` for the separate lazy `/three` route; ordinary consumers still require neither optional peer. Compatibility evidence applies to the fixture's exact pair and local runtime, not deployment.

package/README.md

@@ -6,14 +6,14 @@ Use it when you want this visual style with typed controls, feedback, navigation
 
 [Live catalogue](https://contour.abuzr.in/) · [npm package](https://www.npmjs.com/package/@abuzareal/contour-ui) · [Maintainer](https://github.com/abuzareal)
 
-The catalogue currently uses **0.1.1**; this release is **0.1.2**. Catalogue examples include application patterns as well as package components. Check the exports below before treating an example as an importable component.
+This source checkout targets **0.2.0**. Package publication and application upgrades are separate; check the npm registry for release availability and each application's manifest for its installed version. Catalogue examples include application patterns as well as package components. Check the exports below before treating an example as an importable component.
 
 ## Install
 
 Use an existing React application with a bundler that resolves package CSS imports. Contour ships ESM and TypeScript declarations. The package declares Node.js 22 or newer; repository tooling uses Vite 8, which needs Node.js 22.12+ or 24+.
 
 ```sh
-npm install @abuzareal/contour-ui@0.1.2 --save-exact
+npm install @abuzareal/contour-ui@0.2.0 --save-exact
 ```
 
 Your app must provide matching `react` and `react-dom` versions: **18.3.1 or React 19**. The compatibility script covers 18.3.1, 19.0.0, and 19.3.0; it doesn't establish support for every framework or React Server Component setup. Put interactive components inside a client boundary when your framework requires one.
@@ -157,15 +157,15 @@ Give scenes a sized container and a usable static fallback. `SceneBoundary` hide
 
 ## Release notes and upgrades
 
-**0.1.2** adds the optional `fonts-latin.css` export, clearer setup documentation, and links to the Contour UI documentation site. Component APIs and runtime dependencies remain unchanged from 0.1.1. React 19 support and the interaction fixes from 0.1.1 are retained. `CHANGELOG.md` is included in the package archive and [npm's Code view](https://www.npmjs.com/package/@abuzareal/contour-ui?activeTab=code); it contains the upgrade details for each version.
+**0.2.0** adds native field refs, controlled tabs and disclosure state, menu keyboard improvements, native reset synchronization, Three.js lifecycle fixes and a tested Next.js App Router integration. Existing uncontrolled defaults and React 18/19 support remain. `fonts-latin.css`, introduced in 0.1.2, now uses packaged relative font URLs for webpack resolution. `CHANGELOG.md` is included in the package archive and [npm's Code view](https://www.npmjs.com/package/@abuzareal/contour-ui?activeTab=code); it contains the upgrade details for each version.
 
 ```sh
-npm install @abuzareal/contour-ui@0.1.2 --save-exact
+npm install @abuzareal/contour-ui@0.2.0 --save-exact
 ```
 
 Commit your manifest and lockfile, run your application's checks, and review both themes, dialogs, forms, and motion before deploying. Version 0.1.1 includes a document scroll lock for dialogs and drawers. Review any app-level lock before removing it, including nested dialogs and short screens. Package publication doesn't update deployed consumers automatically.
 
-The package is public under MIT. The source repository and its issue tracker currently require collaborator access. Public users can inspect the distributed code, CSS, declarations, and release documents through npm. Contact the [maintainer](https://github.com/abuzareal) for support; see `SECURITY.md` in the package for vulnerability reporting guidance.
+The package and [source repository](https://github.com/abuzareal/contour-ui) are public under MIT. Report reproducible defects in the [issue tracker](https://github.com/abuzareal/contour-ui/issues); use [SECURITY.md](SECURITY.md) for private vulnerability reporting. Public users can inspect code, CSS, declarations and release documents through GitHub or npm.
 
 ## Develop this library
 
@@ -180,8 +180,60 @@ npm audit
 npm pack --dry-run
 ```
 
-`validate` checks types, lint, builds, Node/component tests, dialog browser behavior, and archive contents. `test:compat` builds packed React 18/19 consumers and compiles the source with React 19 types. `test:consumer` checks one packed consumer, with optional peers absent. `test:optional` verifies strict `/three` and `/scroll` declarations and builds their imports with explicit peers and Three.js types. The compatibility gate runs both checks and verifies the Latin font assets. Compatibility runs need registry access for clean installs.
+`validate` checks types, lint, builds, Node/component tests, dialog and Three.js browser behavior, and archive contents. `test:compat` builds packed React 18/19 consumers and compiles the source with React 19 types. `test:consumer` checks one packed consumer, with optional peers absent. `test:optional` verifies strict `/three` and `/scroll` declarations and builds their imports with explicit peers and Three.js types. The compatibility gate runs both checks and verifies the Latin font assets. Compatibility runs need registry access for clean installs.
 
 `src/` owns components, hooks, helpers, and public entries. `styles/` owns CSS. `tests/` owns regressions and browser checks; `scripts/` owns builds and package/consumer checks. `dist/` is generated. `RELEASING.md` in the source checkout and package archive covers validation and publication.
 
 MIT licensed. Fontsource fonts and dependencies retain their own licenses.
+
+## APIs added in 0.2.0
+
+Version 0.2.0 adds native refs to TextField, TextArea and SelectField; synchronizes uncontrolled counters and auto-resize after native form reset; adds controlled Tabs (`activeTabId`, `onTabChange`) and disclosures (`open`, `defaultOpen`, `onOpenChange`); and adds disabled menu items, stable item ids and typeahead. These additions are absent from 0.1.2. Switching a field/disclosure between controlled and uncontrolled ownership during its lifetime is unsupported.
+
+Existing uncontrolled calls remain valid. Use a native ref to focus a field or integrate a form controller; controlled tabs and disclosures require the caller to update the selected id or open state:
+
+```tsx
+import { useRef, useState } from "react";
+import { Button, Popover, Tabs, TextField } from "@abuzareal/contour-ui";
+
+export function AccountControls() {
+  const input = useRef<HTMLInputElement>(null);
+  const [activeTabId, setActiveTabId] = useState("details");
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <TextField ref={input} label="Name" name="name" />
+      <Button onClick={() => input.current?.focus()}>Focus name</Button>
+      <Tabs
+        label="Account"
+        activeTabId={activeTabId}
+        onTabChange={setActiveTabId}
+        tabs={[
+          { id: "details", label: "Details", content: <p>Account details</p> },
+          {
+            id: "settings",
+            label: "Settings",
+            content: <p>Account settings</p>,
+          },
+        ]}
+      />
+      <Popover trigger="Help" title="Help" open={open} onOpenChange={setOpen}>
+        <p>Account help</p>
+      </Popover>
+    </>
+  );
+}
+```
+
+Interactive module boundaries retain `use client` in the built package. The pinned Next.js App Router consumer checks the packed 0.2.0 archive. Follow [Next.js setup](NEXTJS.md) for the pinned Next.js 16.4.0 / React 19.3.0 pair. Pure URL/theme-bootstrap helpers remain usable from the server. A separate fixture mode checks lazy optional Three.js loading and navigation cleanup. Lenis integration, other Next versions and alternate bundlers remain separate compatibility questions.
+
+Custom `useThreeStage` setup can register disposal through `context.onDispose?.(cleanup)` immediately after acquiring each resource, including resources allocated before setup returns. Registered resources are released on failed initialization and unmount; avoid also disposing the same resource in `StageScene.dispose`. A stage may implement `resize()` to reflow after aspect changes while motion is paused.
+
+## Compatibility boundaries
+
+Styles are global, not a scoped CSS engine. Existing class names such as `.field` and `.menu` can collide with host CSS. Import Contour styles before deliberate application overrides; keep application selectors area-prefixed. The optional reset and fonts affect the document. Tokens use root `data-theme`; `useTheme` retains the legacy `aa-theme` local-storage key for compatibility. A multi-library page must decide which system owns its root theme.
+
+Menus and popovers remain local panels without portals or collision detection; use them where the container can accommodate their content. No submenu or arbitrary trigger-composition contract is claimed. BrandMark and page/editorial helpers preserve existing identity and layout assumptions; they are optional exports rather than universal primitives. Do not copy private internals or deep-import them.
+
+For contribution setup and review expectations, see [CONTRIBUTING.md](CONTRIBUTING.md). Contour currently provides React components; no Vue, Svelte or Angular adapter is included.

package/RELEASING.md

@@ -1,49 +1,23 @@
 # Releasing Contour UI
 
-## Package-page documentation and release notes
+Source is public at [github.com/abuzareal/contour-ui](https://github.com/abuzareal/contour-ui); the package is public under MIT. Query npm for the latest published version; the source manifest does not prove publication. Source changes are not delivered to consumers until publication and an exact dependency/lockfile update. The npm README changes only when a new version is published; do not overwrite or unpublish an existing version to edit it.
 
-The npm Readme tab renders the root `README.md`. npm updates it when a new package version is published; editing this repository does not update the existing npm page. Follow [npm's README update guidance](https://docs.npmjs.com/about-package-readme-files/). Do not try to overwrite a published version or unpublish it to change documentation.
+Before selecting a release version, review public API and visual changes, types, dependencies, licenses, changelog and compatibility limits. Use patch for compatible fixes, minor for additions, and document every incompatible 0.x change explicitly. README examples must match the archive. Record publication dates only after verifying the registry. A local check is not deployment evidence.
 
-Keep installation, a working example, CSS/theme setup, supported APIs, optional dependencies, limits, and a release summary in the README. Keep the detailed version history in `CHANGELOG.md`, which ships in the archive and is available through npm's Code view. The private GitHub repository is not a public documentation destination. When public docs and changelog routes exist, add their verified URLs to the README and package metadata.
+## Verify and publish one archive
 
-Write new changes under **Unreleased**, or under a version heading explicitly marked **Pending release** when the next version has been chosen. At publication, remove the pending label and record the verified publication date. Use sections only when they contain useful changes: Added, Fixes, Compatibility, Upgrading, and Known limitations. Each entry should name the affected component/API and describe the user's resulting behavior. Include a migration example for incompatible changes. For a documentation-only patch, state that runtime behavior and dependency contracts are unchanged.
+1. Obtain maintainer authorization to publish; validation alone is not authorization.
+2. Select an unused registry version and update package.json, its lockfile and release notes. Never reuse an existing registry version; a locally verified archive does not make it publishable under an already released version. Use a reviewed release commit on main and a matching `vVERSION` tag. The hosted workflow checks the tag version and that its source is an ancestor of origin/main. It cannot publish from a pull request.
+3. Run `npm ci --ignore-scripts`; install Chromium once with `npx playwright install chromium`. Use Node 22.12+ or 24+.
+4. Set `CONTOUR_RELEASE_DIR` to an existing temporary directory and run `npm run verify:release`. It runs validate once, packs one archive, tests that archive in clean React 18/19 core and optional consumers plus the pinned Next App Router fixture, audits dependencies, and writes `verified-archive.json` with its SHA-256. Core consumers must have no Three.js or Lenis installed. Review failures and advisories instead of bypassing gates.
+5. Inspect the archive contents, verify its checksum against `verified-archive.json`, and publish that exact path using `npm publish /absolute/path/to/archive.tgz --ignore-scripts --access public`. `--ignore-scripts` is appropriate here because that exact archive has already passed the release gates; it is not permission to publish an unchecked package. Source `npm publish` retains a prepublishOnly guard. The hosted workflow verifies the checksum again and publishes the archive with provenance, avoiding duplicate source gates.
+6. The owner completes npm authentication/2FA personally. Never put tokens, OTPs or credentials in this repository or logs. Prefer configured trusted publishing and short-lived identity over persistent tokens.
+7. Verify registry version, tarball/integrity and publication date; install that exact registry version in each affected consumer, commit its manifest/lockfile, and run its required checks before deployment. Do not substitute a local link or source copy for release validation.
 
-Link each release to available evidence: changed APIs, relevant tests, and public issues/PRs when readers can access them. Do not invent dates, issue numbers, performance gains, accessibility certification, or compatibility results. Confirm that README examples use the exports and props in the release archive. Run the same release gates for a documentation patch; the archive, manifest, tag, changelog, and registry version must agree. Publishing still requires the maintainer's authorization.
+The tag workflow is configured for a public repository on main. Configuration does not prove that its npm trusted-publisher relationship is active; check npm/GitHub settings before relying on it. Publication requires authorization even when CI passes.
 
-## Initial release
+## Validation cost
 
-1. Verify `npm whoami` is `abuzareal`; the package is `@abuzareal/contour-ui` and public under MIT.
-2. Run `npm ci --ignore-scripts`, install Chromium with `npx playwright install chromium` on a new machine, then run `npm run validate`, `npm run test:compat`, and `npm audit`. Review every advisory; do not release with unexplained audit findings.
-3. Test the actual packed archive in clean React 18 and React 19 consumers without optional Three.js or Lenis, and in the catalogue and portfolio with their full browser suites.
-4. Check `npm pack --dry-run --json` and licenses. No private data, credentials, unrelated assets, maps, or app content may enter the archive.
-5. Push the reviewed source and release commit to the independent GitHub repository. The owner currently keeps this repository private; the npm distribution remains public under MIT.
-6. Set `private` to `false` only for an approved, validated release. Publish from the verified owner account: `npm publish --access public`. Complete npm's required authentication/2FA personally.
-7. Verify registry metadata, install the exact registry version in both consumers, rerun checks, and commit the manifest/lockfile changes. Do not commit temporary filesystem/archive dependencies.
-8. Tag the matching package version and record the release. Every future release requires a new version; npm versions cannot be overwritten.
+Browser checks remain for native dialog, reset timing and graphics lifecycle behavior. jsdom does not reproduce all browser default actions. Compatibility checks reuse one archive and avoid another library build when `CONTOUR_ARCHIVE` is provided. Documentation-only diffs retain types, lint, build, archive checks and audit; runtime diffs keep component, browser and complete compatibility checks. Changes to components, hooks, entries, styles, build/package configuration or the Next fixture also run the pinned Next check. Unknown history falls back to complete gates. No measured CI speedup is claimed until the updated workflow has run.
 
-## Future trusted releases
-
-After the first package exists, configure npm's GitHub trusted publisher for owner `abuzareal`, repository `contour-ui`, workflow `release.yml`. Authenticate interactively to set this relationship; do not paste credentials into code or chat. Enable two-factor authentication on the owner account and prefer disabling ordinary token publishing after trusted publishing has been successfully verified.
-
-With account 2FA enabled, configure and verify the relationship using npm 11.15 or later:
-
-```sh
-npm trust github @abuzareal/contour-ui --file release.yml --repo abuzareal/contour-ui --allow-publish
-npm trust list @abuzareal/contour-ui
-```
-
-The release workflow accepts a manually dispatched version already present in package.json and requires the matching `vVERSION` tag to identify its source. It reruns validation, dependency audit, and clean-consumer tests before publishing with provenance. Push the reviewed release commit to main before tagging. Never publish from a pull-request event or add a persistent npm token to the workflow.
-
-The repository is currently private, so the configured workflow deliberately skips publishing. Release locally after running the checklist. Trusted publishing can be configured for a private repository, but npm does not support provenance attestations from private source repositories. If hosted releases are enabled later, review private-runner spending settings and remove the explicit provenance requirement for private source. The current workflow is ready for a future public repository and must not be presented as active automation while the repository stays private.
-
-Increment PATCH for compatible fixes, MINOR for compatible additions, and MAJOR for incompatible APIs or substantial incompatible default behavior. While the package is at 0.x, document every change carefully and keep consumers pinned to exact versions. Review visual changes in consuming apps even when the API is compatible.
-
-## Dependency updates and cost
-
-Dependabot is selected because it is integrated with GitHub and requires no extra hosted service or bot account. It proposes weekly npm and action updates; the library is not auto-merged. npm distribution is public. Standard-hosted Actions run only if the repository is public; checks run locally while it stays private. Do not enable paid runners, private npm distribution, or paid security subscriptions as part of this setup.
-
-The library's validation workflows deliberately skip private repositories. Consumer policies vary: Portfolio allows private pull requests to opt in with the `run-validation` label. Check each consumer's workflow and run its required checks locally when CI is skipped. Enabling private-repository Actions requires reviewing that account's included usage and spending settings first.
-
-Consumers install with `npm install @abuzareal/contour-ui@VERSION --save-exact`, commit their lockfile, run their checks, and redeploy. Portfolio, Design-System, Atmos, Orbit, and the library remain independent repositories.
-
-The compatibility gate also installs the optional Three.js and Lenis peers in separate packed consumers. It checks `/three` and `/scroll` with `skipLibCheck: false`, builds their imports, and verifies the Latin WOFF2 export. Core consumers continue to run without those optional peers. Run `npm run test:optional` for that focused check.
+Dependabot proposes dependency/action changes for review; changes are not auto-merged. Actions use pinned revisions and minimal permissions. Do not enable paid runners or private distribution as part of a release. Contributor and application checks remain separate from registry/deployment verification.

package/SECURITY.md

@@ -1,6 +1,6 @@
 # Security
 
-Report suspected vulnerabilities privately using GitHub's private vulnerability reporting for this repository once enabled. If that option is unavailable, contact the maintainer privately through their GitHub profile; do not post exploit details or credentials in a public issue.
+Report suspected vulnerabilities privately to abuzart1999@gmail.com. Include the affected version and a minimal reproduction without credentials or unrelated personal data. If GitHub private vulnerability reporting is available on this repository, it is another private channel. Do not post exploit details or credentials in a public issue.
 
 The latest published release is the supported version. Dependency audits identify known reported vulnerabilities, not all possible defects. No claim of complete security or formal accessibility certification is made.
 

package/dist/components/hero/SceneBoundary.js

@@ -1,3 +1,4 @@
+"use client";
 /** Error boundary that hides the 3D scene if its lazy module or renderer throws. */
 import { Component } from "react";
 export default class SceneBoundary extends Component {

package/dist/components/hero/Sculpture.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 /** Hero sculpture: three chrome/lime links that follow the pointer and drift while motion is on. */
 import { useRef } from "react";
@@ -5,10 +6,13 @@ import * as THREE from "three";
 import useThreeStage from "../../hooks/useThreeStage.js";
 import { createChrome, createLime, createLinkGeometry, } from "../../lib/threeMaterials.js";
 const restRotation = new THREE.Euler(-0.15, -0.1, -0.1);
-function setupSculpture({ scene }) {
+function setupSculpture({ scene, onDispose }) {
     const chrome = createChrome();
+    onDispose?.(() => chrome.dispose());
     const lime = createLime();
+    onDispose?.(() => lime.dispose());
     const geometry = createLinkGeometry();
+    onDispose?.(() => geometry.dispose());
     // Three interlocking links arranged as one assembly.
     const assembly = new THREE.Group();
     const firstLink = new THREE.Mesh(geometry, chrome);
@@ -36,9 +40,7 @@ function setupSculpture({ scene }) {
             assembly.position.y = 0;
         },
         dispose: () => {
-            geometry.dispose();
-            chrome.dispose();
-            lime.dispose();
+            scene.remove(assembly);
         },
     };
 }

package/dist/components/three/ObjectStudy.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 /** Lays out a set of 3D objects in a responsive grid; each turns slowly and the set leans toward the pointer. */
 import { useRef } from "react";
@@ -22,8 +23,9 @@ export default function ObjectStudy({ label, motionEnabled, study, }) {
     useThreeStage(hostRef, {
         motionEnabled,
         cameraDistance,
-        setup: ({ scene, camera }) => {
+        setup: ({ scene, camera, onDispose }) => {
             const set = objectStudies[study]();
+            onDispose?.(set.dispose);
             const group = new THREE.Group();
             set.objects.forEach((object) => {
                 object.rotation.copy(restTilt);
@@ -42,7 +44,6 @@ export default function ObjectStudy({ label, motionEnabled, study, }) {
             arrange();
             return {
                 update: ({ delta, elapsed, pointer }) => {
-                    arrange();
                     set.objects.forEach((object, index) => {
                         object.rotation.y += delta * 0.45;
                         object.rotation.x =
@@ -57,7 +58,10 @@ export default function ObjectStudy({ label, motionEnabled, study, }) {
                     group.rotation.set(0, 0, 0);
                     set.objects.forEach((object) => object.rotation.copy(restTilt));
                 },
-                dispose: set.dispose,
+                resize: arrange,
+                dispose: () => {
+                    scene.remove(group);
+                },
             };
         },
     });

package/dist/components/ui/Alert.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Asterisk, CircleCheck, CircleX, Info, TriangleAlert, X, } from "lucide-react";
 import { cx } from "../../lib/classNames.js";

package/dist/components/ui/BrandMark.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { safeHref } from "../../lib/safeHref.js";
 export default function BrandMark({ label, href = "#hero", onClick, }) {

package/dist/components/ui/Checkbox.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /** Square checkbox with an acid check, optional description, error, and indeterminate state. */
 import { useEffect, useId, useRef } from "react";

package/dist/components/ui/CountUp.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /** Number that counts up the first time it scrolls into view; screen readers get the final value. */
 import { useEffect, useRef, useState } from "react";

package/dist/components/ui/DataTable.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /** Editorial data table with mono headers, optional column sorting, and horizontal scroll on small screens. */
 import { useMemo, useState } from "react";

package/dist/components/ui/Dialog.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /** Modal dialog on the native <dialog> element; also slides in from either edge as a drawer. */
 import { useEffect, useId, useRef } from "react";

package/dist/components/ui/DropdownMenu.d.ts

@@ -5,10 +5,16 @@ export type MenuItem = {
     onSelect: () => void;
     icon?: ReactNode;
     danger?: boolean;
+    disabled?: boolean;
+    /** Stable identity when labels are duplicated or translated. */
+    id?: string;
 };
 export type DropdownMenuProps = {
     label: string;
     items: MenuItem[];
     align?: "start" | "end";
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
 };
-export default function DropdownMenu({ label, items, align, }: DropdownMenuProps): import("react").JSX.Element;
+export default function DropdownMenu({ label, items, align, open: controlledOpen, defaultOpen, onOpenChange, }: DropdownMenuProps): import("react").JSX.Element;

package/dist/components/ui/DropdownMenu.js

@@ -1,38 +1,86 @@
+"use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /** Button-triggered action menu with roving focus, Escape/outside dismissal, and focus return. */
-import { useCallback, useEffect, useId, useRef, useState, } from "react";
+import { useCallback, useEffect, useId, useRef } from "react";
 import { ChevronDown } from "lucide-react";
+import useOpenState from "../../hooks/useOpenState.js";
 import useDismiss from "../../hooks/useDismiss.js";
 import { cx } from "../../lib/classNames.js";
 import { nextIndexForKey } from "../../lib/keyboard.js";
-export default function DropdownMenu({ label, items, align = "start", }) {
+export default function DropdownMenu({ label, items, align = "start", open: controlledOpen, defaultOpen = false, onOpenChange, }) {
     const menuId = useId();
-    const [open, setOpen] = useState(false);
+    const [open, setOpen] = useOpenState(controlledOpen, defaultOpen, onOpenChange);
     const container = useRef(null);
     const trigger = useRef(null);
+    const initialFocus = useRef("first");
+    const search = useRef({ value: "", time: 0 });
     const itemRefs = useRef([]);
     const close = useCallback((returnFocus = true) => {
         setOpen(false);
         if (returnFocus)
             trigger.current?.focus();
-    }, []);
+    }, [setOpen]);
     useDismiss(container, open, useCallback((reason) => close(reason === "escape"), [close]));
     useEffect(() => {
-        if (open)
-            itemRefs.current[0]?.focus();
+        if (!open)
+            return;
+        search.current = { value: "", time: 0 };
+        const enabled = itemRefs.current.filter((item) => item && !item.disabled);
+        (initialFocus.current === "last" ? enabled.at(-1) : enabled[0])?.focus();
     }, [open]);
-    return (_jsxs("div", { ref: container, className: cx("menu", `menu-${align}`), children: [_jsxs("button", { ref: trigger, type: "button", className: "menu-trigger", "aria-haspopup": "menu", "aria-expanded": open, "aria-controls": menuId, onClick: () => setOpen((value) => !value), children: [label, _jsx(ChevronDown, { size: 15, "aria-hidden": "true", className: "menu-chevron" })] }), _jsx("div", { id: menuId, role: "menu", "aria-label": label, className: "menu-list", hidden: !open, children: items.map((item, index) => (_jsxs("button", { ref: (element) => {
+    return (_jsxs("div", { ref: container, className: cx("menu", `menu-${align}`), children: [_jsxs("button", { ref: trigger, type: "button", className: "menu-trigger", "aria-haspopup": "menu", "aria-expanded": open, "aria-controls": menuId, onClick: () => {
+                    initialFocus.current = "first";
+                    setOpen(!open);
+                }, onKeyDown: (event) => {
+                    if (event.key !== "ArrowDown" && event.key !== "ArrowUp")
+                        return;
+                    event.preventDefault();
+                    initialFocus.current = event.key === "ArrowUp" ? "last" : "first";
+                    if (open) {
+                        const enabled = itemRefs.current.filter((item) => item && !item.disabled);
+                        (initialFocus.current === "last"
+                            ? enabled.at(-1)
+                            : enabled[0])?.focus();
+                    }
+                    else
+                        setOpen(true);
+                }, children: [label, _jsx(ChevronDown, { size: 15, "aria-hidden": "true", className: "menu-chevron" })] }), _jsx("div", { id: menuId, role: "menu", "aria-label": label, className: "menu-list", hidden: !open, children: items.map((item, index) => (_jsxs("button", { ref: (element) => {
                         itemRefs.current[index] = element;
-                    }, type: "button", role: "menuitem", tabIndex: -1, className: cx("menu-item", item.danger && "menu-item-danger"), onClick: () => {
+                    }, type: "button", role: "menuitem", tabIndex: -1, disabled: item.disabled, className: cx("menu-item", item.danger && "menu-item-danger"), onClick: () => {
                         item.onSelect();
                         close();
                     }, onKeyDown: (event) => {
                         if (event.key === "Tab")
                             return close(false);
-                        const next = nextIndexForKey(event.key, index, items.length, "vertical");
-                        if (next === null)
-                            return;
-                        event.preventDefault();
-                        itemRefs.current[next]?.focus();
-                    }, children: [item.icon, item.label] }, item.label))) })] }));
+                        const enabled = items
+                            .map((entry, position) => (entry.disabled ? -1 : position))
+                            .filter((position) => position !== -1);
+                        const next = nextIndexForKey(event.key, enabled.indexOf(index), enabled.length, "vertical");
+                        if (next !== null) {
+                            event.preventDefault();
+                            itemRefs.current[enabled[next]]?.focus();
+                        }
+                        else if (event.key.length === 1 &&
+                            !event.ctrlKey &&
+                            !event.altKey &&
+                            !event.metaKey) {
+                            const now = performance.now();
+                            const previous = now - search.current.time < 500 ? search.current.value : "";
+                            const value = previous &&
+                                [...previous].every((letter) => letter === event.key.toLowerCase())
+                                ? event.key.toLowerCase()
+                                : previous + event.key.toLowerCase();
+                            search.current = { value, time: now };
+                            const start = enabled.indexOf(index) + 1;
+                            const ordered = [
+                                ...enabled.slice(start),
+                                ...enabled.slice(0, start),
+                            ];
+                            const match = ordered.find((position) => items[position].label.toLowerCase().startsWith(value));
+                            if (match !== undefined) {
+                                event.preventDefault();
+                                itemRefs.current[match]?.focus();
+                            }
+                        }
+                    }, children: [item.icon, item.label] }, item.id ?? item.label))) })] }));
 }

package/dist/components/ui/FlipCard.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /** Two-sided card that flips in 3D; a button toggles it so the back is reachable without hover. */
 import { useState, version } from "react";

package/dist/components/ui/Magnetic.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 /** Pulls its child toward a fine pointer while hovered, then springs back (an awwwards staple). */
 import { useRef } from "react";

package/dist/components/ui/Pagination.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /** Page navigation with previous/next controls and a condensed list of two-digit page numbers. */
 import { ArrowLeft, ArrowRight } from "lucide-react";

package/dist/components/ui/Popover.d.ts

@@ -6,5 +6,8 @@ export type PopoverProps = {
     title: string;
     children: ReactNode;
     align?: "start" | "end";
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
 };
-export default function Popover({ trigger, title, children, align, }: PopoverProps): import("react").JSX.Element;
+export default function Popover({ trigger, title, children, align, open: controlledOpen, defaultOpen, onOpenChange, }: PopoverProps): import("react").JSX.Element;

package/dist/components/ui/Popover.js

@@ -1,18 +1,20 @@
+"use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /** Non-modal floating panel anchored to a trigger; closes on Escape or an outside press. */
-import { useCallback, useId, useRef, useState } from "react";
+import { useCallback, useId, useRef } from "react";
+import useOpenState from "../../hooks/useOpenState.js";
 import useDismiss from "../../hooks/useDismiss.js";
 import { cx } from "../../lib/classNames.js";
-export default function Popover({ trigger, title, children, align = "start", }) {
+export default function Popover({ trigger, title, children, align = "start", open: controlledOpen, defaultOpen = false, onOpenChange, }) {
     const panelId = useId();
     const titleId = useId();
-    const [open, setOpen] = useState(false);
+    const [open, setOpen] = useOpenState(controlledOpen, defaultOpen, onOpenChange);
     const container = useRef(null);
     const button = useRef(null);
     useDismiss(container, open, useCallback((reason) => {
         setOpen(false);
         if (reason === "escape")
             button.current?.focus();
-    }, []));
-    return (_jsxs("div", { ref: container, className: cx("popover", `popover-${align}`), children: [_jsx("button", { ref: button, type: "button", className: "menu-trigger", "aria-expanded": open, "aria-controls": panelId, onClick: () => setOpen((value) => !value), children: trigger }), _jsxs("div", { id: panelId, role: "dialog", "aria-labelledby": titleId, className: "popover-panel", hidden: !open, children: [_jsx("strong", { id: titleId, className: "popover-title", children: title }), children] })] }));
+    }, [setOpen]));
+    return (_jsxs("div", { ref: container, className: cx("popover", `popover-${align}`), children: [_jsx("button", { ref: button, type: "button", className: "menu-trigger", "aria-expanded": open, "aria-controls": panelId, onClick: () => setOpen(!open), children: trigger }), _jsxs("div", { id: panelId, role: "dialog", "aria-labelledby": titleId, className: "popover-panel", hidden: !open, children: [_jsx("strong", { id: titleId, className: "popover-title", children: title }), children] })] }));
 }

package/dist/components/ui/RadioGroup.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /** Fieldset of round radio options sharing one name, with a mono legend. */
 import { useId } from "react";

package/dist/components/ui/Reveal.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 /** Fades and lifts its children into view the first time they enter the viewport. */
 import { useEffect, useRef } from "react";

package/dist/components/ui/ScrollProgress.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 /** Thin acid bar fixed to the top of the viewport that tracks page scroll progress. */
 import { useEffect, useRef } from "react";

package/dist/components/ui/SegmentedControl.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 /** Single-choice pill group (filter buttons) with arrow-key navigation. */
 import { useRef } from "react";