native-document 1.0.16 → 1.0.17-1.2

package/docs/components/layout.md

@@ -0,0 +1,279 @@
+---
+title: Layout Components
+description: Stack, HStack, VStack, AbsoluteStack, FixedStack, RelativeStack - flexible layout building blocks
+---
+
+# Layout Components
+
+Layout components provide flexible, semantic containers for building UI structure.
+
+```javascript
+import { HStack, VStack, Row, Col, AbsoluteStack, FixedStack, RelativeStack, Divider } from 'native-document/components';
+import { Stack } from 'native-document/components'; // only needed to register the renderer
+```
+
+---
+
+## `Stack` - Abstract Base
+
+`Stack` is the abstract base class for all layout components. Do not use it directly - use `HStack`, `VStack`, `Row`, or `Col` instead.
+
+All stack variants share the same `$description` structure and methods:
+
+### `$description`
+
+```javascript
+{
+    orientation:    'horizontal', // 'horizontal' | 'vertical'
+        content:        [],
+        spacing:        null,         // string | number
+        alignment:      'center',     // 'leading' | 'center' | 'trailing' | 'stretch'
+        justifyContent: 'between',    // 'start' | 'center' | 'end' | 'between' | 'around'
+        wrap:           false,
+        grow:           false,
+        shrink:         false,
+        reverse:        false,
+        props:          {}
+}
+```
+
+### Methods
+
+```javascript
+// Spacing
+.spacing(8)
+
+    // Alignment
+    .alignLeading()     // alignment: 'leading'
+    .alignCenter()      // alignment: 'center'
+    .alignTrailing()    // alignment: 'trailing'
+    .alignStretch()     // alignment: 'stretch'
+
+    // Justify
+    .justifyStart()
+    .justifyCenter()
+    .justifyEnd()
+    .justifyBetween()
+    .justifyAround()
+
+    // Combined
+    .center()           // alignCenter() + justifyCenter()
+
+    // Other
+    .wrap()
+    .grow()
+    .shrink()
+    .reverse()
+```
+
+### Renderer
+
+Each variant needs its own renderer registered separately:
+
+```javascript
+import { HStack, VStack } from 'native-document/components';
+import { HStackRender, VStackRender } from 'native-document/ui';
+
+HStack.use(HStackRender);
+VStack.use(VStackRender);
+// Row and Col share HStack and VStack renderers automatically
+```
+
+Or write your own:
+
+```javascript
+HStack.use(($description) => {
+    return Div({
+        class: buildStackClasses($description),
+        style: $description.spacing ? { gap: $description.spacing + 'px' } : {},
+        ...$description.props
+    }, $description.content);
+});
+```
+
+---
+
+## `HStack` - Horizontal Stack
+
+Alias for `Stack` with `orientation: 'horizontal'`. Also available as `Row`.
+
+```javascript
+HStack([
+    Avatar(user.avatar),
+    Div(user.name)
+]).alignCenter().spacing(12)
+
+// Row is an alias for HStack
+Row([
+    Button('Cancel').ghost(),
+    Button('Save').primary()
+]).justifyEnd().spacing(8)
+```
+
+---
+
+## `VStack` - Vertical Stack
+
+`Stack` with `orientation: 'vertical'` and `alignment: 'leading'` by default. Also available as `Col`.
+
+```javascript
+VStack([
+    H2('Title'),
+    P('Description'),
+    Button('Action').primary()
+]).spacing(16).alignStretch()
+
+// Col is an alias for VStack
+Col([Label('Name'), Input({ value: name })]).spacing(4)
+```
+
+---
+
+## `AbsoluteStack` / `FixedStack` / `RelativeStack` - Positioned Containers
+
+All three extend `PositionStack` and share the same API. They differ only in CSS `position`:
+
+| Component | CSS position |
+|---|---|
+| `AbsoluteStack` | `absolute` |
+| `FixedStack` | `fixed` |
+| `RelativeStack` | `relative` |
+
+### `$description`
+
+```javascript
+{
+    position: 'absolute', // 'absolute' | 'fixed' | 'relative'
+        content:  [],
+        top:      null,  // string | number
+        right:    null,
+        bottom:   null,
+        left:     null,
+        width:    null,
+        height:   null,
+        zIndex:   null,
+        anchor:   null,  // preset anchor shorthand
+        props:    {}
+}
+```
+
+### Methods
+
+```javascript
+AbsoluteStack(Div('Tooltip'))
+    .top(0)
+    .right(0)
+    .width(200)
+    .height(100)
+    .zIndex(50)
+
+    // Size helpers
+    .fullWidth()        // width: '100%'
+    .fullHeight()       // height: '100%'
+    .fullSize()         // width + height: '100%'
+    .size(200, 100)     // width: 200, height: 100
+    .size(200)          // width: 200, height: 200
+
+    // Z-index helpers
+    .above(100)         // zIndex: 100
+    .below()            // zIndex: -1
+
+    // Anchor presets (position combinations)
+    .fill()             // anchor: 'fill'
+    .topLeading()       // anchor: 'top-leading'
+    .atTopCenter()      // anchor: 'top-center'
+    .atTopTrailing()    // anchor: 'top-trailing'
+    .atCenterLeading()  // anchor: 'center-leading'
+    .atCenter()         // anchor: 'center'
+    .atCenterTrailing() // anchor: 'center-trailing'
+    .atBottomLeading()  // anchor: 'bottom-leading'
+    .atBottomCenter()   // anchor: 'bottom-center'
+    .atBottomTrailing() // anchor: 'bottom-trailing'
+```
+
+### Example
+
+```javascript
+// Floating action button
+const fab = FixedStack(
+    Button(PlusIcon).circle().primary()
+)
+    .atBottomTrailing()
+    .right(24)
+    .bottom(24)
+    .above(100)
+
+// Overlay badge
+const badge = AbsoluteStack(Span('3'))
+    .atTopTrailing()
+    .top(-8)
+    .right(-8)
+```
+
+---
+
+## `Divider`
+
+A horizontal or vertical separator, optionally with a label.
+
+```javascript
+Divider(label?, props?)
+```
+
+### `$description`
+
+```javascript
+{
+    label:       null,      // string | null
+        orientation: 'horizontal', // 'horizontal' | 'vertical'
+        props:       {}
+}
+```
+
+### Methods
+
+```javascript
+Divider()           // horizontal, no label
+Divider('OR')       // with label
+Divider().vertical() // vertical
+
+    .orientation('vertical')
+    .vertical()
+    .horizontal()
+```
+
+### Example
+
+```javascript
+VStack([
+    Input({ placeholder: 'Email', value: email }),
+    Input({ placeholder: 'Password', type: 'password', value: password }),
+    Button('Sign in').primary().block(),
+    Divider('OR'),
+    Button('Continue with Google').ghost().block()
+]).spacing(16)
+```
+
+
+---
+
+## Theming
+
+```css
+:root {
+    --divider-color:          var(--gray-lite-3);
+    --divider-label-color:    var(--gray);
+    --divider-label-size:     var(--note-size);
+    --divider-label-gap:      var(--space-comfortable);
+    --divider-thickness:      1px;
+    --divider-spacing:        16px;
+}
+```
+
+---
+
+## Next Steps
+
+- **[Getting Started](./getting-started.md)** - Register renderers
+- **[Button](./button.md)** - Button component
+- **[Modal](./modal.md)** - Modal with draggable and resizable

package/docs/components/list.md

@@ -0,0 +1,73 @@
+---
+title: List
+description: Flexible list component with single/multi selection, checkbox or click-to-select modes, dividers, and keyboard navigation
+---
+
+# List
+
+> **Status: coming soon.** The `List` API is fully defined but the default renderer is not yet implemented. You can use `List` today by providing your own renderer via `List.use()`.
+
+```javascript
+import { List } from 'native-document/components';
+
+List(props?)
+```
+
+## Custom Renderer
+
+Until the default renderer ships, register your own:
+
+```javascript
+import { Ul, Li } from 'native-document/elements';
+
+List.use({
+    list: ($d, instance) => {
+        return Ul({ class: `list ${$d.inset ? 'list-inset' : ''}` });
+    }
+});
+```
+
+> `List.use()` expects an object with a `list` key, not a function directly.
+
+## Methods
+
+### Data
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.items(items)` | `items: *[]` | Static item list |
+| `.dynamic(obs?)` | `obs?: ObservableArray` | Bind to a reactive array |
+| `.data(data)` | `data: *` | Data passed to the renderer |
+
+### Selection
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.selectable(enabled?)` | `enabled?: boolean` | Enable item selection |
+| `.multiSelect(enabled?)` | `enabled?: boolean` | Allow multiple selections. Enables `.selectable()` automatically |
+| `.selectByClick()` | - | Select items on click (mutually exclusive with `selectByCheckbox`) |
+| `.selectByCheckbox()` | - | Select items via a checkbox (mutually exclusive with `selectByClick`) |
+| `.selectedValuesModel(obs)` | `obs: Observable<*[]>` | Bind selected values to an external observable |
+
+### Layout
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.withDivider(enabled?)` | `enabled?: boolean` | Show a divider between items |
+| `.inset(enabled?)` | `enabled?: boolean` | Add inset padding |
+| `.loopOnKeyboard(enabled)` | `enabled: boolean` | Loop keyboard navigation at list boundaries. Default `true` |
+
+### Events
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.onItemClick(handler)` | `handler: (item, event) => void` | Fires when an item is clicked |
+| `.onItemSelect(handler)` | `handler: (item) => void` | Fires when an item is selected |
+
+---
+
+## Next Steps
+
+- **[Components Overview](./index.md)** - BaseComponent and renderer pattern
+- **[Getting Started](./getting-started.md)** - Register default renderers
+- **[Traits](./traits.md)** - `HasItems` trait used by this component

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