native-document 1.0.166 → 1.0.168

package/docs/components/breadcrumb.md

@@ -0,0 +1,89 @@
+---
+title: Breadcrumb
+description: Breadcrumb navigation component with custom separators and click handlers
+---
+
+# Breadcrumb
+
+```javascript
+import { Breadcrumb } from 'native-document/components';
+
+Breadcrumb(props?)
+```
+
+## Default Renderer
+
+```javascript
+import { BreadcrumbRender } from 'native-document/ui';
+
+Breadcrumb.use(BreadcrumbRender);
+```
+
+## Methods
+
+```javascript
+// Add items
+.item(label, href?, value?)
+.items([{ label, href, value }, ...])
+.removeItem(index)
+
+// Bind to an observable array
+.bind(Observable.array([...]))
+
+// Separator
+.separator('/')
+.separator(ChevronIcon)
+.renderSeparator(($description) => Span(' > '))
+
+// Events
+.onItemClick((item, index) => Router.push(item.href))
+
+// Custom renderers
+.renderItem(($item) => Link({ href: $item.href }, $item.label))
+```
+
+## Example
+
+```javascript
+Breadcrumb()
+    .item('Home', '/')
+    .item('Products', '/products')
+    .item('Laptops', '/products/laptops')
+    .item('MacBook Pro')  // current - no href
+    .separator('/')
+    .onItemClick((item) => {
+        if (item.href) {
+            Router.push(item.href);
+        }
+    })
+```
+
+## Reactive Binding
+
+```javascript
+const crumbs = Observable.array([
+    { label: 'Home',     href: '/' },
+    { label: 'Products', href: '/products' }
+]);
+
+Breadcrumb().bind(crumbs).separator(ChevronRight)
+
+// Update dynamically
+crumbs.push({ label: 'Laptops', href: '/products/laptops' });
+```
+
+---
+
+## Theming
+
+```css
+:root {
+    --breadcrumb-font-size:       var(--description-size);
+    --breadcrumb-color:           var(--gray);
+    --breadcrumb-color-active:    var(--text-color);
+    --breadcrumb-color-hover:     var(--color-primary);
+    --breadcrumb-separator-color: var(--gray-lite-2);
+    --breadcrumb-separator:       '/';
+    --breadcrumb-gap:             var(--space-cozy);
+}
+```

package/docs/components/button.md

@@ -0,0 +1,183 @@
+---
+title: Button
+description: Headless Button component with variants, sizes, loading state, icons, and presets
+---
+
+# Button
+
+```javascript
+import { Button } from 'native-document/components';
+
+Button(label, props?)
+```
+
+## Default Renderer
+
+```javascript
+import { ButtonRender } from 'native-document/ui';
+import { SpinnerRender } from 'native-document/ui';
+
+Button.use(ButtonRender);
+Spinner.use(SpinnerRender); // required - loading state is rendered as a spinner
+```
+
+## `$description`
+
+```javascript
+{
+    label:            'Submit',
+        type:             null,         // 'button' | 'submit' | 'reset'
+        variant:          null,
+        size:             null,         // 'small' | 'medium' | 'large'
+        icon:             null,         // DOM element
+        iconPosition:     'leading',    // 'leading' | 'trailing' | 'top' | 'bottom'
+        iconOnly:         false,
+        loading:          null,         // Observable<boolean>
+        disabled:         null,         // Observable<boolean>
+        outline:          false,
+        block:            false,
+        borderRadiusType: null,         // 'rounded' | 'pill' | 'circle' | 'smooth'
+        props:            {} // HTML attributes for the root element
+}
+```
+
+## Methods
+
+### Variants
+
+```javascript
+.primary()
+    .secondary()
+    .danger()
+    .success()
+    .warning()
+    .ghost()
+    .link()
+    .outline()
+```
+
+### Size
+
+```javascript
+.small()
+    .medium()
+    .large()
+```
+
+### Shape
+
+```javascript
+.rounded()
+    .pill()
+    .circle()
+    .smooth()
+```
+
+### Icon
+
+```javascript
+.icon(element, position?)
+    .iconAtLeading()
+    .iconAtTrailing()
+    .iconAtTop()
+    .iconAtBottom()
+    .iconOnly()
+```
+
+### State
+
+```javascript
+.loading(observable | true)
+    .disabled(observable | true)
+    .block()
+    .type('submit')
+```
+
+## Example
+
+```javascript
+const isLoading = Observable(false);
+
+Button('Save Changes')
+    .primary()
+    .large()
+    .rounded()
+    .loading(isLoading)
+    .icon(SaveIcon)
+    .nd
+    .onClick(async () => {
+        isLoading.set(true);
+        await save();
+        isLoading.set(false);
+    })
+```
+
+## Presets
+
+```javascript
+Button.preset('save', (label, props) => {
+    return Button(label || 'Save', props).primary();
+});
+Button.preset('cancel', (label, props) => {
+    return Button(label || 'Cancel', props).ghost();
+});
+
+Button.save()
+Button.cancel('Go back')
+```
+
+## Custom Renderer Example
+
+```javascript
+Button.use(($description) => {
+    return NativeButton({
+        type:     $description.type || 'button',
+        class:    buildClasses($description),
+        disabled: $description.disabled,
+        ...$description.props
+    }, [
+        ShowIf($description.loading, () => Spinner()),
+        ShowIf($description.icon && $description.iconPosition === 'leading', () => $description.icon),
+        ShowIf(!$description.iconOnly, $description.label),
+        ShowIf($description.icon && $description.iconPosition === 'trailing', () => $description.icon),
+    ]);
+});
+```
+
+---
+
+## Theming
+
+```css
+:root {
+    --btn-height-small:            28px;
+    --btn-height-medium:           36px;
+    --btn-height-large:            44px;
+    --btn-padding-small:           0 var(--space-cozy-comfortable);
+    --btn-padding-medium:          0 var(--space-comfortable);
+    --btn-padding-large:           0 var(--space-relaxed);
+    --btn-font-size-small:         var(--note-size);
+    --btn-font-size-medium:        var(--description-size);
+    --btn-font-size-large:         var(--text-size);
+    --btn-icon-size-small:         14px;
+    --btn-icon-size-medium:        16px;
+    --btn-icon-size-large:         18px;
+    --btn-loader-size:             14px;
+    --btn-gap:                     var(--space-cozy);
+    --btn-font-weight:             500;
+    --btn-transition:              background 120ms ease, color 120ms ease, border-color 120ms ease;
+    --btn-disabled-opacity:        0.45;
+    --btn-color-primary:           var(--color-primary);
+    --btn-color-primary-hover:     var(--color-primary-hover);
+    --btn-color-secondary:         var(--color-secondary);
+    --btn-color-secondary-hover:   var(--color-secondary-hover);
+    --btn-color-danger:            var(--color-danger);
+    --btn-color-danger-hover:      var(--color-danger-hover);
+    --btn-color-success:           var(--color-success);
+    --btn-color-success-hover:     var(--color-success-hover);
+    --btn-color-warning:           var(--color-warning);
+    --btn-color-warning-hover:     var(--color-warning-hover);
+    --btn-color-info:              var(--color-info);
+    --btn-color-info-hover:        var(--color-info-hover);
+}
+```

package/docs/components/card.md

@@ -0,0 +1,69 @@
+---
+title: Card
+description: Versatile content container with optional image, header, footer, and actions
+---
+
+# Card
+
+> **Status: coming soon.** The `Card` API is fully defined but the default renderer is not yet implemented. You can use `Card` today by providing your own renderer via `Card.use()`.
+
+```javascript
+import { Card } from 'native-document/components';
+
+Card(props?)
+```
+
+## Custom Renderer
+
+Until the default renderer ships, register your own:
+
+```javascript
+import { Div, Img, H3, P, Button, HStack } from 'native-document/elements';
+
+Card.use(($d, instance) => {
+    return Div({ class: `card ${$d.variant ?? ''}` }, [
+        $d.image ? Img({ src: $d.image.src, class: `card-image card-image-${$d.image.position}` }) : null,
+        Div({ class: 'card-body' }, [
+            $d.title    ? H3({ class: 'card-title' }, $d.title)       : null,
+            $d.subtitle ? P({ class: 'card-subtitle' }, $d.subtitle)  : null,
+            $d.content  ? Div({ class: 'card-content' }, $d.content)  : null,
+        ]),
+        $d.actions?.length ? HStack({ class: 'card-footer' },
+            $d.actions.map(a => Button(a.label).nd.onClick(a.callback))
+        ) : null,
+    ]);
+});
+```
+
+## Methods
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.title(element)` | `element: NdChild` | Card title |
+| `.subtitle(element)` | `element: NdChild` | Card subtitle |
+| `.image(src, position?)` | `src: string`, `position?: 'top' \| 'bottom' \| 'left' \| 'right'` | Card image. Default position: `'top'` |
+| `.content(element)` | `element: NdChild` | Card body content |
+| `.action(label, callback)` | `label: NdChild`, `callback: () => void` | Add a footer action button |
+| `.clearActions()` | - | Remove all action buttons |
+| `.variant(name)` | `name: string` | CSS variant class |
+| `.elevated()` | - | Shorthand for `.variant('elevated')` |
+| `.outlined()` | - | Shorthand for `.variant('outlined')` |
+| `.flat()` | - | Shorthand for `.variant('flat')` |
+| `.horizontal()` | - | Horizontal layout (image on the left) |
+| `.clickable(handler)` | `handler: (event) => void` | Make the entire card clickable |
+| `.hoverable()` | - | Add hover effect |
+| `.loading(val?)` | `val?: boolean \| Observable<boolean>` | Show loading state |
+| `.onClick(handler)` | `handler: (event) => void` | Click event |
+| `.onHover(handler)` | `handler: (event) => void` | Hover event |
+| `.renderImage(fn)` | `fn: ($d, instance) => NdChild` | Custom image renderer |
+| `.renderHeader(fn)` | `fn: ($d, instance) => NdChild` | Custom header renderer |
+| `.renderContent(fn)` | `fn: ($d, instance) => NdChild` | Custom content renderer |
+| `.renderFooter(fn)` | `fn: ($d, instance) => NdChild` | Custom footer renderer |
+| `.layout(fn)` | `fn: ($d, instance) => NdChild` | Fully custom layout |
+
+---
+
+## Next Steps
+
+- **[Components Overview](./index.md)** - BaseComponent and renderer pattern
+- **[Getting Started](./getting-started.md)** - Register default renderers

package/docs/components/context-menu.md

@@ -0,0 +1,118 @@
+---
+title: Context Menu
+description: Right-click context menu with trigger binding, items, groups, and dividers
+---
+
+# Context Menu
+
+```javascript
+import { ContextMenu, ContextMenuGroup, ContextMenuItem } from 'native-document/components';
+import { Menu, MenuGroup, MenuItem, MenuDivider, MenuLink } from 'native-document/components';
+```
+
+`ContextMenu.use()` takes two arguments - a renderer and a handler. The handler wires the right-click behavior to any element, making `.nd.contextMenu()` available on all elements.
+
+## Default Renderer
+
+```javascript
+import {
+    ContextMenuRender, contextMenuHandler,
+    MenuRender, MenuGroupRender, MenuItemRender,
+    MenuDividerRender, MenuLinkRender
+} from 'native-document/ui';
+
+Menu.use(MenuRender);
+MenuGroup.use(MenuGroupRender);
+MenuItem.use(MenuItemRender);
+MenuDivider.use(MenuDividerRender);
+MenuLink.use(MenuLinkRender);
+ContextMenu.use(ContextMenuRender, contextMenuHandler);
+```
+
+## Building a Context Menu
+
+```javascript
+const tableContextMenu = ContextMenu()
+    .menu((menu) => {
+        menu
+            .item('Edit',      { action: (data) => openEdit(data) })
+            .item('Duplicate', { action: (data) => duplicate(data) })
+            .divider()
+            // pass a function to get the MenuItem instance for fluent configuration
+            .item('Delete', (item) => {
+                item
+                    .action((data) => deleteRow(data))
+                    .icon(TrashIcon)
+                    .shortcut('+Delete')
+                    .danger()
+            })
+    });
+
+// Attach to any element, pass contextual data
+TableRow(item)
+    .nd.contextMenu(tableContextMenu, item)
+```
+
+## Methods
+
+```javascript
+.menu((menu) => { menu.item(...) })
+.position(x, y)
+.show()
+.hide()
+.trigger(element)
+```
+
+## `ContextMenuItem`
+
+```javascript
+ContextMenuItem()
+    .label('Edit')
+    .icon(EditIcon)
+    .action((data) => openEditor(data))
+    .shortcut('+E')        // short convention: + = meta/ctrl, ++ = meta+alt
+    .disabled(false)
+    .danger()
+```
+
+### Shortcut convention
+
+| Syntax | Meaning |
+|---|---|
+| `'+S'` | Ctrl/Cmd + S |
+| `'++S'` | Ctrl/Cmd + Alt + S |
+| `'+Shift+S'` | Ctrl/Cmd + Shift + S |
+| `'Ctrl+S'` | Standard form |
+| `'Cmd+Shift+S'` | Standard form |
+
+Shortcuts are displayed automatically per OS - Mac uses symbols (`⌘ S`), Windows uses labels (`Ctrl+S`).
+
+See **[ShortcutManager](./shortcut-manager.md)** for the full reference.
+
+## `ContextMenuGroup`
+
+Groups items under a label:
+
+```javascript
+ContextMenuGroup('File actions')
+    .item('New',  handler)
+    .item('Open', handler)
+    .divider()
+    .item('Save', handler)
+```
+
+---
+
+## Theming
+
+```css
+:root {
+    --context-menu-bg:                  var(--background);
+    --context-menu-border:              var(--gray-lite-3);
+    --context-menu-radius:              var(--radius-card);
+    --context-menu-shadow:              var(--shadow-lg);
+    --context-menu-z-index:             99999;
+    --context-menu-min-width:           180px;
+    --context-menu-animation-duration:  0.12s;
+}
+```