native-document 1.0.166 → 1.0.169

package/docs/components/tabs.md

@@ -0,0 +1,153 @@
+---
+title: Tabs
+description: Tabs component with sortable tabs, closable tabs, overflow handling, and flexible navigation positioning
+---
+
+# Tabs
+
+```javascript
+import { Tabs } from 'native-document/components';
+
+Tabs(props?)
+```
+
+## Default Renderer
+
+```javascript
+import { TabsRender } from 'native-document/ui';
+
+Tabs.use(TabsRender);
+```
+
+## `$description`
+
+```javascript
+{
+    active:               Observable(''),
+    tabs:                 {},
+    sortable:             false,
+    tabAppearance:        'segmented', // 'segmented' | 'pills' | 'underline'
+    stickyHeader:         false,
+    overflow:             'scroll',    // 'scroll' | 'menu'
+    navigationBarPosition:'top',
+    tabsAlignment:        'leading',   // 'leading' | 'trailing' | 'center' | 'justified'
+    closable:             false,
+    focusOnNewTab:        false,
+    props:                {} // HTML attributes for the root element
+}
+```
+
+## Methods
+
+### Building tabs
+
+```javascript
+.tab(label, content, key?)
+.tabWithIcon(icon, label, content, key?)
+
+.tab('Overview', OverviewPanel, 'overview')
+.tabWithIcon(HomeIcon, 'Dashboard', DashboardPanel, 'dashboard')
+
+.tabs([
+    { key: 'home',    label: 'Home',    content: HomePanel },
+    { key: 'profile', label: 'Profile', content: ProfilePanel }
+])
+
+.addTab(null, 'New Tab', EmptyPanel, 'tab-1')
+.closeTab('settings')
+
+.active('overview')
+.active(Observable('overview'))
+```
+
+### Appearance
+
+```javascript
+.pills()
+.segmented()
+.underline()
+```
+
+### Navigation position
+
+```javascript
+.navigationBarAtTop()
+.navigationBarAtLeft()
+.navigationBarAtRight()
+.navigationBarAsDock()
+```
+
+### Alignment
+
+```javascript
+.tabsAtLeading()
+.tabsAtTrailing()
+.tabsAtCenter()
+.tabsJustified()
+```
+
+### Behavior
+
+```javascript
+.sortable()
+.closable()
+.stickyHeader()
+.focusOnNewTab()
+.overflow('scroll')
+.overflow('menu')
+.addPlusButton((tabs) => {
+    const key = `tab-${Date.now()}`;
+    tabs.addTab(null, 'New Tab', EmptyPanel, key);
+})
+```
+
+### Events
+
+```javascript
+.onChange((key)         => loadTabContent(key))
+.onClickTab((key)       => console.log('Clicked:', key))
+.onCloseTab((key)       => confirmClose(key))
+.onBeforeTabClose((key) => confirm('Close this tab?'))
+.onAddTab((key)         => console.log('Tab added:', key))
+```
+
+### Custom renderers
+
+```javascript
+.renderTab(($tab) => HStack([$tab.icon, Span($tab.label)]).spacing(4))
+.renderCloseButton(() => Span('x'))
+.renderPlusButton(() => Span('+'))
+```
+
+## Example
+
+```javascript
+Tabs()
+    .tabWithIcon(HomeIcon,     'Dashboard', DashboardPanel,  'dashboard')
+    .tabWithIcon(UsersIcon,    'Users',     UsersPanel,      'users')
+    .tabWithIcon(SettingsIcon, 'Settings',  SettingsPanel,   'settings')
+    .active('dashboard')
+    .tabsJustified()
+    .stickyHeader()
+    .onChange((key) => Router.push({ name: key }))
+```
+
+---
+
+## Theming
+
+```css
+:root {
+    --tabs-border:              var(--gray-lite-3);
+    --tabs-radius:              var(--radius-button);
+    --tabs-font-size:           var(--description-size);
+    --tabs-font-weight:         500;
+    --tab-padding:              var(--space-cozy) var(--space-comfortable);
+    --tab-color:                var(--gray);
+    --tab-color-active:         var(--color-primary);
+    --tab-color-hover:          var(--text-color);
+    --tab-bg-hover:             var(--gray-lite-5);
+    --tab-indicator-height:     2px;
+    --tabs-content-padding:     var(--space-comfortable) 0;
+}
+```

package/docs/components/toast.md

@@ -0,0 +1,119 @@
+---
+title: Toast
+description: Toast notification component with auto-dismiss, actions, and positioning
+---
+
+# Toast
+
+```javascript
+import { Toast } from 'native-document/components';
+
+Toast(content, props?)
+```
+
+## Default Renderer
+
+```javascript
+import { ToastRender } from 'native-document/ui';
+import { ButtonRender } from 'native-document/ui';
+
+Toast.use(ToastRender);
+Button.use(ButtonRender); // required - actions are rendered as buttons
+```
+
+## `$description`
+
+```javascript
+{
+    visibility:   Observable(true),
+    type:         null,          // 'info' | 'success' | 'warning' | 'error'
+    title:        null,
+    content:      null,
+    icon:         null,
+    showIcon:     true,
+    duration:     5000,          // ms, 0 = no auto-dismiss
+    closable:     true,
+    pauseOnHover: true,
+    position:     'top-trailing',
+    actions:      [],
+    props:        {} // HTML attributes for the root element
+}
+```
+
+## Methods
+
+```javascript
+// Type
+.info()
+.success()
+.warning()
+.error()
+
+// Content
+.title('Saved!')
+.content(Div('Your changes have been saved.'))
+.icon(CheckIcon)
+.showIcon(false)
+
+// Behavior
+.duration(3000)
+.duration(0)          // no auto-dismiss
+.closable(false)
+.pauseOnHover(false)
+
+// Position
+.atTopLeading()
+.atTopTrailing()      // default
+.atTopCenter()
+.atBottomLeading()
+.atBottomTrailing()
+.atBottomCenter()
+
+// Actions
+.action('Undo', () => undo())
+.action('Retry', retry)
+
+// Programmatic
+.close()
+
+// Events
+.onClose(() => console.log('Dismissed'))
+```
+
+## Example
+
+```javascript
+const saveToast = Toast('Your changes have been saved.')
+    .success()
+    .title('Saved!')
+    .duration(3000)
+    .atTopTrailing()
+    .action('Undo', () => undoChanges())
+
+Button('Save')
+    .primary()
+    .nd.onClick(async () => {
+        await saveData();
+        saveToast.show()
+    })
+```
+
+---
+
+## Theming
+
+```css
+:root {
+    --toast-width:              320px;
+    --toast-padding:            var(--space-comfortable);
+    --toast-gap:                var(--space-cozy);
+    --toast-radius:             var(--radius-card);
+    --toast-font-size:          var(--note-size);
+    --toast-title-size:         var(--description-size);
+    --toast-title-weight:       600;
+    --toast-shadow:             var(--shadow-lg);
+    --toast-container-gap:      var(--space-cozy);
+    --toast-container-offset:   var(--space-comfortable);
+    --toast-duration:           0.25s;
+}
+```

package/docs/components/tooltip.md

@@ -0,0 +1,151 @@
+---
+title: Tooltip
+description: Tooltip component with automatic trigger binding, positioning, and interactive mode
+---
+
+# Tooltip
+
+```javascript
+import { Tooltip } from 'native-document/components';
+
+Tooltip(content, props?)
+```
+
+When `Tooltip.use()` is called, it automatically adds a `.nd.tooltip()` method to all NDElements and BaseComponents.
+
+## Default Renderer
+
+```javascript
+import { TooltipRender } from 'native-document/ui';
+
+Tooltip.use(TooltipRender);
+```
+
+## `$description`
+
+```javascript
+{
+    trigger:          null,
+    interaction:      'hover',          // 'hover' | 'click' | 'focus'
+    content:          null,
+    title:            null,
+    position:         'top',
+    isOpen:           Observable(false),
+    offset:           8,
+    hideDelay:        0,
+    arrow:            true,
+    interactive:      true,
+    updatePositionOn: null,
+    variant:          null,
+    props:            {}
+}
+```
+
+## Methods
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.content(element)` | `element: NdChild` | Tooltip body content |
+| `.title(text)` | `text: string` | Tooltip title |
+| `.trigger(element)` | `element: HTMLElement` | Element that opens the tooltip |
+| `.onHovered()` | - | Open on hover (default) |
+| `.onClicked()` | - | Open on click |
+| `.onFocused()` | - | Open on focus |
+| `.atTop()` | - | Position above trigger |
+| `.atBottom()` | - | Position below trigger |
+| `.atLeft()` | - | Position left of trigger |
+| `.atRight()` | - | Position right of trigger |
+| `.arrow(enabled?)` | `enabled?: boolean` | Show/hide the arrow. Default: `true` |
+| `.offset(px)` | `px: number` | Distance from the trigger in px |
+| `.hideDelay(ms)` | `ms: number` | Delay before hiding on hover leave |
+| `.interactive(enabled)` | `enabled: boolean` | Keep open when hovering the tooltip itself |
+| `.updatePositionOn(observable)` | `observable: Observable` | Recalculate position when the observable changes |
+| `.open()` | - | Open programmatically |
+| `.close()` | - | Close programmatically |
+| `.toggle()` | - | Toggle open/close |
+
+## Via `.nd.tooltip()`
+
+Once registered, any element gains `.nd.tooltip()`:
+
+```javascript
+// Simple string
+Button('Delete')
+    .danger()
+    .nd.tooltip('Permanently delete this item')
+
+// Tooltip instance for full control
+const hint = Tooltip(
+    VStack([
+        Strong('Keyboard shortcut'),
+        Span('Cmd S')
+    ]).spacing(4)
+)
+.atBottom()
+.arrow()
+
+Button('Save')
+    .primary()
+    .nd.tooltip(hint)
+```
+
+## Presets
+
+```javascript
+Tooltip.preset('shortcut', (content, props) => {
+    return Tooltip(content, props)
+        .atBottom()
+        .hideDelay(100);
+});
+
+Button('Save').nd.tooltip(Tooltip.shortcut('Cmd S'))
+Button('Open').nd.tooltip(Tooltip.shortcut('Cmd O'))
+```
+
+## `updatePositionOn`
+
+Pass an observable to trigger a position recalculation when its value changes - useful when the trigger element moves or resizes dynamically:
+
+```javascript
+const isExpanded = Observable(false);
+
+Tooltip('More info')
+    .trigger(myButton)
+    .updatePositionOn(isExpanded)
+```
+
+---
+
+## 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 **[Popover](./popover.md)** for the richer alternative.
+
+
+---
+
+## Theming
+
+```css
+:root {
+    --tooltip-bg:               #1a1a2e;
+    --tooltip-color:            var(--white);
+    --tooltip-border:           transparent;
+    --tooltip-radius:           var(--radius-button);
+    --tooltip-shadow:           var(--shadow-lg);
+    --tooltip-padding:          var(--space-cozy) var(--space-cozy-comfortable);
+    --tooltip-min-width:        0;
+    --tooltip-max-width:        280px;
+    --tooltip-z-index:          100001;
+    --tooltip-font-size:        var(--note-size);
+    --tooltip-arrow-size:       6px;
+    --tooltip-animation-duration: 0.12s;
+}
+```

package/docs/components/traits.md

@@ -0,0 +1,261 @@
+---
+title: Traits
+description: Reusable behavior mixins for NativeDocument components - HasEventEmitter, HasDraggable, HasResizable, HasItems, HasPosition
+---
+
+# Traits
+
+Traits are behavior mixins that add capabilities to components. They are applied via `BaseComponent.use()` and follow the same composition pattern as the rest of the framework.
+
+```javascript
+import { BaseComponent, HasEventEmitter, HasDraggable, HasResizable } from '@native-document/components';
+
+BaseComponent.use(MyComponent, HasEventEmitter, HasDraggable, HasResizable);
+```
+
+> `HasDraggable` and `HasResizable` both **require** `HasEventEmitter` to be applied first.
+
+---
+
+## `HasEventEmitter`
+
+Adds a custom event system to a component. Components use this to communicate state changes to their parent.
+
+### Methods
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.on(eventName, callback)` | `eventName: string`, `callback: function` | Register a listener. Multiple listeners allowed per event. |
+| `.emit(eventName, ...args)` | `eventName: string`, `...args` | Emit an event. Async - all listeners awaited in order. |
+| `.trigger(eventName, ...args)` | same as `emit` | Alias for `emit`. |
+| `.hasListeners(eventName)` | `eventName: string` | Returns `true` if any listeners are registered. |
+
+### Built-in component events
+
+| Event | When |
+|---|---|
+| `open` | Component becomes visible |
+| `close` | Component is dismissed |
+| `change` | Value or selection changes |
+| `select` | An item is selected |
+
+### Example
+
+```javascript
+import { Modal } from '@native-document/components';
+
+const confirmModal = Modal(Div('Are you sure?'))
+    .title('Confirm')
+    .on('close', (confirmed) => {
+        if (confirmed) deleteItem();
+    });
+
+Button('Delete')
+    .danger()
+    .nd.onClick(() => confirmModal.open())
+```
+
+---
+
+## `HasDraggable`
+
+Adds mouse-driven drag behavior to a component. Requires `HasEventEmitter`.
+
+### Methods
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.makeDraggable(element, grip?)` | `element: HTMLElement`, `grip?: HTMLElement` | Makes the element draggable. Returns a cleanup function. `grip` defaults to `element`. |
+| `.move(x, y)` | `x: number`, `y: number` | Programmatically move to an absolute position (px). |
+
+### CSS classes
+
+| Class | When applied |
+|---|---|
+| `is-draggable` | On the grip element |
+| `is-dragging` | While drag is active |
+
+### Events
+
+| Event | Args | When |
+|---|---|---|
+| `onDragStart` | `(event, initialX, initialY)` | Mouse down on grip |
+| `onDrag` | `(event, x, y)` | Mouse move while dragging |
+| `onDragEnd` | - | Mouse up |
+
+```javascript
+MyModal
+    .on('onDragStart', (e, x, y) => console.log('Started at', x, y))
+    .on('onDrag',      (e, x, y) => console.log('Moving to', x, y))
+    .on('onDragEnd',   ()        => console.log('Done'))
+```
+
+---
+
+## `HasResizable`
+
+Adds mouse-driven resize behavior to a component. Requires `HasEventEmitter`.
+
+### Methods
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.makeResizable(element, options?)` | `element: HTMLElement`, `options?: object` | Makes the element resizable. Returns a cleanup function. |
+
+Options:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `directions` | `string[]` | `['right', 'bottom', 'bottom-right']` | Which resize handles to show. Available: `right`, `left`, `top`, `bottom`, `top-right`, `top-left`, `bottom-right`, `bottom-left` |
+| `size.minWidth` | `number` | `200` | Minimum width in px |
+| `size.minHeight` | `number` | `200` | Minimum height in px |
+| `size.maxWidth` | `number` | - | Maximum width in px |
+| `size.maxHeight` | `number` | - | Maximum height in px |
+
+### CSS classes
+
+| Class | Applied to | When |
+|---|---|---|
+| `is-resizable` | Parent element | Always (when resizable) |
+| `resize-handle is-{direction}` | Handle divs | Always |
+| `is-resizing` | `document.body` | While resize is active |
+
+### Events
+
+| Event | Args | When |
+|---|---|---|
+| `onResizeStart` | `(event, width, height)` | Mouse down on handle |
+| `onResize` | `(event, width, height)` | Mouse move while resizing |
+| `onResizeEnd` | `(width, height)` | Mouse up |
+
+```javascript
+MyPanel
+    .on('onResizeStart', (e, w, h) => console.log('Started at', w, h))
+    .on('onResize',      (e, w, h) => saveSize(w, h))
+    .on('onResizeEnd',   (w, h)    => persist({ width: w, height: h }))
+```
+
+---
+
+## `HasItems`
+
+Manages a reactive collection of items. Used internally by `Accordion`, `Menu`, `Tabs`, `Dropdown`.
+
+### Methods
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.dynamic(observableArray?)` | `observableArray?: ObservableArray` | Binds to an existing array or creates a new `Observable.array()`. |
+| `.bind(observableArray?)` | same as `dynamic` | Alias for `dynamic`. |
+| `.items(items)` | `items: array` | Replaces all current items. |
+| `.clear()` | - | Removes all items. |
+| `.removeItem(item)` | `item: *` | Removes a specific item by reference. |
+
+### Example
+
+```javascript
+import { BaseComponent, HasEventEmitter, HasItems } from '@native-document/components';
+import { Div, Span } from 'native-document/elements';
+import { ForEach } from 'native-document/elements';
+
+function TagList(props = {}) {
+    if (!(this instanceof TagList)) return new TagList(props);
+    BaseComponent.call(this);
+    this.$description = { items: [], props };
+}
+
+BaseComponent.extends(TagList);
+BaseComponent.use(TagList, HasEventEmitter, HasItems);
+
+TagList.use(($d) => {
+    return Div({ class: 'tag-list' },
+        ForEach($d.items, tag => Span({ class: 'tag' }, tag))
+    );
+});
+
+TagList()
+    .dynamic()
+    .items(['JavaScript', 'TypeScript', 'Python'])
+```
+
+---
+
+## `HasPosition` / `HasFullPosition`
+
+Position shorthand methods for components that accept a `position` prop (`Tooltip`, `Popover`, `Toast`). Applied internally - you do not need to apply them manually.
+
+### `HasPosition` - 4 directions + center
+
+| Method | Sets `position` to |
+|---|---|
+| `.atTop()` | `'top'` |
+| `.atBottom()` | `'bottom'` |
+| `.atLeft()` | `'left'` |
+| `.atRight()` | `'right'` |
+| `.atCenter()` | `'center'` |
+
+### `HasFullPosition` - all positions
+
+| Method | Sets `position` to |
+|---|---|
+| `.atTop()` | `'top'` |
+| `.atBottom()` | `'bottom'` |
+| `.atLeft()` | `'left'` |
+| `.atRight()` | `'right'` |
+| `.atTopLeading()` | `'top-leading'` |
+| `.atTopTrailing()` | `'top-trailing'` |
+| `.atTopCenter()` | `'top-center'` |
+| `.atBottomLeading()` | `'bottom-leading'` |
+| `.atBottomTrailing()` | `'bottom-trailing'` |
+| `.atBottomCenter()` | `'bottom-center'` |
+| `.atLeadingCenter()` | `'leading-center'` |
+| `.atTrailingCenter()` | `'trailing-center'` |
+
+---
+
+## Building Custom Components with Traits
+
+```javascript
+import { BaseComponent, HasEventEmitter, HasDraggable } from '@native-document/components';
+import { Div, H2 } from 'native-document/elements';
+
+function FloatingPanel(title, content, props = {}) {
+    if (!(this instanceof FloatingPanel)) {
+        return new FloatingPanel(title, content, props);
+    }
+    BaseComponent.call(this);
+    this.$description = { title, content, props };
+}
+
+FloatingPanel.defaultTemplate = null;
+FloatingPanel.use = function(template) {
+    FloatingPanel.defaultTemplate = template;
+};
+
+BaseComponent.extends(FloatingPanel);
+BaseComponent.use(FloatingPanel, HasEventEmitter, HasDraggable);
+
+FloatingPanel.use(($d, component) => {
+    const header = Div({ class: 'panel-header' }, H2($d.title));
+    const body   = Div({ class: 'panel-body' },   $d.content);
+    const panel  = Div({ class: 'panel', style: 'position: absolute', ...$d.props }, [header, body]);
+
+    component.postBuild(() => {
+        component.makeDraggable(panel, header);
+    });
+
+    return panel;
+});
+
+FloatingPanel('Settings', Div('Panel content'))
+    .on('onDragEnd', () => console.log('Moved'))
+    .nd
+```
+
+---
+
+## Next Steps
+
+- **[Components Overview](./index.md)** - BaseComponent philosophy
+- **[Modal](./modal.md)** - Uses HasEventEmitter, HasDraggable, HasResizable
+- **[Getting Started](./getting-started.md)** - Register renderers