@deadragdoll/reactnu 0.1.9

package/docs/DialogHelpers.md

@@ -0,0 +1,85 @@
+# Dialog Helpers
+
+`useNuWindowManager()` includes two async helper dialogs built on top of the managed window layer:
+
+- `showMessageBox(options)`
+- `showInputBox(options)`
+
+Both helpers open managed dialogs and resolve through a `Promise`.
+
+## MessageBox
+
+```tsx
+const windowManager = useNuWindowManager();
+
+const result = await windowManager.showMessageBox({
+  title: "Diagnostics",
+  message: "Continue with the maintenance pass?",
+  kind: "info",
+  preset: "yes-no-cancel"
+});
+```
+
+Supported options:
+
+- `title?: string`
+- `message: ReactNode`
+- `kind?: "normal" | "info" | "error"`
+- `preset?: "ok" | "ok-cancel" | "yes-no" | "yes-no-cancel"`
+- `yes?: boolean`
+- `no?: boolean`
+- `cancel?: boolean`
+- `ok?: boolean`
+- `yesLabel?: string`
+- `noLabel?: string`
+- `cancelLabel?: string`
+- `okLabel?: string`
+- `appModal?: boolean`
+- `domain?: string`
+- `style?: CSSProperties`
+
+Result type:
+
+- `"ok" | "yes" | "no" | "cancel"`
+
+Notes:
+
+- If no buttons are specified, `MessageBox` falls back to `OK`.
+- `preset` provides the starting button set, but explicit button flags still override it.
+- Button labels can be overridden without changing the result values.
+- If the dialog is closed through the title bar, the helper resolves to the best dismiss result for the configured buttons.
+
+## InputBox
+
+```tsx
+const windowManager = useNuWindowManager();
+
+const value = await windowManager.showInputBox({
+  title: "Archive Report",
+  label: "Target path",
+  defaultValue: "C:\\LOGS\\SURFACE.MAP",
+  hint: "Type the report path and confirm."
+});
+```
+
+Supported options:
+
+- `title?: string`
+- `label: string`
+- `defaultValue?: string`
+- `placeholder?: string`
+- `hint?: string`
+- `okLabel?: string`
+- `cancelLabel?: string`
+- `appModal?: boolean`
+- `domain?: string`
+- `style?: CSSProperties`
+
+Result type:
+
+- `string | null`
+
+Notes:
+
+- `null` means the dialog was cancelled or closed.
+- `InputBox` uses the same managed dialog layer as all other windowed UI.

package/docs/Dropdown.md

@@ -0,0 +1,44 @@
+# Dropdown
+
+`Dropdown` is a select-like control built from a compact DOS-style field and a popup `ListBox`.
+
+## Usage
+
+```tsx
+<Dropdown
+  label="Run profile"
+  value={profileId}
+  onValueChange={(nextValue) => setProfileId(nextValue)}
+  data={[
+    {
+      category: null,
+      items: [
+        { id: "default", name: { text: "DEFAULT.NU" } },
+        { id: "repair", name: { text: "REPAIR.NU" } }
+      ]
+    }
+  ]}
+/>
+```
+
+## Key Props
+
+- `label: string`
+- `data: ListBoxGroup[]`
+- `value?: string`
+- `defaultValue?: string`
+- `onValueChange?: (value, item, group) => void`
+- `placeholder?: string`
+- `hint?: string`
+- `disabled?: boolean`
+- `slotClassNames?` / `slotStyles?` for internal surface customization
+
+## Keyboard
+
+- `ArrowUp` / `ArrowDown` change the value while closed
+- `Enter` / `Space` open the list
+
+## Notes
+
+- The popup width is clamped to the width of the closed control.
+- This component is intentionally select-like; searchable combo-box behavior should live in a separate component.

package/docs/Frame.md

@@ -0,0 +1,38 @@
+# Frame
+
+`Frame` is a lightweight container with a simple border and optional title.
+
+## Usage
+
+```tsx
+<Frame title="Commands">
+  <ListBox data={groups} />
+</Frame>
+```
+
+## Key Props
+
+- `fill?: boolean`
+- `title?: string`
+- `titleStart?: ReactNode`
+- `titleContent?: ReactNode`
+- `titleEnd?: ReactNode`
+- `titleProps?: { background?: string; color?: string; borderColor?: string }`
+- `titleStyle?: CSSProperties`
+- `contentStyle?: CSSProperties`
+- `variant?: "outline" | "title-bar"`
+- `titleAlign?: "start" | "center" | "end"`
+- `titleBold?: boolean`
+- `children`
+
+## Notes
+
+- `fill` defaults to `true`, so `Frame` stretches naturally inside flex/grid parents and also fills block-style hosts such as window bodies.
+- `outline` keeps the title floating over the top border.
+- `title-bar` renders a solid title strip across the full width.
+- `titleProps` controls frame chrome around the title area: title background, title text color, and frame border color.
+- `titleStyle` and `contentStyle` remain available for additional local overrides without creating a separate Frame variant.
+- `title` remains a shorthand for simple text titles.
+- `titleContent` lets you replace the center title payload with custom markup.
+- `titleStart` and `titleEnd` let you place custom controls or indicators on the left and right of the title shell.
+- if only `titleStart` or `titleEnd` is provided, `Frame` renders just that fragment without a default text title.

package/docs/GETTING_STARTED.md

@@ -0,0 +1,110 @@
+# Getting Started
+
+This guide shows the recommended host setup for a ReactNU application.
+
+## Recommended Shell
+
+```tsx
+import {
+  AppBarHost,
+  AppBarItem,
+  NuDesktop,
+  NuThemeProvider,
+  NuView,
+  WindowBar,
+  useNuWindowManager
+} from "@deadragdoll/reactnu";
+
+function ShellAppBar() {
+  const windowManager = useNuWindowManager();
+
+  return (
+    <AppBarHost>
+      <WindowBar
+        items={windowManager.windows.map((windowEntry) => ({
+          active: windowEntry.active,
+          domain: windowEntry.domain,
+          id: windowEntry.id,
+          minimized: windowEntry.minimized,
+          title: windowEntry.title
+        }))}
+        onActivateWindow={windowManager.activateWindow}
+      />
+      <AppBarItem alignment="end">12:40</AppBarItem>
+    </AppBarHost>
+  );
+}
+
+export function App() {
+  return (
+    <NuThemeProvider>
+      <NuDesktop appBar={<ShellAppBar />}>
+        <NuView padding="md">Workspace content</NuView>
+      </NuDesktop>
+    </NuThemeProvider>
+  );
+}
+```
+
+## Recommended Order
+
+1. `NuThemeProvider`
+2. `NuDesktop`
+3. host-driven `appBar`
+4. workspace content
+5. open windows through `useNuWindowManager()`
+
+## Opening A Window
+
+```tsx
+import { Button, useNuWindowManager } from "@deadragdoll/reactnu";
+
+function Launcher() {
+  const windowManager = useNuWindowManager();
+
+  return (
+    <Button
+      onClick={() =>
+        windowManager.openWindow({
+          title: "Inspector",
+          content: <div>Window content</div>
+        })
+      }
+    >
+      &Open inspector
+    </Button>
+  );
+}
+```
+
+## Opening A Dialog
+
+```tsx
+windowManager.openDialog({
+  title: "Confirm",
+  content: ({ close }) => <Button onClick={close}>&Close</Button>
+});
+```
+
+## Recommended Folder Shape
+
+```text
+src/
+  app/
+    App.tsx
+    DesktopAppBar.tsx
+    DesktopMenu.tsx
+  windows/
+    InspectorWindow.tsx
+    ReportWindow.tsx
+  dialogs/
+    ConfirmDialog.tsx
+  views/
+    DashboardView.tsx
+```
+
+## Notes
+
+- `NuDesktop` already creates the app host and window manager layers.
+- `WindowBar` is host-owned. It is not injected automatically.
+- Use `NuView` whenever a pane or cell needs to own scrolling explicitly.

package/docs/Glyph.md

@@ -0,0 +1,29 @@
+# Glyph
+
+`NuGlyph` is the reusable icon primitive for small UI symbols.
+
+## Usage
+
+```tsx
+<NuGlyph name="window-close" />
+<NuGlyph name="dropdown-arrow" />
+```
+
+## Key Props
+
+- `name: NuGlyphName`
+- standard `span` props such as `className`
+
+## Current Glyph Set
+
+- `check-fill`
+- `dropdown-arrow`
+- `window-close`
+- `window-maximize`
+- `window-minimize`
+- `window-resize`
+- `window-restore`
+
+## Notes
+
+- New control-specific symbols should be added here instead of being redrawn ad hoc in component styles.

package/docs/Info.md

@@ -0,0 +1,51 @@
+# Info
+
+`Info` is a lightweight fill-container for informational copy. It does not add window chrome or borders; it pairs with `InfoAccent` for inline highlighted fragments.
+
+## Usage
+
+```tsx
+<Info>
+  Hello, you must <InfoAccent>Accept</InfoAccent> the rules before continuing.
+</Info>
+```
+
+Custom accent:
+
+```tsx
+<Info accentColor="#ffffff">
+  Current profile: <InfoAccent>DEFAULT.NU</InfoAccent>
+</Info>
+```
+
+Formatting flags:
+
+```tsx
+<Info>
+  For bar
+  <InfoAccent bold italic underline upper>
+    baz
+  </InfoAccent>
+  HelloWorld
+</Info>
+```
+
+## Key Props
+
+- `fill?: boolean`
+- `accentColor?: CSSProperties["color"]`
+- standard `div` props such as `className`, `style`, `children`
+
+`InfoAccent` props:
+
+- `bold?: boolean`
+- `italic?: boolean`
+- `underline?: boolean`
+- `upper?: boolean`
+- standard `span` props such as `className`, `style`, `children`
+
+## Notes
+
+- `fill` defaults to `true`, so `Info` stretches with its parent container.
+- `InfoAccent` is the intended inline emphasis API for `Info`.
+- `accentColor` is inherited by nested `InfoAccent` fragments.

package/docs/ListBox.md

@@ -0,0 +1,35 @@
+# ListBox
+
+`ListBox` is the main scrollable selection surface for grouped or flat item collections.
+
+## Usage
+
+```tsx
+<ListBox
+  data={groups}
+  selectedId={selectedId}
+  onItemSelect={(item) => setSelectedId(item.id ?? "")}
+/>
+```
+
+## Key Props
+
+- `data: ListBoxGroup[]`
+- `selectedId?: string`
+- `onItemSelect?: (item, group) => void`
+- `checkedIds?: string[]`
+- `onItemCheckChange?: (item, group, checked) => void`
+- `onItemDoubleClick?: (item, group) => void`
+- `rightCheckBox?: boolean`
+- `emptyText?: string`
+
+## Keyboard
+
+- `ArrowUp` / `ArrowDown`
+- `Home` / `End`
+- `Enter`
+- `Space` for check toggling
+
+## Notes
+
+- The same data format supports both grouped and flat lists by using `category: null`.

package/docs/ListView.md

@@ -0,0 +1,62 @@
+# ListView
+
+`ListView` renders a report-style list with columns, row selection, optional checkboxes, and per-column custom cell renderers.
+
+## Usage
+
+```tsx
+type Row = ListViewRowBase & {
+  name: string;
+  size: string;
+  type: string;
+};
+
+const columns: ListViewColumn<Row>[] = [
+  { id: "name", title: "&Name", field: "name", width: "18ch" },
+  { id: "type", title: "&Type", field: "type", width: "10ch" },
+  { id: "size", title: "&Size", field: "size", align: "end", width: "8ch" }
+];
+
+<ListView
+  columns={columns}
+  data={rows}
+  activeRowId={activeRowId}
+  onActiveRowChange={(row) => setActiveRowId(row.id)}
+  selectedId={selectedId}
+  showCheckBox
+  checkedIds={checkedIds}
+  onRowSelect={(row) => setSelectedId(row.id)}
+  onRowCheckChange={(row, checked) => {}}
+/>;
+```
+
+## Key Props
+
+- `columns`
+- `data`
+- `activeRowId`
+- `defaultActiveRowId`
+- `onActiveRowChange`
+- `selectedId`
+- `onRowSelect`
+- `onRowDoubleClick`
+- `showCheckBox`
+- `checkedIds`
+- `onRowCheckChange`
+- `uncheckedShape`
+
+## Notes
+
+- Keyboard navigation follows the same pattern as other list-like controls.
+- Column titles support `&` mnemonic markup.
+- A column can use `field` for simple value rendering or `renderCell` for custom content.
+
+## Imperative Handle
+
+`ListView` also supports `ref` with:
+
+- `focus()`
+- `scrollToRow(rowId)`
+- `activateRow(rowId)`
+- `toggleRowCheck(rowId)`
+- `getActiveRowId()`

package/docs/MainMenu.md

@@ -0,0 +1,36 @@
+# MainMenu
+
+`MainMenu` is the classic top application menu bar with nested submenus.
+
+## Usage
+
+```tsx
+<MainMenu items={menuItems} />
+```
+
+## Key Props
+
+- `items: MainMenuNode[]`
+- `onItemSelect?: (item) => void`
+
+## Menu Model
+
+- `MainMenuItem`
+  - `id`
+  - `text`
+  - `hotkey?`
+  - `shortcut?`
+  - `checked?`
+  - `disabled?`
+  - `hidden?`
+  - `items?`
+  - `onSelect?`
+- `MainMenuDivider`
+  - `id`
+  - `type: "divider"`
+
+## Notes
+
+- Top-level dropdowns open below their root items.
+- Nested submenus open to the right.
+- Active and hovered items use the same black selection pattern used elsewhere in the library.

package/docs/MaskedField.md

@@ -0,0 +1,124 @@
+# MaskedField
+
+`MaskedField` is a bracketed single-line input with a readable mask grammar and built-in invalid feedback.
+
+## Usage
+
+```tsx
+<MaskedField
+  label="Dial prefix"
+  mask="+(D)"
+  defaultValue="7"
+/>
+
+<MaskedField
+  label="Recovery code"
+  mask="(D3-D2-D2)"
+  defaultValue="1234567"
+  hint="Fixed literals stay inline with the mask."
+/>
+```
+
+## Key Props
+
+- `label: string`
+- `mask: string`
+- `hint?: string`
+- `debounceMs?: number`
+- `onDebouncedChange?: (value) => void`
+- `slotClassNames?` / `slotStyles?` for internal surface customization
+- standard `input` props such as `value`, `defaultValue`, `onChange`, `disabled`
+
+## Immediate And Debounced Flow
+
+- `onChange` stays immediate and should drive live state in the host.
+- `onDebouncedChange` is optional and runs after `debounceMs`.
+- If you need to show current validity right away, use your controlled `value` together with `getMaskedFieldState(mask, value)`.
+
+## Mask Syntax
+
+- `D` = one digit
+- `A` = one letter
+- `D*` = zero or more digits
+- `A*` = zero or more letters
+- `D3` = exactly three digits
+- `A2` = exactly two letters
+- `D3+` = three or more digits
+- `A4+` = four or more letters
+- any other character is treated as a literal
+
+Examples:
+
+- `+(D)`
+- `(D3)`
+- `(D3-D2-D2)`
+- `A3-D3`
+
+## Validation
+
+- The field filters incoming text through the mask and auto-inserts literals when enough token content exists.
+- If the current value is incomplete for the mask, the field turns red with yellow text.
+- Empty value stays neutral, so a fresh field does not start in an error state.
+
+## Notes
+
+- `MaskedField` is intentionally separate from `TextField`, so plain text inputs stay simple.
+- Unbounded segments such as `D*` and `D3+` are best used as the final variable part of the mask. That keeps formatting deterministic.
+
+## Current Scope
+
+For the current library stage, `MaskedField` is considered production-ready for:
+
+- fixed masks with literals
+- short operational codes
+- dial prefixes
+- serial-like identifiers
+- numeric masks with immediate invalid feedback
+- host flows where live state and debounced state are both useful
+
+The current implementation deliberately stops short of advanced editor-like caret management.
+
+## Final-State Roadmap
+
+If we continue this control toward a fuller final state, the main work areas are:
+
+1. Caret and selection behavior.
+   File: [packages/ui/src/components/MaskedField/MaskedField.tsx](/home/code4bones/Devs/coding/ReactNU/packages/ui/src/components/MaskedField/MaskedField.tsx)
+   This is where cursor preservation, middle-of-string edits, backspace-over-literals, and paste normalization should be finished.
+
+2. Mask grammar and formatting engine.
+   File: [packages/ui/src/components/MaskedField/textMask.ts](/home/code4bones/Devs/coding/ReactNU/packages/ui/src/components/MaskedField/textMask.ts)
+   This is the place to extend token kinds, add richer rules like hex/alnum/upper/lower, or tighten behavior for unbounded segments.
+
+3. Public state contract.
+   Files:
+   [packages/ui/src/components/MaskedField/MaskedField.tsx](/home/code4bones/Devs/coding/ReactNU/packages/ui/src/components/MaskedField/MaskedField.tsx)
+   [packages/ui/src/components/MaskedField/index.ts](/home/code4bones/Devs/coding/ReactNU/packages/ui/src/components/MaskedField/index.ts)
+   If we need a stronger final API, this is where to add explicit exports such as `MaskedFieldState`, `onValidityChange`, or `onMaskComplete`.
+
+4. Visual invalid and pending states.
+   File: [packages/ui/src/components/MaskedField/MaskedField.less](/home/code4bones/Devs/coding/ReactNU/packages/ui/src/components/MaskedField/MaskedField.less)
+   This is the right place for any future visual split between `pending`, `invalid`, and `complete`, or for adding a dedicated state marker.
+
+5. Real usage regression coverage.
+   File: [apps/sandbox/src/DemoApp.tsx](/home/code4bones/Devs/coding/ReactNU/apps/sandbox/src/DemoApp.tsx)
+   The dedicated `Masked Field` demo window should stay the proving ground for new mask forms, paste flows, and live host-state scenarios.
+
+## Recommended Next Improvements
+
+These are the best-practice upgrades worth doing later, but not required right now:
+
+- preserve caret position during reformatting
+- add `onValidityChange`
+- add `onMaskComplete`
+- export a typed `MaskedFieldState`
+- introduce richer token families only when a real use case appears
+
+## Non-Goals For Now
+
+These are intentionally out of scope for the current version:
+
+- regex-style masks
+- full parser-expression language
+- locale-aware date/number semantics
+- aggressive auto-correction beyond the current readable token model

package/docs/Memo.md

@@ -0,0 +1,32 @@
+# Memo
+
+`Memo` renders an editable multiline text area that fills its parent by default.
+
+## Usage
+
+```tsx
+<Memo
+  content={`Operator note:
+Check drive map before running repair.`}
+/>
+```
+
+## Key Props
+
+- `content?: string`
+- `value?: string`
+- `defaultValue?: string`
+- `onValueChange?: (value: string) => void`
+- `fill?: boolean`
+- `scroll?: "auto" | "x" | "y" | "both" | "hidden"`
+- `background?: CSSProperties["background"]`
+- `focusBackground?: CSSProperties["background"]`
+- `focusTextColor?: CSSProperties["color"]`
+- `textColor?: CSSProperties["color"]`
+
+## Notes
+
+- `Memo` uses a native `textarea` and preserves line breaks.
+- By default it uses a sand-colored background and black text.
+- `content` works as convenient initial text for uncontrolled usage.
+- Focus colors are configurable and default to the same surface colors unless overridden.

package/docs/NuAppHostProvider.md

@@ -0,0 +1,28 @@
+# NuAppHostProvider
+
+`NuAppHostProvider` owns the application-level main menu state.
+
+## Usage
+
+```tsx
+<NuAppHostProvider>
+  <NuDesktop appBar={<AppBar />}>
+    <App />
+  </NuDesktop>
+</NuAppHostProvider>
+```
+
+## Related API
+
+Use `useAppHostMenu()` to access:
+
+- `mainMenu`
+- `setMainMenu(...)`
+- `setMenuFlags(id, flags)`
+- `setMenuItem(id, patch)`
+- `setSubmenuTree(id, items)`
+
+## Notes
+
+- `NuDesktop` expects to live inside this provider.
+- The app host menu layer also receives the MDI bridge used by the `mdi.host` menu slot.