native-document 1.0.166 → 1.0.168

package/docs/components/index.md

@@ -0,0 +1,337 @@
+---
+title: Components
+description: NativeDocument's headless UI component system - describe your interface without choosing a theme, build fast, change the look anytime
+---
+
+# Components
+
+NativeDocument ships a separate `@native-document/components` package with 50+ UI components.
+
+## Install
+
+```bash
+npm install @native-document/components
+```
+
+```javascript
+import { Button, Modal, Tabs } from '@native-document/components';
+```
+
+---
+
+## The Philosophy
+
+### Describe your interface. Worry about the look later.
+
+The goal of the component system is simple: let you **build fast without making visual decisions upfront**.
+
+When you write `Button('Save').variant('primary').size('large').rounded().loading(isSubmitting)`, you are describing **what the component should look like and what state it is in** - primary, large, rounded, loading. You are not deciding *how* those descriptions translate to pixels. That is the renderer's job.
+
+`rounded()` says "this should be rounded". The renderer decides whether that means `border-radius: 4px`, `border-radius: 9999px`, a CSS class, or a Tailwind utility. You can change that decision at any time without touching the component.
+
+This means:
+
+- **Start immediately** - no design system required, no theme to configure first
+- **Change the look anytime** - edit one renderer file and every component updates automatically, without touching a single line of business logic
+- **No CSS wars** - no specificity conflicts, no `!important`, no framework overrides
+- **One component, any visual system** - Tailwind, Bootstrap, your own CSS, or bare styles
+
+### Describe intent. The renderer decides implementation.
+
+Every component lets you express visual intent through a fluent API. A `Button` knows it can be `primary`, `large`, `rounded`, `loading`, or `disabled`. It does not know what CSS rules those words translate to - that is the renderer's responsibility.
+
+When you need to change the UI from Bootstrap to Tailwind, or from flat to material design - you edit the renderer. Nothing else changes.
+
+### The `$description` Contract
+
+Every component builds a `$description` object - a plain object that describes the current state of the component. The renderer receives this object and returns a DOM element.
+
+```javascript
+// What Button.$description looks like:
+{
+    label:            'Submit',
+        type:             'submit',
+    variant:          'primary',
+    size:             'large',
+    icon:             null,
+    iconPosition:     'leading',
+    loading:          Observable(false),
+    disabled:         Observable(false),
+    outline:          false,
+    block:            false,
+    borderRadiusType: 'rounded',
+    props:            { class: 'my-btn' },
+    render:           null  // custom per-instance renderer
+}
+```
+
+The renderer is a function that receives `$description` and returns a DOM element:
+
+```javascript
+Button.use(($description, component) => {
+    return NativeButton({
+        type:     $description.type || 'button',
+        class:    buildClasses($description),
+        disabled: $description.disabled
+    }, [
+        ShowIf($description.loading, () => Spinner()),
+        $description.icon && $description.iconPosition === 'leading'
+            ? $description.icon
+            : null,
+        $description.label,
+        $description.icon && $description.iconPosition === 'trailing'
+            ? $description.icon
+            : null,
+    ]);
+});
+```
+
+### Fluent API
+
+Every component uses a fluent builder API. Methods configure the `$description` and return `this` for chaining. The component is only rendered when you access `.nd` or append it to the DOM:
+
+```javascript
+Button('Submit')
+    .variant('primary')
+    .size('large')
+    .loading(isSubmitting)
+    .disabled(isDisabled)
+    .rounded()
+    .nd.onClick(() => submitForm())
+```
+
+### Rendering is Lazy
+
+The component function runs immediately, but the DOM is not built until:
+
+- You access `.nd` (triggers `.toNdElement()`)
+- You append the component to the DOM directly
+
+This means you can fully configure a component before it renders.
+
+---
+
+## Registering a Renderer
+
+### Global renderer
+
+```javascript
+import { Button } from '@native-document/components';
+
+// Called once at app startup - applies to all Button instances
+Button.use(($description) => {
+    const classes = ['btn'];
+
+    if ($description.variant) { classes.push(`btn-${$description.variant}`); }
+    if ($description.size)    { classes.push(`btn-${$description.size}`); }
+    if ($description.block)   { classes.push('btn-block'); }
+    if ($description.outline) { classes.push('btn-outline'); }
+
+    return NativeButton({
+        type:     $description.type || 'button',
+        class:    classes.join(' '),
+        disabled: $description.disabled,
+        ...$description.props
+    }, $description.label);
+});
+```
+
+### Per-instance renderer
+
+Override the global renderer for a specific instance:
+
+```javascript
+Button('Special')
+    .render(($description) => {
+        return NativeButton({ class: 'special-btn' }, $description.label);
+    })
+    .nd.onClick(() => console.log('Special!'))
+```
+
+---
+
+## `setDescription()` - Reactive Updates
+
+`setDescription()` updates the `$description` object. If a key already holds an observable, it calls `.set()` on it instead of replacing it - keeping reactive bindings intact:
+
+```javascript
+const btn = Button('Save').loading(Observable(false));
+
+// Later - updates the observable, DOM reacts automatically
+btn.setDescription({ loading: true });
+```
+
+---
+
+## `showIf()` / `visibility()`
+
+Conditionally render the entire component:
+
+```javascript
+Button('Admin Only')
+    .showIf(user.is(u => u.isAdmin))
+    .variant('danger')
+```
+
+---
+
+## `props()` - Pass HTML Attributes
+
+Pass arbitrary HTML attributes to the root element:
+
+```javascript
+Button('Submit')
+    .props({ id: 'submit-btn', 'data-testid': 'submit' })
+    .variant('primary')
+```
+
+---
+
+## `refSelf()` - Component Reference
+
+Store a reference to the component instance (not the DOM element):
+
+```javascript
+const refs = {};
+
+Button('Save')
+    .variant('primary')
+    .nd.refSelf(refs, 'saveBtn');
+
+// Later - call component methods
+refs.saveBtn.loading(true);
+refs.saveBtn.disabled(true);
+```
+
+---
+
+## `ghostDom()` - Companion Elements
+
+Attach companion elements that are injected into the DOM alongside the component but not exposed to the parent. See [NDElement - ghostDom](../native-document-element.md) for the full explanation.
+
+---
+
+## `postBuild(callback)`
+
+Register a callback that runs after the component renders:
+
+```javascript
+Button('Submit')
+    .postBuild((element, component) => {
+        console.log('Button rendered:', element);
+    })
+```
+
+---
+
+## `BaseComponent.extends()` and `BaseComponent.use()`
+
+These are the tools for building custom components:
+
+```javascript
+import { BaseComponent } from '@native-document/components';
+
+// Create a new component that inherits from BaseComponent
+function MyCard(title, props = {}) {
+    if (!(this instanceof MyCard)) {
+        return new MyCard(title, props);
+    }
+    BaseComponent.call(this);
+    this.$description = { title, props };
+}
+
+MyCard.defaultTemplate = null;
+
+MyCard.use = function(template) {
+    MyCard.defaultTemplate = template;
+};
+
+// Set up prototype chain
+BaseComponent.extends(MyCard);
+
+// Add methods
+MyCard.prototype.subtitle = function(subtitle) {
+    this.$description.subtitle = subtitle;
+    return this;
+};
+
+// Register renderer
+MyCard.use(($description) => {
+    return Div({ class: 'card', ...$description.props }, [
+        H2($description.title),
+        $description.subtitle ? P($description.subtitle) : null,
+    ]);
+});
+
+// Usage
+MyCard('Hello').subtitle('World').nd
+```
+
+### `BaseComponent.use()` - Apply Traits
+
+Mix behavior traits into a component:
+
+```javascript
+import { BaseComponent, HasEventEmitter, HasDraggable } from '@native-document/components';
+
+BaseComponent.use(MyCard, HasEventEmitter, HasDraggable);
+// MyCard now has .on(), .emit(), .makeDraggable() etc.
+```
+
+---
+
+## Default Renderers
+
+The package ships with a default renderer for every component, imported from `'native-document/src/ui'`. You can use them as a starting point or ignore them entirely and write your own from scratch.
+
+Create a `src/core/renderers.js` file and import it once at app startup:
+
+```javascript
+import {
+    Button, Alert, Badge, Modal, Tabs, Dropdown, DropdownItem
+    // ... all components you use
+} from 'native-document/components';
+
+import {
+    ButtonRender, AlertRender, BadgeRender, ModalRender, TabsRender,
+    DropdownRender, DropdownItemRender
+    // ... matching renders
+} from 'native-document/src/ui';
+
+Button.use(ButtonRender);
+Alert.use(AlertRender);
+Badge.use(BadgeRender);
+Modal.use(ModalRender);
+Tabs.use(TabsRender);
+Dropdown.use(DropdownRender);
+DropdownItem.use(DropdownItemRender);
+// ...
+```
+
+> `ContextMenu` is the only exception - its `.use()` takes both a renderer and a handler:
+> ```javascript
+> import { ContextMenuRender, contextMenuHandler } from 'native-document/src/ui';
+> ContextMenu.use(ContextMenuRender, contextMenuHandler);
+> ```
+
+When you want to customize, call `Component.use()` with your own renderer - it replaces the default globally:
+
+```javascript
+Button.use(($d) => {
+    return NativeButton({
+        class: buildMyClasses($d),
+        ...$d.props
+    }, $d.label);
+});
+```
+
+You can also mix - use the defaults for most components and override only the ones you want to customize.
+
+---
+
+## Next Steps
+
+- **[Getting Started](./getting-started.md)** - Build your first component with a renderer
+- **[Traits](./traits.md)** - HasEventEmitter, HasDraggable, HasResizable
+- **[Button](./button.md)** - Button component API
+- **[Layout](./layout.md)** - Stack, Row, Col, Divider

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