@deadragdoll/reactnu 0.1.9

package/docs/NuThemeProvider.md

@@ -0,0 +1,64 @@
+# NuThemeProvider
+
+`NuThemeProvider` applies design tokens for the active visual theme.
+
+## Usage
+
+```tsx
+<NuThemeProvider>
+  <NuDesktop appBar={<AppBar />}>
+    <App />
+  </NuDesktop>
+</NuThemeProvider>
+```
+
+Typography can also be configured at the provider level:
+
+```tsx
+<NuThemeProvider
+  defaultFontFamily={'"Comic Sans MS", "Comic Sans", cursive'}
+  defaultFontSize={16}
+>
+  <App />
+</NuThemeProvider>
+```
+
+## Related API
+
+- `useNuTheme()`
+- `nuThemes`
+- `resolveNuTheme(...)`
+- `isNuThemeName(...)`
+
+## Provider Typography
+
+`NuThemeProvider` now owns both theme tokens and base typography for the full UI tree.
+
+Supported props:
+
+- `desktopPatternMode?: "dot-grid" | "dense-dots" | "coarse-dots" | "grid" | "solid"`
+- `defaultDesktopPatternMode?: ...`
+- `onDesktopPatternModeChange?: (mode) => void`
+- `fontFamily?: string`
+- `defaultFontFamily?: string`
+- `onFontFamilyChange?: (fontFamily) => void`
+- `fontSize?: number`
+- `defaultFontSize?: number`
+- `onFontSizeChange?: (fontSize) => void`
+- `crtGlitch?: boolean | NuCrtGlitchProps`
+  enables the ambient CRT-glitch effect (see [CrtGlitch](./CrtGlitch.md)). `true` uses its defaults; pass an options object to tune them. Defaults to `false` — opt-in.
+
+`useNuTheme()` exposes:
+
+- `desktopPatternMode`
+- `fontFamily`
+- `fontSize`
+- `setDesktopPatternMode(...)`
+- `setFontFamily(...)`
+- `setFontSize(...)`
+
+## Notes
+
+- The default theme is the classic DOS/Norton-inspired palette.
+- Theme tokens drive desktop, windowing, controls, selection, and inactive overlays.
+- Provider typography affects preview content, managed windows, dialogs, menus, and popup portals rendered inside the theme scope.

package/docs/NuView.md

@@ -0,0 +1,58 @@
+# NuView
+
+`NuView` is a generic fill-and-scroll container for hosting content inside frames, panes, dialogs, and splitter cells.
+
+## Usage
+
+```tsx
+<NuView padding="sm">
+  <Frame title="Inspector">
+    <Stack gap="md">{/* content */}</Stack>
+  </Frame>
+</NuView>
+```
+
+## Key Props
+
+- `fill?: boolean`
+- `scroll?: "auto" | "x" | "y" | "both" | "hidden"`
+- `padding?: "none" | "sm" | "md" | "lg"`
+
+## Notes
+
+- `fill` defaults to `true`, so `NuView` expands to the available area in common pane/frame layouts.
+- `NuView` is the place where host code should declare scroll behavior, instead of relying on incidental overflow from parent containers.
+- It is intended to simplify content composition inside `Splitter`, `Frame`, `Window`, and similar layout shells.
+
+## Recommended Ownership
+
+`NuView` should usually own the viewport area.
+
+Good fit:
+
+- splitter cells
+- resizable panes
+- frame-like shells inside windows
+- any place where the host wants one explicit scroll/fill container
+
+Typical pattern:
+
+```tsx
+<NuView scroll="auto" padding="sm">
+  <Frame title="Status">{/* content */}</Frame>
+</NuView>
+```
+
+This is especially important in `Splitter` layouts, where `NuView` should sit directly inside the pane and define how that pane scrolls.
+
+## Protocol Note
+
+During splitter integration we hit a concrete bug:
+
+- `NuView` was implemented too deep in the tree.
+- It did not own the pane viewport.
+- Scroll behavior looked wrong because the pane owner and the viewport owner were different components.
+
+The current rule is:
+
+`pane -> NuView -> content`

package/docs/NuWindowProvider.md

@@ -0,0 +1,81 @@
+# NuWindowProvider
+
+`NuWindowProvider` is the window manager for the desktop shell.
+
+## Usage
+
+```tsx
+<NuWindowProvider>
+  <Workspace />
+</NuWindowProvider>
+```
+
+## Main API
+
+Use `useNuWindowManager()` to access:
+
+- `openWindow(definition)`
+- `openDialog(definition)`
+- `showMessageBox(options)`
+- `showInputBox(options)`
+- `closeWindow(id)`
+- `updateWindow(id, patch)`
+- `activateWindow(id)`
+- `bringToFront(id)`
+- `toggleWindowMinimized(id)`
+- `toggleWindowMaximized(id)`
+- `closeAll()`
+- `windows`
+
+## Managed Window Persistence
+
+`NuManagedWindowDefinition` also supports:
+
+- `onOpen?: () => NuManagedWindowSnapshot | void`
+- `onClose?: (snapshot: NuManagedWindowSnapshot) => boolean | void`
+
+This lets the host save and restore window geometry:
+
+```tsx
+let savedWindowState: NuManagedWindowSnapshot | undefined;
+
+windowManager.openWindow({
+  title: "Inspector",
+  content: <Inspector />,
+  onOpen: () => savedWindowState,
+  onClose: (snapshot) => {
+    savedWindowState = snapshot;
+    return true;
+  }
+});
+```
+
+## Helper Dialogs
+
+The same manager also provides async helper dialogs:
+
+```tsx
+const result = await windowManager.showMessageBox({
+  title: "Diagnostics",
+  message: "Continue with the maintenance pass?",
+  kind: "info",
+  yes: true,
+  no: true
+});
+
+const value = await windowManager.showInputBox({
+  title: "Archive Report",
+  label: "Target path",
+  defaultValue: "C:\\LOGS\\SURFACE.MAP"
+});
+```
+
+See [Dialog Helpers](./DialogHelpers.md) for the full option list.
+
+## Notes
+
+- Supports app-modal and owner-modal dialogs.
+- Keeps window list order stable for app-bar display while still maintaining a separate visual z-stack.
+- `onOpen` is applied when the managed window record is created.
+- `onClose` receives the latest saved geometry and `maximized/minimized` state.
+- Returning `false` from `onClose` vetoes the close request.

package/docs/PageControl.md

@@ -0,0 +1,28 @@
+# PageControl
+
+`PageControl` is the tabbed page surface for switching between compact tool panels inside the same window.
+
+## Usage
+
+```tsx
+<PageControl
+  pages={[
+    { id: "summary", label: "&Summary", content: <SummaryPanel /> },
+    { id: "detail", label: "&Detail", content: <DetailPanel /> }
+  ]}
+/>
+```
+
+## Key Props
+
+- `pages: PageControlPage[]`
+- `activePageId?: string`
+- `defaultActivePageId?: string`
+- `onActivePageChange?: (page) => void`
+- `fill?: boolean`
+
+## Notes
+
+- The component supports controlled and uncontrolled page selection.
+- Keyboard navigation includes `Left/Right`, `Up/Down`, `Home`, and `End`.
+- `Tabs` is exported as an alias of `PageControl`.

package/docs/Panel.md

@@ -0,0 +1,23 @@
+# Panel
+
+`Panel` is a heavier container surface for primary application regions.
+
+## Usage
+
+```tsx
+<Panel title="System Core" footer="F1 Help" inset>
+  <Content />
+</Panel>
+```
+
+## Key Props
+
+- `title?: string`
+- `footer?: string`
+- `inset?: boolean`
+- `children`
+
+## Notes
+
+- `Panel` is the main raised surface.
+- `inset` is useful for denser workspace-like regions inside a larger shell.

package/docs/PopupMenu.md

@@ -0,0 +1,42 @@
+# PopupMenu
+
+`PopupMenu` is a context-style menu surface built on the same menu item model as `MainMenu`.
+
+## Usage
+
+```tsx
+const popupMenu = usePopupMenu();
+
+<Button onClick={popupMenu.openFromClick}>Open popup</Button>
+<PopupMenu
+  anchor={popupMenu.anchor}
+  open={popupMenu.open}
+  onOpenChange={popupMenu.setOpen}
+  items={items}
+/>
+```
+
+## Key Props
+
+- `items: MainMenuNode[]`
+- `anchor: PopupMenuAnchor | null`
+- `open?: boolean`
+- `defaultOpen?: boolean`
+- `onOpenChange?: (open) => void`
+- `onItemSelect?: (item) => void`
+
+## Related Hook
+
+- `usePopupMenu()`
+  - `anchor`
+  - `open`
+  - `setOpen`
+  - `close()`
+  - `openAtPoint(x, y)`
+  - `openAtElement(element)`
+  - `openFromClick(event)`
+  - `openFromContextMenu(event)`
+
+## Notes
+
+- Popup menus render through a portal and are not clipped by local overflow containers.

package/docs/ProgressBar.md

@@ -0,0 +1,33 @@
+# ProgressBar
+
+`ProgressBar` renders a DOS-style determinate or indeterminate progress indicator.
+
+## Usage
+
+```tsx
+<ProgressBar
+  label="Surface scan"
+  value={42}
+  max={100}
+  hint="Scanning allocation map"
+/>
+```
+
+## Key Props
+
+- `value?: number`
+- `min?: number`
+- `max?: number`
+- `indeterminate?: boolean`
+- `showValue?: boolean`
+- `label?: string`
+- `hint?: string`
+- `trackBackground?: CSSProperties["background"]`
+- `valueRenderer?: (percent, value, min, max) => ReactNode`
+
+## Notes
+
+- `value` is clamped to the `min..max` range.
+- `showValue` controls the right-side textual progress output.
+- `indeterminate` ignores `aria-valuenow` and animates the fill instead.
+- `trackBackground` lets the host override the progress track background while keeping the fill white.

package/docs/PropertyGrid.md

@@ -0,0 +1,63 @@
+# PropertyGrid
+
+`PropertyGrid` is the hierarchical inspector surface for labeled settings, expandable groups, and embedded editors.
+
+## Usage
+
+```tsx
+<PropertyGrid
+  entries={[
+    { id: "general", type: "section", title: "&General" },
+    {
+      id: "target",
+      label: "&Target",
+      content: <TextField label="Target" defaultValue="C:\\SYSTEM" />
+    },
+    {
+      id: "rect",
+      type: "group",
+      label: "&Box",
+      summary: <>Rect(0,0,10,20)</>,
+      children: [
+        {
+          id: "top",
+          label: "&Top",
+          content: <SpinBox label="Top" value={0} />
+        }
+      ]
+    }
+  ]}
+/>
+```
+
+## Key Props
+
+- `entries: PropertyGridEntry[]`
+- `labelWidth?: string`
+- `fill?: boolean`
+- `bordered?: boolean`
+- `activeId?: string`
+- `defaultActiveId?: string`
+- `onActiveIdChange?: (activeId) => void`
+- `expandedIds?: string[]`
+- `defaultExpandedIds?: string[]`
+- `onExpandedIdsChange?: (expandedIds) => void`
+
+## Notes
+
+- Use section rows to break long inspectors into logical blocks.
+- Group rows provide expandable hierarchy with a summary cell on the right.
+- Nested groups can be arbitrarily deep. A common pattern is a collapsed summary row like `Rect(0,0,10,20)` that expands into leaf editors such as `Top`, `Left`, `Width`, and `Height`.
+- Item rows accept arbitrary React content in the value column.
+- Clicking an item key activates the editor in the value column. For checkbox-like editors, the key click also toggles the value.
+- Keyboard navigation now follows inspector-style semantics:
+  - `Up` / `Down` move between rows
+  - `Home` / `End` jump to the first or last interactive row
+  - `Right` expands a group or activates the current item editor
+  - `Left` collapses the current group or moves focus to the parent group
+  - `Enter` / `Space` toggle a group or activate the current item editor
+- Item keys use the same white-surface / inverse-text treatment as the rest of the library's menu-like key slots.
+- Group keys use the inactive-button surface, so expandable branches are visually distinct from leaf properties.
+- Borders are optional through `bordered`; the default presentation is borderless.
+- Embedded ReactNU field controls have their internal top labels visually suppressed inside the property cell, because the grid already owns the left label column.
+- `PropertyGrid` is already suitable as a practical inspector surface, but it is still not a full schema engine. The next logical expansion would be deeper in-place editing semantics and richer nested property schemas.

package/docs/RadioGroup.md

@@ -0,0 +1,36 @@
+# RadioGroup
+
+`RadioGroup` renders a set of DOS-style radio options with one active value.
+
+## Usage
+
+```tsx
+<RadioGroup
+  label="&Boot mode"
+  hint="Choose the recovery startup profile."
+  options={[
+    { label: "&Safe mode", value: "safe" },
+    { label: "&Network mode", value: "network" },
+    { label: "&Full diagnostics", value: "full" }
+  ]}
+  value={bootMode}
+  onValueChange={setBootMode}
+/>
+```
+
+## Key Props
+
+- `label?: string`
+- `hint?: string`
+- `name?: string`
+- `options: Array<{ label, value, disabled?, hint? }>`
+- `value?: string`
+- `defaultValue?: string`
+- `onValueChange?: (value) => void`
+- `slotClassNames?` / `slotStyles?` for group-level customization
+
+## Notes
+
+- Supports controlled and uncontrolled usage.
+- `RadioButton` is also available as a lower-level building block.
+- Mnemonic highlighting follows the `&` marker convention.

package/docs/ReportCell.md

@@ -0,0 +1,27 @@
+# ReportCell
+
+`ReportCell` is a lightweight helper for report-style table cells.
+
+It is intentionally optional. Host code can return plain text or any custom
+`ReactNode`, but `ReportCell` keeps alignment and tone consistent for
+`ListView` and `TreeListView`-style columns.
+
+## Usage
+
+```tsx
+<ReportCell align="end" tone="muted">
+  44 KB
+</ReportCell>
+```
+
+## Props
+
+- `align?: "start" | "center" | "end"`
+- `tone?: "default" | "muted" | "accent" | "danger" | "success"`
+
+## Notes
+
+- `ReportCell` does not own column sizing.
+- It is a content helper, not a container control.
+- Use it when host-provided cells should still follow the library's report
+  alignment and color language.

package/docs/SLOT_CUSTOMIZATION.md

@@ -0,0 +1,85 @@
+# Slot Customization
+
+ReactNU components are moving to a shared internal customization contract:
+
+- `slotStyles`
+- `slotClassNames`
+
+This is the preferred way to override internal surfaces without rewriting a component.
+
+## Shape
+
+Typical usage:
+
+```tsx
+<Frame
+  slotStyles={{
+    title: { background: "black", color: "yellow" },
+    body: { background: "#6262e3" }
+  }}
+  slotClassNames={{
+    root: "my-frame",
+    title: "my-frame-title"
+  }}
+  title="Target Controls"
+/>
+```
+
+## Rules
+
+- `className` and `style` still target the component root.
+- `slotClassNames` and `slotStyles` target internal named slots.
+- Slot names should be literal and structural:
+  - `root`
+  - `label`
+  - `body`
+  - `title`
+  - `input`
+  - `hint`
+  - `popup`
+  - `listbox`
+- Component-specific legacy props such as `titleStyle` or `contentStyle` may still exist for compatibility, but new work should prefer slot-based customization.
+
+## Internal Primitive Rule
+
+Slot customization does not replace shared internal primitives.
+
+If two controls share the same internal visual part, prefer:
+
+- one shared internal primitive
+- plus slot customization on top of that primitive
+
+instead of:
+
+- separate duplicated markup
+- separate duplicated LESS
+- followed by two independent slot APIs
+
+Example:
+
+- `Dropdown` and `ComboBox` share the internal `ControlOpener` primitive
+- each control still exposes its own slot names around that primitive
+
+## Current Direction
+
+This contract is now the standard for new and updated controls.
+
+The first wave already covers the main surface and control layer:
+
+- `Frame`
+- `Panel`
+- `Button`
+- `PageControl`
+- `ToolBar`
+- `ProgressBar`
+- `TickBar`
+- `TextField`
+- `SpinBox`
+- `CheckBox`
+
+Additional controls should follow the same pattern as they are touched, instead of inventing one-off prop names.
+
+When extending a component:
+
+- add slots only for meaningful structural surfaces
+- do not expose every nested implementation detail as a slot unless it is a real customization surface

package/docs/STORYBOOK.md

@@ -0,0 +1,96 @@
+# Storybook
+
+ReactNU now ships with a dedicated Storybook layer for component coverage, visual regression review, and API exploration.
+
+## Scripts
+
+- `npm run storybook`
+  starts Storybook in dev mode
+- `npm run build-storybook`
+  produces a static build in `storybook-static/`
+
+## Global Toolbars
+
+The Storybook preview exposes provider-level globals for:
+
+- theme
+- font family
+- font size
+- desktop pattern mode
+
+These are wired through `NuThemeProvider`, so stories can be checked under the same typography and desktop-surface conditions as the sandbox.
+
+## Host Composition Rules
+
+Storybook uses more than one kind of host on purpose.
+
+Use a bounded surface with direct components when you only need:
+
+- isolated control review
+- static window chrome
+- local layout examples
+
+Use `NuWindowProvider` in a bounded container when you need:
+
+- managed windows
+- helper dialogs
+- modal layering
+- `useNuWindowManager()` flows
+
+Use full `NuDesktop` only when the story is explicitly about:
+
+- desktop shell composition
+- menu/app-bar integration
+- fixed desktop semantics
+
+This distinction matters because `NuDesktop` is intentionally fullscreen/fixed by nature, while many Storybook stories need a bounded preview host.
+
+## Coverage Goals
+
+The current Storybook covers the main package surfaces:
+
+- theming and slot customization
+- buttons and event feedback
+- input controls
+- selectors and async lookup
+- toolbar and page control navigation
+- list and tree controls
+- property inspector layout
+- surface/layout primitives
+- direct desktop and window chrome
+
+## Why Storybook Exists Alongside Sandbox
+
+The sandbox remains the free-form integration lab.
+
+Storybook serves a different role:
+
+- isolated component review
+- prop and event exploration
+- theme/font regression checks
+- docs-friendly usage examples
+- easier review of slot-level customization
+
+## Current Scope
+
+Storybook is intended to show:
+
+- how a control behaves on its own
+- how it behaves under different theme and typography settings
+- how slot overrides affect internal surfaces
+
+The sandbox still remains the better place for:
+
+- long-lived desktop workflows
+- managed window orchestration
+- complex multi-control interaction sequences
+
+## Popup Story Guidance
+
+Popup-like controls in Storybook should follow the same contract as the library runtime:
+
+- popup rendered into `document.body`
+- popup themed from the nearest `.nu-theme-root`
+- geometry measured from the visible anchor
+
+If a popup appears correct in sandbox but drifts in Storybook, treat that first as a host-composition issue rather than immediately changing the control API.

package/docs/SearchBox.md

@@ -0,0 +1,41 @@
+# SearchBox
+
+`SearchBox` is the async lookup control for remote or database-backed search.
+
+## Usage
+
+```tsx
+<SearchBox
+  dataProvider={(query) => fetchStations(query)}
+  getItemId={(item) => item.id}
+  getItemText={(item) => item.name}
+  label="Station search"
+  onItemSelect={(item) => setSelectedStation(item)}
+/>
+```
+
+## Key Props
+
+- `dataProvider: (query) => Promise<T[]>`
+- `getItemId: (item, index) => string`
+- `getItemText: (item) => string`
+- `getItemDetails?: (item) => ReactNode`
+- `getItemDisabled?: (item) => boolean`
+- `label: string`
+- `hint?: string`
+- `query?: string`
+- `defaultQuery?: string`
+- `onQueryChange?: (query) => void`
+- `onItemSelect?: (item) => void`
+- `debounceMs?: number`
+- `minQueryLength?: number`
+- `loadingText?: string`
+- `emptyText?: string`
+- `errorText?: string`
+
+## Notes
+
+- `SearchBox` is intentionally separate from `ComboBox`.
+- Use `ComboBox` for local editable lists.
+- Use `SearchBox` when results come from an async provider such as a database or remote service.
+- The input remains the focus owner; `Enter` commits the first result when available.