@deadragdoll/reactnu 0.1.9

package/docs/SpinBox.md

@@ -0,0 +1,25 @@
+# SpinBox
+
+`SpinBox` is the numeric field with inline decrement and increment controls.
+
+## Usage
+
+```tsx
+<SpinBox defaultValue={32} label="Cluster size" min={1} max={128} step={1} />
+```
+
+## Key Props
+
+- `label: string`
+- `hint?: string`
+- `value?: number`
+- `defaultValue?: number`
+- `min?: number`
+- `max?: number`
+- `step?: number`
+- `onValueChange?: (value) => void`
+
+## Notes
+
+- `ArrowUp` and `ArrowDown` adjust the value.
+- Manual text edits are allowed; invalid draft text is normalized back to the last valid numeric value on blur.

package/docs/Splitter.md

@@ -0,0 +1,91 @@
+# Splitter
+
+`Splitter` divides available space into two resizable panes with a draggable separator.
+
+## Usage
+
+```tsx
+<Splitter
+  defaultValue={0.4}
+  first={
+    <NuView padding="sm">
+      <Frame title="Navigator">{/* content */}</Frame>
+    </NuView>
+  }
+  second={
+    <NuView padding="sm">
+      <Frame title="Inspector">{/* content */}</Frame>
+    </NuView>
+  }
+/>
+```
+
+## Key Props
+
+- `orientation?: "vertical" | "horizontal"`
+- `value?: number`
+- `defaultValue?: number`
+- `onValueChange?: (value: number) => void`
+- `saveId?: string`
+- `min?: number`
+- `max?: number`
+- `first`
+- `second`
+
+## Notes
+
+- `vertical` means side-by-side panes with a vertical drag handle.
+- `horizontal` means stacked panes with a horizontal drag handle.
+- `value`, `min`, `max`, and `defaultValue` are ratio-based in the `0..1` range.
+- `saveId` stores the latest ratio in `localStorage` and restores it for uncontrolled usage.
+- Nested splitters work through normal composition; each pane can render another `Splitter`.
+- The separator supports pointer dragging and keyboard resizing with arrow keys, `Home`, and `End`.
+
+## Layout Protocol
+
+For splitter cells, the recommended ownership is:
+
+`Splitter cell -> NuView -> content`
+
+That means:
+
+- `Splitter` only divides space.
+- `NuView` owns fill, scroll, and optional padding.
+- The actual content component (`Frame`, `ListView`, custom layout, etc.) lives inside `NuView`.
+
+Recommended:
+
+```tsx
+<Splitter
+  first={
+    <NuView padding="sm">
+      <Frame title="Navigator">{/* content */}</Frame>
+    </NuView>
+  }
+  second={
+    <NuView scroll="auto">
+      <MyPane />
+    </NuView>
+  }
+/>
+```
+
+Avoid using the inverse ownership when the viewport should belong to the cell:
+
+```tsx
+<Frame title="Navigator">
+  <NuView>{/* content */}</NuView>
+</Frame>
+```
+
+That pattern makes the frame own the area and the viewport live too deep in the tree, which is usually not what you want in splitter layouts.
+
+## Protocol Note
+
+This was introduced after a layout bug in the splitter preview:
+
+- `NuView` was living inside `Frame`, instead of owning the splitter cell.
+- `Frame` was being treated like the viewport owner.
+- As a result, scroll behavior and clipping looked wrong for pane-sized content.
+
+The fix was to treat `NuView` as the viewport contract and keep `Splitter` itself layout-only.

package/docs/Stack.md

@@ -0,0 +1,26 @@
+# Stack
+
+`Stack` is a small flex layout helper.
+
+## Usage
+
+```tsx
+<Stack gap="md">
+  <TextField label="Target" />
+  <Button>Run</Button>
+</Stack>
+```
+
+## Key Props
+
+- `direction?: "row" | "column"`
+- `gap?: "sm" | "md" | "lg"`
+- `align?: "start" | "center" | "end" | "stretch"`
+- `justify?: "start" | "center" | "end" | "space-between" | "space-around"`
+- standard `div` props
+
+## Notes
+
+- `align` maps to `align-items`.
+- `justify` maps to `justify-content`.
+- `Stack` is intentionally small, but these two props cover the common row/column alignment cases without dropping to inline styles.

package/docs/StatusBarItem.md

@@ -0,0 +1,31 @@
+# StatusBarItem
+
+`StatusBarItem` is a placement helper for window status bars.
+
+## Usage
+
+```tsx
+<Window
+  title="Activity Log"
+  statusBar={
+    <>
+      <StatusBarItem grow>F2 Save F3 Search</StatusBarItem>
+      <StatusBarItem align="end">3 warnings</StatusBarItem>
+    </>
+  }
+>
+  <Content />
+</Window>
+```
+
+## Key Props
+
+- `grow?: boolean`
+- `align?: "start" | "center" | "end"`
+- `children`
+
+## Notes
+
+- `StatusBarItem` is layout-only.
+- It does not render its own border or segmented chrome.
+- The host controls the visual content inside the item.

package/docs/TOKEN_CHECKLIST.md

@@ -0,0 +1,122 @@
+# Token Checklist
+
+Practical checklist for keeping new components visually consistent with the rest of the library.
+
+## Source Of Truth
+
+- Runtime theme tokens: [`packages/ui/src/theme/themes.ts`](../packages/ui/src/theme/themes.ts)
+- CSS variable defaults: [`packages/ui/src/variables.less`](../packages/ui/src/variables.less)
+
+If a component needs a new reusable visual value, add it there first instead of hardcoding it locally.
+
+## Core Color Tokens
+
+- Desktop and shell:
+  - `--nu-desktop-bg`
+  - `--nu-desktop-pattern`
+  - `--nu-color-shell`
+  - `--nu-color-app-bg`
+  - `--nu-color-app-bg-alt`
+- Chrome and panels:
+  - `--nu-color-chrome`
+  - `--nu-color-panel`
+  - `--nu-color-panel-inset`
+  - `--nu-color-title-bg`
+  - `--nu-color-title-text`
+- Text:
+  - `--nu-text-primary`
+  - `--nu-text-muted`
+  - `--nu-text-inverse`
+  - `--nu-text-accent`
+  - `--nu-text-hotkey`
+- Controls:
+  - `--nu-color-button-face`
+  - `--nu-color-button-face-alt`
+  - `--nu-color-button-danger`
+  - `--nu-color-button-text`
+  - `--nu-color-field-bg`
+  - `--nu-color-field-text`
+- Borders, focus, shadow:
+  - `--nu-border-light`
+  - `--nu-border-dark`
+  - `--nu-border-accent`
+  - `--nu-shadow-color`
+  - `--nu-focus-color`
+- Window overlays:
+  - `--nu-window-inactive-overlay`
+  - `--nu-window-modal-backdrop`
+
+## Layout And Geometry Tokens
+
+- Spacing:
+  - `--nu-space-xs`
+  - `--nu-space-sm`
+  - `--nu-space-md`
+  - `--nu-space-lg`
+  - `--nu-space-xl`
+- Typography:
+  - `--nu-font-body`
+- Shared geometry:
+  - `--nu-glyph-cell-size`
+  - `--nu-control-height`
+  - `--nu-frame-thickness`
+  - `--nu-rule-thickness`
+- Button mechanics:
+  - `--nu-button-shadow-x`
+  - `--nu-button-shadow-y`
+  - `--nu-button-shadow-offset-x`
+  - `--nu-button-shadow-offset-y`
+  - `--nu-button-press-depth-x`
+  - `--nu-button-press-depth-y`
+- Window shadow:
+  - `--nu-window-shadow-bg`
+  - `--nu-window-shadow-offset-x`
+  - `--nu-window-shadow-offset-y`
+- Scrollbar:
+  - `--nu-scrollbar-track`
+  - `--nu-scrollbar-thumb`
+  - `--nu-scrollbar-button-bg`
+  - `--nu-scrollbar-button-size`
+
+## Checklist For A New Component
+
+- Surface:
+  - Is the background coming from an existing panel, chrome, button, or field token?
+- Text:
+  - Is default text using one of `primary`, `inverse`, `muted`, `accent`, `hotkey`?
+- Focus and selection:
+  - Is active/focused state using the same black/yellow system as existing controls?
+- Borders:
+  - Are border colors coming from `light`, `dark`, or `accent` tokens?
+- Spacing:
+  - Are paddings and gaps based on `--nu-space-*`?
+- Height:
+  - If it is a control row, is it aligned to `--nu-control-height`?
+- Glyphs:
+  - If it shows an icon/checkmark/caret, is it using `NuGlyph` and the shared glyph cell?
+- Shadows:
+  - If it is raised, is it reusing button/window shadow logic instead of inventing a new one?
+- Theme coverage:
+  - Would the component still read correctly in `classic`, `amber`, and `phosphor`?
+- Hardcoded values:
+  - Are any colors or dimensions local only because they are truly component-specific?
+
+## When To Add A New Token
+
+Add a token when:
+
+- the value is already repeated in more than one component
+- the value expresses a visual role, not just a one-off tweak
+- the value should vary by theme
+
+Do not add a token when:
+
+- the value is internal to one component only
+- the value is purely structural and unlikely to be reused
+- the value is still experimental and not yet stable
+
+## Current Gaps To Watch
+
+- Some component-specific structural values still live locally in `*.less`.
+- Scrollbar tokens are partially shared, but geometry is still tied to current implementation details.
+- Mnemonic/hotkey color is standardized, but keyboard behavior itself is not tokenized and should stay behavioral, not visual.

package/docs/TextField.md

@@ -0,0 +1,27 @@
+# TextField
+
+`TextField` is the basic text input primitive using the DOS-style bracketed slot.
+
+## Usage
+
+```tsx
+<TextField
+  label="Target volume"
+  defaultValue="C:\\SYSTEM"
+  hint="Classic Blue is the default theme."
+/>
+```
+
+## Key Props
+
+- `label: string`
+- `hint?: string`
+- `debounceMs?: number`
+- `onDebouncedChange?: (value) => void`
+- standard `input` props such as `value`, `defaultValue`, `onChange`, `disabled`
+
+## Notes
+
+- The control uses brackets and a dark input slot rather than a conventional bordered web input.
+- `onChange` remains immediate; `onDebouncedChange` is optional and runs after the debounce delay.
+- For masked input, use [MaskedField](./MaskedField.md) instead of overloading `TextField`.

package/docs/TickBar.md

@@ -0,0 +1,57 @@
+# TickBar
+
+`TickBar` is a DOS-style slider with keyboard support, pointer dragging, and visible tick marks.
+
+## Usage
+
+```tsx
+import { TickBar } from "@deadragdoll/reactnu";
+
+function Example() {
+  return (
+    <TickBar
+      hint="Arrow keys adjust the value"
+      label="Volume"
+      max={100}
+      min={0}
+      orientation="horizontal"
+      step={5}
+      value={65}
+    />
+  );
+}
+```
+
+## Props
+
+- `label?: string`
+- `hint?: string`
+- `min?: number`
+- `max?: number`
+- `step?: number`
+- `orientation?: "horizontal" | "vertical"`
+- `value?: number`
+- `defaultValue?: number`
+- `onValueChange?: (value: number) => void`
+- `tickCount?: number`
+- `showValue?: boolean`
+- `valueRenderer?: (value, min, max) => ReactNode`
+- `disabled?: boolean`
+- `fill?: boolean`
+
+## Behavior
+
+- Supports controlled and uncontrolled value flow.
+- Pointer down on the track moves the thumb immediately.
+- Dragging continues while the pointer is captured by the track.
+- `vertical` mode maps `min` to the bottom and `max` to the top.
+- Keyboard:
+  - `ArrowLeft`, `ArrowDown` decrement
+  - `ArrowRight`, `ArrowUp` increment
+  - `PageDown`, `PageUp` move by `step * 10`
+  - `Home`, `End` jump to `min` and `max`
+- Values are clamped to `min` / `max` and snapped to `step`.
+
+## Notes
+
+- If `tickCount` is omitted, the control derives a reasonable number of visible marks from `min`, `max`, and `step`.

package/docs/ToolBar.md

@@ -0,0 +1,51 @@
+# ToolBar
+
+`ToolBar` is the compact action strip for command buttons and separators.
+
+For the same button behavior outside a toolbar container, use [CommandButton](./CommandButton.md).
+
+## Usage
+
+```tsx
+<ToolBar>
+  <ToolButton icon="folder">&Scan</ToolButton>
+  <ToolButton icon="star" pressed>
+    &Watch
+  </ToolButton>
+  <ToolSeparator />
+  <ToolDropButton
+    icon="folder"
+    menuItems={[
+      { id: "export-map", text: "Export &map" },
+      { id: "export-log", text: "Export &log" }
+    ]}
+  >
+    &Export
+  </ToolDropButton>
+</ToolBar>
+```
+
+## Exports
+
+- `CommandButton`
+- `ToolBar`
+- `ToolButton`
+- `ToolDropButton`
+- `ToolSeparator`
+
+## Key Props
+
+- `fill?: boolean`
+- `wrap?: boolean`
+- `slotStyles`
+- `slotClassNames`
+
+## Notes
+
+- `ToolBar` is layout-only and defaults to `fill={true}`.
+- `wrap={true}` lets tools continue on the next row when the container is too narrow.
+- `ToolButton` supports `toggled` for toggle-style tools. `pressed` is kept as a legacy alias through the shared command-button layer.
+- `ToolButton` also supports `icon` and optional `dropdown`.
+- `ToolDropButton` is a convenience wrapper for `ToolButton dropdown`.
+- If `menuItems` are provided, `ToolDropButton` opens `PopupMenu` automatically and reports selection through `onMenuItemSelect`.
+- `ToolSeparator` is decorative and should only be used between tools.

package/docs/TreeListView.md

@@ -0,0 +1,84 @@
+# TreeListView
+
+`TreeListView` combines a hierarchical tree column with report-style columns.
+The tree geometry stays under component control, while report cells can be
+filled by the host.
+
+## Usage
+
+```tsx
+type Node = TreeListItemBase<Node> & {
+  metrics?: {
+    humidity: number;
+    temperature: number;
+    wind: number;
+  };
+};
+
+const columns: TreeListColumn<Node>[] = [
+  { id: "name", title: "&Name", tree: true, width: "24ch" },
+  { id: "temp", title: "&Temp", align: "end", width: "9ch" },
+  { id: "humidity", title: "&Humidity", align: "end", width: "10ch" }
+];
+
+<TreeListView
+  columns={columns}
+  data={nodes}
+  getCellContent={(itemId, columnId, context) => {
+    if (columnId === "temp" && context.item.metrics) {
+      return (
+        <ReportCell align="end">
+          {`${context.item.metrics.temperature.toFixed(1)}C`}
+        </ReportCell>
+      );
+    }
+
+    return undefined;
+  }}
+  selectedId={selectedId}
+  onItemSelect={(item) => setSelectedId(item.id)}
+  onItemCheckChange={(item, checked) => {}}
+/>;
+```
+
+## Key Props
+
+- `columns`
+- `data`
+- `getCellContent`
+- `dataVersion`
+- `selectedId`
+- `activeItemId`
+- `defaultActiveItemId`
+- `expandedIds`
+- `defaultExpandedIds`
+- `onItemSelect`
+- `onItemDoubleClick`
+- `onItemCheckChange`
+- `onExpandedIdsChange`
+- `onActiveItemChange`
+- `checkedIds`
+- `uncheckedShape`
+
+## Imperative Handle
+
+- `focus()`
+- `scrollToItem(itemId)`
+- `activateItem(itemId)`
+- `expandItem(itemId)`
+- `collapseItem(itemId)`
+- `toggleItemCheck(itemId)`
+- `getActiveItemId()`
+
+## Notes
+
+- Mark one column with `tree: true` to host the hierarchy.
+- If no column is marked as tree, the first column is used.
+- Keyboard behavior follows the same pattern as `TreeView`, while columns behave like `ListView`.
+- `getCellContent(itemId, columnId, context)` is the preferred way to populate
+  report columns from host data.
+- `dataVersion` is available for live-data scenarios where report content
+  changes frequently even if the tree structure itself stays stable.
+- Columns auto-size from visible content by default.
+- `minWidth` sets a lower bound for auto-sized and resized columns.
+- Columns are resizable unless `resizable={false}` is set on a column.

package/docs/TreeView.md

@@ -0,0 +1,53 @@
+# TreeView
+
+`TreeView` renders a recursive hierarchy with DOS-style connector geometry.
+
+## Usage
+
+```tsx
+<TreeView
+  data={[
+    {
+      title: "Drive C:",
+      id: "1",
+      expanded: true,
+      children: [
+        { title: "SYSTEM", id: "1-1" },
+        { title: "LOGS", id: "1-2", checked: true }
+      ]
+    }
+  ]}
+  selectedId={selectedId}
+  onItemSelect={(item) => setSelectedId(item.id)}
+  onItemCheckChange={(item, checked) => {}}
+/>
+```
+
+## Key Props
+
+- `data: TreeItem[]`
+- `selectedId?: string`
+- `expandedIds?: string[]`
+- `defaultExpandedIds?: string[]`
+- `emptyText?: string`
+- `uncheckedShape?: "box" | "none"`
+- `onItemSelect?: (item) => void`
+- `onItemDoubleClick?: (item) => void`
+- `onItemCheckChange?: (item, checked) => void`
+- `onExpandedIdsChange?: (expandedIds) => void`
+
+## Imperative Handle
+
+- `focus()`
+- `scrollToItem(itemId)`
+- `activateItem(itemId)`
+- `expandItem(itemId)`
+- `collapseItem(itemId)`
+- `toggleItemCheck(itemId)`
+- `getActiveItemId()`
+
+## Notes
+
+- Tree geometry is owned by the component.
+- The host provides item data and optional controlled state.
+- Keyboard navigation supports arrows, `Home`, `End`, `Enter`, and `Space`.

package/docs/Window.md

@@ -0,0 +1,53 @@
+# Window
+
+`Window` is the main floating chrome primitive used for desktop windows and dialogs.
+
+## Usage
+
+```tsx
+<Window title="Activity Log" mode="window" statusBar="F2 Save">
+  <Content />
+</Window>
+```
+
+```tsx
+<Window
+  title="Activity Log"
+  mode="window"
+  statusBar={
+    <>
+      <StatusBarItem grow>F2 Save F3 Search Alt+F3 Close</StatusBarItem>
+      <StatusBarItem align="end">3 warnings</StatusBarItem>
+    </>
+  }
+>
+  <Content />
+</Window>
+```
+
+## Key Props
+
+- `title: string`
+- `mode?: "dialog" | "window"`
+- `border?: "single" | "double"`
+- `minimized?: boolean`
+- `maximized?: boolean`
+- `closeable?: boolean`
+- `draggable?: boolean`
+- `resizable?: boolean`
+- `scrollable?: boolean`
+- `statusBar?: ReactNode`
+- `titleButtons?: WindowTitleButtonDefinition[]`
+- `onClose?()`
+- `onToggleMinimized?()`
+- `onToggleMaximized?()`
+- `onPositionChange?(position)`
+- `onSizeChange?(size)`
+- `onActivate?()`
+
+## Notes
+
+- Drag and resize are implemented with pointer events and local DOM updates for smoother motion.
+- The public `WindowTitleButton` and `useWindowTitleButtons()` helpers support custom title-bar controls.
+- `StatusBarItem` only provides placement semantics (`grow`, `align`) and does not enforce its own border or chrome.
+- Plain string `statusBar` still works for simple status lines.

package/docs/WindowBar.md

@@ -0,0 +1,24 @@
+# WindowBar
+
+`WindowBar` renders open windows in the desktop app bar.
+
+## Usage
+
+```tsx
+<WindowBar
+  items={windowManager.windows}
+  onActivateWindow={(id) => windowManager.activateWindow(id)}
+/>
+```
+
+## Behavior
+
+- Shows open windows in creation order
+- Marks the active window
+- Groups windows by `domain`
+- Opens a picker dialog when a grouped domain is clicked
+
+## Notes
+
+- Grouping is driven by `NuManagedWindowDefinition.domain`.
+- Grouped pickers use the shared MDI-style window picker dialog logic.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@deadragdoll/reactnu",
+  "version": "0.1.9",
+  "private": false,
+  "description": "React components with a precise DOS-era utility interface.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "react",
+    "typescript",
+    "component-library",
+    "dos",
+    "norton-utilities"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepack": "node scripts/prepare-package-docs.mjs && npm run build",
+    "postpack": "node scripts/prepare-package-docs.mjs --clean",
+    "build:styles": "mkdir -p dist && lessc src/globals.less dist/styles.css && prettier --write dist/styles.css",
+    "watch:styles": "mkdir -p dist && lessc --watch src/globals.less dist/styles.css",
+    "build": "tsup src/index.ts --clean --tsconfig tsconfig.json --format esm,cjs --external react,react-dom && tsc -p tsconfig.build.json && npm run build:styles",
+    "dev": "npm run build:styles && tsup src/index.ts --watch --tsconfig tsconfig.json --format esm,cjs --external react,react-dom"
+  },
+  "peerDependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  }
+}