native-document 1.0.166 → 1.0.169

package/docs/components/skeleton.md

@@ -0,0 +1,155 @@
+---
+title: Skeleton
+description: Placeholder that mimics content shape while loading
+---
+
+# Skeleton
+
+```javascript
+import { Skeleton } from 'native-document/components';
+
+Skeleton(props?)
+```
+
+A placeholder that mimics the shape of content while it loads.
+
+## Default Renderer
+
+```javascript
+import { SkeletonRender } from 'native-document/ui';
+
+Skeleton.use(SkeletonRender);
+```
+
+## `$description`
+
+```javascript
+{
+    type:             'rect',    // 'rect' | 'circle' | 'text' | 'avatar' | 'image'
+    variant:          'pulse',   // 'pulse' | 'wave'
+    borderRadiusType: 'rounded',
+    lines:            null,      // number - for text type
+    width:            null,
+    height:           null,
+    loading:          null,      // Observable<boolean>
+    repeat:           null,      // number - repeat N times
+    props:            {} // HTML attributes for the root element
+}
+```
+
+## Methods
+
+```javascript
+// Type
+.rect()
+    .circle()
+    .text(lines?)
+    .avatar()
+    .image()
+
+    // Animation
+    .pulse()
+    .wave()
+
+    // Size
+    .width(200)
+    .height(100)
+    .size(width, height)
+
+    // Shape
+    .rounded()
+    .pill()
+    .smooth()
+
+    // Options
+    .lines(3)
+    .repeat(4)
+    .loading(isLoading)
+```
+
+## Built-in Presets
+
+Skeleton ships with four ready-to-use presets:
+
+### `Skeleton.card(type?)`
+
+A card with an image area and text lines below:
+
+```javascript
+Skeleton.card()
+Skeleton.card('featured') // adds type as extra CSS class
+```
+
+### `Skeleton.list(items?)`
+
+A list of rows with avatar and text lines. Default: 3 items:
+
+```javascript
+Skeleton.list()
+Skeleton.list(5)
+```
+
+### `Skeleton.table(rows?, cols?)`
+
+A table with a header row and data rows. Default: 5 rows, 4 cols:
+
+```javascript
+Skeleton.table()
+Skeleton.table(10, 6)
+```
+
+### `Skeleton.paragraph(lines?)`
+
+A block of text lines. Default: 3 lines:
+
+```javascript
+Skeleton.paragraph()
+Skeleton.paragraph(5)
+```
+
+---
+
+## Custom Presets
+
+Register your own reusable shapes with `Skeleton.preset()` or `Skeleton.presets()`:
+
+```javascript
+Skeleton.preset('userRow', (skeleton) => {
+    return skeleton.avatar().circle().size(40, 40);
+});
+
+// Register multiple at once
+Skeleton.presets({
+    title:   (s) => s.rect().width(200).height(24).rounded(),
+    avatar:  (s) => s.circle().size(48, 48),
+});
+
+// Usage
+Skeleton.userRow()
+Skeleton.title()
+```
+
+## Example
+
+```javascript
+ShowIf(isLoading, () =>
+    VStack([
+        Skeleton().avatar().circle().size(48, 48),
+        Skeleton().text(3)
+    ]).spacing(8)
+)
+```
+
+---
+
+## Theming
+
+```css
+:root {
+    --skeleton-color:          var(--gray-lite-4);
+    --skeleton-highlight:      var(--gray-lite-5);
+    --skeleton-radius:         var(--radius-button);
+    --skeleton-wave-duration:  1.6s;
+    --skeleton-pulse-duration: 1.2s;
+}
+```

package/docs/components/spinner.md

@@ -0,0 +1,100 @@
+---
+title: Spinner
+description: Loading indicator with multiple types, sizes, and overlay support
+---
+
+# Spinner
+
+```javascript
+import { Spinner } from 'native-document/components';
+
+Spinner(props?)
+```
+
+A loading indicator.
+
+## Default Renderer
+
+```javascript
+import { SpinnerRender } from 'native-document/ui';
+
+Spinner.use(SpinnerRender);
+```
+
+## `$description`
+
+```javascript
+{
+    type:              'circle',  // 'circle' | 'dots' | 'bars' | 'pulse' | 'ring'
+    variant:           'primary',
+    color:             null,
+    size:              'small',   // 'xs' | 'small' | 'medium' | 'large'
+    label:             null,
+    labelPosition:     null,      // 'top' | 'bottom' | 'left' | 'right'
+    overlay:           null,
+    backdrop:          null,
+    fullScreenOverlay: null,
+    speed:             'normal',  // 'slow' | 'normal' | 'fast'
+    props:             {} // HTML attributes for the root element
+}
+```
+
+## Methods
+
+```javascript
+// Type
+.circle()
+.dots()
+.bars()
+.pulse()
+.ring()
+
+// Size
+.extraSmall()
+.small()
+.medium()
+.large()
+
+// Style
+.primary()
+.color('#3b82f6')
+.speed('fast')
+
+// Label
+.label('Loading...')
+.labelPosition('bottom')
+
+// Overlay
+.overlay()
+.fullScreenOverlay()
+```
+
+## Example
+
+```javascript
+ShowIf(isLoading, () => Spinner().large().label('Loading...'))
+```
+
+---
+
+## Theming
+
+```css
+:root {
+    --spinner-size-extra-small: 16px;
+    --spinner-size-small:       24px;
+    --spinner-size-medium:      36px;
+    --spinner-size-large:       48px;
+    --spinner-size-extra-large: 64px;
+    --spinner-speed-slow:       1.2s;
+    --spinner-speed-normal:     0.8s;
+    --spinner-speed-fast:       0.4s;
+    --spinner-thickness:        3px;
+    --spinner-color:            var(--color-primary);
+    --spinner-color-primary:    var(--color-primary);
+    --spinner-color-secondary:  var(--color-secondary-text);
+    --spinner-color-success:    var(--color-success);
+    --spinner-color-danger:     var(--color-danger);
+    --spinner-color-warning:    var(--color-warning);
+}
+```

package/docs/components/splitter.md

@@ -0,0 +1,133 @@
+---
+title: Splitter
+description: Resizable split panel layout with horizontal and vertical orientations
+---
+
+# Splitter
+
+```javascript
+import { Splitter, SplitterPanel, SplitterGutter } from 'native-document/components';
+```
+
+## Default Renderer
+
+```javascript
+import { SplitterRender, SplitterPanelRender, SplitterGutterRender } from 'native-document/ui';
+
+Splitter.use(SplitterRender);
+SplitterPanel.use(SplitterPanelRender);
+SplitterGutter.use(SplitterGutterRender);
+```
+
+---
+
+## `Splitter`
+
+### Methods
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.horizontal()` | - | Side-by-side layout (default) |
+| `.vertical()` | - | Stacked layout |
+| `.gutterSize(px)` | `px: number` | Width of the drag handle in px |
+| `.panel(content, options?, props?)` | `content: NdChild`, `options?: object` | Add a panel inline |
+| `.panels(panels)` | `panels: SplitterPanel[]` | Add multiple panels at once |
+| `.dynamic()` | - | Enable dynamic panel management (add/remove at runtime) |
+| `.removePanel(panel)` | `panel: SplitterPanel` | Remove a panel dynamically |
+| `.onResize(handler)` | `handler: (sizes) => void` | Fires on every resize |
+| `.onPanelAdd(handler)` | `handler: (panel) => void` | Fires when a panel is added dynamically |
+| `.onPanelRemove(handler)` | `handler: (panel) => void` | Fires when a panel is removed dynamically |
+
+The inline `options` object for `.panel(content, options)` accepts the same properties as `SplitterPanel` methods: `size`, `minSize`, `maxSize`, `collapsible`.
+
+---
+
+## `SplitterPanel`
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.content(element)` | `element: NdChild` | Panel content |
+| `.size(value)` | `value: string \| number` | Initial size (`'30%'`, `300`) |
+| `.minSize(px)` | `px: number` | Minimum size in px |
+| `.maxSize(px)` | `px: number` | Maximum size in px |
+| `.collapsible(enabled?)` | `enabled?: boolean` | Allow collapsing to 0 |
+| `.collapsed(val?)` | `val?: boolean` | Start collapsed |
+| `.resizable(enabled?)` | `enabled?: boolean` | Enable/disable resize for this panel |
+| `.fixed()` | - | Panel is not resizable and keeps its size |
+| `.data(data)` | `data: *` | Attach metadata to the panel |
+
+---
+
+## `SplitterGutter`
+
+The drag handle between panels. No extra methods - its appearance is controlled entirely by the renderer.
+
+---
+
+## Dynamic panels
+
+Use `.dynamic()` to add or remove panels at runtime. Track a panel reference to remove it later:
+
+```javascript
+const sidebar = SplitterPanel(SidebarContent)
+    .size('25%')
+    .minSize(150)
+    .collapsible();
+
+const splitter = Splitter()
+    .dynamic()
+    .panel(sidebar)
+    .panel(SplitterPanel(MainContent).size('75%'))
+    .onPanelAdd((panel) => console.log('Panel added'))
+    .onPanelRemove((panel) => console.log('Panel removed'));
+
+// Remove the sidebar later
+Button('Hide sidebar').nd.onClick(() => splitter.removePanel(sidebar))
+```
+
+---
+
+## Example
+
+```javascript
+Splitter()
+    .horizontal()
+    .gutterSize(4)
+    .panel(
+        SplitterPanel(FileExplorer)
+            .size('20%')
+            .minSize(150)
+            .collapsible()
+    )
+    .panel(
+        SplitterPanel(
+            Splitter()
+                .vertical()
+                .panel(CodeEditor, { size: '70%' })
+                .panel(Terminal,   { size: '30%', minSize: 100 })
+        ).size('80%')
+    )
+    .onResize((sizes) => savePanelSizes(sizes))
+```
+
+
+---
+
+## Theming
+
+```css
+:root {
+    --splitter-gutter-size:              1px;
+    --splitter-gutter-hit-area:          8px;
+    --splitter-gutter-color:             var(--gray-lite-3);
+    --splitter-gutter-handle-size:       32px;
+    --splitter-gutter-handle-color:      var(--gray-lite-2);
+    --splitter-gutter-handle-color-hover: var(--color-primary);
+}
+```
+
+---
+
+## Next Steps
+
+- **[Layout](./layout.md)** - Stack-based layout components

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