native-document 1.0.166 → 1.0.168

package/docs/components/stepper.md

@@ -0,0 +1,163 @@
+---
+title: Stepper
+description: Multi-step wizard component with validation, navigation, and custom renderers
+---
+
+# Stepper
+
+```javascript
+import { Stepper, StepperStep } from 'native-document/components';
+```
+
+## Default Renderer
+
+```javascript
+import { StepperRender, StepperStepRender } from 'native-document/ui';
+
+Stepper.use(StepperRender);
+StepperStep.use(StepperStepRender);
+```
+
+---
+
+## `Stepper`
+
+### Configuration
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.step(step)` | `step: StepperStep` | Add a step |
+| `.data(data)` | `data: *` | Initial data passed to all steps |
+| `.currentStep(obs)` | `obs: Observable<number>` | Bind the current step index to an observable |
+| `.linear(enabled?)` | `enabled?: boolean` | Steps must complete in order (default) |
+| `.nonLinear()` | - | Can jump to any step freely |
+| `.editable(enabled?)` | `enabled?: boolean` | Allow returning to completed steps |
+| `.horizontal()` | - | Horizontal layout (default) |
+| `.vertical()` | - | Vertical layout |
+| `.alternativeLabel(enabled?)` | `enabled?: boolean` | Labels below the indicators |
+| `.showNumbers(enabled?)` | `enabled?: boolean` | Show step numbers in indicators |
+| `.showConnector(enabled?)` | `enabled?: boolean` | Show connector line between steps |
+
+### Navigation position
+
+| Method | Description |
+|---|---|
+| `.navigationAtBottom()` | Navigation buttons at the bottom, horizontal layout |
+| `.navigationAtTop()` | Navigation buttons at the top, horizontal layout |
+| `.navigationAtLeading()` | Navigation buttons on the leading side, vertical layout |
+
+### Navigation methods
+
+| Method | Parameters | Description |
+|---|---|---|
+| `await stepper.next()` | - | Validates current step, then advances |
+| `stepper.previous()` | - | Go to previous step |
+| `await stepper.goToStep(index)` | `index: number` | Jump to a step (0-indexed) |
+| `stepper.reset()` | - | Reset to step 0 |
+
+### Events
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.onStepChange(handler)` | `handler: (current, previous) => void` | Fires on every step change |
+| `.onNext(handler)` | `handler: (step, index) => void` | Fires when advancing |
+| `.onPrevious(handler)` | `handler: (step, index) => void` | Fires when going back |
+| `.onComplete(handler)` | `handler: (data) => void` | Fires when last step is completed |
+| `.onReset(handler)` | `handler: () => void` | Fires on reset |
+
+### Custom renderers
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.renderStepIndicator(fn)` | `fn: ($step) => NdChild` | Custom step indicator (circle/icon) |
+| `.renderStepIndicatorConnector(fn)` | `fn: ($step) => NdChild` | Custom connector between indicators |
+| `.renderContent(fn)` | `fn: ($step) => NdChild` | Custom step content wrapper |
+
+---
+
+## `StepperStep`
+
+```javascript
+StepperStep(title)
+```
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.description(text)` | `text: string` | Subtitle below the step title |
+| `.icon(element)` | `element: NdChild` | Icon displayed in the indicator |
+| `.content(element)` | `element: NdChild` | Step body content |
+| `.key(key)` | `key: string` | Unique identifier for this step |
+| `.optional()` | - | Mark step as optional (can be skipped) |
+| `.disabled(val)` | `val: boolean \| Observable<boolean>` | Disable the step |
+| `.visibility(val)` | `val: boolean \| Observable<boolean>` | Show or hide the step reactively |
+| `.validator(fn)` | `fn: () => boolean \| Promise<boolean>` | Validation function - must return `true` to advance |
+
+---
+
+## Example
+
+```javascript
+const refs = {};
+
+const wizard = Stepper()
+    .linear()
+    .step(
+        StepperStep('Account')
+            .content(AccountForm().nd.refSelf(refs, 'accountForm'))
+            .validator(async () => refs.accountForm.validate())
+    )
+    .step(
+        StepperStep('Profile')
+            .description('Tell us about yourself')
+            .content(ProfileForm)
+            .optional()
+    )
+    .step(
+        StepperStep('Done')
+            .icon(CheckIcon)
+            .content(SuccessPanel)
+    )
+    .navigationAtBottom()
+    .onComplete(async (data) => {
+        await registerUser(data);
+    })
+
+document.body.appendChild(wizard);
+```
+
+
+---
+
+## Theming
+
+```css
+:root {
+    --stepper-connector-color:           var(--gray-lite-3);
+    --stepper-connector-color-active:    var(--color-primary);
+    --stepper-connector-color-completed: var(--color-success);
+    --stepper-connector-thickness:       2px;
+    --step-indicator-size:               32px;
+    --step-indicator-bg:                 var(--gray-lite-4);
+    --step-indicator-bg-active:          var(--color-primary);
+    --step-indicator-bg-completed:       var(--color-success);
+    --step-indicator-bg-error:           var(--color-danger);
+    --step-indicator-color:              var(--gray);
+    --step-indicator-color-active:       var(--white);
+    --step-indicator-font-size:          var(--hint-size);
+    --step-indicator-font-weight:        600;
+    --step-label-size:                   var(--hint-size);
+    --step-label-color:                  var(--gray);
+    --step-label-color-active:           var(--text-color);
+    --step-label-weight:                 500;
+    --step-description-size:             var(--note-size);
+    --step-description-color:            var(--gray);
+    --stepper-content-padding:           var(--space-comfortable) 0;
+}
+```
+
+---
+
+## Next Steps
+
+- **[Components Overview](./index.md)** - BaseComponent philosophy
+- **[FormControl](./form/form-control.md)** - Form validation with steps

package/docs/components/switch.md

@@ -0,0 +1,113 @@
+---
+title: Switch
+description: Toggle switch component with two-way binding, variants, icons, and inner labels
+---
+
+# Switch
+
+```javascript
+import { Switch } from 'native-document/components';
+
+Switch(props?)
+```
+
+## Default Renderer
+
+```javascript
+import { SwitchRender } from 'native-document/ui';
+
+Switch.use(SwitchRender);
+```
+
+## `$description`
+
+```javascript
+{
+    value:         Observable(false),
+    label:         null,
+    labelPosition: Observable('right'), // 'left' | 'right' | 'top' | 'bottom'
+    variant:       Observable('primary'),
+    outline:       false,
+    disabled:      false,
+    loading:       false,
+    readonly:      false,
+    onIcon:        null,
+    offIcon:       null,
+    innerOnLabel:  null,
+    innerOffLabel: null,
+    props:         {} // HTML attributes for the root element
+}
+```
+
+## Methods
+
+```javascript
+// Binding
+.model(Observable(false))
+
+// Label
+.label('Enable notifications')
+.labelPosition('left')  // 'left' | 'right' | 'top' | 'bottom'
+
+// Inner labels (inside the toggle)
+.innerLabel('Yes', 'No')
+
+// Icons
+.icon(SunIcon, MoonIcon)  // onIcon, offIcon
+
+// Variants
+.primary()
+.success()
+.danger()
+.warning()
+.ghost()
+.outline()
+
+// State
+.disabled(Observable(false))
+.loading(Observable(false))
+.readonly(true)
+
+// Programmatic
+.toggle()
+.on()
+.off()
+
+// Events
+.onChange((value) => console.log('Changed:', value))
+.onOn(()  => console.log('Switched on'))
+.onOff(() => console.log('Switched off'))
+```
+
+## Example
+
+```javascript
+const darkMode = Observable(false);
+
+Switch()
+    .model(darkMode)
+    .label('Dark mode')
+    .icon(SunIcon, MoonIcon)
+    .innerLabel('On', 'Off')
+    .onChange((value) => applyTheme(value ? 'dark' : 'light'))
+```
+
+---
+
+## Theming
+
+```css
+:root {
+    --switch-width:            44px;
+    --switch-height:           24px;
+    --switch-thumb-size:       18px;
+    --switch-thumb-offset:     3px;
+    --switch-border-width:     0px;
+    --switch-track-bg:         var(--gray-lite-3);
+    --switch-track-bg-active:  var(--color-primary);
+    --switch-thumb-bg:         var(--background);
+    --switch-thumb-shadow:     0 1px 3px rgba(0, 0, 0, 0.2);
+    --switch-transition:       0.2s ease;
+    --switch-label-gap:        var(--space-cozy);
+}
+```

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