native-document 1.0.16 → 1.0.17-1.2

package/docs/cache.md

@@ -0,0 +1,180 @@
+---
+title: Cache
+description: Lazy initialization, singleton patterns, and key-based memoization utilities
+---
+
+# Cache
+
+NativeDocument provides three caching utilities for optimizing function execution: lazy initialization, eager singletons, and key-based memoization.
+
+```javascript
+import { utils } from 'native-document';
+const { Cache } = utils;
+
+// Or
+import { Cache } from 'native-document/utils';
+```
+
+---
+
+## `Cache.once(fn)` - Lazy Initialization
+
+The function is **not executed immediately**. It runs only when you access a property on the returned Proxy object. The result is cached after the first access.
+
+```javascript
+const Config = Cache.once(() => {
+    console.log('Loading config...');
+    return {
+        apiUrl:     'https://api.example.com',
+        timeout:    5000,
+        maxRetries: 3
+    };
+});
+
+// Function not executed yet
+Config.apiUrl; // "Loading config..." -> "https://api.example.com"
+Config.timeout; // no log -> 5000 (cached)
+```
+
+Use for optional features or heavy modules that may not always be needed:
+
+```javascript
+const API = Cache.once(() => {
+    const client = new NativeFetch('https://api.example.com');
+    client.interceptors.request(config => {
+        config.headers['Authorization'] = `Bearer ${getToken()}`;
+        return config;
+    });
+    return {
+        users: {
+            list: ()   => client.get('/users'),
+            get:  (id) => client.get(`/users/${id}`)
+        }
+    };
+});
+
+// Client created only on first use
+const users = await API.users.list();
+```
+
+---
+
+## `Cache.singleton(fn)` - Eager Singleton
+
+The function executes on the **first call** and caches the result. All subsequent calls return the same instance.
+
+```javascript
+const getLogger = Cache.singleton(() => {
+    console.log('Creating logger...');
+    return {
+        log:   msg => console.log(`[LOG] ${msg}`),
+        error: msg => console.error(`[ERROR] ${msg}`)
+    };
+});
+
+const logger  = getLogger(); // "Creating logger..."
+const logger2 = getLogger(); // no log
+console.log(logger === logger2); // true
+```
+
+Use for core services that must exist exactly once:
+
+```javascript
+const getConfig = Cache.singleton(() => ({
+    apiUrl:  import.meta.env.VITE_API_URL,
+    debug:   import.meta.env.DEV,
+    version: '1.0.0'
+}));
+
+const getAPI = Cache.singleton(() => {
+    const config = getConfig();
+    const client = new NativeFetch(config.apiUrl);
+    client.interceptors.request(req => {
+        const token = localStorage.getItem('token');
+        if (token) {
+            req.headers['Authorization'] = `Bearer ${token}`;
+        }
+        return req;
+    });
+    return client;
+});
+```
+
+---
+
+## `Cache.memoize(fn)` - Key-Based Memoization
+
+Each property access creates and caches a **separate instance** using the property name as the key argument.
+
+```javascript
+const Endpoints = Cache.memoize((resource) => {
+    console.log(`Creating endpoint: ${resource}`);
+    const api = getAPI();
+    return {
+        list:   (params = {}) => api.get(`/${resource}`, params),
+        get:    (id)          => api.get(`/${resource}/${id}`),
+        create: (data)        => api.post(`/${resource}`, data),
+        update: (id, data)    => api.put(`/${resource}/${id}`, data),
+        delete: (id)          => api.delete(`/${resource}/${id}`)
+    };
+});
+
+await Endpoints.users.list();    // "Creating endpoint: users"
+await Endpoints.users.get('1');  // no log - cached
+await Endpoints.posts.list();    // "Creating endpoint: posts"
+```
+
+Use for resources that share the same structure but need separate instances per key:
+
+```javascript
+// Namespaced localStorage
+const Storage = Cache.memoize((namespace) => ({
+    get:    (key) => JSON.parse(localStorage.getItem(`${namespace}:${key}`)),
+    
+    set:    (key, val) => localStorage.setItem(`${namespace}:${key}`, JSON.stringify(val)),
+    
+    remove: (key) => localStorage.removeItem(`${namespace}:${key}`)
+}));
+
+Storage.user.set('theme', 'dark');
+Storage.app.set('version', '1.0.0');
+
+// Form fields with observables
+const Fields = Cache.memoize(name => ({
+    value:  Observable(''),
+    error:  Observable(null),
+    reset:  () => { Fields[name].value.set(''); Fields[name].error.set(null); }
+}));
+
+Fields.email.value.set('alice@example.com');
+Fields.password.value.set('secret');
+```
+
+---
+
+## Comparison
+
+| | `Cache.once()` | `Cache.singleton()` | `Cache.memoize()` |
+|---|---|---|---|
+| **Execution** | Lazy - on property access | Eager - on first call | Lazy - per key on property access |
+| **Access** | `obj.property` | `fn()` | `obj.key.method()` |
+| **Instances** | 1 | 1 | 1 per key |
+| **Best for** | Optional modules | Core services | Resources by type |
+
+---
+
+## Best Practices
+
+1. Use `Cache.singleton()` for core services (API client, config, logger)
+2. Use `Cache.once()` for optional or heavy modules that may not be needed
+3. Use `Cache.memoize()` for resources that share structure but need separate instances
+4. Keep memoize keys simple and predictable - avoid dynamic or timestamp-based keys
+5. Be aware that `Cache.memoize()` instances stay in memory - use only for a finite set of keys
+
+---
+
+## Next Steps
+
+- **[NativeFetch](./native-fetch.md)** - HTTP client with interceptors
+- **[State Management](./state-management.md)** - Global state with Store
+- **[Observables](./observables.md)** - Reactive state management

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