native-document 1.0.166 → 1.0.169

package/docs/components/icons.md

@@ -0,0 +1,321 @@
+---
+title: Icons
+description: Adapter-based icon system with chainable API and support for Tabler, Phosphor, and Google Material Icons
+---
+
+# Icons
+
+NativeDocument provides an adapter-based icon system. Icon names are semantic and stable - switching from one icon library to another requires changing only the adapter and the CSS import.
+
+```javascript
+// Usage - always via the Icon namespace
+Icon.search.fill()
+Icon.star.fill().large()
+Icon.arrowRight.bold().color('red')
+Icon.user.fill().size(32)
+```
+
+---
+
+## Setup
+
+### 1. Register the adapter
+
+In your app entry point (`main.js`):
+
+```javascript
+import { Icon }         from 'native-document/icons';
+import TablerIconRender from 'native-document/ui/icon/tabler';
+
+Icon.use(TablerIconRender, {
+    variant: 'outline',  // default variant
+    size:    'medium',   // default size: small | medium | large | extraLarge
+});
+```
+
+### 2. Import the CSS
+
+In the same entry point, import the icon font alongside your theme:
+
+```javascript
+// main.js
+import 'native-document/src/ui/theme.scss';
+import '@tabler/icons-webfont/dist/tabler-icons.css';
+```
+
+---
+
+## Methods
+
+### Variants
+
+| Method | Sets variant to |
+|---|---|
+| `.thin()` | `'thin'` |
+| `.light()` | `'light'` |
+| `.regular()` | `'regular'` |
+| `.bold()` | `'bold'` |
+| `.fill()` | `'fill'` |
+| `.duotone()` | `'duotone'` |
+| `.variant(name)` | any custom string |
+
+### Sizes
+
+| Method | Sets size to |
+|---|---|
+| `.small()` | `'small'` - 16px |
+| `.medium()` | `'medium'` - 24px |
+| `.large()` | `'large'` - 32px |
+| `.extraLarge()` | `'extraLarge'` - 48px |
+| `.size(value)` | number in px or named string |
+
+### Other
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.color(value)` | `value: string` | CSS color value |
+| `.weight(value)` | `value: string` | Stroke weight (adapter-dependent) |
+
+All methods accept `Observable` values - the icon updates automatically when the observable changes:
+
+```javascript
+const isDark = Observable(false);
+
+Icon.star
+    .variant(isDark.transform((d) => d ? 'fill' : 'outline'))
+    .color(isDark.transform((d) => d ? 'gold' : 'currentColor'))
+```
+
+---
+
+## Available icons
+
+> The standard set covers the most common use cases. Each adapter maps these names to its own icon names - not every icon exists in every library.
+
+### Navigation
+`Icon.arrowLeft`, `Icon.arrowRight`, `Icon.arrowUp`, `Icon.arrowDown`, `Icon.chevronLeft`, `Icon.chevronRight`, `Icon.chevronUp`, `Icon.chevronDown`, `Icon.home`, `Icon.menu`, `Icon.close`, `Icon.back`, `Icon.forward`, `Icon.expand`, `Icon.collapse`, `Icon.fullscreen`, `Icon.fullscreenExit`
+
+### Actions
+`Icon.search`, `Icon.filter`, `Icon.sort`, `Icon.edit`, `Icon.delete`, `Icon.add`, `Icon.remove`, `Icon.save`, `Icon.copy`, `Icon.download`, `Icon.upload`, `Icon.share`, `Icon.refresh`, `Icon.more`, `Icon.settings`, `Icon.drag`, `Icon.resize`, `Icon.undo`, `Icon.redo`, `Icon.scan`, `Icon.print`, `Icon.import`, `Icon.export`
+
+### Feedback
+`Icon.check`, `Icon.checkCircle`, `Icon.error`, `Icon.warning`, `Icon.info`, `Icon.help`, `Icon.loading`, `Icon.success`
+
+### User
+`Icon.user`, `Icon.userCircle`, `Icon.users`, `Icon.lock`, `Icon.unlock`, `Icon.eye`, `Icon.eyeOff`, `Icon.bell`, `Icon.notification`
+
+### Files & Media
+`Icon.file`, `Icon.folder`, `Icon.image`, `Icon.document`, `Icon.attachment`, `Icon.link`, `Icon.externalLink`, `Icon.play`, `Icon.pause`, `Icon.stop`, `Icon.mute`, `Icon.sound`, `Icon.video`, `Icon.camera`
+
+### Interface
+`Icon.grid`, `Icon.list`, `Icon.calendar`, `Icon.clock`, `Icon.tag`, `Icon.tags`, `Icon.qrCode`, `Icon.barcode`
+
+### Text editing
+`Icon.bold`, `Icon.italic`, `Icon.underline`, `Icon.strikethrough`, `Icon.alignLeft`, `Icon.alignCenter`, `Icon.alignRight`, `Icon.alignJustify`, `Icon.orderedList`, `Icon.unorderedList`, `Icon.indent`, `Icon.outdent`, `Icon.scissors`, `Icon.fontColor`, `Icon.highlight`
+
+### Data & charts
+`Icon.barChart`, `Icon.lineChart`, `Icon.pieChart`, `Icon.areaChart`, `Icon.table`, `Icon.database`
+
+### Commerce & finance
+`Icon.shoppingCart`, `Icon.creditCard`, `Icon.wallet`, `Icon.bank`, `Icon.gift`, `Icon.percentage`, `Icon.dollar`, `Icon.euro`
+
+### Communication
+`Icon.mail`, `Icon.message`, `Icon.comment`, `Icon.phone`
+
+### System & dev
+`Icon.cloud`, `Icon.cloudUpload`, `Icon.cloudDownload`, `Icon.api`, `Icon.code`, `Icon.bug`, `Icon.tool`, `Icon.robot`
+
+### Location
+`Icon.map`, `Icon.compass`, `Icon.global`, `Icon.location`
+
+### Shapes & objects
+`Icon.star`, `Icon.heart`, `Icon.flag`, `Icon.trophy`, `Icon.medal`, `Icon.rocket`, `Icon.fire`, `Icon.thunder`, `Icon.smile`, `Icon.frown`, `Icon.like`, `Icon.dislike`, `Icon.safety`, `Icon.key`
+
+---
+
+## Custom icons
+
+Create your own renderer that wraps the base adapter. Use NativeDocument elements for reactive support:
+
+```javascript
+import { Img, Span, ShowIf } from 'native-document/elements';
+import TablerIconRender from 'native-document/ui/icon/tabler/TablerIconRender';
+
+function MyIconRender($desc) {
+    // Handle your custom icons
+    if ($desc.name === 'logo' || $desc.name === 'dashboard') {
+        const size = $desc.size?.__$Observable
+            ? $desc.size.transform((s) => typeof s === 'number' ? `${s}px` : `${SIZES[s] ?? 24}px`)
+            : `${typeof $desc.size === 'number' ? $desc.size : 24}px`;
+
+        return Img({
+            src: `/icons/${$desc.name}.svg`,
+            'aria-hidden': 'true',
+            style: {
+                width:  size,
+                height: size,
+                color:  $desc.color ?? 'currentColor',
+            },
+        });
+    }
+
+    // Fall back to Tabler for everything else
+    return TablerIconRender($desc);
+}
+
+Icon.use(MyIconRender, { size: 'medium' });
+```
+
+---
+
+## Adapters
+
+### Tabler Icons
+
+> Outline and filled variants - the standard set covers the most common icons from Tabler's library.
+
+**Install**
+
+```bash
+npm install @tabler/icons-webfont
+```
+
+**main.js**
+
+```javascript
+import { Icon }         from 'native-document/icons';
+import TablerIconRender from 'native-document/ui/icon/tabler';
+import 'native-document/src/ui/theme.scss';
+import '@tabler/icons-webfont/dist/tabler-icons.css';
+
+// Uncomment to enable .fill() variant
+// import '@tabler/icons-webfont/dist/tabler-icons-filled.css';
+
+Icon.use(TablerIconRender, { variant: 'outline', size: 'medium' });
+```
+
+**Supported variants**
+
+| Variant | Description | Required CSS |
+|---|---|---|
+| `outline` (default) | Stroked icons | `tabler-icons.css` |
+| `fill` | Filled icons | `tabler-icons-filled.css` |
+
+**Example**
+
+```javascript
+Icon.search              // outline, medium
+Icon.search.fill()       // filled
+Icon.star.fill().large() // filled, 32px
+```
+
+---
+
+### Phosphor Icons
+
+> 6 weights - the standard set covers the most common icons from Phosphor's library.
+
+**Install**
+
+```bash
+npm install @phosphor-icons/web
+```
+
+**main.js**
+
+```javascript
+import { Icon }           from 'native-document/icons';
+import PhosphorIconRender from 'native-document/ui/icon/phosphor';
+import 'native-document/src/ui/theme.scss';
+
+// Check the exact path in your node_modules/@phosphor-icons/web/ directory
+import '@phosphor-icons/web/src/regular/style.css';
+
+// Import only the weights you need
+// import '@phosphor-icons/web/src/thin/style.css';
+// import '@phosphor-icons/web/src/light/style.css';
+// import '@phosphor-icons/web/src/bold/style.css';
+// import '@phosphor-icons/web/src/fill/style.css';
+// import '@phosphor-icons/web/src/duotone/style.css';
+
+Icon.use(PhosphorIconRender, { variant: 'regular', size: 'medium' });
+```
+
+> The CSS path may vary depending on the installed version. If you get a resolve error, run `ls node_modules/@phosphor-icons/web/` to find the correct path.
+
+**Supported variants**
+
+| Variant | Description | Required CSS |
+|---|---|---|
+| `thin` | Thinnest stroke | `thin/style.css` |
+| `light` | Light stroke | `light/style.css` |
+| `regular` (default) | Standard stroke | `regular/style.css` |
+| `bold` | Bold stroke | `bold/style.css` |
+| `fill` | Filled | `fill/style.css` |
+| `duotone` | Two-tone | `duotone/style.css` |
+
+**Example**
+
+```javascript
+Icon.search                // regular, medium
+Icon.search.bold()         // bold
+Icon.star.fill().large()   // filled, 32px
+Icon.heart.duotone()       // duotone
+```
+
+---
+
+### Google Material Icons
+
+> Filled, outlined, round, sharp, two-tone - the standard set covers the most common icons from Material's library.
+
+**Install**
+
+```bash
+npm install material-icons
+```
+
+**main.js**
+
+```javascript
+import { Icon }           from 'native-document/icons';
+import MaterialIconRender from 'native-document/ui/icon/material';
+import 'native-document/src/ui/theme.scss';
+import 'material-icons/iconfont/filled.css';
+
+// Import only the styles you need
+// import 'material-icons/iconfont/outlined.css';
+// import 'material-icons/iconfont/round.css';
+// import 'material-icons/iconfont/sharp.css';
+// import 'material-icons/iconfont/two-tone.css';
+
+Icon.use(MaterialIconRender, { variant: 'fill', size: 'medium' });
+```
+
+**Supported variants**
+
+| Variant | Description | Required CSS |
+|---|---|---|
+| `fill` / `regular` (default) | Filled icons | `filled.css` |
+| `outline` | Outlined icons | `outlined.css` |
+| `round` | Rounded icons | `round.css` |
+| `sharp` | Sharp corners | `sharp.css` |
+| `twoTone` | Two-tone icons | `two-tone.css` |
+
+> Material Icons uses **ligatures** - the icon name is the text content of the element, converted to an icon by the font. This is handled automatically by the renderer.
+
+**Example**
+
+```javascript
+Icon.search                       // filled, medium
+Icon.search.variant('outline')    // outlined
+Icon.star.large()                 // filled, 32px
+```
+
+---
+
+## Next Steps
+
+- **[Components Overview](./index.md)** - BaseComponent and renderer pattern
+- **[Getting Started](./getting-started.md)** - Register default renderers
+- **[Theming](../theming.md)** - CSS tokens reference

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