native-document 1.0.165 → 1.0.168

package/docs/components/menu.md

@@ -0,0 +1,215 @@
+---
+title: Menu
+description: Menu component with items, links, groups, dividers, keyboard navigation, and active state
+---
+
+# Menu
+
+```javascript
+import { Menu, MenuItem, MenuGroup, MenuLink, MenuDivider } from 'native-document/components';
+```
+
+## Default Renderer
+
+```javascript
+import {
+    MenuRender, MenuItemRender,
+    MenuGroupRender, MenuLinkRender, MenuDividerRender
+} from 'native-document/ui';
+
+Menu.use(MenuRender);
+MenuItem.use(MenuItemRender);
+MenuGroup.use(MenuGroupRender);
+MenuLink.use(MenuLinkRender);
+MenuDivider.use(MenuDividerRender);
+```
+
+## Methods
+
+### Orientation
+
+```javascript
+.horizontal()
+.vertical()
+.inline()
+```
+
+### Building items
+
+```javascript
+.item(label, options?)
+.item('Dashboard', { action: () => navigate('/'), icon: DashboardIcon, key: 'home' })
+
+// Function form - receives MenuItem instance
+.item('Settings', (item) => {
+    item.action(() => navigate('/settings'))
+        .icon(SettingsIcon)
+        .key('settings')
+        .shortcut('+,')
+})
+
+// Link item
+.link(label, options?)
+.link('Documentation', { href: 'https://docs.example.com', target: '_blank' })
+
+// Router link
+.linkTo(label, options?)
+.linkTo('Home', { href: 'home' })
+.linkTo('Profile', { href: { name: 'user', params: { id: 1 } } })
+
+// Separator
+.separator()
+.divider()  // alias
+
+// Group
+.group(label, (group) => {
+    group.item('Profile',  { action: () => navigate('/profile') })
+    group.item('Security', { action: () => navigate('/security') })
+    group.separator()
+    group.item('Logout',   { action: () => logout(), icon: LogoutIcon })
+})
+```
+
+### Active state
+
+```javascript
+.active(() => router.currentState().route?.name)      // callback
+.active(currentRoute.select(r => r.name))             // observable
+```
+
+### Behavior
+
+```javascript
+.closeOnSelect(false)
+.keyboardLoop(false)
+.clickFirst()
+.compactThreshold(80)
+```
+
+### Dynamic items
+
+```javascript
+.bind(observableArray)
+```
+
+### Events
+
+```javascript
+.onItemClick((item)  => console.log('Clicked:', item.label))
+.onItemSelect((item) => console.log('Selected:', item.key))
+```
+
+## Example - Sidebar Navigation
+
+```javascript
+Menu()
+    .vertical()
+    .active(router.currentState().select(s => s.route?.name))
+    .item('Dashboard', { action: () => Router.push('/'),      icon: HomeIcon,     key: 'home' })
+    .item('Users',     { action: () => Router.push('/users'), icon: UsersIcon,    key: 'users' })
+    .separator()
+    .group('Settings', (group) => {
+        group.item('General',  { action: () => Router.push('/settings'),          key: 'settings' })
+        group.item('Security', { action: () => Router.push('/settings/security'), key: 'security' })
+    })
+    .separator()
+    .item('Logout', { action: () => logout(), icon: LogoutIcon, key: 'logout' })
+```
+
+## Example - Top Navigation
+
+```javascript
+Menu()
+    .horizontal()
+    .linkTo('Home',     { href: 'home' })
+    .linkTo('Products', { href: 'products' })
+    .linkTo('Pricing',  { href: 'pricing' })
+    .link('Docs', { href: 'https://docs.example.com', target: '_blank' })
+```
+
+---
+
+## `MenuItem`
+
+```javascript
+MenuItem()
+    .label('Dashboard')
+    .icon(DashboardIcon)
+    .key('dashboard')
+    .action(() => navigate('/dashboard'))
+    .shortcut('+D')
+    .disabled(Observable(false))
+    .selected(Observable(false))
+    .trailing(Badge('New').success())
+```
+
+See **[ShortcutManager](./shortcut-manager.md)** for the shortcut convention.
+
+---
+
+## `MenuGroup`
+
+```javascript
+MenuGroup('Settings')
+    .icon(SettingsIcon)
+    .collapsable()
+    .collapsed(true)
+    .item('Profile',  { action: () => navigate('/profile') })
+    .item('Security', { action: () => navigate('/security') })
+    .divider()
+    .item('Logout', { action: logout })
+```
+
+---
+
+## `MenuLink`
+
+Extends `MenuItem` with a `.target()` method:
+
+```javascript
+MenuLink()
+    .label('Documentation')
+    .icon(BookIcon)
+    .action('https://docs.example.com')
+    .target('_blank')
+```
+
+---
+
+## `MenuDivider`
+
+```javascript
+MenuDivider()
+// or via shorthand:
+menu.separator()
+```
+
+---
+
+## Theming
+
+```css
+:root {
+    --menu-bg:                  var(--background);
+    --menu-border:              var(--gray-lite-3);
+    --menu-radius:              var(--radius-card);
+    --menu-shadow:              var(--shadow-md);
+    --menu-font-size:           var(--description-size);
+    --menu-gap:                 var(--space-tiny);
+    --menu-padding:             var(--space-cozy) 0;
+    --menu-item-padding:        var(--space-cozy) var(--space-comfortable);
+    --menu-item-radius:         var(--radius-button);
+    --menu-item-gap:            var(--space-cozy);
+    --menu-item-color:          var(--text-color);
+    --menu-item-color-hover:    var(--text-color);
+    --menu-item-color-active:   var(--color-primary);
+    --menu-item-color-disabled: var(--gray-lite-2);
+    --menu-item-bg-hover:       var(--gray-lite-5);
+    --menu-group-label-size:    var(--hint-size);
+    --menu-group-label-color:   var(--gray);
+    --menu-shortcut-size:       var(--note-size);
+    --menu-shortcut-color:      var(--gray);
+    --menu-divider-color:       var(--gray-lite-3);
+    --sub-menu-shadow:          var(--shadow-lg);
+}
+```

package/docs/components/modal.md

@@ -0,0 +1,156 @@
+---
+title: Modal
+description: Modal dialog with draggable and resizable support
+---
+
+# Modal
+
+```javascript
+import { Modal } from 'native-document/components';
+```
+
+## Default Renderers
+
+```javascript
+import { ModalRender } from 'native-document/ui';
+
+Modal.use(ModalRender);
+```
+
+---
+
+## `Modal`
+
+```javascript
+Modal(content, props?)
+```
+
+### `$description`
+
+```javascript
+{
+    content:         null,
+    title:           null,
+    footer:          null,
+    size:            null,       // 'small' | 'medium' | 'large' | 'xl'
+    centered:        true,
+    scrollable:      false,
+    closeOnBackdrop: true,
+    closeOnEscape:   true,
+    closable:        true,
+    fullscreen:      false,
+    draggable:       false,
+    resizable:       false,
+    focusTrap:       true,
+    lockScroll:      true,
+    isOpen:          Observable(false),
+    props:           {} // HTML attributes for the root element
+}
+```
+
+### Methods
+
+```javascript
+// Content
+.title('Confirm deletion')
+.content(Div('Are you sure?'))
+.footer(
+    HStack([
+        Button('Cancel').ghost().nd.onClick(() => modal.close()),
+        Button('Delete').danger().nd.onClick(() => confirmDelete())
+    ]).justifyEnd().spacing(8)
+)
+
+// Size
+.small()
+.medium()
+.large()
+.extraLarge()
+.fullscreen()
+
+// Behavior
+.centered()
+.scrollable()
+.closeOnBackdrop(false)
+.closeOnEscape(false)
+.closable(false)
+.focusTrap(false)
+.lockScroll(false)
+
+// Draggable & Resizable
+.draggable()
+.resizable()
+.resizable(true, { size: { minWidth: 300, minHeight: 200 } })
+
+// Programmatic
+.open()
+.close()
+.toggle()
+
+// Events
+.onOpen(()        => console.log('Opened'))
+.onClose(()       => console.log('Closed'))
+.onBeforeOpen(()  => console.log('About to open'))
+.onBeforeClose(() => console.log('About to close'))
+
+// Custom renderers
+.renderHeader(($description) => Div({ class: 'modal-header' }, $description.title))
+.renderContent(($description) => Div({ class: 'modal-body' }, $description.content))
+.renderFooter(($description) => Div({ class: 'modal-footer' }, $description.footer))
+```
+
+### Example
+
+```javascript
+Modal(
+    Div([
+        P('This action cannot be undone.'),
+        P('All associated data will be permanently removed.')
+    ])
+)
+.title('Delete Account')
+.footer(
+    HStack([
+        Button('Cancel').ghost().nd.onClick(() => deleteModal.close()),
+        Button('Yes, delete').danger().nd.onClick(async () => {
+            await deleteAccount();
+            deleteModal.close();
+        })
+    ]).justifyEnd().spacing(8)
+)
+.small()
+.onOpen(() => trackEvent('delete_modal_open'))
+.trigger(
+    Button('Delete account')
+        .danger()
+)
+```
+
+---
+
+## Theming
+
+```css
+:root {
+    --modal-bg:                   var(--white);
+    --modal-border:               var(--gray-lite-5);
+    --modal-radius:               var(--radius-card);
+    --modal-shadow:               var(--shadow-lg);
+    --modal-z-index:              10001;
+    --modal-font-size:            var(--description-size);
+    --modal-header-size:          var(--text-size);
+    --modal-header-weight:        600;
+    --modal-padding:              var(--space-comfortable);
+    --modal-header-padding:       var(--space-tiny);
+    --modal-animation-duration:   0.2s;
+    --modal-width-small:          400px;
+    --modal-width-medium:         560px;
+    --modal-width-large:          720px;
+    --modal-width-extra-large:    960px;
+    --modal-backdrop-bg:          rgba(0, 0, 0, 0.8);
+    --modal-close-width:          25px;
+    --modal-close-height:         25px;
+    --modal-close-hover-bg-color: var(--contrasted-red);
+    --modal-close-hover-color:    var(--white);
+}
+```

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