@abuzareal/contour-ui 0.2.0 → 0.3.0

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 (41) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/COMPOSITION.md +193 -0
  3. package/CONTRACTS.md +93 -0
  4. package/CONTRIBUTING.md +2 -0
  5. package/NEXTJS.md +3 -1
  6. package/PUBLIC-API.md +231 -0
  7. package/README.md +11 -7
  8. package/RELEASING.md +1 -1
  9. package/dist/components/ui/Button.d.ts +10 -2
  10. package/dist/components/ui/Button.js +7 -3
  11. package/dist/components/ui/Checkbox.d.ts +7 -1
  12. package/dist/components/ui/Checkbox.js +14 -6
  13. package/dist/components/ui/DepthButton.d.ts +5 -2
  14. package/dist/components/ui/DepthButton.js +8 -3
  15. package/dist/components/ui/Dialog.d.ts +21 -3
  16. package/dist/components/ui/Dialog.js +17 -11
  17. package/dist/components/ui/ExternalLink.d.ts +3 -2
  18. package/dist/components/ui/ExternalLink.js +7 -3
  19. package/dist/components/ui/IconButton.d.ts +10 -2
  20. package/dist/components/ui/IconButton.js +7 -3
  21. package/dist/components/ui/Popover.d.ts +19 -4
  22. package/dist/components/ui/Popover.js +16 -9
  23. package/dist/components/ui/Slider.d.ts +2 -1
  24. package/dist/components/ui/Slider.js +5 -4
  25. package/dist/components/ui/Switch.d.ts +2 -1
  26. package/dist/components/ui/Switch.js +5 -4
  27. package/dist/components/ui/Tabs.d.ts +16 -4
  28. package/dist/components/ui/Tabs.js +46 -24
  29. package/dist/components/ui/ThemeToggle.d.ts +2 -1
  30. package/dist/components/ui/ThemeToggle.js +5 -3
  31. package/dist/hooks/useClipboardCopy.js +29 -6
  32. package/dist/hooks/useControlRef.js +2 -2
  33. package/dist/hooks/useTabRefs.d.ts +4 -0
  34. package/dist/hooks/useTabRefs.js +12 -0
  35. package/dist/lib/componentProps.d.ts +5 -0
  36. package/dist/lib/componentProps.js +1 -0
  37. package/dist/lib/composeEventHandlers.d.ts +4 -0
  38. package/dist/lib/composeEventHandlers.js +8 -0
  39. package/dist/lib/composeRefs.d.ts +3 -0
  40. package/dist/lib/composeRefs.js +24 -0
  41. package/package.json +5 -2
package/PUBLIC-API.md ADDED
@@ -0,0 +1,231 @@
1
+ # Public API and maturity register
2
+
3
+ Contract version: **0.3.0**, reviewed 12 October 2026. Export names and stylesheet APIs remain unchanged. Native refs and typed root/part props are added; state callbacks and default appearance remain compatible. These additions are absent from 0.2.1. See [composition contracts](COMPOSITION.md). 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.3.0/tests/public-api.test.mjs), [component behavior](https://github.com/abuzareal/contour-ui/blob/v0.3.0/tests/components.test.mjs), [native dialog](https://github.com/abuzareal/contour-ui/blob/v0.3.0/tests/dialog.browser.mjs), [graphics lifecycle](https://github.com/abuzareal/contour-ui/blob/v0.3.0/tests/stage.browser.mjs), [React matrix](https://github.com/abuzareal/contour-ui/blob/v0.3.0/scripts/test-compat.mjs) and [Next](https://github.com/abuzareal/contour-ui/blob/v0.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/src/components/ui/Button.tsx#L21) | @abuzareal | stable (0.x) | Native action button | Forwarded native button ref on React 18/19; loading disables activation; native attributes preserved. | [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.3.0/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.3.0/src/components/ui/Checkbox.tsx#L19) | @abuzareal | stable (0.x) | Native checkbox with label/error | Forwarded native input ref coexists with indeterminate handling; generated ID remains; caller ARIA descriptions/validity preserved. | [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.3.0/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.3.0/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.3.0/src/components/ui/DepthButton.tsx#L11) | @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.3.0/src/components/ui/Dialog.tsx#L29) | @abuzareal | stable (0.x) | Native modal or edge drawer | Native dialog ref and root/panel/body/footer/close-button props; app owns open/onClose; no initial-focus override. | [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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/src/components/ui/ExternalLink.tsx#L12) | @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.3.0/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.3.0/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.3.0/src/components/ui/IconButton.tsx#L16) | @abuzareal | stable (0.x) | Native button with required accessible label | Forwarded native button ref on React 18/19; caller supplies a meaningful accessible 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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/src/components/ui/Popover.tsx#L25) | @abuzareal | experimental | Nonmodal panel with owned trigger | Root/owned trigger/panel props and refs supported; no portal/collision/custom-trigger/initial-focus API; nested Escape limitation remains. | [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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/src/components/ui/Slider.tsx#L18) | @abuzareal | stable (0.x) | Controlled native range input | Forwarded native range-input ref; no name/form/reset API; submit application state and keep 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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/src/components/ui/Switch.tsx#L14) | @abuzareal | stable (0.x) | Controlled on/off button | Forwarded native switch-button ref; boolean value callback; no name/form/uncontrolled reset API. | [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.3.0/src/components/ui/Tabs.tsx#L35) | @abuzareal | stable (0.x) | Controlled or default tab selection | Root/list/tab/panel props and refs; controlled/default selected ID; no disabled-tab/orientation/component-replacement 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.3.0/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.3.0/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.3.0/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.3.0/src/components/ui/ThemeToggle.tsx#L13) | @abuzareal | stable (0.x) | Document-theme control | Native button ref; root data-theme and aa-theme storage; no 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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/src/components/ui/Button.tsx#L12) | @abuzareal | stable (0.x) | Type contract for Button | Type-only; no runtime value. Forwarded native button ref on React 18/19; loading disables activation; native attributes preserved. | [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.3.0/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.3.0/src/components/ui/Checkbox.tsx#L9) | @abuzareal | stable (0.x) | Type contract for Checkbox | Type-only; no runtime value. Forwarded native input ref coexists with indeterminate handling; generated ID remains; caller ARIA descriptions/validity preserved. | [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.3.0/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.3.0/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.3.0/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.3.0/src/components/ui/DepthButton.tsx#L7) | @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.3.0/src/components/ui/Dialog.tsx#L12) | @abuzareal | stable (0.x) | Type contract for Dialog | Type-only; no runtime value. Native dialog ref and root/panel/body/footer/close-button props; app owns open/onClose; no initial-focus override. | [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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/src/components/ui/ExternalLink.tsx#L7) | @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.3.0/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.3.0/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.3.0/src/components/ui/IconButton.tsx#L7) | @abuzareal | stable (0.x) | Type contract for IconButton | Type-only; no runtime value. Forwarded native button ref on React 18/19; caller supplies a meaningful accessible 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.3.0/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.3.0/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.3.0/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.3.0/src/components/ui/Popover.tsx#L12) | @abuzareal | experimental | Type contract for Popover | Type-only; no runtime value. Root/owned trigger/panel props and refs supported; no portal/collision/custom-trigger/initial-focus API; nested Escape limitation remains. | [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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/src/components/ui/Slider.tsx#L6) | @abuzareal | stable (0.x) | Type contract for Slider | Type-only; no runtime value. Forwarded native range-input ref; no name/form/reset API; submit application state and keep 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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/src/components/ui/Switch.tsx#L6) | @abuzareal | stable (0.x) | Type contract for Switch | Type-only; no runtime value. Forwarded native switch-button ref; boolean value callback; no name/form/uncontrolled reset API. | [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.3.0/src/components/ui/Tabs.tsx#L18) | @abuzareal | stable (0.x) | Type contract for Tabs | Type-only; no runtime value. Root/list/tab/panel props and refs; controlled/default selected ID; no disabled-tab/orientation/component-replacement 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.3.0/src/components/ui/Tabs.tsx#L26) | @abuzareal | stable (0.x) | Type contract for Tabs | Type-only; no runtime value. Root/list/tab/panel props and refs; controlled/default selected ID; no disabled-tab/orientation/component-replacement 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.3.0/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.3.0/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.3.0/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.3.0/src/components/ui/ThemeToggle.tsx#L8) | @abuzareal | stable (0.x) | Type contract for ThemeToggle | Type-only; no runtime value. Native button ref; root data-theme and aa-theme storage; no 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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.0/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.3.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.
10
+
11
+ [Public API and maturity register](PUBLIC-API.md) · [Architecture, scope and compatibility](CONTRACTS.md)
12
+
13
+ Version 0.3.0 adds native refs for actions/choices and typed root/part props for Dialog, Tabs and Popover. It preserves existing state callbacks, styles, runtime dependencies and optional entry boundaries. See [refs, parts and link composition](COMPOSITION.md). Check npm availability before installing; this 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.3.0 --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.
@@ -114,7 +118,7 @@ The root entry also exports theme, motion, clipboard, dismissal, navigation, and
114
118
 
115
119
  Use visible field labels, accessible names for icon buttons, and text alongside status colors. `DataTable` sorts scalar string/number values; `Pagination` expects a positive integer page count and a page within that range. Flip cards use a button and make the hidden face inert.
116
120
 
117
- Props support varies between components. Don't assume every export forwards DOM refs, accepts arbitrary native attributes, supports router `asChild` composition, or integrates with form libraries through refs. Verify the relevant type before adopting it.
121
+ Props support varies between components. Button/IconButton/DepthButton/ThemeToggle, ExternalLink and the native fields/choices expose the targets listed in [the composition guide](COMPOSITION.md#native-ref-targets). Dialog/Tabs/Popover support their documented root and owned parts. Don't assume every wrapper or multi-control group forwards a single DOM ref, accepts arbitrary native attributes, supports router `asChild` composition, or integrates with form libraries through refs. Verify the relevant type before adopting it.
118
122
 
119
123
  ## Optional scenes and scrolling
120
124
 
@@ -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.3.0 --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,9 +192,9 @@ 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/open-state control between controlled and uncontrolled ownership during its lifetime is unsupported.
192
196
 
193
- 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:
197
+ Existing uncontrolled calls remain valid. Use a native ref to focus a field or integrate a form controller; controlled tabs and popover/menu open state require the caller to update the selected id or open state:
194
198
 
195
199
  ```tsx
196
200
  import { useRef, useState } from "react";
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/Button.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  /** Pill button in four emphasis levels and three sizes, with loading and icon slots. */
2
- import type { ButtonHTMLAttributes, ReactNode } from "react";
2
+ import { type ButtonHTMLAttributes, type ReactNode } from "react";
3
3
  import { type ButtonSize, type ButtonVariant } from "../../lib/classNames.js";
4
4
  export type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
5
5
  variant?: ButtonVariant;
@@ -9,4 +9,12 @@ export type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
9
9
  leadingIcon?: ReactNode;
10
10
  loading?: boolean;
11
11
  };
12
- export default function Button({ variant, size, icon, leadingIcon, loading, disabled, className, children, type, ...rest }: ButtonProps): import("react").JSX.Element;
12
+ declare const Button: import("react").ForwardRefExoticComponent<ButtonHTMLAttributes<HTMLButtonElement> & {
13
+ variant?: ButtonVariant;
14
+ size?: ButtonSize;
15
+ /** Icon placed after the label; it nudges forward on hover. */
16
+ icon?: ReactNode;
17
+ leadingIcon?: ReactNode;
18
+ loading?: boolean;
19
+ } & import("react").RefAttributes<HTMLButtonElement>>;
20
+ export default Button;
package/dist/components/ui/Button.js CHANGED
@@ -1,6 +1,10 @@
1
+ "use client";
1
2
  import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
3
+ /** Pill button in four emphasis levels and three sizes, with loading and icon slots. */
4
+ import { forwardRef } from "react";
2
5
  import { buttonClassName, } from "../../lib/classNames.js";
3
6
  import Spinner from "./Spinner.js";
4
- export default function Button({ variant, size, icon, leadingIcon, loading = false, disabled, className, children, type = "button", ...rest }) {
5
- return (_jsxs("button", { ...rest, type: type, className: buttonClassName(variant, size, className), disabled: disabled || loading, "aria-busy": loading || undefined, children: [loading ? _jsx(Spinner, { size: "sm", label: "Loading" }) : leadingIcon, _jsx("span", { children: children }), icon && _jsx("span", { className: "button-icon", children: icon })] }));
6
- }
7
+ const Button = forwardRef(function Button({ variant, size, icon, leadingIcon, loading = false, disabled, className, children, type = "button", ...rest }, ref) {
8
+ return (_jsxs("button", { ref: ref, ...rest, type: type, className: buttonClassName(variant, size, className), disabled: disabled || loading, "aria-busy": loading || undefined, children: [loading ? _jsx(Spinner, { size: "sm", label: "Loading" }) : leadingIcon, _jsx("span", { children: children }), icon && _jsx("span", { className: "button-icon", children: icon })] }));
9
+ });
10
+ export default Button;
package/dist/components/ui/Checkbox.d.ts CHANGED
@@ -6,4 +6,10 @@ export type CheckboxProps = Omit<InputHTMLAttributes<HTMLInputElement>, "type" |
6
6
  error?: string;
7
7
  indeterminate?: boolean;
8
8
  };
9
- export default function Checkbox({ label, description, error, indeterminate, className, ...rest }: CheckboxProps): import("react").JSX.Element;
9
+ declare const Checkbox: import("react").ForwardRefExoticComponent<Omit<InputHTMLAttributes<HTMLInputElement>, "id" | "type"> & {
10
+ label: string;
11
+ description?: string;
12
+ error?: string;
13
+ indeterminate?: boolean;
14
+ } & import("react").RefAttributes<HTMLInputElement>>;
15
+ export default Checkbox;
package/dist/components/ui/Checkbox.js CHANGED
@@ -1,15 +1,23 @@
1
1
  "use client";
2
2
  import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
3
3
  /** Square checkbox with an acid check, optional description, error, and indeterminate state. */
4
- import { useEffect, useId, useRef } from "react";
4
+ import { forwardRef, useEffect, useId } from "react";
5
5
  import { Check, Minus } from "lucide-react";
6
+ import useControlRef from "../../hooks/useControlRef.js";
6
7
  import { cx } from "../../lib/classNames.js";
7
- export default function Checkbox({ label, description, error, indeterminate = false, className, ...rest }) {
8
+ const Checkbox = forwardRef(function Checkbox({ label, description, error, indeterminate = false, className, ...rest }, forwardedRef) {
8
9
  const id = useId();
9
- const ref = useRef(null);
10
+ const { ref, attach } = useControlRef(forwardedRef);
10
11
  useEffect(() => {
11
12
  if (ref.current)
12
13
  ref.current.indeterminate = indeterminate;
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 }))] })] }));
15
- }
14
+ }, [indeterminate, ref]);
15
+ return (_jsxs("div", { className: cx("choice", error && "choice-invalid", className), children: [_jsxs("span", { className: "choice-control", children: [_jsx("input", { ...rest, ref: attach, id: id, type: "checkbox", className: "choice-input", "aria-invalid": error ? true : rest["aria-invalid"], "aria-describedby": [
16
+ rest["aria-describedby"],
17
+ description && `${id}-description`,
18
+ error && `${id}-error`,
19
+ ]
20
+ .filter(Boolean)
21
+ .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 }))] })] }));
22
+ });
23
+ export default Checkbox;
package/dist/components/ui/DepthButton.d.ts CHANGED
@@ -1,6 +1,9 @@
1
1
  /** Physical, layered button that presses down into its base (CSS 3D depth). */
2
- import type { ButtonHTMLAttributes, ReactNode } from "react";
2
+ import { type ButtonHTMLAttributes, type ReactNode } from "react";
3
3
  export type DepthButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
4
4
  children: ReactNode;
5
5
  };
6
- export default function DepthButton({ children, type, ...rest }: DepthButtonProps): import("react").JSX.Element;
6
+ declare const DepthButton: import("react").ForwardRefExoticComponent<ButtonHTMLAttributes<HTMLButtonElement> & {
7
+ children: ReactNode;
8
+ } & import("react").RefAttributes<HTMLButtonElement>>;
9
+ export default DepthButton;
package/dist/components/ui/DepthButton.js CHANGED
@@ -1,4 +1,9 @@
1
+ "use client";
1
2
  import { jsx as _jsx } from "react/jsx-runtime";
2
- export default function DepthButton({ children, type = "button", ...rest }) {
3
- return (_jsx("button", { ...rest, type: type, className: "depth-button", children: _jsx("span", { className: "depth-button-face", children: children }) }));
4
- }
3
+ /** Physical, layered button that presses down into its base (CSS 3D depth). */
4
+ import { forwardRef } from "react";
5
+ import { cx } from "../../lib/classNames.js";
6
+ const DepthButton = forwardRef(function DepthButton({ children, className, type = "button", ...rest }, ref) {
7
+ return (_jsx("button", { ref: ref, ...rest, type: type, className: cx("depth-button", className), children: _jsx("span", { className: "depth-button-face", children: children }) }));
8
+ });
9
+ export default DepthButton;