nuvox 0.1.0

package/CONTRACT.md

@@ -0,0 +1,255 @@
+# Nuvox Foundation — Contract
+
+This is the rulebook for building each future component on top of this
+base. It exists so decisions get made once, here, instead of once per
+component. Every rule below is backed by a specific bug found in the old
+codebase — see the parenthetical.
+
+## 1. Size scale
+Import `Size` from `src/core/types.ts`. Don't declare a component-local
+size union. If a component genuinely needs a wider scale (Modal + "full",
+Avatar + "2xl"), extend the shared type explicitly:
+```ts
+export type ModalSize = Size | "full"
+```
+(Old bug: 4 different, undocumented size scales across 41 components.)
+
+## 2. Base props
+Every component's prop interface extends `BaseComponentProps`
+(`className`, `style`, `theme`). Only add `color` / `radius` as
+component-specific overrides if the component genuinely needs one —
+but when you do, use the same shape every other component uses.
+(Old bug: `color` on 6/41 components, `radius` on 2/41, no rule for
+which.)
+
+## 3. Nullish coalescing only
+Use `??` for every prop default, never `||`. `||` silently discards a
+valid `false`/`0`/`""`.
+(Old bug: 36 files used `??`, 5 used `||`, inconsistently.)
+
+## 4. Ref forwarding is the default, not a judgment call
+Every component uses `forwardRef`. See `src/react/Button.tsx` as the
+template. The only exemption is a component with no focusable or
+interactive native element at all (`Divider`, `NuvoxProvider`,
+`ToastProvider` — it renders a variable-length list of toasts inside
+a portal, with no single focusable element to forward to — other
+pure layout/context wrappers) — that's a concrete, checkable exception,
+not a "forward it if it seems worth it" judgment call. Anything with a
+real DOM node a consumer might plausibly focus, measure, or scroll
+forwards its ref, full stop.
+(Old bug: 1 of 41 components forwarded a ref — and the failure mode
+was exactly "judgment calls made independently, 41 times." A vague
+exception clause reopens that same door.)
+
+## 5. Theme/accent override, not theme/accent logic
+A component with `theme?: string` and/or `color?: string` props
+(both from `BaseComponentProps`) wraps its output with
+`withThemeOverride(theme, ...)` and/or `withAccentOverride(color, ...)`
+from `theme-engine/NuvoxProvider`. A component never branches on
+theme or accent identity (`if (theme === "glass")`, `if (color ===
+"teal")`) — it only ever consumes semantic CSS variables. This should
+read naturally whether the theme catalog stays at 3 or grows to 15,
+and whether the accent palette stays at 9 or grows to 30.
+(Old bug: components didn't have this override at all; the doc's
+planned priority rule — component > provider > default — was never
+implemented in code. A second bug, found later: a component accepted
+`theme`/`color` via `BaseComponentProps` and silently ignored both —
+accepting a prop is not the same as applying it; test for the
+override actually taking effect, not just that the prop compiles.)
+
+## 5b. Theme is shape, accent is color — never conflate them
+`ThemeTokens` (see `contract.ts`) has no `color.brand` field, on
+purpose. A theme controls radius, shadow, motion, border treatment,
+and glass/gradient/glow effects — the properties in the doc's own
+original vision of what makes Cyberpunk feel different from Brutalism.
+It does not control the brand accent color at all. Brand color is a
+separate, orthogonal registry (`accents.ts`) that a consumer picks
+independently — "our brand is teal" has to work whether the shape is
+Light, Cyberpunk, or Brutalism, not just the one theme an author
+happened to design it against.
+
+This was a real bug, not a hypothetical: `gradient`, `minimalism`, and
+`skeuomorphism` were each authored with their own hardcoded
+`color.brand` scale, which meant every Button rendered pixel-identical
+to Light for anyone who hadn't noticed the hue never differed. It
+compiled fine and passed every completeness check, because
+completeness and distinctness are different properties (see Rule 7's
+note on this) — and it was orthogonality that was actually missing,
+not distinctness.
+
+**The one deliberate exception:** `success`/`danger`/`warning`/`info`
+stay theme-defined and are NOT part of the accent system. Their exact
+shade can differ per theme for contrast (dark themes need a lighter
+green than light themes to stay legible), but their meaning — green
+reads as success, red as danger — is not something a consumer should
+be able to accidentally reassign by picking an accent. If you ever
+find yourself wanting `color="success"` to be a valid accent value,
+that's the signal to stop — semantic color and brand color solve
+different problems and must stay separate registries.
+
+## 5c. Text on a solid accent surface uses `--color-brand-onAccent`, never `--color-textInverse`
+This was also a real bug, not a hypothetical: Button's `solid`
+variant, Badge's `solid` variant, and Checkbox's checkmark all paired
+`--color-brand-500` (the accent's fixed color — same value in every
+theme, per Rule 5b) with `--color-textInverse` (a THEME token,
+computed assuming the surface underneath is light or dark depending
+on *that theme*). Those two axes usually agree — until an accent like
+`graphite` (a gray scale, 500: `#525252`) meets `dark` theme
+(`textInverse: #111827`, chosen assuming a *light* surface). Dark
+gray text on a mid-gray background is close to unreadable, and
+nothing in the type system catches it, because both tokens
+individually resolve fine.
+
+The fix: `generate-css.ts` computes `--color-brand-onAccent` per
+accent, from that accent's own 500 shade via WCAG relative luminance
+(`tokens/contrast.ts`) — not borrowed from whichever theme happens to
+be active. Any component painting text directly on
+`--color-brand-500` (or another accent step used as a fill) uses
+`--color-brand-onAccent` for that text, full stop.
+`tests/accent-contrast.test.ts` enforces every registered accent's
+computed value clears WCAG AA (4.5:1) against its own 500 shade — a
+new accent that fails this fails CI, not a future bug report.
+
+The related, softer case — outline-variant text (`color-mix(in srgb,
+var(--color-brand-600) 65%, var(--color-text) 35%)`) sitting directly
+on a theme's own ambient background rather than a solid accent fill —
+is audited across all 99 theme × accent pairs in
+`tests/outline-text-contrast.test.ts`. That audit surfaced two real
+bugs *in the audit itself* before confirming the actual blend was
+fine: naive hex parsing silently turned `"transparent"` and CSS
+gradient strings into black (bitwise ops coerce `NaN` to `0`), and a
+translucent `rgba()` surface color had its alpha dropped, testing
+against the wrong effective color entirely. Both are fixed in
+`tokens/contrast.ts` (`parseColorWithAlpha`, `compositeOver`,
+`isSolidColor`) — worth knowing about if a future theme introduces
+another non-solid color value, since the same class of silent
+mis-parsing is exactly the kind of bug that doesn't announce itself.
+
+## 6. Portals go through ThemedPortal, never createPortal directly
+Any component that renders outside its own DOM subtree (Popover, Modal,
+Toast, Tooltip, Select, Combobox, DatePicker, Dropdown, ContextMenu,
+Drawer, ColorPicker, PhoneInput, Command, Tour, Kanban's drag layer...)
+imports `ThemedPortal` from `theme-engine/ThemedPortal.tsx` and passes
+it an `anchorRef`. Do not hand-roll the `closest('[data-theme]')` +
+`MutationObserver` fix again — that's exactly how it ended up
+duplicated 12 times and missing from 3 components last time.
+
+## 7. Every new theme is a `.ts` file satisfying `ThemeTokens`
+Author it with `defineTheme()` — an incomplete theme is a compile
+error, not a rendering bug. Register it via `registerTheme()`. Run
+`npm run build:tokens` to regenerate the CSS. Never hand-write a theme
+CSS file directly.
+(Old bug: themes were hand-authored CSS with no completeness check —
+a theme could silently ship missing a variable.)
+
+**Completeness is not the same as distinctness.** A theme derived from
+another via spread (the recommended pattern) can be 100% complete —
+every required key present and non-empty — while still being
+structurally indistinguishable from the theme it was derived from (same
+radius, same shadow, same motion). This is exactly what happened before
+`color.brand` was removed from `ThemeTokens` entirely (see Rule 5b):
+`gradient`, `minimalism`, and `skeuomorphism` each shipped with light's
+brand scale untouched, and it passed every check that existed at the
+time, because completeness and distinctness are different properties.
+Rule 5b's fix (moving brand out of themes entirely) closes that
+specific failure mode structurally — a theme literally cannot
+reintroduce a brand color to forget to change, because the field
+doesn't exist. `tests/theme-distinctness.test.ts` is the remaining
+safety net, now checking radius/shadow/motion/border fingerprints
+instead — run it (it's part of `npm test`) for every new theme, and
+don't treat "it compiles and the completeness test passes" as
+equivalent to "it's structurally different from the theme it was
+derived from."
+
+## 7b. Every new accent is a `.ts` file satisfying a full `ColorScale`
+Same pattern as themes, deliberately: create
+`src/tokens/accents/<name>.ts` exporting an `AccentDefinition`
+(`name`, `label`, `scale`), register it via `registerAccent()` in
+`accents.ts`. An incomplete scale throws immediately at registration
+(`assertCompleteScale`), not silently at render time. Accents don't
+need a distinctness test against every theme the way themes do against
+each other — `tests/accent-distinctness.test.ts` only checks accents
+against other accents (no two share a `500` step), since accents and
+themes are different registries serving different purposes.
+
+## 8. Every component ships with tests before it's considered done
+This is a **floor, not a checklist to stop at**. The four tests below
+are the minimum every component needs regardless of what it is; a
+complex component (DataGrid, RichTextEditor, Kanban) needs many more
+tests specific to its own behavior on top of these four, not instead
+of them:
+- One test proving the default (no-props) render is correct
+- One test proving `theme` override scopes correctly (skip if the
+  component has no visual output, e.g. a hook)
+- One test proving ref forwarding, if applicable
+- If the component portals: one test proving `ThemedPortal` picked up
+  the right theme
+(Old bug: zero tests existed anywhere in the 41-component, ~37k-line
+library.)
+
+## 9. Docs come last, and prefer an existing framework
+Don't build a documentation site until there are components worth
+documenting. Prefer an existing documentation framework (Storybook,
+Nextra, Starlight, or whatever's current when you get there) unless
+there's a specific, compelling reason to build your own — the rule is
+"don't default to building a platform," not "you may never build one."
+(Old bug: three separate documentation apps totaling ~83,500 lines —
+more than twice the size of the entire component library.)
+
+## 10. Public API stability
+Once a prop ships in a released version, it's a promise. Don't rename
+`variant` to `appearance`, don't change what a value means, don't
+change a callback's signature — pick one:
+- **alias** the old name to the new one and deprecate with a console
+  warning,
+- or **bump the major version** and document the breaking change.
+Internal architecture (core/, theme-engine/) can be refactored freely;
+anything a consumer imports and passes props to cannot change shape
+silently. This wasn't tested against the old codebase the way the
+other rules were — Nuvox v1 never shipped a public version — but it's
+the rule that protects everything else in this document from being
+undermined the moment real consumers exist.
+
+## 11. Every overlay component meets the same accessibility baseline
+Any component that opens/closes, floats, or portals (Modal, Drawer,
+Popover, Dropdown, Select, Combobox, ContextMenu, Tour, Toast,
+Tooltip...) implements, without exception:
+- `Escape` closes it (where closing is a valid action)
+- Focus is trapped inside while open, and returns to the trigger on
+  close
+- Correct ARIA role (`dialog`, `listbox`, `menu`, etc.) and state
+  attributes (`aria-expanded`, `aria-modal`, ...)
+- Full keyboard navigation appropriate to the component (arrow keys
+  for a listbox, tab cycling in a modal)
+This is the same failure shape as Rule 6 (ThemedPortal) waiting to
+happen — a fix that's easy to duplicate 12 times and forget 3 times if
+each component reimplements it locally. Build focus-trap/escape/ARIA
+handling as a shared hook (e.g. `useOverlayBehavior`) the same way
+`ThemedPortal` centralized the theme fix, rather than reimplementing it
+per component.
+
+## 12. Components compose primitives, they don't reimplement them
+A `Select` doesn't hand-roll its own text field, its own floating
+panel, and its own option-highlighting logic — it composes an `Input`,
+a `Popover`/`ThemedPortal`, and a shared list/option primitive. If two
+components need the same behavior (an editable text field, a floating
+panel, a keyboard-navigable list), that behavior gets built once and
+both components use it. This isn't backed by a specific bug the way
+the other rules are — Nuvox v1 didn't get far enough architecturally
+for this to bite yet — but it's the same principle as Rule 6 (portal
+theming) and Rule 11 (overlay behavior) applied generally: the more
+logic two components share by composition, the fewer places a fix has
+to be duplicated or forgotten later.
+
+---
+
+## Adding a new rule to this document
+Before adding a Rule 13, ask: **does this prevent a class of bugs, or
+just one bug?** "Shared size scale," "theme contract," "ref policy" —
+these prevent a class (N components each making the same kind of
+decision independently). "Buttons should use 14px font" is a design
+token, not an architectural invariant — it belongs in a theme file,
+not here. A contract that grows past what people actually remember and
+apply stops being a contract and becomes a document nobody rereads.
+Keep it to rules that would still make sense five years from now,
+regardless of what the component catalog looks like by then.

package/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 Nuvox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This project includes icons adapted from Lucide (ISC License) and, via
+Lucide, from Feather (MIT License). See THIRD-PARTY-NOTICES.md for the
+full, required notices.
+

package/README.md

@@ -0,0 +1,99 @@
+# Nuvox
+
+A framework-agnostic React component library with a themeable,
+token-driven design system. 41 components, 11 visual themes, 9 named
+accent colors (plus support for any raw CSS color), and 492 icons —
+fully typed, accessible, and built on zero runtime dependencies.
+
+## The core idea: theme is shape, color is color
+
+A **theme** (`light`, `dark`, `cyberpunk`, `glass`, ...) controls
+radius, shadow, motion, and border treatment. Your **accent color**
+is a completely separate choice — pick a named accent or any raw CSS
+color, and it works identically with every theme:
+
+```tsx
+<NuvoxProvider theme="cyberpunk" accent="teal">
+  <Button>Cyberpunk shape, teal brand — not tied to each other</Button>
+</NuvoxProvider>
+
+<Button color="#ff6600">A raw hex color works too, no setup</Button>
+```
+
+## Install
+
+```bash
+npm install nuvox
+```
+
+`react` and `react-dom` are peer dependencies (React 18+) — npm 7+
+installs them automatically if they're missing.
+
+## Quick start
+
+```tsx
+import { NuvoxProvider, Button } from "nuvox/react";
+import "nuvox/themes.css"; // theme + accent CSS variables
+import "nuvox/styles.css"; // component styles
+
+function App() {
+  return (
+    <NuvoxProvider theme="dark" accent="teal">
+      <Button>Hello Nuvox</Button>
+    </NuvoxProvider>
+  );
+}
+```
+
+Both stylesheets are required — `themes.css` defines the CSS
+variables, `styles.css` reads them into visible styles.
+
+## What's in the box
+
+- **41 components** across forms (Input, Select, Checkbox, Slider...),
+  overlays (Modal, Popover, Dropdown, Drawer...), composite widgets
+  (Combobox, DatePicker, CommandPalette...), and navigation
+  (Tabs, Accordion, Breadcrumb, Pagination...)
+- **11 themes** (light, dark, glass, dark-glass, minimalism,
+  brutalism, neobrutalism, cyberpunk, gradient, material,
+  skeuomorphism) — switchable at runtime with no re-render logic
+- **9 named accent colors**, or drop in any raw CSS color with zero
+  registration
+- **492 icons**, tree-shakeable, each accepting `size` and `color`
+- Full TypeScript support out of the box — no separate `@types`
+  package needed
+- Accessible by default: every overlay component handles focus
+  trapping, Escape-to-close, and correct ARIA roles/states
+
+## Switch themes and accents independently
+
+```tsx
+<NuvoxProvider theme="dark" accent="indigo">
+  <Button>Ambient dark + indigo</Button>
+  <Button theme="glass">Glass shape, still indigo accent</Button>
+  <Button color="teal">Dark shape, teal accent instead</Button>
+</NuvoxProvider>
+```
+
+You can also register your own theme or accent from your own code —
+see the [docs site](#docs--examples) for the full guide.
+
+## Docs & examples
+
+Every component has a live, interactive example alongside its API
+reference in the docs site:
+
+```bash
+npm run docs:install   # first time only
+npm run docs:dev       # → http://localhost:3000
+```
+
+- `/docs` — installation and setup
+- `/docs/components` — every component, with live previews
+- `/docs/themes` — the full theme/accent catalog, try them live
+- `/docs/icons` — browse and search all 492 icons
+
+
+## License
+
+MIT

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,52 @@
+# Third-Party Notices
+
+Nuvox's own code is MIT licensed — see [`LICENSE`](./LICENSE). Some icons in
+`src/icons/` are adapted from the [Lucide](https://lucide.dev) icon set,
+which requires its own license notice to travel with the code. That notice
+is reproduced below, unmodified, as required.
+
+---
+
+ISC License
+
+Copyright (c) 2026 Lucide Icons and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+---
+
+The following Lucide icons are derived from the Feather project:
+
+airplay, alert-circle, alert-octagon, alert-triangle, aperture, arrow-down-circle, arrow-down-left, arrow-down-right, arrow-down, arrow-left-circle, arrow-left, arrow-right-circle, arrow-right, arrow-up-circle, arrow-up-left, arrow-up-right, arrow-up, at-sign, calendar, cast, check, chevron-down, chevron-left, chevron-right, chevron-up, chevrons-down, chevrons-left, chevrons-right, chevrons-up, circle, clipboard, clock, code, columns, command, compass, corner-down-left, corner-down-right, corner-left-down, corner-left-up, corner-right-down, corner-right-up, corner-up-left, corner-up-right, crosshair, database, divide-circle, divide-square, dollar-sign, download, external-link, feather, frown, hash, headphones, help-circle, info, italic, key, layout, life-buoy, link-2, link, loader, lock, log-in, log-out, maximize, meh, minimize, minimize-2, minus-circle, minus-square, minus, monitor, moon, more-horizontal, more-vertical, move, music, navigation-2, navigation, octagon, pause-circle, percent, plus-circle, plus-square, plus, power, radio, rss, search, server, share, shopping-bag, sidebar, smartphone, smile, square, table-2, tablet, target, terminal, trash-2, trash, triangle, tv, type, upload, x-circle, x-octagon, x-square, x, zoom-in, zoom-out
+
+The MIT License (MIT) (for the icons listed above)
+
+Copyright (c) 2013-present Cole Bemis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.