native-document 1.0.166 → 1.0.169

package/docs/components/pagination.md

@@ -0,0 +1,95 @@
+---
+title: Pagination
+description: Standalone pagination component with first/last, ellipsis, and custom renderers
+---
+
+# Pagination
+
+```javascript
+import { Pagination } from 'native-document/components';
+
+Pagination(props?)
+```
+
+Standalone pagination. Also built into `DataTable`.
+
+## Default Renderer
+
+```javascript
+import { PaginationRender } from 'native-document/ui';
+
+Pagination.use(PaginationRender);
+```
+
+## Methods
+
+```javascript
+// State
+.currentPage(Observable(1))
+.totalPages(Observable(10))
+.totalItems(Observable(200))
+.pageSize(20)
+.disabled(Observable(false))
+
+// Display
+.siblingCount(1)      // pages shown around current page
+.boundaryCount(1)     // pages shown at start and end
+.showFirstLast()
+.showPreviousNext()
+
+// Navigation (programmatic)
+.goToPage(3)
+.next()
+.previous()
+.first()
+.last()
+.hasNext()
+.hasPrevious()
+
+// Events
+.onPageChange((page) => fetchData(page))
+.onChange((page) => fetchData(page))  // alias
+
+// Custom renderers
+.renderPage(($page) => Button($page.label))
+.renderEllipsis(() => Span('...'))
+.renderPrevious(() => Span('Prev'))
+.renderNext(() => Span('Next'))
+.renderFirst(() => Span('First'))
+.renderLast(() => Span('Last'))
+```
+
+## Example
+
+```javascript
+const page  = Observable(1);
+const total = Observable(50);
+
+Pagination()
+    .currentPage(page)
+    .totalPages(total)
+    .siblingCount(2)
+    .showFirstLast()
+    .onPageChange((p) => {
+        page.set(p);
+        fetchUsers(p);
+    })
+```
+
+---
+
+## Theming
+
+```css
+:root {
+    --pagination-gap:       var(--space-cozy);
+    --pagination-font-size: var(--description-size);
+    --page-size:            36px;
+    --page-radius:          var(--radius-button);
+    --page-color:           var(--text-color);
+    --page-bg-hover:        var(--gray-lite-5);
+    --page-bg-active:       var(--color-primary);
+    --page-color-active:    var(--white);
+    --page-color-disabled:  var(--gray-lite-2);
+}
+```

package/docs/components/popover.md

@@ -0,0 +1,131 @@
+---
+title: Popover
+description: Floating panel anchored to a trigger element with flexible positioning and interaction modes
+---
+
+# Popover
+
+```javascript
+import { Popover } from 'native-document/components';
+
+Popover(content, props?)
+```
+
+A floating panel anchored to a trigger element. Lighter than Modal - no overlay, positions relative to trigger.
+
+## Default Renderer
+
+```javascript
+import { PopoverRender } from 'native-document/ui';
+
+Popover.use(PopoverRender);
+```
+
+## `$description`
+
+```javascript
+{
+    content:             null,
+    header:              null,
+    footer:              null,
+    trigger:             null,
+    interaction:         'click',   // 'click' | 'hover' | 'focus'
+    position:            'bottom',
+    offset:              [0, 8],
+    arrow:               false,
+    shift:               false,
+    closeOnEscape:       true,
+    closeOnClickOutside: true,
+    focusTrap:           false,
+    returnFocus:         true,
+    matchTriggerWidth:   null,
+    updatePositionOn:    null,
+    isOpen:              Observable(false),
+    props:               {}
+}
+```
+
+## Methods
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.content(element)` | `element: NdChild` | Popover body |
+| `.header(element)` | `element: NdChild` | Popover header |
+| `.footer(element)` | `element: NdChild` | Popover footer |
+| `.trigger(element)` | `element: HTMLElement` | Element that opens the popover |
+| `.onClicked()` | - | Open on click (default) |
+| `.onHovered()` | - | Open on hover |
+| `.onFocused()` | - | Open on focus |
+| `.position(pos)` | `pos: string` | Position relative to trigger: `top`, `bottom`, `left`, `right`, `top-start`, `bottom-end`, etc. |
+| `.offset([x, y])` | `[x: number, y: number]` | Offset from trigger in px |
+| `.arrow()` | - | Show arrow pointing to trigger |
+| `.shift()` | - | Keep popover in viewport when near edges |
+| `.closeOnEscape(enabled)` | `enabled: boolean` | Default `true` |
+| `.closeOnClickOutside(enabled)` | `enabled: boolean` | Default `true` |
+| `.focusTrap()` | - | Trap focus inside the popover |
+| `.returnFocus(enabled)` | `enabled: boolean` | Return focus to trigger on close. Default `true` |
+| `.matchTriggerWidth()` | - | Set popover width to match the trigger width |
+| `.updatePositionOn(observable)` | `observable: Observable` | Recalculate position when the observable changes |
+| `.open()` | - | Open programmatically |
+| `.close()` | - | Close programmatically |
+| `.toggle()` | - | Toggle open/close |
+
+## Example
+
+```javascript
+Popover(
+    VStack([
+        Avatar(user.avatar).medium(),
+        Div(user.name),
+        Div(user.email),
+        Divider(),
+        Button('View profile')
+            .ghost()
+            .block()
+            .nd.onClick(() => {
+                userPopover.close();
+                Router.push({ name: 'profile' });
+            })
+    ]).spacing(8)
+)
+.position('bottom-end')
+.arrow()
+.trigger(Button('Show Profile').warning())
+```
+
+---
+
+## Tooltip vs Popover
+
+| | Tooltip | Popover |
+|---|---|---|
+| **Purpose** | Short contextual hint | Rich floating panel |
+| **Content** | Text or simple element | Header, body, footer |
+| **Triggered by** | Hover (default) | Click (default) |
+| **Focus trap** | No | Optional |
+| **Use when** | Labeling an icon, short help text | User profile card, settings panel |
+
+See **[Tooltip](./tooltip.md)** for the lightweight alternative.
+
+
+---
+
+## Theming
+
+```css
+:root {
+    --popover-bg:               var(--background);
+    --popover-border:           var(--gray-lite-3);
+    --popover-radius:           var(--radius-card);
+    --popover-shadow:           var(--shadow-lg);
+    --popover-padding:          0;
+    --popover-min-width:        200px;
+    --popover-max-width:        320px;
+    --popover-z-index:          100001;
+    --popover-font-size:        var(--description-size);
+    --popover-header-size:      var(--text-size);
+    --popover-header-weight:    600;
+    --popover-arrow-size:       8px;
+    --popover-animation-duration: 0.15s;
+}
+```

package/docs/components/progress.md

@@ -0,0 +1,111 @@
+---
+title: Progress
+description: Progress bar and circular progress indicator
+---
+
+# Progress
+
+```javascript
+import { Progress } from 'native-document/components';
+
+Progress(props?)
+```
+
+## Default Renderer
+
+```javascript
+import { ProgressRender } from 'native-document/ui';
+
+Progress.use(ProgressRender);
+```
+
+## `$description`
+
+```javascript
+{
+    value:            null,   // number | Observable<number>
+    type:             null,   // 'linear' | 'circular'
+    variant:          null,
+    max:              100,
+    size:             null,
+    stroke:           null,   // circular stroke width
+    height:           null,   // linear height
+    showValue:        null,
+    showPercentage:   null,
+    label:            null,
+    format:           null,   // (value, max) => string
+    indeterminate:    null,
+    striped:          null,
+    animated:         null,
+    borderRadiusType: null,
+    props:            {}
+}
+```
+
+## Methods
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.value(val)` | `val: number \| Observable<number>` | Current value |
+| `.max(val)` | `val: number` | Maximum value. Default `100` |
+| `.type(type)` | `'linear' \| 'circular'` | Progress type |
+| `.primary()` | - | Primary color variant |
+| `.success()` | - | Success color variant |
+| `.danger()` | - | Danger color variant |
+| `.warning()` | - | Warning color variant |
+| `.size(size)` | `'small' \| 'large'` | Size preset |
+| `.height(px)` | `px: number` | Height in px (linear) |
+| `.stroke(px)` | `px: number` | Stroke width in px (circular) |
+| `.showValue()` | - | Display the numeric value |
+| `.showPercentage()` | - | Display the percentage |
+| `.label(text)` | `text: string` | Label beside the bar |
+| `.format(fn)` | `fn: (value, max) => string` | Custom value formatter |
+| `.indeterminate()` | - | Indeterminate animation (no known value) |
+| `.striped()` | - | Striped style |
+| `.animated()` | - | Animate the stripes |
+| `.rounded()` | - | Rounded border radius |
+| `.pill()` | - | Pill border radius |
+| `.onComplete(handler)` | `handler: () => void` | Fires once when value reaches max |
+
+## Example
+
+```javascript
+const progress = Observable(0);
+
+Progress()
+    .value(progress)
+    .primary()
+    .showPercentage()
+    .striped()
+    .animated()
+    .onComplete(() => {
+        Toast('Upload complete!').success().show();
+    })
+```
+
+
+---
+
+## Theming
+
+```css
+:root {
+    --progress-height-small:             4px;
+    --progress-height-medium:            8px;
+    --progress-height-large:             14px;
+    --progress-color:                    var(--gray-lite-4);
+    --progress-color-primary:            var(--color-primary);
+    --progress-color-secondary:          var(--color-secondary);
+    --progress-color-success:            var(--color-success);
+    --progress-color-danger:             var(--color-danger);
+    --progress-color-warning:            var(--color-warning);
+    --progress-color-info:               var(--color-info);
+    --progress-circle-size:              80px;
+    --progress-circle-thickness:         6px;
+    --progress-label-size:               var(--note-size);
+    --progress-label-color:              var(--gray);
+    --progress-stripe-size:              20px;
+    --progress-animation-duration:       1s;
+    --progress-indeterminate-duration:   1.5s;
+}
+```

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);
+}
+```