native-document 1.0.166 → 1.0.168

package/docs/components/shortcut-manager.md

@@ -0,0 +1,221 @@
+---
+title: ShortcutManager
+description: Register, display, and manage keyboard shortcuts with OS-aware rendering and context scoping
+---
+
+# ShortcutManager
+
+`ShortcutManager` handles global and context-scoped keyboard shortcuts. It parses shortcut strings, renders them correctly per OS (Mac symbols or Windows labels), and dispatches handlers on keydown.
+
+```javascript
+import { ShortcutManager } from 'native-document';
+```
+
+---
+
+## Initialization
+
+Call `init()` once at app startup to activate the global keyboard listener:
+
+```javascript
+ShortcutManager.init();
+```
+
+---
+
+## Shortcut Conventions
+
+Two formats are supported:
+
+### Short convention
+
+Starts with `+`. The first `+` means Ctrl/Cmd (meta):
+
+| Shortcut | Meaning |
+|---|---|
+| `'+S'` | Ctrl/Cmd + S |
+| `'++S'` | Ctrl/Cmd + Alt + S |
+| `'+Shift+S'` | Ctrl/Cmd + Shift + S |
+| `'+Alt+S'` | Ctrl/Cmd + Alt + S |
+
+### Standard convention
+
+```
+'Ctrl+S'
+'Cmd+Shift+S'
+'Alt+F4'
+'Ctrl+Alt+Delete'
+```
+
+Both formats are equivalent and can be mixed freely.
+
+---
+
+## OS-Aware Display
+
+`ShortcutManager.display(shortcut)` formats a shortcut string for the current OS:
+
+```javascript
+ShortcutManager.display('+S')
+// Mac:     "⌘ S"
+// Windows: "Ctrl+S"
+
+ShortcutManager.display('+Shift+S')
+// Mac:     "⌘ ⇧ S"
+// Windows: "Ctrl+Shift+S"
+
+ShortcutManager.display('++S')
+// Mac:     "⌘ ⌥ S"
+// Windows: "Ctrl+Alt+S"
+```
+
+Mac symbols:
+
+| Key | Symbol |
+|---|---|
+| Meta / Cmd | `⌘` |
+| Shift | `⇧` |
+| Alt / Option | `⌥` |
+| Ctrl | `⌃` |
+
+Use `display()` in your renderer to show the shortcut label next to menu items:
+
+```javascript
+MenuItem.use(($description) => {
+    return Div({ class: 'menu-item' }, [
+        $description.label,
+        $description.shortcut
+            ? Span({ class: 'shortcut' }, ShortcutManager.display($description.shortcut))
+            : null
+    ]);
+});
+```
+
+---
+
+## Registering Shortcuts
+
+### `ShortcutManager.register(shortcut, handler, options?)`
+
+```javascript
+ShortcutManager.register('+S', () => save(), { source: 'editor' });
+ShortcutManager.register('+Z', () => undo(), { source: 'editor' });
+ShortcutManager.register('+Shift+Z', () => redo(), { source: 'editor' });
+```
+
+Options:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `context` | `string` | `'global'` | Scope the shortcut to a named context |
+| `source` | `string` | `'unknown'` | Label used in conflict warnings |
+| `force` | `boolean` | `false` | Override an existing registration without warning |
+
+### `ShortcutManager.unregister(shortcut, context?)`
+
+```javascript
+ShortcutManager.unregister('+S');
+ShortcutManager.unregister('+S', 'editor');
+```
+
+### `ShortcutManager.has(shortcut, context?)`
+
+```javascript
+if (!ShortcutManager.has('+S')) {
+    ShortcutManager.register('+S', () => save());
+}
+```
+
+---
+
+## Contexts
+
+Contexts let you scope shortcuts so the same key combination can do different things in different parts of the app. A `'global'` shortcut always fires. A context shortcut only fires when that context is active (you control activation logic):
+
+```javascript
+// Global - always active
+ShortcutManager.register('+S', () => save(), {
+    context: 'global',
+    source:  'app'
+});
+
+// Scoped - only active in the modal context
+ShortcutManager.register('Escape', () => closeModal(), {
+    context: 'modal',
+    source:  'modal'
+});
+
+// Unregister when leaving context
+ShortcutManager.unregister('Escape', 'modal');
+```
+
+---
+
+## Conflict Handling
+
+Registering the same shortcut in the same context twice logs a warning:
+
+```javascript
+ShortcutManager.register('+S', () => save(),    { source: 'editor' });
+ShortcutManager.register('+S', () => download(), { source: 'toolbar' });
+// warn: "+S" is already registered by "editor" in context "global". Use { force: true } to override.
+```
+
+Use `force: true` to override without warning:
+
+```javascript
+ShortcutManager.register('+S', () => download(), { force: true, source: 'toolbar' });
+```
+
+---
+
+## Usage with Menu Items
+
+```javascript
+import { MenuItem } from 'native-document/components';
+
+MenuItem()
+    .label('Save')
+    .icon(SaveIcon)
+    .shortcut('+S')
+    .action(() => save())
+```
+
+The shortcut string is passed as-is to `ShortcutManager.display()` by the renderer to show the OS-formatted label.
+
+---
+
+## Integration with Dropdown and Context Menu
+
+`DropdownItem` and `ContextMenuItem` both accept a `.shortcut()` method that passes the string directly to `ShortcutManager.display()` in the renderer:
+
+```javascript
+import { DropdownItem } from 'native-document/components';
+
+DropdownItem()
+    .label('Save')
+    .icon(SaveIcon)
+    .shortcut('+S')
+    .action(() => save())
+
+// ContextMenuItem works the same way
+ContextMenuItem()
+    .label('Delete')
+    .shortcut('Delete')
+    .danger()
+    .action((data) => deleteRow(data))
+```
+
+The shortcut label is display-only in Dropdown and ContextMenu items - they do not automatically register the shortcut with `ShortcutManager`. Register shortcuts separately if you want them to fire on keydown:
+
+```javascript
+ShortcutManager.register('+S', () => save(), { source: 'toolbar' });
+```
+
+---
+
+## Next Steps
+
+- **[Menu](./menu.md)** - Menu with shortcut labels
+- **[Dropdown](./dropdown.md)** - Dropdown items with shortcuts
+- **[Context Menu](./context-menu.md)** - Context menu items with shortcuts

package/docs/components/simple-table.md

@@ -0,0 +1,107 @@
+---
+title: SimpleTable
+description: Lightweight table component for static or observable data with custom cell renderers
+---
+
+# SimpleTable
+
+```javascript
+import { SimpleTable } from 'native-document/components';
+
+SimpleTable(props?)
+```
+
+A lightweight table for static or observable data.
+
+## Default Renderer
+
+```javascript
+import { SimpleTableRender } from 'native-document/ui';
+
+SimpleTable.use(SimpleTableRender);
+```
+
+## Methods
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.column(key, title, props?, callback?)` | `key: string`, `title: string`, `props?: object`, `callback?: (value, row) => element` | Add a column. `callback` renders a custom cell. |
+| `.group(title, fn)` | `title: string`, `fn: (group) => void` | Group columns under a shared header. |
+| `.data(data)` | `data: array \| ObservableArray` | Static array or reactive observable array |
+| `.empty(element)` | `element: NdChild` | Content shown when data is empty |
+| `.noHeader()` | - | Hide the table header row |
+| `.onRowClick(handler)` | `handler: (row) => void` | Fired when a row is clicked |
+| `.rowProps(fn)` | `fn: (row) => object` | Dynamic HTML attributes per row |
+
+## Example
+
+```javascript
+SimpleTable()
+    .column('name',  'Name')
+    .column('email', 'Email')
+    .column('role',  'Role', {}, (value) => Badge(value).primary())
+    .column('actions', '', {}, (value, row) =>
+        HStack([
+            Button('Edit')
+                .small()
+                .nd.onClick(() => edit(row)),
+            Button('Delete')
+                .small()
+                .danger()
+                .nd.onClick(() => remove(row))
+        ]).spacing(4)
+    )
+    .data(users)
+    .empty(Div('No users found'))
+    .onRowClick((row) => openUserDetail(row))
+```
+
+## Column Groups
+
+Group related columns under a shared header:
+
+```javascript
+SimpleTable()
+    .column('name', 'Name')
+    .group('Address', (group) => {
+        group.column('city',    'City')
+        group.column('country', 'Country')
+        group.column('zip',     'ZIP')
+    })
+    .column('actions', '', {}, (value, row) => Button('Edit').small())
+    .data(users)
+```
+
+---
+
+## SimpleTable vs DataTable
+
+| | SimpleTable | DataTable |
+|---|---|---|
+| **Sorting** | Manual | Built-in |
+| **Filtering / Search** | Manual | Built-in |
+| **Pagination** | Manual | Built-in |
+| **Selection** | No | Yes |
+| **Server-side** | Manual | Built-in |
+| **Use when** | Small static or observable list | Large dataset with sort/filter/pagination |
+
+See **[DataTable](./data-table.md)** for the full-featured alternative.
+
+
+---
+
+## Theming
+
+```css
+:root {
+    --simple-table-font-size:       var(--description-size);
+    --simple-table-cell-padding-v:  var(--space-cozy);
+    --simple-table-cell-padding-h:  var(--space-comfortable);
+    --simple-table-border-color:    var(--color-border-tertiary);
+    --simple-table-header-color:    var(--color-text-secondary);
+    --simple-table-header-bg:       var(--color-background-secondary);
+    --simple-table-header-weight:   600;
+    --simple-table-hover-bg:        var(--color-background-secondary);
+    --simple-table-empty-color:     var(--color-text-secondary);
+}
+```

package/docs/components/skeleton.md

@@ -0,0 +1,155 @@
+---
+title: Skeleton
+description: Placeholder that mimics content shape while loading
+---
+
+# Skeleton
+
+```javascript
+import { Skeleton } from 'native-document/components';
+
+Skeleton(props?)
+```
+
+A placeholder that mimics the shape of content while it loads.
+
+## Default Renderer
+
+```javascript
+import { SkeletonRender } from 'native-document/ui';
+
+Skeleton.use(SkeletonRender);
+```
+
+## `$description`
+
+```javascript
+{
+    type:             'rect',    // 'rect' | 'circle' | 'text' | 'avatar' | 'image'
+    variant:          'pulse',   // 'pulse' | 'wave'
+    borderRadiusType: 'rounded',
+    lines:            null,      // number - for text type
+    width:            null,
+    height:           null,
+    loading:          null,      // Observable<boolean>
+    repeat:           null,      // number - repeat N times
+    props:            {} // HTML attributes for the root element
+}
+```
+
+## Methods
+
+```javascript
+// Type
+.rect()
+    .circle()
+    .text(lines?)
+    .avatar()
+    .image()
+
+    // Animation
+    .pulse()
+    .wave()
+
+    // Size
+    .width(200)
+    .height(100)
+    .size(width, height)
+
+    // Shape
+    .rounded()
+    .pill()
+    .smooth()
+
+    // Options
+    .lines(3)
+    .repeat(4)
+    .loading(isLoading)
+```
+
+## Built-in Presets
+
+Skeleton ships with four ready-to-use presets:
+
+### `Skeleton.card(type?)`
+
+A card with an image area and text lines below:
+
+```javascript
+Skeleton.card()
+Skeleton.card('featured') // adds type as extra CSS class
+```
+
+### `Skeleton.list(items?)`
+
+A list of rows with avatar and text lines. Default: 3 items:
+
+```javascript
+Skeleton.list()
+Skeleton.list(5)
+```
+
+### `Skeleton.table(rows?, cols?)`
+
+A table with a header row and data rows. Default: 5 rows, 4 cols:
+
+```javascript
+Skeleton.table()
+Skeleton.table(10, 6)
+```
+
+### `Skeleton.paragraph(lines?)`
+
+A block of text lines. Default: 3 lines:
+
+```javascript
+Skeleton.paragraph()
+Skeleton.paragraph(5)
+```
+
+---
+
+## Custom Presets
+
+Register your own reusable shapes with `Skeleton.preset()` or `Skeleton.presets()`:
+
+```javascript
+Skeleton.preset('userRow', (skeleton) => {
+    return skeleton.avatar().circle().size(40, 40);
+});
+
+// Register multiple at once
+Skeleton.presets({
+    title:   (s) => s.rect().width(200).height(24).rounded(),
+    avatar:  (s) => s.circle().size(48, 48),
+});
+
+// Usage
+Skeleton.userRow()
+Skeleton.title()
+```
+
+## Example
+
+```javascript
+ShowIf(isLoading, () =>
+    VStack([
+        Skeleton().avatar().circle().size(48, 48),
+        Skeleton().text(3)
+    ]).spacing(8)
+)
+```
+
+---
+
+## Theming
+
+```css
+:root {
+    --skeleton-color:          var(--gray-lite-4);
+    --skeleton-highlight:      var(--gray-lite-5);
+    --skeleton-radius:         var(--radius-button);
+    --skeleton-wave-duration:  1.6s;
+    --skeleton-pulse-duration: 1.2s;
+}
+```

package/docs/components/spinner.md

@@ -0,0 +1,100 @@
+---
+title: Spinner
+description: Loading indicator with multiple types, sizes, and overlay support
+---
+
+# Spinner
+
+```javascript
+import { Spinner } from 'native-document/components';
+
+Spinner(props?)
+```
+
+A loading indicator.
+
+## Default Renderer
+
+```javascript
+import { SpinnerRender } from 'native-document/ui';
+
+Spinner.use(SpinnerRender);
+```
+
+## `$description`
+
+```javascript
+{
+    type:              'circle',  // 'circle' | 'dots' | 'bars' | 'pulse' | 'ring'
+    variant:           'primary',
+    color:             null,
+    size:              'small',   // 'xs' | 'small' | 'medium' | 'large'
+    label:             null,
+    labelPosition:     null,      // 'top' | 'bottom' | 'left' | 'right'
+    overlay:           null,
+    backdrop:          null,
+    fullScreenOverlay: null,
+    speed:             'normal',  // 'slow' | 'normal' | 'fast'
+    props:             {} // HTML attributes for the root element
+}
+```
+
+## Methods
+
+```javascript
+// Type
+.circle()
+.dots()
+.bars()
+.pulse()
+.ring()
+
+// Size
+.extraSmall()
+.small()
+.medium()
+.large()
+
+// Style
+.primary()
+.color('#3b82f6')
+.speed('fast')
+
+// Label
+.label('Loading...')
+.labelPosition('bottom')
+
+// Overlay
+.overlay()
+.fullScreenOverlay()
+```
+
+## Example
+
+```javascript
+ShowIf(isLoading, () => Spinner().large().label('Loading...'))
+```
+
+---
+
+## Theming
+
+```css
+:root {
+    --spinner-size-extra-small: 16px;
+    --spinner-size-small:       24px;
+    --spinner-size-medium:      36px;
+    --spinner-size-large:       48px;
+    --spinner-size-extra-large: 64px;
+    --spinner-speed-slow:       1.2s;
+    --spinner-speed-normal:     0.8s;
+    --spinner-speed-fast:       0.4s;
+    --spinner-thickness:        3px;
+    --spinner-color:            var(--color-primary);
+    --spinner-color-primary:    var(--color-primary);
+    --spinner-color-secondary:  var(--color-secondary-text);
+    --spinner-color-success:    var(--color-success);
+    --spinner-color-danger:     var(--color-danger);
+    --spinner-color-warning:    var(--color-warning);
+}
+```

package/docs/components/splitter.md

@@ -0,0 +1,133 @@
+---
+title: Splitter
+description: Resizable split panel layout with horizontal and vertical orientations
+---
+
+# Splitter
+
+```javascript
+import { Splitter, SplitterPanel, SplitterGutter } from 'native-document/components';
+```
+
+## Default Renderer
+
+```javascript
+import { SplitterRender, SplitterPanelRender, SplitterGutterRender } from 'native-document/ui';
+
+Splitter.use(SplitterRender);
+SplitterPanel.use(SplitterPanelRender);
+SplitterGutter.use(SplitterGutterRender);
+```
+
+---
+
+## `Splitter`
+
+### Methods
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.horizontal()` | - | Side-by-side layout (default) |
+| `.vertical()` | - | Stacked layout |
+| `.gutterSize(px)` | `px: number` | Width of the drag handle in px |
+| `.panel(content, options?, props?)` | `content: NdChild`, `options?: object` | Add a panel inline |
+| `.panels(panels)` | `panels: SplitterPanel[]` | Add multiple panels at once |
+| `.dynamic()` | - | Enable dynamic panel management (add/remove at runtime) |
+| `.removePanel(panel)` | `panel: SplitterPanel` | Remove a panel dynamically |
+| `.onResize(handler)` | `handler: (sizes) => void` | Fires on every resize |
+| `.onPanelAdd(handler)` | `handler: (panel) => void` | Fires when a panel is added dynamically |
+| `.onPanelRemove(handler)` | `handler: (panel) => void` | Fires when a panel is removed dynamically |
+
+The inline `options` object for `.panel(content, options)` accepts the same properties as `SplitterPanel` methods: `size`, `minSize`, `maxSize`, `collapsible`.
+
+---
+
+## `SplitterPanel`
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.content(element)` | `element: NdChild` | Panel content |
+| `.size(value)` | `value: string \| number` | Initial size (`'30%'`, `300`) |
+| `.minSize(px)` | `px: number` | Minimum size in px |
+| `.maxSize(px)` | `px: number` | Maximum size in px |
+| `.collapsible(enabled?)` | `enabled?: boolean` | Allow collapsing to 0 |
+| `.collapsed(val?)` | `val?: boolean` | Start collapsed |
+| `.resizable(enabled?)` | `enabled?: boolean` | Enable/disable resize for this panel |
+| `.fixed()` | - | Panel is not resizable and keeps its size |
+| `.data(data)` | `data: *` | Attach metadata to the panel |
+
+---
+
+## `SplitterGutter`
+
+The drag handle between panels. No extra methods - its appearance is controlled entirely by the renderer.
+
+---
+
+## Dynamic panels
+
+Use `.dynamic()` to add or remove panels at runtime. Track a panel reference to remove it later:
+
+```javascript
+const sidebar = SplitterPanel(SidebarContent)
+    .size('25%')
+    .minSize(150)
+    .collapsible();
+
+const splitter = Splitter()
+    .dynamic()
+    .panel(sidebar)
+    .panel(SplitterPanel(MainContent).size('75%'))
+    .onPanelAdd((panel) => console.log('Panel added'))
+    .onPanelRemove((panel) => console.log('Panel removed'));
+
+// Remove the sidebar later
+Button('Hide sidebar').nd.onClick(() => splitter.removePanel(sidebar))
+```
+
+---
+
+## Example
+
+```javascript
+Splitter()
+    .horizontal()
+    .gutterSize(4)
+    .panel(
+        SplitterPanel(FileExplorer)
+            .size('20%')
+            .minSize(150)
+            .collapsible()
+    )
+    .panel(
+        SplitterPanel(
+            Splitter()
+                .vertical()
+                .panel(CodeEditor, { size: '70%' })
+                .panel(Terminal,   { size: '30%', minSize: 100 })
+        ).size('80%')
+    )
+    .onResize((sizes) => savePanelSizes(sizes))
+```
+
+
+---
+
+## Theming
+
+```css
+:root {
+    --splitter-gutter-size:              1px;
+    --splitter-gutter-hit-area:          8px;
+    --splitter-gutter-color:             var(--gray-lite-3);
+    --splitter-gutter-handle-size:       32px;
+    --splitter-gutter-handle-color:      var(--gray-lite-2);
+    --splitter-gutter-handle-color-hover: var(--color-primary);
+}
+```
+
+---
+
+## Next Steps
+
+- **[Layout](./layout.md)** - Stack-based layout components