@abuzareal/contour-ui 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/CONTRACTS.md +93 -0
  3. package/CONTRIBUTING.md +2 -0
  4. package/PUBLIC-API.md +231 -0
  5. package/README.md +9 -5
  6. package/RELEASING.md +1 -1
  7. package/dist/components/ui/Checkbox.js +7 -1
  8. package/dist/hooks/useClipboardCopy.js +29 -6
  9. package/package.json +4 -2
package/CHANGELOG.md CHANGED
@@ -6,6 +6,24 @@ Changes to the published `@abuzareal/contour-ui` package. Version headings refer
6
6
 
7
7
  No changes recorded.
8
8
 
9
+ ## 0.2.1
10
+
11
+ A baseline contract release with compatible Checkbox ARIA and clipboard lifecycle fixes. Export names, prop types, visual defaults, dependencies and optional peer boundaries are unchanged from 0.2.0.
12
+
13
+ - Checkbox preserves caller-supplied validation attributes and associates its description and error with the native input.
14
+ - Clipboard feedback ignores writes that settle after unmount or after a newer copy request. No reset timer is created for an obsolete result.
15
+
16
+ - Publish the complete public-export and maturity register, including runtime/type-only distinctions, ownership, intended use, documentation destinations, known limits and scoped verification references.
17
+ - Publish architecture, adoption scope, environment/support evidence, dependency/size explanations and compatibility/deprecation rules.
18
+ - Clarify native form/ref limitations, local overlay behavior, inherited CSS/theme contracts and experimental/legacy APIs. Disclosure exposes defaultOpen; controlled open state belongs to Popover and DropdownMenu.
19
+ - Include both reference documents in the verified npm archive. Existing 0.2.0 consumers need no API or style migration; update the exact package pin and lockfile to receive the documents.
20
+
21
+ ```sh
22
+ npm install @abuzareal/contour-ui@0.2.1 --save-exact
23
+ ```
24
+
25
+ Publication is not established by this source heading. Verify npm availability; the catalogue's installed and hosted versions are separate.
26
+
9
27
  ## 0.2.0
10
28
 
11
29
  - 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.
package/CONTRACTS.md ADDED
@@ -0,0 +1,93 @@
1
+ # Architecture, scope and compatibility
2
+
3
+ Contract version **0.2.1**, reviewed 12 October 2026. Contour is an early 0.x React library with typed controls, paper/ink surfaces, a lime accent, light/dark themes, restrained motion and separate optional depth/scene APIs. The [public API and maturity register](PUBLIC-API.md) lists every exported value, type and stylesheet, its maintainer, status, use and limits.
4
+
5
+ ## Intended adoption scope
6
+
7
+ Use Contour in React web applications that want its supplied appearance and can manage global CSS and one document-level theme. Starting workflows are editable text/native choices, application-owned search/results, scalar locally sorted tables, modal settings and feedback. Existing editorial motion/identity exports remain available within their limits.
8
+
9
+ The first acceptance workflow is settings/search/table composition: edit a named TextField/SelectField/Checkbox, submit or reset the native form, own pending/error/retry in the app, filter supplied scalar records, change the root theme and open a settings Dialog. The catalogue already has [application patterns](https://contour.abuzr.in/docs/patterns) with local simulated adapters, not a backend. Switch and Slider settings currently use application state; RadioGroup uses a generated field name. Do not claim a stable caller-named FormData contract for those three controls.
10
+
11
+ Fetching, response validation, permissions, domain validation, persistence, URL state, server operations and truthful async outcomes belong to the application. A toast or demonstration does not mean data was saved. Apps supply labels, useful content, keyboard paths and accessible compositions.
12
+
13
+ Current scope excludes a general Combobox, multi-select, date/range picker, remote grid, tree, command palette, upload backend, chart/editor engine and non-React adapters. DataTable supports scalar string/number rows and local sorting. Drawer is Dialog placement; banner is Alert layout. New capabilities require a bounded contract, tests, documentation and demonstrated need.
14
+
15
+ No promise of enterprise completeness, universal embedding, all locales/RTL, every browser/framework or accessibility certification is made. Early 0.x status and experimental limits are adoption information.
16
+
17
+ ## Package and application ownership
18
+
19
+ | Area | Owner |
20
+ | --- | --- |
21
+ | Reusable controls, semantic tokens, shared theme/motion/browser lifecycle, public APIs and package releases | contour-ui |
22
+ | Catalogue shell/chapters, executable documentation/source display, discovery, examples and site delivery | Design-System |
23
+ | Product layouts/routes, domain data/calculations, workflows, requests, validation and product-specific scenes | Each application |
24
+
25
+ Repositories remain independent. Contour source is public and MIT licensed; catalogue source is currently private while hosted documentation is public. The catalogue's `private: true` prevents npm publication; it is separate from GitHub visibility. Visibility, history/assets/licensing review and CI runner policy are separate decisions.
26
+
27
+ Catalogue UI/hook/scene compatibility modules intentionally forward public package APIs; they are not copied implementations. Preserve them while callers exist. New integrations can import public exports directly. Editing library source does not update an installed or deployed application.
28
+
29
+ ## Implementation and dependency model
30
+
31
+ React is the UI runtime. Strict TypeScript/TSX source compiles through `tsc` into ES2022 ESM modules and declarations. The build copies CSS and selected licensed Latin font assets. It does not bundle React or compile the library into a Vite app. Vite serves development/consumer fixtures; Design-System is the Vite application. Consumers can write JavaScript or TypeScript.
32
+
33
+ | Category | Current packages | Consumer consequence |
34
+ | --- | --- | --- |
35
+ | Runtime dependencies | lucide-react; @fontsource-variable/dm-sans; @fontsource-variable/space-grotesk; @fontsource/dm-mono | Install with Contour. Selected imports determine browser output. Font CSS is optional; font installation currently is not. |
36
+ | Required peers | react/react-dom: `^18.3.1 || ^19.0.0` | App supplies a matching pair; allowed range is broader than individually tested versions. |
37
+ | Optional peers | three: `^0.186.1`; lenis: `^1.3.26` | Core works without either. Install explicitly for the matching optional entry. |
38
+ | Development dependencies | TypeScript, Vite, Oxlint, Testing Library, jsdom, Playwright, React/types and optional peer dev copies | Source authoring/tests/build; not downstream Contour production dependencies. |
39
+
40
+ Use explicit public paths; deep imports into dist internals are unsupported. CSS is marked as side-effectful to retain imported styles. The archive contains built modules/declarations/assets and release documents, with no consumer install scripts or private research.
41
+
42
+ Archive bytes, installed dependency bytes, browser JS/CSS, emitted fonts and actual requested/cached network assets are different measurements. An installed icon collection is not proof all icons download. JavaScript tree shaking does not remove unused aggregate CSS rules automatically. Size claims require version, fixture, tool versions, compression and exclusions; independent component gzip samples cannot be added as an application total.
43
+
44
+ ## Environment and validation policy
45
+
46
+ | Environment | Declared or exercised scope | Limits |
47
+ | --- | --- | --- |
48
+ | React/ReactDOM | Peer range above; packed matrix exercises 18.3.1, 19.0.0 and 19.3.0 | Matching pairs required. Other allowed patches are not individually certified. |
49
+ | TypeScript | Strict source/fixtures; pinned optional/Next fixtures use 5.9.3; React 18 and 19 declarations compiled | No universal older/newer compiler support claim; JS users need no compiler at runtime. |
50
+ | Node | Manifest >=22 for installation/tooling; use 22.12+ or 24+ with current Vite tooling | Browser components do not need Node in the browser. Actual runner versions are recorded per check. |
51
+ | ESM/CSS-capable bundler | Packed Vite consumers exercise imports/declarations/CSS/fonts with no optional peers | No CommonJS build or unbundled-browser CSS loader promised. |
52
+ | Next.js | Next 16.4.0 / React and ReactDOM 19.3.0, App Router, webpack production build | [NEXTJS.md](NEXTJS.md); other versions, Turbopack, Pages Router and Next Lenis remain unverified. |
53
+ | Optional Three | Separate consumers and lazy Next mode; explicit Three/types, WebGL, sized host and static fallback | Experimental API; sampled lifecycle checks do not validate every custom scene/GPU/device. |
54
+ | Optional scroll | Separate declaration/build consumer with Lenis and one scroll owner | Caller handles pause/reduced motion; generic Next Lenis integration unverified. |
55
+ | Browsers | Playwright Chromium exercises selected native-dialog/reset/graphics/hydration/catalogue journeys | Emulation is not a physical device. Chromium/axe is not Firefox/WebKit/Safari or manual VoiceOver/NVDA verification. |
56
+
57
+ Release gates use one exact archive: types/lint/build, Node/component tests, native-dialog/graphics browser checks, exports/archive inspection, React matrix, optional consumers, pinned Next core/lazy-Three modes and dependency audit. Catalogue has separate required checks/affected journeys. Record checksum, actual environments and passed/failed/skipped/blocked results. Historical results are dated evidence, not a fresh pass; see [RELEASING.md](RELEASING.md).
58
+
59
+ Interactive modules retain emitted client directives. Server-importable pure helpers do not mean interactive hooks run as Server Components. Keep handlers/state/providers in client boundaries. The bootstrap string has no user interpolation; restrictive CSP requires nonce/hash authorization. A fixture does not certify every deployment/CSP composition.
60
+
61
+ ## Styles, theme and motion
62
+
63
+ `styles.css` supplies tokens/components/utilities; `tokens.css` supplies tokens alone. Reset and either font stylesheet are optional. Import deliberate app overrides afterward. Current classes such as button/card/menu/mono and variables --bg/--fg are global. Reset contains inherited page-width/site-shell/section offsets; tokens retain portfolio/header values. These contracts are preserved; later isolation requires a versioned compatibility path.
64
+
65
+ Theme follows root data-theme and legacy aa-theme origin storage. Independent subtree themes are not a general contract; choose one owner in a multi-library page. Optional branded fonts are DM Sans, Space Grotesk and DM Mono. Existing font tokens also permit system fonts. Select Latin or broader coverage intentionally and preserve notices.
66
+
67
+ Respect system reduced motion and app pause. CSS depth is core; WebGL is separate. Lazy scenes need sized hosts, useful static content outside SceneBoundary, capped rendering cost, no unnecessary hidden/offscreen work and symmetric cleanup. Register owned custom cleanup immediately through onDispose, including failed initialization; avoid double disposal. Mount-captured setup changes need explicit remount.
68
+
69
+ ## Native semantics and known integration limits
70
+
71
+ Preserve native input/select/details/dialog behavior where appropriate. Future replacements require a written rationale and equivalent labels/descriptions, submission/disabled omission, validation/reset timing, keyboard/focus, modal scroll locking and cleanup, with relevant component/browser checks.
72
+
73
+ - TextField/TextArea/SelectField forward native refs; Button/IconButton do not on React 18. Ref/native-prop support varies; inspect declarations.
74
+ - Checkbox owns its ID/ref; 0.2.1 preserves caller ARIA validity and composes external descriptions with its own description/error. Switch/Slider/RadioGroup lack caller-named form contracts; serialize state deliberately.
75
+ - Popover/DropdownMenu use local absolute panels without portal/collision/submenu/custom-trigger contracts. Independent document listeners close both nested Popovers on one Escape: a reproduced defect.
76
+ - Tooltip closes on pointer leave and CSS prevents content hover: a source finding/accessibility risk requiring correction and pointer/focus verification, not a formal conformance audit. Hints must be supplemental and noninteractive.
77
+ - Dialog/Tabs/Popover have closed customization props. Do not invent root refs, slots or arbitrary attributes absent from declarations.
78
+ - Disclosure is native details with defaultOpen and required className, not controlled open/onOpenChange. Controlled open state belongs to Popover/DropdownMenu.
79
+ - BrandMark/editorial section/heading helpers and selected navigation/print hooks retain inherited page assumptions. They remain supported legacy APIs, not universal product primitives.
80
+
81
+ Recording these limits does not complete their later API/form/overlay/style fixes.
82
+
83
+ ## Change, deprecation and migration policy
84
+
85
+ The public contract includes documented exports/paths, props/events, types, styles/imports/tokens, native/ref/state behavior, visual defaults, theme/storage ownership and support environments. Undocumented private DOM structure is not a customization API; existing global classes used by consumers nevertheless need deliberate migration.
86
+
87
+ During 0.x, compatible fixes/docs use patch and compatible additions use minor. Incompatible API/type/CSS/token/visual/environment changes require a 0.x minor, explicit release notes and a tested migration. Do not hide narrower props, class/key renames or removals in a patch. Retain aliases/compatibility styles where feasible; document unavoidable changes before upgrade. Legacy status is not formal deprecation or permission to delete.
88
+
89
+ Formal deprecation identifies replacement/affected versions, marks the API/docs where feasible, and supplies migration guidance; no silent patch removal. After 1.0, incompatible public contracts require a major, additions minor and compatible fixes patch. No fixed support-window or response SLA is promised by this single-maintainer project.
90
+
91
+ Releases choose an unused version, align manifest/lock/tag/changelog, validate a candidate archive and state material limits. Consumers keep exact pins until the released version is installed, their lockfile updated and relevant checks pass. Package publication does not deploy an application.
92
+
93
+ 1.0 requires settled supported contracts, appropriate docs/evidence, successful outside-use workflows and no known critical/high-impact defect in the promoted scope. Complete stabilization, then rerun final release gates. Deferred component backlog completion is not a prerequisite.
package/CONTRIBUTING.md CHANGED
@@ -13,3 +13,5 @@ For a fix, add a regression that fails for the previous behavior. Use component
13
13
  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.
14
14
 
15
15
  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.
16
+
17
+ Public API changes must follow [the compatibility policy](CONTRACTS.md#change-deprecation-and-migration-policy) and update [the maturity register](PUBLIC-API.md). Preserve native semantics and optional entry isolation; an experimental or legacy label does not authorize an undocumented removal.
package/PUBLIC-API.md ADDED
@@ -0,0 +1,231 @@
1
+ # Public API and maturity register
2
+
3
+ Contract version: **0.2.1**, reviewed 12 October 2026. Export names, prop types and stylesheet APIs are unchanged from 0.2.0; Checkbox ARIA and clipboard lifecycle behavior receive compatible fixes. This register inventories the public entry declarations and actual JavaScript module exports; a catalogue specimen is not automatically a package export. Source links target the matching release tag. The catalogue URLs are discovery links, not immutable versioned documentation; its displayed example version may differ.
4
+
5
+ Maintainer: [@abuzareal](https://github.com/abuzareal). Every row has the same named owner; there is no implied support team or response-time guarantee. See [architecture, scope and compatibility](CONTRACTS.md), [contributing](CONTRIBUTING.md) and [private security reporting](SECURITY.md).
6
+
7
+ ## Status definitions
8
+
9
+ - **Stable (0.x):** the current documented contract is supported and changes require release notes and validation. This is not a 1.0 compatibility promise, full documentation coverage or proof of every state/browser.
10
+ - **Experimental:** supported only within the stated limits; interaction/scene APIs may change in an explicitly documented 0.x minor release. Existing users still receive migration instructions.
11
+ - **Legacy:** retained for existing editorial/personal-site integrations. It is not removed or formally deprecated by this register. Prefer application-owned identity/layout in new products.
12
+ - Types inherit their defining module's status. Type-only exports cannot be imported as runtime values. New 1.0 promotions require complete docs, relevant behavior/integration evidence and outside-use feedback.
13
+
14
+ ## Validation evidence key
15
+
16
+ **D**: emitted `.d.ts` contract and TypeScript checks. **C**: core import and packed consumers, with selected component regressions. **N**: separate packed optional-peer/declaration/build fixtures. **P**: package/bootstrap and exact pinned Next fixture. **G**: selected graphics lifecycle/paused-resize browser checks. The source fixtures are [public API](https://github.com/abuzareal/contour-ui/blob/v0.2.1/tests/public-api.test.mjs), [component behavior](https://github.com/abuzareal/contour-ui/blob/v0.2.1/tests/components.test.mjs), [native dialog](https://github.com/abuzareal/contour-ui/blob/v0.2.1/tests/dialog.browser.mjs), [graphics lifecycle](https://github.com/abuzareal/contour-ui/blob/v0.2.1/tests/stage.browser.mjs), [React matrix](https://github.com/abuzareal/contour-ui/blob/v0.2.1/scripts/test-compat.mjs) and [Next](https://github.com/abuzareal/contour-ui/blob/v0.2.1/scripts/test-next.mjs).
17
+
18
+ These identify reproducible checks, not claims that every row has a dedicated behavioral test. In particular, declaration compilation is not runtime validation, passing Chromium/axe is not manual screen-reader verification, and no blanket WCAG or framework certification is claimed. Release gates must run against the candidate archive before publication.
19
+
20
+ ## Core: @abuzareal/contour-ui
21
+
22
+ 72 runtime exports; 60 type-only exports.
23
+
24
+ ### Runtime exports
25
+
26
+ | Export / source | Maintainer | Status | Intended use | Known limits | Documentation | Evidence |
27
+ | --- | --- | --- | --- | --- | --- | --- |
28
+ | [`Alert`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Alert.tsx#L37) | @abuzareal | stable (0.x) | Inline feedback or banner | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#feedback) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
29
+ | [`Avatar`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Avatar.tsx#L19) | @abuzareal | stable (0.x) | Image or initials identity | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#metadata) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
30
+ | [`Badge`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Badge.tsx#L16) | @abuzareal | stable (0.x) | Short status label | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#metadata) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
31
+ | [`BrandMark`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/BrandMark.tsx#L12) | @abuzareal | legacy | Fixed inherited AA mark | Fixed inherited personal mark; supported for existing consumers, not a general logo system. | [Reference](https://contour.abuzr.in/docs#identity) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
32
+ | [`Breadcrumbs`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Breadcrumbs.tsx#L9) | @abuzareal | stable (0.x) | Page hierarchy navigation | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#navigation) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
33
+ | [`Button`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Button.tsx#L19) | @abuzareal | stable (0.x) | Native action button | No forwarded DOM ref on React 18; native attributes otherwise supported. | [Reference](https://contour.abuzr.in/docs#buttons) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
34
+ | [`Card`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Card.tsx#L16) | @abuzareal | stable (0.x) | Content and footer container | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#content) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
35
+ | [`Checkbox`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Checkbox.tsx#L18) | @abuzareal | stable (0.x) | Native checkbox with label/error | Internal ref/generated ID; no caller ID/ref contract; 0.2.1 preserves external ARIA and composes description/error. | [Reference](https://contour.abuzr.in/docs/components/checkbox) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
36
+ | [`CountUp`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/CountUp.tsx#L18) | @abuzareal | stable (0.x) | Animated numeric display | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
37
+ | [`DataTable`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/DataTable.tsx#L24) | @abuzareal | stable (0.x) | Scalar rows with local sorting | String/number row values and local sort only; no remote sort, selection, loading controller or virtualization. | [Reference](https://contour.abuzr.in/docs#data-table) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
38
+ | [`DepthButton`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/DepthButton.tsx#L8) | @abuzareal | stable (0.x) | Native action with CSS depth | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#buttons) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
39
+ | [`Dialog`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Dialog.tsx#L19) | @abuzareal | stable (0.x) | Native modal or edge drawer | Closed props; no native ref/root/part or initial-focus customization; app owns open/onClose. | [Reference](https://contour.abuzr.in/docs/components/dialog) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
40
+ | [`Disclosure`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Disclosure.tsx#L14) | @abuzareal | stable (0.x) | Native details/summary disclosure | Native details; defaultOpen only, no controlled open/onOpenChange; className is required. | [Reference](https://contour.abuzr.in/docs#content) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
41
+ | [`Divider`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Divider.tsx#L6) | @abuzareal | stable (0.x) | Content separation | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#content) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
42
+ | [`DropdownMenu`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/DropdownMenu.tsx#L30) | @abuzareal | experimental | Action menu with keyboard selection | Local absolute panel; no portal/collision/submenu API; shares nested-dismissal limitation. | [Reference](https://contour.abuzr.in/docs/components/dropdown-menu) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
43
+ | [`EmptyState`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/EmptyState.tsx#L11) | @abuzareal | stable (0.x) | Empty-result content and action | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#content) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
44
+ | [`ExternalLink`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/ExternalLink.tsx#L10) | @abuzareal | stable (0.x) | Styled native external anchor | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#buttons) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
45
+ | [`Field`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Field.tsx#L19) | @abuzareal | stable (0.x) | Label, hint and error frame | Caller wires the child ID/describedby; wrapper does not wire arbitrary children automatically. | [Reference](https://contour.abuzr.in/docs#field) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
46
+ | [`FlipCard`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/FlipCard.tsx#L19) | @abuzareal | stable (0.x) | Button-controlled two-face card | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
47
+ | [`IconButton`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/IconButton.tsx#L14) | @abuzareal | stable (0.x) | Native button with required accessible label | No forwarded DOM ref on React 18; caller supplies meaningful label. | [Reference](https://contour.abuzr.in/docs#buttons) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
48
+ | [`Kbd`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Kbd.tsx#L4) | @abuzareal | stable (0.x) | Keyboard shortcut label | Displays a shortcut, does not register one. | [Reference](https://contour.abuzr.in/docs#metadata) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
49
+ | [`Magnetic`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Magnetic.tsx#L13) | @abuzareal | stable (0.x) | Pointer-dependent decorative movement | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
50
+ | [`Marquee`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Marquee.tsx#L12) | @abuzareal | stable (0.x) | Repeated moving content strip | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
51
+ | [`Pagination`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Pagination.tsx#L25) | @abuzareal | stable (0.x) | Page-selection controls | Positive integer pages and in-range one-based page; application owns URL/fetch/slicing. | [Reference](https://contour.abuzr.in/docs#navigation) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
52
+ | [`Popover`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Popover.tsx#L20) | @abuzareal | experimental | Nonmodal panel with owned trigger | Local absolute panel; no portal/collision/custom-trigger/initial-focus API; nested Escape closes multiple layers. | [Reference](https://contour.abuzr.in/docs#floating) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
53
+ | [`ProgressBar`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/ProgressBar.tsx#L12) | @abuzareal | stable (0.x) | Determinate or indeterminate progress | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs/components/progress-bar) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
54
+ | [`RadioGroup`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/RadioGroup.tsx#L21) | @abuzareal | stable (0.x) | Native radio choices | Uses generated name; no caller field-name/form/ref contract; submit application state for stable keys. | [Reference](https://contour.abuzr.in/docs#choices) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
55
+ | [`Reveal`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Reveal.tsx#L13) | @abuzareal | stable (0.x) | Visibility-triggered content reveal | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
56
+ | [`RevealHeading`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/RevealHeading.tsx#L15) | @abuzareal | legacy | Editorial heading-line composition | Editorial h2 composition; application must preserve heading order. | [Reference](https://contour.abuzr.in/docs#identity) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
57
+ | [`ScrollProgress`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/ScrollProgress.tsx#L6) | @abuzareal | stable (0.x) | Document scroll readout | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
58
+ | [`SectionLabel`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/SectionLabel.tsx#L11) | @abuzareal | legacy | Editorial section metadata | Depends on Section editorial metadata/aside contract; not a general label primitive. | [Reference](https://contour.abuzr.in/docs#identity) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
59
+ | [`SegmentedControl`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/SegmentedControl.tsx#L14) | @abuzareal | stable (0.x) | Controlled single-choice buttons | No native named field or disabled-option API; application owns value and submission. | [Reference](https://contour.abuzr.in/docs#choices) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
60
+ | [`SelectField`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/SelectField.tsx#L17) | @abuzareal | stable (0.x) | Labelled native select | Native forwarded select ref; native choices, not searchable Combobox. | [Reference](https://contour.abuzr.in/docs/components/select-field) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
61
+ | [`Skeleton`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Skeleton.tsx#L11) | @abuzareal | stable (0.x) | Loading placeholder | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#feedback) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
62
+ | [`Slider`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Slider.tsx#L18) | @abuzareal | stable (0.x) | Controlled native range input | No name/form/ref contract; submit application state; keep numeric values within meaningful bounds. | [Reference](https://contour.abuzr.in/docs#choices) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
63
+ | [`GitHubIcon`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/SocialIcons.tsx#L5) | @abuzareal | stable (0.x) | GitHub SVG mark | SVG only; caller owns link destination and accessible name. | [Reference](https://contour.abuzr.in/docs#identity) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
64
+ | [`LinkedInIcon`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/SocialIcons.tsx#L16) | @abuzareal | stable (0.x) | LinkedIn SVG mark | SVG only; caller owns link destination and accessible name. | [Reference](https://contour.abuzr.in/docs#identity) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
65
+ | [`Spinner`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Spinner.tsx#L13) | @abuzareal | stable (0.x) | Loading status indicator | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#feedback) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
66
+ | [`Stat`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Stat.tsx#L10) | @abuzareal | stable (0.x) | Supplied value and label display | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#metadata) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
67
+ | [`Stepper`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Stepper.tsx#L13) | @abuzareal | stable (0.x) | Step-progress display | Progress display, not a navigable wizard; application owns state and validation. | [Reference](https://contour.abuzr.in/docs#navigation) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
68
+ | [`Switch`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Switch.tsx#L14) | @abuzareal | stable (0.x) | Controlled on/off button | State callback only; no name/form/ref/uncontrolled reset contract; submit application state. | [Reference](https://contour.abuzr.in/docs#choices) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
69
+ | [`Tabs`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Tabs.tsx#L29) | @abuzareal | stable (0.x) | Controlled or default tab selection | Closed props; selected ID controlled or default; no general slot/disabled-tab/orientation API. | [Reference](https://contour.abuzr.in/docs/components/tabs) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
70
+ | [`Tag`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Tag.tsx#L11) | @abuzareal | stable (0.x) | Short label with optional removal | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#metadata) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
71
+ | [`TextArea`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/TextArea.tsx#L24) | @abuzareal | stable (0.x) | Native textarea, counter and resize | Native forwarded textarea ref; parent owns controlled reset; sizing is browser dependent. | [Reference](https://contour.abuzr.in/docs/components/text-area) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
72
+ | [`TextField`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/TextField.tsx#L26) | @abuzareal | stable (0.x) | Native input with label/counter | Native forwarded input ref; parent owns controlled values/reset; do not switch state ownership. | [Reference](https://contour.abuzr.in/docs/components/text-field) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
73
+ | [`ThemeToggle`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/ThemeToggle.tsx#L12) | @abuzareal | stable (0.x) | Document-theme control | Root data-theme and aa-theme origin storage; no independently scoped theme provider. | [Reference](https://contour.abuzr.in/docs#theme-copy) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
74
+ | [`TiltCard`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/TiltCard.tsx#L13) | @abuzareal | stable (0.x) | Pointer-dependent CSS depth | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
75
+ | [`Timeline`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Timeline.tsx#L8) | @abuzareal | stable (0.x) | Ordered entries supplied by caller | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#content) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
76
+ | [`ToastProvider`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/ToastProvider.tsx#L67) | @abuzareal | stable (0.x) | Toast context, queue and announcements | No application persistence; important failures need a durable visible record as well. | [Reference](https://contour.abuzr.in/docs/components/toast-provider) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
77
+ | [`Tooltip`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Tooltip.tsx#L14) | @abuzareal | experimental | Supplemental text hint | Pointer leave closes it and CSS prevents content hover; supplemental noninteractive text only; no collision engine. | [Reference](https://contour.abuzr.in/docs#floating) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
78
+ | [`useClipboardCopy`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useClipboardCopy.ts#L10) | @abuzareal | stable (0.x) | Clipboard operation and feedback state | Clipboard access can fail; obsolete text/request/unmount completions are discarded in 0.2.1; app presents truthful feedback. | [Reference](https://contour.abuzr.in/docs#theme-copy) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
79
+ | [`useDismiss`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useDismiss.ts#L6) | @abuzareal | experimental | Document Escape/outside-press subscription | Independent global document listeners; no layer stack/portal/owner-document model; caller manages focus. | [Reference](https://contour.abuzr.in/docs#browser-hooks) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
80
+ | [`useHeaderScroll`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useHeaderScroll.ts#L9) | @abuzareal | legacy | Editorial header/section state | Assumes main section[id] and header-theme regions; application owns page structure. | [Reference](https://contour.abuzr.in/docs#browser-hooks) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
81
+ | [`useIdleTrigger`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useIdleTrigger.ts#L9) | @abuzareal | stable (0.x) | Idle-time activation | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#browser-hooks) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
82
+ | [`useInitialHashScroll`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useInitialHashScroll.ts#L8) | @abuzareal | legacy | Initial document-hash scrolling | Initial hash only; application owns routing and unknown targets. | [Reference](https://contour.abuzr.in/docs#browser-hooks) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
83
+ | [`useMobileMenu`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useMobileMenu.ts#L8) | @abuzareal | experimental | Menu open/close and resize state | Caller provides semantics/focus; closes on Escape/outside press and desktop resize. | [Reference](https://contour.abuzr.in/docs#browser-hooks) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
84
+ | [`useMotionPreference`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useMotionPreference.ts#L8) | @abuzareal | stable (0.x) | System reduced-motion subscription | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#theme-copy) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
85
+ | [`usePrintPreparation`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/usePrintPreparation.ts#L6) | @abuzareal | legacy | Temporary print theme/disclosure changes | Mutates root theme/details during printing; application must verify print layout. | [Reference](https://contour.abuzr.in/docs#browser-hooks) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
86
+ | [`useScrollSpy`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useScrollSpy.ts#L9) | @abuzareal | stable (0.x) | Active section observation | Stable section IDs and existing DOM anchors required; does not provide routing. | [Reference](https://contour.abuzr.in/docs#browser-hooks) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
87
+ | [`useTheme`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useTheme.ts#L84) | @abuzareal | stable (0.x) | Shared document-theme preference | Root data-theme and aa-theme origin storage; client lifecycle; embedding needs one theme owner. | [Reference](https://contour.abuzr.in/docs#theme-copy) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
88
+ | [`useToast`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useToast.ts#L19) | @abuzareal | stable (0.x) | Toast commands from provider | Must be called under ToastProvider; ephemeral feedback is not an operation result. | [Reference](https://contour.abuzr.in/docs#toasts) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
89
+ | [`SceneBoundary`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/hero/SceneBoundary.tsx#L9) | @abuzareal | experimental | Hide failed scene subtree | Renders null after failure; no fallback prop/reset API; keep usable static content outside it. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
90
+ | [`safeHref`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/safeHref.ts#L2) | @abuzareal | stable (0.x) | Reject executable URL schemes | Scheme validation only, not URL trust/authorization validation. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
91
+ | [`cx`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/classNames.ts#L2) | @abuzareal | stable (0.x) | Join optional CSS class names | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
92
+ | [`buttonClassName`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/classNames.ts#L10) | @abuzareal | stable (0.x) | Shared button-class recipe for buttons/anchors | Returns existing global classes; styled anchor retains native link responsibilities. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
93
+ | [`formatIndex`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/format.ts#L4) | @abuzareal | stable (0.x) | Two-digit index formatting | Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
94
+ | [`readStorage`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/storage.ts#L14) | @abuzareal | legacy | Read local/session string safely | Returns raw string/null; caller parses and validates; no persistence guarantee. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
95
+ | [`writeStorage`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/storage.ts#L23) | @abuzareal | legacy | Attempt local/session string persistence | Returns success boolean; browser policy can block persistence. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
96
+ | [`storageKeys`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/storage.ts#L3) | @abuzareal | legacy | Inherited shared storage key names | Legacy aa-* keys are public compatibility constraints; no silent rename. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
97
+ | [`nextIndexForKey`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/keyboard.ts#L14) | @abuzareal | stable (0.x) | Keyboard navigation index calculation | Calculates index, does not move focus or perform selection. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
98
+ | [`fieldDescribedBy`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/a11y.ts#L4) | @abuzareal | stable (0.x) | Field hint/error ID calculation | Error description takes precedence over hint; caller connects the target input. | [Reference](https://contour.abuzr.in/docs#field) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
99
+ | [`motionDisabledFor`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/motion.ts#L4) | @abuzareal | stable (0.x) | System and ancestor motion check | Browser/ancestor check; app still owns animation cancellation. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
100
+
101
+ ### Type-only exports
102
+
103
+ | Export / source | Maintainer | Status | Intended use | Known limits | Documentation | Evidence |
104
+ | --- | --- | --- | --- | --- | --- | --- |
105
+ | [`Section`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/types.ts#L1) | @abuzareal | stable (0.x) | Type contract for Section | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
106
+ | [`AlertTone`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Alert.tsx#L15) | @abuzareal | stable (0.x) | Type contract for Alert | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#feedback) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
107
+ | [`AlertProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Alert.tsx#L27) | @abuzareal | stable (0.x) | Type contract for Alert | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#feedback) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
108
+ | [`AvatarProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Avatar.tsx#L4) | @abuzareal | stable (0.x) | Type contract for Avatar | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#metadata) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
109
+ | [`BadgeTone`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Badge.tsx#L5) | @abuzareal | stable (0.x) | Type contract for Badge | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#metadata) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
110
+ | [`BadgeProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Badge.tsx#L8) | @abuzareal | stable (0.x) | Type contract for Badge | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#metadata) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
111
+ | [`BrandMarkProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/BrandMark.tsx#L6) | @abuzareal | legacy | Type contract for BrandMark | Type-only; no runtime value. Fixed inherited personal mark; supported for existing consumers, not a general logo system. | [Reference](https://contour.abuzr.in/docs#identity) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
112
+ | [`BreadcrumbsProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Breadcrumbs.tsx#L5) | @abuzareal | stable (0.x) | Type contract for Breadcrumbs | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#navigation) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
113
+ | [`ButtonProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Button.tsx#L10) | @abuzareal | stable (0.x) | Type contract for Button | Type-only; no runtime value. No forwarded DOM ref on React 18; native attributes otherwise supported. | [Reference](https://contour.abuzr.in/docs#buttons) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
114
+ | [`CardProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Card.tsx#L5) | @abuzareal | stable (0.x) | Type contract for Card | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#content) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
115
+ | [`CheckboxProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Checkbox.tsx#L8) | @abuzareal | stable (0.x) | Type contract for Checkbox | Type-only; no runtime value. Internal ref/generated ID; no caller ID/ref contract; 0.2.1 preserves external ARIA and composes description/error. | [Reference](https://contour.abuzr.in/docs/components/checkbox) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
116
+ | [`CountUpProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/CountUp.tsx#L7) | @abuzareal | stable (0.x) | Type contract for CountUp | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
117
+ | [`TableColumn`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/DataTable.tsx#L7) | @abuzareal | stable (0.x) | Type contract for DataTable | Type-only; no runtime value. String/number row values and local sort only; no remote sort, selection, loading controller or virtualization. | [Reference](https://contour.abuzr.in/docs#data-table) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
118
+ | [`DataTableProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/DataTable.tsx#L15) | @abuzareal | stable (0.x) | Type contract for DataTable | Type-only; no runtime value. String/number row values and local sort only; no remote sort, selection, loading controller or virtualization. | [Reference](https://contour.abuzr.in/docs#data-table) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
119
+ | [`DepthButtonProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/DepthButton.tsx#L4) | @abuzareal | stable (0.x) | Type contract for DepthButton | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#buttons) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
120
+ | [`DialogProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Dialog.tsx#L9) | @abuzareal | stable (0.x) | Type contract for Dialog | Type-only; no runtime value. Closed props; no native ref/root/part or initial-focus customization; app owns open/onClose. | [Reference](https://contour.abuzr.in/docs/components/dialog) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
121
+ | [`DisclosureProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Disclosure.tsx#L5) | @abuzareal | stable (0.x) | Type contract for Disclosure | Type-only; no runtime value. Native details; defaultOpen only, no controlled open/onOpenChange; className is required. | [Reference](https://contour.abuzr.in/docs#content) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
122
+ | [`DividerProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Divider.tsx#L2) | @abuzareal | stable (0.x) | Type contract for Divider | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#content) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
123
+ | [`MenuItem`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/DropdownMenu.tsx#L11) | @abuzareal | experimental | Type contract for DropdownMenu | Type-only; no runtime value. Local absolute panel; no portal/collision/submenu API; shares nested-dismissal limitation. | [Reference](https://contour.abuzr.in/docs/components/dropdown-menu) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
124
+ | [`DropdownMenuProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/DropdownMenu.tsx#L21) | @abuzareal | experimental | Type contract for DropdownMenu | Type-only; no runtime value. Local absolute panel; no portal/collision/submenu API; shares nested-dismissal limitation. | [Reference](https://contour.abuzr.in/docs/components/dropdown-menu) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
125
+ | [`EmptyStateProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/EmptyState.tsx#L4) | @abuzareal | stable (0.x) | Type contract for EmptyState | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#content) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
126
+ | [`ExternalLinkProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/ExternalLink.tsx#L5) | @abuzareal | stable (0.x) | Type contract for ExternalLink | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#buttons) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
127
+ | [`FieldProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Field.tsx#L6) | @abuzareal | stable (0.x) | Type contract for Field | Type-only; no runtime value. Caller wires the child ID/describedby; wrapper does not wire arbitrary children automatically. | [Reference](https://contour.abuzr.in/docs#field) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
128
+ | [`FlipCardProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/FlipCard.tsx#L8) | @abuzareal | stable (0.x) | Type contract for FlipCard | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
129
+ | [`IconButtonProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/IconButton.tsx#L5) | @abuzareal | stable (0.x) | Type contract for IconButton | Type-only; no runtime value. No forwarded DOM ref on React 18; caller supplies meaningful label. | [Reference](https://contour.abuzr.in/docs#buttons) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
130
+ | [`MagneticProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Magnetic.tsx#L7) | @abuzareal | stable (0.x) | Type contract for Magnetic | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
131
+ | [`MarqueeProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Marquee.tsx#L5) | @abuzareal | stable (0.x) | Type contract for Marquee | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
132
+ | [`PaginationProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Pagination.tsx#L7) | @abuzareal | stable (0.x) | Type contract for Pagination | Type-only; no runtime value. Positive integer pages and in-range one-based page; application owns URL/fetch/slicing. | [Reference](https://contour.abuzr.in/docs#navigation) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
133
+ | [`PopoverProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Popover.tsx#L9) | @abuzareal | experimental | Type contract for Popover | Type-only; no runtime value. Local absolute panel; no portal/collision/custom-trigger/initial-focus API; nested Escape closes multiple layers. | [Reference](https://contour.abuzr.in/docs#floating) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
134
+ | [`ProgressBarProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/ProgressBar.tsx#L5) | @abuzareal | stable (0.x) | Type contract for ProgressBar | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs/components/progress-bar) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
135
+ | [`RadioGroupProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/RadioGroup.tsx#L7) | @abuzareal | stable (0.x) | Type contract for RadioGroup | Type-only; no runtime value. Uses generated name; no caller field-name/form/ref contract; submit application state for stable keys. | [Reference](https://contour.abuzr.in/docs#choices) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
136
+ | [`RevealProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Reveal.tsx#L6) | @abuzareal | stable (0.x) | Type contract for Reveal | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
137
+ | [`HeadingLine`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/RevealHeading.tsx#L4) | @abuzareal | legacy | Type contract for RevealHeading | Type-only; no runtime value. Editorial h2 composition; application must preserve heading order. | [Reference](https://contour.abuzr.in/docs#identity) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
138
+ | [`RevealHeadingProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/RevealHeading.tsx#L10) | @abuzareal | legacy | Type contract for RevealHeading | Type-only; no runtime value. Editorial h2 composition; application must preserve heading order. | [Reference](https://contour.abuzr.in/docs#identity) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
139
+ | [`SectionLabelProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/SectionLabel.tsx#L5) | @abuzareal | legacy | Type contract for SectionLabel | Type-only; no runtime value. Depends on Section editorial metadata/aside contract; not a general label primitive. | [Reference](https://contour.abuzr.in/docs#identity) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
140
+ | [`SegmentedControlProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/SegmentedControl.tsx#L7) | @abuzareal | stable (0.x) | Type contract for SegmentedControl | Type-only; no runtime value. No native named field or disabled-option API; application owns value and submission. | [Reference](https://contour.abuzr.in/docs#choices) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
141
+ | [`SelectFieldProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/SelectField.tsx#L9) | @abuzareal | stable (0.x) | Type contract for SelectField | Type-only; no runtime value. Native forwarded select ref; native choices, not searchable Combobox. | [Reference](https://contour.abuzr.in/docs/components/select-field) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
142
+ | [`SkeletonProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Skeleton.tsx#L5) | @abuzareal | stable (0.x) | Type contract for Skeleton | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#feedback) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
143
+ | [`SliderProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Slider.tsx#L6) | @abuzareal | stable (0.x) | Type contract for Slider | Type-only; no runtime value. No name/form/ref contract; submit application state; keep numeric values within meaningful bounds. | [Reference](https://contour.abuzr.in/docs#choices) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
144
+ | [`SocialIconProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/SocialIcons.tsx#L3) | @abuzareal | stable (0.x) | Type contract for LinkedInIcon | Type-only; no runtime value. SVG only; caller owns link destination and accessible name. | [Reference](https://contour.abuzr.in/docs#identity) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
145
+ | [`SpinnerProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Spinner.tsx#L5) | @abuzareal | stable (0.x) | Type contract for Spinner | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#feedback) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
146
+ | [`StatProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Stat.tsx#L4) | @abuzareal | stable (0.x) | Type contract for Stat | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#metadata) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
147
+ | [`StepperProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Stepper.tsx#L6) | @abuzareal | stable (0.x) | Type contract for Stepper | Type-only; no runtime value. Progress display, not a navigable wizard; application owns state and validation. | [Reference](https://contour.abuzr.in/docs#navigation) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
148
+ | [`SwitchProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Switch.tsx#L6) | @abuzareal | stable (0.x) | Type contract for Switch | Type-only; no runtime value. State callback only; no name/form/ref/uncontrolled reset contract; submit application state. | [Reference](https://contour.abuzr.in/docs#choices) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
149
+ | [`TabItem`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Tabs.tsx#L14) | @abuzareal | stable (0.x) | Type contract for Tabs | Type-only; no runtime value. Closed props; selected ID controlled or default; no general slot/disabled-tab/orientation API. | [Reference](https://contour.abuzr.in/docs/components/tabs) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
150
+ | [`TabsProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Tabs.tsx#L20) | @abuzareal | stable (0.x) | Type contract for Tabs | Type-only; no runtime value. Closed props; selected ID controlled or default; no general slot/disabled-tab/orientation API. | [Reference](https://contour.abuzr.in/docs/components/tabs) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
151
+ | [`TagProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Tag.tsx#L6) | @abuzareal | stable (0.x) | Type contract for Tag | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#metadata) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
152
+ | [`TextAreaProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/TextArea.tsx#L16) | @abuzareal | stable (0.x) | Type contract for TextArea | Type-only; no runtime value. Native forwarded textarea ref; parent owns controlled reset; sizing is browser dependent. | [Reference](https://contour.abuzr.in/docs/components/text-area) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
153
+ | [`TextFieldProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/TextField.tsx#L16) | @abuzareal | stable (0.x) | Type contract for TextField | Type-only; no runtime value. Native forwarded input ref; parent owns controlled values/reset; do not switch state ownership. | [Reference](https://contour.abuzr.in/docs/components/text-field) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
154
+ | [`ThemeToggleProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/ThemeToggle.tsx#L7) | @abuzareal | stable (0.x) | Type contract for ThemeToggle | Type-only; no runtime value. Root data-theme and aa-theme origin storage; no independently scoped theme provider. | [Reference](https://contour.abuzr.in/docs#theme-copy) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
155
+ | [`TiltCardProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/TiltCard.tsx#L7) | @abuzareal | stable (0.x) | Type contract for TiltCard | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#motion) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
156
+ | [`TimelineProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Timeline.tsx#L4) | @abuzareal | stable (0.x) | Type contract for Timeline | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#content) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
157
+ | [`TooltipProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/ui/Tooltip.tsx#L7) | @abuzareal | experimental | Type contract for Tooltip | Type-only; no runtime value. Pointer leave closes it and CSS prevents content hover; supplemental noninteractive text only; no collision engine. | [Reference](https://contour.abuzr.in/docs#floating) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
158
+ | [`CopyStatus`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useClipboardCopy.ts#L6) | @abuzareal | stable (0.x) | Type contract for useClipboardCopy | Type-only; no runtime value. Clipboard access can fail; obsolete text/request/unmount completions are discarded in 0.2.1; app presents truthful feedback. | [Reference](https://contour.abuzr.in/docs#theme-copy) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
159
+ | [`Theme`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useTheme.ts#L9) | @abuzareal | stable (0.x) | Type contract for useTheme | Type-only; no runtime value. Root data-theme and aa-theme origin storage; client lifecycle; embedding needs one theme owner. | [Reference](https://contour.abuzr.in/docs#theme-copy) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
160
+ | [`ToastInput`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useToast.ts#L7) | @abuzareal | stable (0.x) | Type contract for useToast | Type-only; no runtime value. Must be called under ToastProvider; ephemeral feedback is not an operation result. | [Reference](https://contour.abuzr.in/docs#toasts) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
161
+ | [`ToastContextValue`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useToast.ts#L13) | @abuzareal | stable (0.x) | Type contract for useToast | Type-only; no runtime value. Must be called under ToastProvider; ephemeral feedback is not an operation result. | [Reference](https://contour.abuzr.in/docs#toasts) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
162
+ | [`ToastContext`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useToast.ts#L17) | @abuzareal | stable (0.x) | Type contract for useToast | Type-only; no runtime value. Must be called under ToastProvider; ephemeral feedback is not an operation result. | [Reference](https://contour.abuzr.in/docs#toasts) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
163
+ | [`ButtonVariant`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/classNames.ts#L5) | @abuzareal | stable (0.x) | Type contract for buttonClassName | Type-only; no runtime value. Returns existing global classes; styled anchor retains native link responsibilities. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
164
+ | [`ButtonSize`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/classNames.ts#L7) | @abuzareal | stable (0.x) | Type contract for buttonClassName | Type-only; no runtime value. Returns existing global classes; styled anchor retains native link responsibilities. | [Reference](https://contour.abuzr.in/docs#utilities) | D: emitted declaration; C: core package compile/import; behavior coverage is sampled |
165
+
166
+ ## Optional: @abuzareal/contour-ui/three
167
+
168
+ 11 runtime exports; 7 type-only exports.
169
+
170
+ ### Runtime exports
171
+
172
+ | Export / source | Maintainer | Status | Intended use | Known limits | Documentation | Evidence |
173
+ | --- | --- | --- | --- | --- | --- | --- |
174
+ | [`Sculpture`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/hero/Sculpture.tsx#L73) | @abuzareal | experimental | Experimental link sculpture scene | WebGL, sized container, lazy/static fallback and motionEnabled required; setup captured on mount. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
175
+ | [`ObjectStudy`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/three/ObjectStudy.tsx#L34) | @abuzareal | experimental | Experimental material/geometry scene | WebGL, sized container, study/label/motionEnabled required; experimental scene contract. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
176
+ | [`useThreeStage`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useThreeStage.ts#L41) | @abuzareal | experimental | Experimental renderer and scene lifecycle | Setup captured on mount; register owned cleanup immediately with onDispose; do not double-dispose. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
177
+ | [`createLinkGeometry`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/threeMaterials.ts#L58) | @abuzareal | experimental | Create owned link geometry | Experimental GPU resource; caller owns disposal, sized lazy scene and usable static fallback. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
178
+ | [`createChrome`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/threeMaterials.ts#L4) | @abuzareal | experimental | Create owned chrome material | Experimental GPU resource; caller owns disposal, sized lazy scene and usable static fallback. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
179
+ | [`createLime`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/threeMaterials.ts#L12) | @abuzareal | experimental | Create owned lime material | Experimental GPU resource; caller owns disposal, sized lazy scene and usable static fallback. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
180
+ | [`createInk`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/threeMaterials.ts#L20) | @abuzareal | experimental | Create owned ink material | Experimental GPU resource; caller owns disposal, sized lazy scene and usable static fallback. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
181
+ | [`createGlass`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/threeMaterials.ts#L29) | @abuzareal | experimental | Create owned glass material | Experimental GPU resource; caller owns disposal, sized lazy scene and usable static fallback. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
182
+ | [`createMaterialSet`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/threeStudies.ts#L18) | @abuzareal | experimental | Create owned material-study objects | Experimental GPU resource; caller owns disposal, sized lazy scene and usable static fallback. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
183
+ | [`createGeometrySet`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/threeStudies.ts#L31) | @abuzareal | experimental | Create owned geometry-study objects | Experimental GPU resource; caller owns disposal, sized lazy scene and usable static fallback. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
184
+ | [`objectStudies`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/threeStudies.ts#L52) | @abuzareal | experimental | Named scene factories | Experimental GPU resource; caller owns disposal, sized lazy scene and usable static fallback. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
185
+
186
+ ### Type-only exports
187
+
188
+ | Export / source | Maintainer | Status | Intended use | Known limits | Documentation | Evidence |
189
+ | --- | --- | --- | --- | --- | --- | --- |
190
+ | [`StageFrame`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useThreeStage.ts#L8) | @abuzareal | experimental | Type contract for useThreeStage | Type-only; no runtime value. Setup captured on mount; register owned cleanup immediately with onDispose; do not double-dispose. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
191
+ | [`StageScene`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useThreeStage.ts#L15) | @abuzareal | experimental | Type contract for useThreeStage | Type-only; no runtime value. Setup captured on mount; register owned cleanup immediately with onDispose; do not double-dispose. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
192
+ | [`StageContext`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useThreeStage.ts#L24) | @abuzareal | experimental | Type contract for useThreeStage | Type-only; no runtime value. Setup captured on mount; register owned cleanup immediately with onDispose; do not double-dispose. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
193
+ | [`SculptureProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/hero/Sculpture.tsx#L16) | @abuzareal | experimental | Type contract for Sculpture | Type-only; no runtime value. WebGL, sized container, lazy/static fallback and motionEnabled required; setup captured on mount. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
194
+ | [`ObjectStudyProps`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/components/three/ObjectStudy.tsx#L12) | @abuzareal | experimental | Type contract for ObjectStudy | Type-only; no runtime value. WebGL, sized container, study/label/motionEnabled required; experimental scene contract. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
195
+ | [`ObjectSet`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/threeStudies.ts#L12) | @abuzareal | experimental | Type contract for objectStudies | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
196
+ | [`ObjectStudyKind`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/threeStudies.ts#L57) | @abuzareal | experimental | Type contract for objectStudies | Type-only; no runtime value. Global CSS/root theme; use declared props only; application composition needs its own validation. | [Reference](https://contour.abuzr.in/docs#optional-three) | D: emitted declaration; N: optional declaration/build fixture; G: sampled graphics lifecycle |
197
+
198
+ ## Optional: @abuzareal/contour-ui/scroll
199
+
200
+ 1 runtime exports; 0 type-only exports.
201
+
202
+ ### Runtime exports
203
+
204
+ | Export / source | Maintainer | Status | Intended use | Known limits | Documentation | Evidence |
205
+ | --- | --- | --- | --- | --- | --- | --- |
206
+ | [`useSmoothScroll`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/hooks/useSmoothScroll.ts#L7) | @abuzareal | experimental | Optional Lenis lifecycle | Install Lenis and its CSS explicitly; one owner; caller disables it for pause/reduced motion. | [Reference](https://contour.abuzr.in/docs#optional-scroll) | D: emitted declaration; N: optional declaration/build fixture |
207
+
208
+ ## Server-safe string/helpers: @abuzareal/contour-ui/theme-bootstrap
209
+
210
+ 2 runtime exports; 0 type-only exports.
211
+
212
+ ### Runtime exports
213
+
214
+ | Export / source | Maintainer | Status | Intended use | Known limits | Documentation | Evidence |
215
+ | --- | --- | --- | --- | --- | --- | --- |
216
+ | [`themeColors`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/themeBootstrap.ts#L6) | @abuzareal | stable (0.x) | Theme-background constants | Fixed backgrounds must match token defaults; consumer themes may need own metadata. | [Reference](https://contour.abuzr.in/docs/getting-started#theme-motion) | D: emitted declaration; P: bootstrap package/Next fixture |
217
+ | [`themeBootstrapScript`](https://github.com/abuzareal/contour-ui/blob/v0.2.1/src/lib/themeBootstrap.ts#L11) | @abuzareal | stable (0.x) | Pre-paint theme initialization string | Authorize inline script through CSP nonce/hash; no user interpolation; root preference only. | [Reference](https://contour.abuzr.in/docs/getting-started#theme-motion) | D: emitted declaration; P: bootstrap package/Next fixture |
218
+
219
+ ## Stylesheet exports
220
+
221
+ | Import | Maintainer | Status | Purpose and limits | Documentation | Evidence |
222
+ | --- | --- | --- | --- | --- | --- |
223
+ | `styles.css` | @abuzareal | stable (0.x) | Aggregate component CSS, tokens and utilities; global classes, not selective CSS tree shaking. | [Styles](README.md#styles-and-customization) | Package/export and consumer build checks |
224
+ | `tokens.css` | @abuzareal | stable (0.x) | Root semantic tokens; includes inherited product values, no general scoped-theme contract. | [Theme contract](CONTRACTS.md#styles-theme-and-motion) | Package/export and source-token inspection |
225
+ | `reset.css` | @abuzareal | legacy | Optional global element defaults plus inherited page-width/site-shell/section offsets; affects the host document. | [Reset scope](CONTRACTS.md#styles-theme-and-motion) | Package/export and consumer build checks |
226
+ | `fonts.css` | @abuzareal | stable (0.x) | Optional Fontsource CSS; branded font dependencies still install; wider character coverage. | [Fonts](README.md#optional-latin-fonts) | Core packed consumer/CSS build checks |
227
+ | `fonts-latin.css` | @abuzareal | stable (0.x) | Optional relative Latin WOFF2 files and notices; choose instead of fonts.css; narrower coverage. | [Fonts](README.md#optional-latin-fonts) | Optional consumer asset and Next webpack checks |
228
+
229
+ The inventory has 86 runtime entries, 67 type-only entries and five stylesheet entries across public paths. Core includes 48 default UI components, two social icons, SceneBoundary, 11 hooks and ten helpers/constants. No `Drawer`, `Banner`, `Combobox`, `FocusBand` or `ProjectCard` runtime export is implied. Drawer is Dialog placement; banner is Alert layout; native Disclosure supplies disclosure behavior. Catalogue page/grid/spacing/resource-card and workflow specimens are application examples.
230
+
231
+ `SceneBoundaryProps` is declared in its module but is not re-exported from the core entry. `ToastContext` is exposed only through a type-only star export; it is not a root runtime value. Use public paths and emitted declarations rather than deep imports into dist internals.
package/README.md CHANGED
@@ -6,14 +6,18 @@ Use it when you want this visual style with typed controls, feedback, navigation
6
6
 
7
7
  [Live catalogue](https://contour.abuzr.in/) · [npm package](https://www.npmjs.com/package/@abuzareal/contour-ui) · [Maintainer](https://github.com/abuzareal)
8
8
 
9
- 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.
9
+ This source checkout targets **0.2.1**. 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.
10
+
11
+ [Public API and maturity register](PUBLIC-API.md) · [Architecture, scope and compatibility](CONTRACTS.md)
12
+
13
+ Version 0.2.1 documents baseline contracts and limitations and includes compatible Checkbox ARIA and clipboard lifecycle fixes. Export names, prop types, style defaults, dependencies and optional entry boundaries match 0.2.0. It remains an early 0.x library.
10
14
 
11
15
  ## Install
12
16
 
13
17
  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+.
14
18
 
15
19
  ```sh
16
- npm install @abuzareal/contour-ui@0.2.0 --save-exact
20
+ npm install @abuzareal/contour-ui@0.2.1 --save-exact
17
21
  ```
18
22
 
19
23
  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,10 +161,10 @@ Give scenes a sized container and a usable static fallback. `SceneBoundary` hide
157
161
 
158
162
  ## Release notes and upgrades
159
163
 
160
- **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.
164
+ **0.2.0** adds native field refs, controlled tabs and popover/menu open 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.
161
165
 
162
166
  ```sh
163
- npm install @abuzareal/contour-ui@0.2.0 --save-exact
167
+ npm install @abuzareal/contour-ui@0.2.1 --save-exact
164
168
  ```
165
169
 
166
170
  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.
@@ -188,7 +192,7 @@ MIT licensed. Fontsource fonts and dependencies retain their own licenses.
188
192
 
189
193
  ## APIs added in 0.2.0
190
194
 
191
- 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.
195
+ 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 Popover/DropdownMenu (`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.
192
196
 
193
197
  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:
194
198
 
package/RELEASING.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  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.
4
4
 
5
- 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.
5
+ Use [the public contract and compatibility policy](CONTRACTS.md#change-deprecation-and-migration-policy) and [the maturity register](PUBLIC-API.md) when classifying changes. 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.
6
6
 
7
7
  ## Verify and publish one archive
8
8
 
package/dist/components/ui/Checkbox.js CHANGED
@@ -11,5 +11,11 @@ export default function Checkbox({ label, description, error, indeterminate = fa
11
11
  if (ref.current)
12
12
  ref.current.indeterminate = indeterminate;
13
13
  }, [indeterminate]);
14
- return (_jsxs("div", { className: cx("choice", error && "choice-invalid", className), children: [_jsxs("span", { className: "choice-control", children: [_jsx("input", { ...rest, ref: ref, id: id, type: "checkbox", className: "choice-input", "aria-invalid": error ? true : undefined, "aria-describedby": error ? `${id}-error` : undefined }), _jsx("span", { className: "choice-box", "aria-hidden": "true", children: indeterminate ? (_jsx(Minus, { size: 13, strokeWidth: 3 })) : (_jsx(Check, { size: 13, strokeWidth: 3 })) })] }), _jsxs("label", { htmlFor: id, className: "choice-text", children: [_jsx("span", { className: "choice-label", children: label }), description && (_jsx("span", { className: "choice-description", children: description })), error && (_jsx("span", { id: `${id}-error`, className: "choice-error mono", children: error }))] })] }));
14
+ return (_jsxs("div", { className: cx("choice", error && "choice-invalid", className), children: [_jsxs("span", { className: "choice-control", children: [_jsx("input", { ...rest, ref: ref, id: id, type: "checkbox", className: "choice-input", "aria-invalid": error ? true : rest["aria-invalid"], "aria-describedby": [
15
+ rest["aria-describedby"],
16
+ description && `${id}-description`,
17
+ error && `${id}-error`,
18
+ ]
19
+ .filter(Boolean)
20
+ .join(" ") || undefined }), _jsx("span", { className: "choice-box", "aria-hidden": "true", children: indeterminate ? (_jsx(Minus, { size: 13, strokeWidth: 3 })) : (_jsx(Check, { size: 13, strokeWidth: 3 })) })] }), _jsxs("label", { htmlFor: id, className: "choice-text", children: [_jsx("span", { className: "choice-label", children: label }), description && (_jsx("span", { id: `${id}-description`, className: "choice-description", children: description })), error && (_jsx("span", { id: `${id}-error`, className: "choice-error mono", children: error }))] })] }));
15
21
  }
package/dist/hooks/useClipboardCopy.js CHANGED
@@ -3,20 +3,43 @@
3
3
  import { useCallback, useEffect, useRef, useState } from "react";
4
4
  const resetDelay = 4000;
5
5
  export default function useClipboardCopy(text) {
6
- const [status, setStatus] = useState("idle");
6
+ const [feedback, setFeedback] = useState({
7
+ text,
8
+ status: "idle",
9
+ });
10
+ // Feedback belongs to the current value, even before effects synchronize.
11
+ if (feedback.text !== text)
12
+ setFeedback({ text, status: "idle" });
13
+ const status = feedback.text === text ? feedback.status : "idle";
7
14
  const resetTimer = useRef(undefined);
8
- useEffect(() => () => clearTimeout(resetTimer.current), []);
15
+ const active = useRef(false);
16
+ const request = useRef(0);
17
+ useEffect(() => {
18
+ active.current = true;
19
+ return () => {
20
+ active.current = false;
21
+ request.current += 1;
22
+ clearTimeout(resetTimer.current);
23
+ };
24
+ }, [text]);
9
25
  const copy = useCallback(async () => {
26
+ if (!active.current)
27
+ return;
28
+ const currentRequest = ++request.current;
10
29
  clearTimeout(resetTimer.current);
11
- setStatus("copying");
30
+ setFeedback({ text, status: "copying" });
31
+ let outcome = "copied";
12
32
  try {
13
33
  await navigator.clipboard.writeText(text);
14
- setStatus("copied");
15
34
  }
16
35
  catch {
17
- setStatus("error");
36
+ outcome = "error";
18
37
  }
19
- resetTimer.current = setTimeout(() => setStatus("idle"), resetDelay);
38
+ // Clipboard writes cannot be cancelled; discard obsolete completions.
39
+ if (!active.current || currentRequest !== request.current)
40
+ return;
41
+ setFeedback({ text, status: outcome });
42
+ resetTimer.current = setTimeout(() => setFeedback({ text, status: "idle" }), resetDelay);
20
43
  }, [text]);
21
44
  return { status, copy };
22
45
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@abuzareal/contour-ui",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "private": false,
5
5
  "description": "Editorial React components, themes, restrained motion, and optional Three.js objects.",
6
6
  "type": "module",
@@ -13,7 +13,9 @@
13
13
  "RELEASING.md",
14
14
  "CONTRIBUTING.md",
15
15
  "CODE_OF_CONDUCT.md",
16
- "NEXTJS.md"
16
+ "NEXTJS.md",
17
+ "CONTRACTS.md",
18
+ "PUBLIC-API.md"
17
19
  ],
18
20
  "sideEffects": [
19
21
  "**/*.css"