native-document 1.0.166 → 1.0.168

package/docs/cli.md

@@ -0,0 +1,179 @@
+---
+title: CLI
+description: The official NativeDocument CLI for scaffolding projects, pages, components, and services
+---
+
+# CLI
+
+The official NativeDocument CLI scaffolds projects, pages, components, and services so you can focus on building.
+
+## Installation
+
+```bash
+npm install -g @native-document/cli
+```
+
+Verify:
+
+```bash
+nd --help
+```
+
+> Source: [github.com/afrocodeur/native-document-cli](https://github.com/afrocodeur/native-document-cli)
+
+---
+
+## `nd create` - New Project
+
+### Default structure
+
+```bash
+nd create MyApp
+cd MyApp
+npm install
+npm start
+```
+
+### Feature-based structure
+
+```bash
+nd create MyApp --feature
+```
+
+Use `--feature` when you want to organize code by domain feature rather than by file type.
+
+---
+
+## Project Structures
+
+### Default
+
+```
+src/
+├── main.js
+├── index.css
+├── core/
+│   ├── lang/
+│   │   ├── lang.js
+│   │   └── locales/
+│   │       ├── en.json
+│   │       └── fr.json
+│   ├── middlewares/
+│   └── services/
+├── routes/
+│   ├── routes.js
+│   └── layouts/
+│       └── DefaultLayout/
+├── components/
+├── pages/
+│   ├── home/
+│   │   ├── HomePage.js
+│   │   └── home.css
+│   └── not-found/
+│       ├── NotFoundPage.js
+│       └── not-found.css
+└── services/
+```
+
+### Feature-based (`--feature`)
+
+Same root structure, plus a `src/features/` folder. Each feature is self-contained:
+
+```
+src/features/auth/
+├── components/
+├── services/
+│   └── AuthService/
+│       └── AuthService.js
+├── utils/
+└── index.js       # public API - import from here
+```
+
+Import from a feature via its public API:
+
+```javascript
+import { AuthService } from '@/features/auth';
+```
+
+---
+
+## Generator Commands
+
+### `nd create:page`
+
+Scaffold a new page:
+
+```bash
+nd create:page dashboard
+nd create:page user/profile    # nested page
+```
+
+Generates a page folder with component and CSS file inside `src/pages/`.
+
+### `nd create:component`
+
+Scaffold a reusable component:
+
+```bash
+nd create:component UserCard
+nd create:component ui/Button  # nested component
+```
+
+Generates a component folder inside `src/components/`.
+
+### `nd create:service`
+
+Scaffold a service (business logic + observables):
+
+```bash
+nd create:service AuthService
+nd create:service api/UserService
+```
+
+Generates a service folder inside `src/services/`.
+
+### `nd create:feature` (feature mode only)
+
+Scaffold a complete feature module:
+
+```bash
+nd create:feature auth
+nd create:feature cart
+```
+
+Generates a feature folder inside `src/features/` with its own components, services, and `index.js`.
+
+---
+
+## Available Scripts
+
+After creating a project:
+
+```bash
+npm start          # start development server (Vite)
+npm run build      # build for production
+npm run preview    # preview the production build
+npm run lint       # run ESLint
+npm run i18n:scan  # scan for missing translation keys
+```
+
+---
+
+## Aliases
+
+The `@` alias points to `src/` and is pre-configured in Vite:
+
+```javascript
+import { AuthService } from '@/services/AuthService';
+import { UserCard }    from '@/components/UserCard';
+import { AuthService } from '@/features/auth'; // feature mode
+```
+
+---
+
+## Next Steps
+
+- **[Getting Started](./getting-started.md)** - First steps after `nd create`
+- **[Routing](./routing.md)** - Define routes in `src/routes/routes.js`
+- **[State Management](./state-management.md)** - Organize state with Store groups
+- **[i18n & Formatting](./i18n.md)** - Set up translations and locale formatting

package/docs/components/accordion.md

@@ -0,0 +1,172 @@
+---
+title: Accordion
+description: Headless Accordion component with multiple expand, variants, and item management
+---
+
+# Accordion
+
+```javascript
+import { Accordion, AccordionItem } from 'native-document/components';
+```
+
+```javascript
+Accordion(props?)
+```
+
+
+## Default Renderers
+
+```javascript
+import { AccordionRender, AccordionItemRender } from 'native-document/ui';
+
+Accordion.use(AccordionRender);
+AccordionItem.use(AccordionItemRender);
+```
+
+---
+
+## `$description`
+
+```javascript
+{
+    items:           [],    // AccordionItem[]
+        multiple:        null,  // boolean - allow multiple open at once
+        variant:         null,  // string
+        renderContent:   null,  // (item) => element - custom content renderer
+        renderIndicator: null,  // (item) => element - custom indicator renderer
+        props:           {} // HTML attributes for the root element
+}
+```
+
+## Methods
+
+### Adding items
+
+```javascript
+// Add by title + content
+Accordion()
+    .item('Section 1', Div('Content 1'))
+    .item('Section 2', Div('Content 2'), { expanded: true, disabled: false })
+
+// Add AccordionItem instance
+Accordion()
+    .item(
+        AccordionItem()
+            .title('Section')
+            .content(Div('Content'))
+    )
+
+// Add multiple at once
+Accordion()
+    .items([
+        { title: 'A', content: Div('Content A') },
+        { title: 'B', content: Div('Content B') }
+    ])
+```
+
+### Behavior
+
+```javascript
+.multiple()         // allow multiple panels open at once
+    .multiple(false)    // only one panel at a time (default)
+```
+
+### Variants
+
+```javascript
+.bordered()    // adds borders
+    .separated()   // space between items
+    .flush()       // no borders, no padding
+```
+
+### Expand / Collapse
+
+```javascript
+.expanded(key, true)   // expand item by key
+    .expanded(key, false)  // collapse item by key
+    .expandAll()
+    .collapseAll()
+    .isExpanded(key)       // returns boolean
+    .getByKey(key)         // returns AccordionItem
+```
+
+### Remove items
+
+```javascript
+.removeItemById(id)
+    .remove(item => item.id === 'my-id') // filter function
+```
+
+### Events
+
+```javascript
+Accordion()
+    .onExpand((item)   => console.log('Expanded:', item.title))
+    .onCollapse((item) => console.log('Collapsed:', item.title))
+```
+
+### Custom renderers
+
+```javascript
+.renderContent(($item) => Div({ class: 'custom-body' }, $item.content))
+    .renderIndicator(($item) => $item.expanded.transform(e => e ? '-' : '+'))
+```
+
+## `AccordionItem`
+
+```javascript
+AccordionItem()
+    .identifyBy('item-1')
+    .title('Section Title')
+    .content(Div('Content'))
+    .icon(InfoIcon)
+    .expanded()
+    .collapsible()
+    .disabled()
+    .showIndicator()
+    .renderHeader(($item) => Div({ class: 'header' }, $item.title))
+    .renderContent(($item) => Div({ class: 'body' }, $item.content))
+    .renderIndicator(($item) => $item.expanded.transform(e => e ? '-' : '+'))
+    .onExpand(() => console.log('Expanded'))
+    .onCollapse(() => console.log('Collapsed'))
+```
+
+## Example
+
+```javascript
+const faq = Accordion()
+    .bordered()
+    .item('What is NativeDocument?',
+        P('A reactive JavaScript framework without Virtual DOM.')
+    )
+    .item('How do I install it?',
+        Div([
+            P('Use the CLI:'),
+            Pre('nd create my-app')
+        ]),
+        { expanded: true }
+    )
+    .item('Is it free?', P('Yes, MIT licensed.'))
+    .onExpand(item => trackFAQ(item.id))
+
+document.body.appendChild(faq)
+```
+
+---
+
+## Theming
+
+```css
+:root {
+    --accordion-border:           var(--gray-lite-3);
+    --accordion-radius:           var(--radius-card);
+    --accordion-font-size:        var(--description-size);
+    --accordion-header-padding:   var(--space-comfortable);
+    --accordion-content-padding:  var(--space-comfortable);
+    --accordion-header-color:     var(--text-color);
+    --accordion-header-color-hover: var(--text-color);
+    --accordion-header-bg-hover:  var(--gray-lite-5);
+    --accordion-indicator-color:  var(--gray);
+    --accordion-transition:       0.2s ease;
+}
+```

package/docs/components/alert.md

@@ -0,0 +1,99 @@
+---
+title: Alert
+description: Contextual message component with title, icon, actions, and auto-dismiss
+---
+
+# Alert
+
+```javascript
+import { Alert } from 'native-document/components';
+
+Alert(content, props?)
+```
+
+Displays a contextual message with optional title, icon, and actions.
+
+## Default Renderer
+
+```javascript
+import { AlertRender } from 'native-document/ui';
+import { ButtonRender } from 'native-document/ui';
+
+Alert.use(AlertRender);
+Button.use(ButtonRender); // required - actions are rendered as buttons
+```
+
+## Methods
+
+```javascript
+// Type
+.info()
+    .success()
+    .warning()
+    .error()
+    .danger()
+
+    // Appearance
+    .filled()
+    .bordered()
+    .outline()
+
+    // Content
+    .title('Alert title')
+    .content(Div('Updated content'))
+    .icon(InfoIcon)
+    .showIcon()
+    .closable()
+    .dismissible()
+    .autoDismiss(3000)
+
+    // Actions
+    .action('Undo', () => undo())
+    .action('Retry', retryFn)
+    .clearActions()
+
+    // Events
+    .onClose(() => console.log('Closed'))
+    .onShow(() => console.log('Shown'))
+
+    // Programmatic
+    .close()
+    .show()
+
+    // Custom renderers
+    .renderTitle(($description) => Strong($description.title))
+    .renderContent(($description) => P($description.content))
+    .renderFooter(($description) => Div($description.actions))
+    .layout(($description) => Div([$description.title, $description.content, $description.footer]))
+```
+
+## Example
+
+```javascript
+Alert('Your changes have been saved successfully.')
+    .success()
+    .filled()
+    .title('Saved!')
+    .icon(CheckIcon)
+    .action('Undo', () => undo())
+```
+
+---
+
+## Theming
+
+```css
+:root {
+    --alert-padding:        var(--space-comfortable);
+    --alert-radius:         var(--radius-card);
+    --alert-gap:            var(--space-cozy);
+    --alert-font-size:      var(--description-size);
+    --alert-title-size:     var(--text-size);
+    --alert-title-weight:   600;
+    --alert-border-width:   1px;
+    --alert-color-info:     var(--color-info);
+    --alert-color-success:  var(--color-success);
+    --alert-color-warning:  var(--color-warning);
+    --alert-color-danger:   var(--color-danger);
+}
+```

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