native-document 1.0.15 → 1.0.16-8.2

package/docs/components/avatar.md

@@ -0,0 +1,160 @@
+---
+title: Avatar
+description: Avatar and AvatarGroup components for displaying user profile pictures, initials, or icons
+---
+
+# Avatar
+
+```javascript
+import { Avatar, AvatarGroup } from 'native-document/components';
+
+Avatar(source?, props?)
+```
+
+## Default Renderer
+
+```javascript
+import { AvatarRender, AvatarGroupRender } from 'native-document/ui';
+
+Avatar.use(AvatarRender);
+AvatarGroup.use(AvatarGroupRender);
+```
+
+## `$description`
+
+```javascript
+{
+    src:       null,     // string | Observable<string>
+    alt:       null,
+    name:      null,     // full name - initials auto-generated
+    initials:  null,     // explicit initials override
+    icon:      null,     // DOM element fallback
+    size:      'medium', // 'xs' | 'small' | 'medium' | 'large' | 'xl'
+    shape:     'circle', // 'circle' | 'square' | 'rounded'
+    variant:   null,     // background color variant
+    color:     null,     // custom background color
+    textColor: null,
+    status:    null,     // 'online' | 'offline' | 'busy' | 'away'
+    props:     {} // HTML attributes for the root element
+}
+```
+
+## Methods
+
+```javascript
+// Source
+.src('/images/alice.jpg')
+.src(Observable('/api/user/avatar'))  // reactive
+.alt('Alice Johnson')
+
+// Name & initials
+.name('Alice Johnson')    // auto-generates initials 'AJ'
+.initials('AJ')           // explicit initials
+
+// Fallback when no src
+.icon(UserIcon)
+
+// Size
+.extraSmall()
+.small()
+.medium()
+.large()
+.extraLarge()
+
+// Shape
+.circle()
+.square()
+.rounded()
+
+// Color (for initials/icon fallback)
+.primary()
+.success()
+.danger()
+.warning()
+.info()
+.color('#6366f1')
+.textColor('#fff')
+
+// Status indicator
+.status('online')   // green dot
+.status('offline')  // gray dot
+.status('busy')     // red dot
+.status('away')     // yellow dot
+.statusAtTopLeading()
+.statusAtBottomLeading()
+.statusAtTopTrailing()
+.statusAtBottomTrailing()
+```
+
+## Example
+
+```javascript
+Avatar(user.avatar)
+    .name(user.name)
+    .status(user.status)
+    .large()
+
+// With initials fallback
+Avatar()
+    .name('Alice Johnson')
+    .primary()
+    .circle()
+```
+
+---
+
+## `AvatarGroup`
+
+```javascript
+AvatarGroup(props?)
+```
+
+Displays a stack of overlapping avatars.
+
+### Methods
+
+```javascript
+.item(avatar)                       // add an Avatar instance
+.items([avatar1, avatar2])          // add multiple
+.max(5)                             // show max N avatars, then "+N more"
+.overlap(12)                        // overlap in px
+.onMoreClick((count) => showAll())  // callback when "+N" is clicked
+```
+
+### Example
+
+```javascript
+AvatarGroup()
+    .item(Avatar(user1.avatar).name(user1.name))
+    .item(Avatar(user2.avatar).name(user2.name))
+    .item(Avatar(user3.avatar).name(user3.name))
+    .max(5)
+    .overlap(12)
+    .onMoreClick((count) => showAllMembers())
+```
+
+---
+
+## Theming
+
+```css
+:root {
+    --avatar-size-extra-small:    24px;
+    --avatar-size-small:          32px;
+    --avatar-size-medium:         40px;
+    --avatar-size-large:          56px;
+    --avatar-size-extra-large:    72px;
+    --avatar-status-size:         10px;
+    --avatar-status-offset:       1px;
+    --avatar-color-primary:       var(--color-primary);
+    --avatar-color-secondary:     var(--color-secondary);
+    --avatar-color-success:       var(--color-success);
+    --avatar-color-danger:        var(--color-danger);
+    --avatar-color-warning:       var(--color-warning);
+    --avatar-color-info:          var(--color-info);
+    /* AvatarGroup */
+    --avatar-group-overlap:       -15px;
+    --avatar-group-more-text-color:       var(--white);
+    --avatar-group-more-background-color: var(--gray-lite-4);
+}
+```

package/docs/components/badge.md

@@ -0,0 +1,102 @@
+---
+title: Badge
+description: Small inline label for status, count, or category
+---
+
+# Badge
+
+```javascript
+import { Badge } from 'native-document/components';
+
+Badge(content, props?)
+```
+
+A small inline label for status, count, or category.
+
+## Default Renderer
+
+```javascript
+import { BadgeRender } from 'native-document/ui';
+
+Badge.use(BadgeRender);
+```
+
+## `$description`
+
+```javascript
+{
+    appearance:       'filled',   // 'filled' | 'outlined' | 'ghost'
+    borderRadiusType: 'pill',
+    variant:          'primary',
+    size:             'medium',
+    content:          null,
+    icon:             null,
+    iconPosition:     'leading',
+    props:            {} // HTML attributes for the root element
+}
+```
+
+## Methods
+
+```javascript
+// Variants
+.primary()
+.secondary()
+.success()
+.danger()
+.warning()
+.info()
+
+// Appearance
+.filled()
+.outlined()
+.ghost()
+
+// Size
+.small()
+.medium()
+.large()
+
+// Shape
+.rounded()
+.pill()
+.circle()
+
+// Icon
+.icon(element, position?)
+
+// Event
+.onClick(handler)
+```
+
+## Example
+
+```javascript
+Badge('New').primary().pill()
+Badge(count).danger()
+Badge('Beta').outlined().warning()
+```
+
+---
+
+## Theming
+
+```css
+:root {
+    --badge-height-small:        18px;
+    --badge-height-medium:       22px;
+    --badge-height-large:        28px;
+    --badge-padding-small:       0 var(--space-cozy);
+    --badge-padding-medium:      0 var(--space-cozy-comfortable);
+    --badge-padding-large:       0 var(--space-comfortable);
+    --badge-font-size-small:     var(--diablo-size);
+    --badge-font-size-medium:    var(--note-size);
+    --badge-font-size-large:     var(--description-size);
+    --badge-color-primary:       var(--color-primary);
+    --badge-color-secondary:     var(--color-secondary);
+    --badge-color-success:       var(--color-success);
+    --badge-color-danger:        var(--color-danger);
+    --badge-color-warning:       var(--color-warning);
+    --badge-color-info:          var(--color-info);
+}
+```

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