@deadragdoll/reactnu 0.1.9

package/docs/CONTRIBUTOR_GUIDE.md

@@ -0,0 +1,393 @@
+# Contributor Guide
+
+This guide is for developers and coding agents who need to extend ReactNU or integrate it into a host application without reverse-engineering the source tree first.
+
+It is intentionally practical.
+
+## What ReactNU Is
+
+ReactNU is a React + TypeScript component library with a Norton Utilities / DOS-era visual language.
+
+The target qualities are:
+
+- crisp geometry
+- dense information layout
+- keyboard-first interaction
+- strong visual hierarchy
+- predictable controlled/uncontrolled behavior
+- reusable host shell composition
+
+ReactNU is not a novelty retro skin. It is a reusable UI system that happens to use a DOS-style visual grammar.
+
+## Recommended Mental Model
+
+Think in layers:
+
+1. Theme and desktop tokens
+2. Low-level controls
+3. Composed surfaces
+4. Window and dialog orchestration
+5. Host application composition
+
+That means:
+
+- a control should not guess desktop ownership
+- a dialog should not guess app-shell structure
+- popup geometry should not guess multiple coordinate systems
+- the host should explicitly own workflow composition
+
+## First Files To Read
+
+If you are new to the repo, read in this order:
+
+1. [Getting Started](./GETTING_STARTED.md)
+2. [Architecture](./ARCHITECTURE.md)
+3. [API Reference](./API_REFERENCE.md)
+4. [Slot Customization](./SLOT_CUSTOMIZATION.md)
+5. [Storybook](./STORYBOOK.md)
+
+If you are working on windowing or popup behavior, also read:
+
+6. [NuWindowProvider](./NuWindowProvider.md)
+7. [Dialog Helpers](./DialogHelpers.md)
+8. [Desktop](./Desktop.md)
+
+## Host Composition Patterns
+
+### Full Desktop Shell
+
+Use this when you want:
+
+- main menu
+- workspace area
+- app bar
+- managed windows
+- desktop-level modal behavior
+
+Recommended ownership:
+
+`NuThemeProvider -> NuDesktop -> workspace content -> managed windows`
+
+Typical example:
+
+```tsx
+<NuThemeProvider>
+  <NuDesktop appBar={<ShellAppBar />}>
+    <Dashboard items={...} />
+  </NuDesktop>
+</NuThemeProvider>
+```
+
+### Bounded Window Host
+
+Use this when you need:
+
+- managed dialogs or windows
+- modal layering
+- `useNuWindowManager()`
+- but not the full desktop shell
+
+This is especially useful for:
+
+- Storybook stories
+- focused demo surfaces
+- embedded host panels
+
+Typical example:
+
+```tsx
+<div style={{ position: "relative", height: "40rem", overflow: "hidden" }}>
+  <NuWindowProvider renderAppBar={false}>
+    <DialogLauncherSurface />
+  </NuWindowProvider>
+</div>
+```
+
+### Do Not Mix These Accidentally
+
+Common mistake:
+
+- using `NuDesktop` when a bounded `NuWindowProvider` is enough
+
+Symptoms:
+
+- content appears to escape the preview region
+- dialogs reposition the whole preview unexpectedly
+- fullscreen/fixed desktop semantics leak into Storybook
+
+## Theme Ownership
+
+Theme state belongs to `NuThemeProvider`.
+
+Current provider-level host settings include:
+
+- theme
+- font family
+- font size
+- desktop pattern mode
+
+Prefer changing typography and desktop surface through the provider, not through ad-hoc DOM overrides.
+
+## Popup And Menu Contract
+
+Popup-like controls currently follow this contract:
+
+- popup renders into `document.body`
+- popup position is measured from `getBoundingClientRect()`
+- popup receives theme vars from the nearest `.nu-theme-root`
+
+Why:
+
+- viewport coordinates stay stable
+- Storybook and sandbox use the same geometry model
+- popup visuals still inherit theme and typography
+
+If a popup appears correct in sandbox but not in Storybook, first suspect host composition or portal assumptions, not the control API.
+
+## Shared Internal Primitive Rule
+
+When two controls share the same visual part, do not duplicate the implementation casually.
+
+Preferred order:
+
+1. shared LESS primitive if only chrome/geometry is shared
+2. shared internal JSX primitive if markup/behavior is mostly shared
+3. public component only if the thing has independent public meaning
+
+Current example:
+
+- `ControlOpener`
+  internal primitive shared by `Dropdown` and `ComboBox`
+
+This keeps:
+
+- glyph metrics
+- opener width
+- border
+- background
+- browser button reset behavior
+
+in one place.
+
+## Slot Customization Contract
+
+Preferred internal customization API:
+
+- `slotStyles`
+- `slotClassNames`
+
+Use:
+
+- `className` / `style` for root
+- `slot*` props for meaningful internal surfaces
+
+Examples of good slot names:
+
+- `root`
+- `label`
+- `title`
+- `body`
+- `popup`
+- `listbox`
+- `input`
+- `field`
+- `hint`
+
+Avoid inventing new one-off props for every surface if a control already supports slot customization.
+
+## Controlled / Uncontrolled Guidance
+
+Use normal React contracts unless there is a strong reason not to.
+
+Prefer:
+
+- `value`
+- `defaultValue`
+- `onValueChange`
+
+or for stateful booleans:
+
+- `open`
+- `defaultOpen`
+- `onOpenChange`
+
+For text-like controls:
+
+- do not blur or steal focus during normal typing paths
+- especially for editable popup controls like `ComboBox` and `SearchBox`
+
+## Keyboard And Focus Rules
+
+ReactNU is intentionally keyboard-forward.
+
+Baseline expectations for interactive controls:
+
+- visible focus
+- sane tab order
+- escape paths for overlays
+- predictable arrow-key semantics where relevant
+
+If a control opens a popup while still being text-editable:
+
+- typing must stay on the input
+- popup focus transfer should happen only on explicit navigation behavior
+
+## Window And Dialog Guidance
+
+Use `openWindow(...)` for document/tool windows.
+
+Use `openDialog(...)` for managed dialogs that still use the normal window manager.
+
+Use helper dialogs when you want standard system prompts:
+
+- `showMessageBox(...)`
+- `showInputBox(...)`
+
+Helper dialogs already own:
+
+- centered footer buttons
+- standard sizing
+- title defaults
+- error/info tone behavior
+
+If you build a custom dialog manually through `openDialog(...)`, you own its internal layout. That includes button centering.
+
+## Storybook Rules
+
+Storybook is not the sandbox.
+
+Use Storybook for:
+
+- isolated control review
+- prop and slot examples
+- theme/font variation
+- narrow interaction checks
+
+Use sandbox for:
+
+- free-form desktop workflows
+- multiple windows over time
+- broader integration exercises
+
+### Storybook Window Stories
+
+Use:
+
+- direct `Window` stories for static shell inspection
+- bounded `NuWindowProvider` stories for managed dialogs/windows
+- full `NuDesktop` only for shell-level stories
+
+### Storybook Layout Density
+
+Avoid giant empty canvases for small controls.
+
+Preferred:
+
+- wrap demos in titled panels
+- keep compact controls content-sized
+- use bounded desktop surfaces for desktop-like stories
+
+## Sandbox Rules
+
+Sandbox is allowed to be richer and more workflow-driven than Storybook.
+
+But avoid turning sandbox code into hidden library architecture.
+
+Good sandbox usage:
+
+- realistic host composition
+- test launchers
+- theme switching
+- live windowing flows
+
+Bad sandbox usage:
+
+- solving library bugs only in sandbox CSS
+- encoding internal library assumptions in demo-only hacks
+
+## Common Pitfalls
+
+### 1. Mixing Portal Roots And Viewport Coordinates
+
+If popup position is measured from `getBoundingClientRect()`, do not render the popup into an arbitrary local root unless the whole component is built around local coordinates.
+
+### 2. Browser Button Defaults
+
+If a shared primitive can render as a real `button`, neutralize browser defaults explicitly:
+
+- `font: inherit`
+- `line-height: 1`
+- `appearance: none`
+
+Otherwise glyphs and geometry drift even when the SVG is the same.
+
+### 3. Hidden Stretch From Flex/Grid Parents
+
+If shadows or chrome look detached, check whether the parent is stretching the child unexpectedly.
+
+### 4. Storybook Isolates Bugs Differently
+
+If behavior differs between sandbox and Storybook:
+
+- inspect the host first
+- inspect portal root and positioning rules second
+- only then change the component internals
+
+## Checklist For A New Control
+
+Before adding a new control:
+
+1. Decide whether it is a real public component or only an internal primitive.
+2. Check whether an existing control or shared layer already solves most of it.
+3. Define the public API in controlled/uncontrolled terms.
+4. Define keyboard behavior.
+5. Define focus behavior.
+6. Define slot surfaces.
+7. Add Storybook coverage.
+8. Add sandbox coverage if the control is workflow-heavy.
+9. Run the narrowest meaningful checks.
+
+## Checklist For Updating An Existing Control
+
+1. Read the current docs page.
+2. Read the component implementation.
+3. Check whether Storybook and sandbox both cover the control.
+4. Prefer a small change.
+5. If two controls share the same fix, look for a shared primitive/helper.
+6. Update docs if the rule becomes architectural.
+
+## Checklist For Popup Controls
+
+1. Confirm anchor measurement surface.
+2. Confirm portal root.
+3. Confirm theme inheritance in the popup.
+4. Confirm width contract:
+   - whole control
+   - field only
+   - custom width
+5. Confirm focus path:
+   - editable input stays editable
+   - menu/list can still be navigated intentionally
+
+## Checklist For Window/Dialog Stories
+
+1. Decide whether the story needs full `NuDesktop`.
+2. If not, prefer bounded `NuWindowProvider`.
+3. Keep the preview area explicitly sized.
+4. Avoid desktop-only CSS classes on standalone window hosts.
+5. Test helper dialogs and custom dialogs separately.
+
+## Current Internal Conventions Worth Preserving
+
+- body portals for popup-like controls
+- provider-owned typography and desktop pattern
+- slot-based internal customization
+- shared internal primitives for repeated chrome
+- bounded Storybook hosts for dialog/window examples
+- explicit scroll ownership
+
+## If You Are Unsure
+
+Choose the smallest rule-preserving change.
+
+If a fix only works in sandbox or only works in Storybook, it is probably not finished.

package/docs/CheckBox.md

@@ -0,0 +1,30 @@
+# CheckBox
+
+`CheckBox` renders a DOS-style checkbox with optional hint text.
+
+## Usage
+
+```tsx
+<CheckBox
+  checked={enabled}
+  hint="Verify structure before commit."
+  label="&Verify structure"
+  onCheckedChange={(nextChecked) => setEnabled(nextChecked)}
+/>
+```
+
+## Key Props
+
+- `label: string`
+- `checked?: boolean`
+- `defaultChecked?: boolean`
+- `hint?: string`
+- `disabled?: boolean`
+- `uncheckedShape?: "box" | "none"`
+- `onCheckedChange?: (checked, event) => void`
+
+## Notes
+
+- Supports controlled and uncontrolled usage.
+- Label mnemonic highlighting follows the `&` marker convention.
+- `uncheckedShape` controls whether the empty box is shown when unchecked.

package/docs/ComboBox.md

@@ -0,0 +1,41 @@
+# ComboBox
+
+`ComboBox` is the editable select control. It combines a text input with a filtered list popup.
+
+## Usage
+
+```tsx
+<ComboBox
+  data={[
+    {
+      category: null,
+      items: [
+        { id: "default", name: { text: "DEFAULT.NU" } },
+        { id: "repair", name: { text: "REPAIR.NU" } }
+      ]
+    }
+  ]}
+  label="Run profile"
+/>
+```
+
+## Key Props
+
+- `data: ListBoxGroup[]`
+- `label: string`
+- `hint?: string`
+- `value?: string`
+- `defaultValue?: string`
+- `inputValue?: string`
+- `defaultInputValue?: string`
+- `onValueChange?: (value, item, group) => void`
+- `onInputValueChange?: (value) => void`
+- `slotClassNames?` / `slotStyles?` for internal surface customization
+
+## Notes
+
+- Typing filters the popup list by item text.
+- `Enter` commits the first filtered match.
+- `ArrowDown` opens the popup.
+- `ComboBox` is intentionally separate from `Dropdown`, which stays non-editable.
+- For async or database-backed lookup, use [SearchBox](./SearchBox.md) instead of overloading `ComboBox`.

package/docs/CommandButton.md

@@ -0,0 +1,45 @@
+# CommandButton
+
+`CommandButton` is the standalone command-style button that shares the same interaction model and compact chrome as `ToolButton`, but does not require a `ToolBar` container.
+
+## Usage
+
+```tsx
+<CommandButton icon="gear">&Run</CommandButton>
+```
+
+With popup menu:
+
+```tsx
+<CommandButton
+  icon="folder"
+  menuItems={[
+    { id: "export-map", text: "Export &map" },
+    { id: "export-log", text: "Export &log" }
+  ]}
+>
+  &Export
+</CommandButton>
+```
+
+## Key Props
+
+- `icon?: NuGlyphName | ReactNode`
+- `toggled?: boolean`
+- `pressed?: boolean`
+- `dropdown?: boolean`
+- `menuItems?: MainMenuNode[]`
+- `onMenuItemSelect?: (item: MainMenuItem) => void`
+- `uncheckedShape?: "box" | "none"`
+- `slotStyles`
+- `slotClassNames`
+- normal button props such as `onClick`, `disabled`, `type`
+
+## Notes
+
+- if `menuItems` are provided, `CommandButton` opens `PopupMenu` automatically
+- `dropdown` only controls the caret visual
+- `menuItems` controls the actual popup behavior
+- `toggled` is the preferred toggle-state prop name
+- `pressed` remains supported as a legacy alias
+- `ToolButton` and `ToolDropButton` are thin wrappers over the same command-button behavior

package/docs/CrtGlitch.md

@@ -0,0 +1,49 @@
+# CrtGlitch
+
+`NuCrtGlitch` is an opt-in ambient effect. It periodically applies a brief RGB-split/warp distortion to a single, randomly chosen control on the page — meant to be caught in peripheral vision, not watched directly.
+
+## Usage
+
+Recommended — enable through the theme provider:
+
+```tsx
+<NuThemeProvider crtGlitch>
+  <NuDesktop appBar={<AppBar />}>
+    <App />
+  </NuDesktop>
+</NuThemeProvider>
+```
+
+With options:
+
+```tsx
+<NuThemeProvider crtGlitch={{ intervalMs: 5000, topLevelRatio: 0.5 }}>
+  <App />
+</NuThemeProvider>
+```
+
+Standalone, if not using `NuThemeProvider`'s `crtGlitch` prop:
+
+```tsx
+<NuCrtGlitch />
+```
+
+## Key Props
+
+- `enabled?: boolean`
+  default `true`. When `false`, the filter definitions stay mounted but inert — no pulses fire.
+- `intervalMs?: number`
+  default `3000`. Average gap between pulses. The actual gap is jittered (0.6x-1.6x of this value) so pulses never fall into a detectable fixed cadence.
+- `durationMs?: number`
+  default `2500`. Average length of a single pulse. Also jittered per pulse (0.7x-1.4x).
+- `targetSelector?: string`
+  CSS selector for the pool of small leaf-control candidates (buttons, checkboxes, glyphs, rows...). Defaults to controls scoped under an open, non-minimized `.nu-window`.
+- `topLevelRatio?: number`
+  default `1/3`. Fraction of pulses that target a whole open window instead of a small leaf control. Falls back to whichever pool actually has candidates if the rolled pool is empty (e.g. no windows open yet).
+
+## Notes
+
+- Opt-in and silent between pulses — the component only renders a hidden SVG `<filter>` definition, nothing visible on its own.
+- No two pulses share the same noise seed, offsets, duration, or gap, so nothing about the effect repeats often enough to read as decorative.
+- Designed to feel like a real, subtle fault rather than a demo effect: small controls glitch far more often than whole windows (see `topLevelRatio`), and offsets/intensity are re-rolled every pulse.
+- Mount once, anywhere under `NuThemeProvider` (or once via the `crtGlitch` prop). A second instance is wasteful, not harmful.

package/docs/Dashboard.md

@@ -0,0 +1,73 @@
+# Dashboard
+
+`Dashboard` is a full-workspace static layout surface for persistent desktop content that lives behind managed windows inside `NuDesktop`.
+
+It supports two static layout modes:
+
+- `grid`: explicit CSS grid placement
+- `lanes`: independent vertical columns
+
+## Usage
+
+```tsx
+<Dashboard
+  gap={12}
+  laneCount={2}
+  items={[
+    {
+      id: "system",
+      lane: 1,
+      minHeight: "18rem",
+      content: <Panel title="System Core">...</Panel>
+    },
+    {
+      id: "tools",
+      lane: 2,
+      minHeight: "18rem",
+      content: <Panel title="Workspace Tools">...</Panel>
+    }
+  ]}
+  layout="lanes"
+/>
+```
+
+## Key Props
+
+- `items: DashboardItem[]`
+- `columnCount?: number`
+- `layout?: "grid" | "lanes"`
+- `laneCount?: number`
+- `gap?: number`
+- `fill?: boolean`
+
+## DashboardItem
+
+Each item describes static CSS grid placement plus render content:
+
+```ts
+type DashboardItem = {
+  id: string | number;
+  lane?: number;
+  column?: string;
+  row?: string;
+  columnSpan?: number;
+  rowSpan?: number;
+  width?: string;
+  maxWidth?: string;
+  minWidth?: string;
+  minHeight?: string;
+  content: ReactNode;
+};
+```
+
+## Notes
+
+- `Dashboard` is a static layout surface, not a drag-and-resize layout engine.
+- Managed `Window` instances still render above it through `NuWindowProvider`.
+- Use it for always-present workspace panels, launch surfaces, inspectors, and dashboard-like control rooms.
+- The control defaults to `fill`, so it is suitable as the direct child of `NuDesktop`.
+- Grid rows use normal CSS content sizing, so panel height follows the child content unless you set explicit `minHeight`.
+- `lanes` mode is useful when each column should stack by its own height, without waiting for taller cells in neighboring columns.
+- In `lanes` mode you can also give an item an explicit `width` or `maxWidth` to avoid stretching it across the full lane.
+- Panel content should usually be another ReactNU surface such as `Panel`, `Frame`, or `NuView`.
+- If a product needs interactive rearrangement, `panelgrid` should be used directly by the host rather than hidden behind `Dashboard`.

package/docs/Desktop.md

@@ -0,0 +1,27 @@
+# Desktop
+
+`NuDesktop` is the top-level desktop shell. It renders a fixed full-screen workspace with three rows:
+
+1. top menu area
+2. central workspace
+3. bottom app bar area
+
+## Usage
+
+```tsx
+<NuDesktop appBar={<SandboxAppBar />}>
+  <App />
+</NuDesktop>
+```
+
+## Key Props
+
+- `children`
+- `appBar?: ReactNode`
+- `appBarContent?: ReactNode`
+- standard `div` props
+
+## Notes
+
+- The desktop owns the browser viewport and is intended to behave like a bounded screen.
+- `appBarContent` is kept as a compatibility alias, but `appBar` is the preferred entry point.