native-document 1.0.166 → 1.0.168

package/docs/i18n.md

@@ -0,0 +1,241 @@
+---
+title: i18n & Formatting
+description: Built-in internationalization with locale-aware formatting, translation helpers, and automatic locale switching
+---
+
+# i18n & Formatting
+
+NativeDocument has built-in i18n support via `Observable.format()` for locale-aware value formatting, and a `tr()` translation helper for string translations. Both react automatically when the locale changes.
+
+---
+
+## Setup
+
+Call `I18nService.use()` at startup with the user's locale, then pass `I18nService.current` to `Observable.setLocale()`:
+
+```javascript
+import { Observable } from 'native-document';
+import { I18nService } from 'native-document/i18n';
+
+I18nService.use(navigator.language.split('-')[0] || 'en');
+Observable.setLocale(I18nService.current);
+```
+
+To switch locale at any time:
+
+```javascript
+I18nService.use('en');
+I18nService.use('fr');
+```
+
+---
+
+## `Observable.format()` - Locale-Aware Formatting
+
+Once the locale is set, call `.format()` on any observable to create a derived observable that formats the value reactively:
+
+```javascript
+import { Observable } from 'native-document';
+import { I18nService } from 'native-document/i18n';
+
+Observable.setLocale(I18nService.current);
+
+const price = Observable(15000);
+const date  = Observable(new Date());
+const ratio = Observable(0.75);
+const count = Observable(3);
+
+// Currency
+Div(price.format('currency'))                          // "15 000 FCFA"
+Div(price.format('currency', { currency: 'EUR' }))    // "15 000,00 €"
+Div(price.format('currency', { notation: 'compact' })) // "15 K FCFA"
+
+// Number
+Div(price.format('number'))                            // "15 000"
+
+// Percent
+Div(ratio.format('percent'))                           // "75 %"
+Div(ratio.format('percent', { decimals: 1 }))          // "75,0 %"
+
+// Date
+Div(date.format('date'))                               // "3 mars 2026"
+Div(date.format('date', { dateStyle: 'full' }))        // "mardi 3 mars 2026"
+Div(date.format('date', { format: 'DD/MM/YYYY' }))     // "03/03/2026"
+
+// Time
+Div(date.format('time'))                               // "20:30"
+Div(date.format('time', { second: '2-digit' }))        // "20:30:00"
+
+// Datetime
+Div(date.format('datetime'))                           // "3 mars 2026, 20:30"
+
+// Relative
+Div(date.format('relative'))                           // "dans 11 jours"
+Div(date.format('relative', { unit: 'month' }))        // "dans 1 mois"
+
+// Plural
+Div(count.format('plural', { singular: 'billet', plural: 'billets' })) // "3 billets"
+
+// Custom transform
+Div(price.format(value => `${value.toLocaleString()} FCFA`))
+```
+
+Formatted observables update automatically when the locale changes:
+
+```javascript
+Observable.setLocale(I18nService.current);
+
+const label = Observable(15000).format('currency', { currency: 'XOF' });
+label.val(); // "15 000 FCFA" (fr)
+
+I18nService.use('en-US');
+label.val(); // "$15,000.00"
+```
+
+### Format types reference
+
+| Type | Input | Key options |
+|---|---|---|
+| `currency` | `number` | `currency`, `notation`, `minimumFractionDigits`, `maximumFractionDigits` |
+| `number` | `number` | `notation`, `minimumFractionDigits`, `maximumFractionDigits` |
+| `percent` | `number` | `decimals` |
+| `date` | `Date \| number` | `dateStyle`, `format` |
+| `time` | `Date \| number` | `hour`, `minute`, `second`, `format` |
+| `datetime` | `Date \| number` | `dateStyle`, `hour`, `minute`, `second`, `format` |
+| `relative` | `Date \| number` | `unit`, `numeric` |
+| `plural` | `number` | `singular`, `plural` |
+
+---
+
+## Extending Formatters
+
+Add custom format types via the `Formatters` object:
+
+```javascript
+import { Formatters } from 'native-document';
+
+Formatters.duration = (value, locale) => {
+    const hours   = Math.floor(value / 3600);
+    const minutes = Math.floor((value % 3600) / 60);
+    return `${hours}h${minutes.toString().padStart(2, '0')}`;
+};
+
+const duration = Observable(3661);
+Div(duration.format('duration')); // "1h01"
+```
+
+---
+
+## `tr()` - Translations
+
+The `tr()` helper returns a translated string for a given key. It is reactive - if the locale changes and the translation changes, the DOM updates automatically.
+
+```javascript
+import { tr } from 'native-document/i18n';
+
+// Basic usage
+Div(tr('welcome_message'))
+P(tr('errors.required'))
+
+// With interpolation
+Div(tr('greeting', { name: 'Alice' }))
+// -> "Hello Alice!" (en) or "Bonjour Alice !" (fr)
+```
+
+### Translation files
+
+The CLI template creates translation files in `src/core/lang/locales/`:
+
+```
+src/core/lang/locales/
+├── en.json
+└── fr.json
+```
+
+Example `en.json`:
+
+```json
+{
+    "welcome_message": "Welcome to my app",
+    "greeting": "Hello {{name}}!",
+    "errors": {
+        "required": "This field is required",
+        "invalid_email": "Please enter a valid email address"
+    },
+    "items": {
+        "singular": "{{count}} item",
+        "plural": "{{count}} items"
+    }
+}
+```
+
+Example `fr.json`:
+
+```json
+{
+    "welcome_message": "Bienvenue dans mon application",
+    "greeting": "Bonjour {{name}} !",
+    "errors": {
+        "required": "Ce champ est obligatoire",
+        "invalid_email": "Veuillez entrer une adresse email valide"
+    },
+    "items": {
+        "singular": "{{count}} élément",
+        "plural": "{{count}} éléments"
+    }
+}
+```
+
+---
+
+## Scanning for Missing Keys
+
+The CLI includes a script that scans your source files for `tr()` calls and reports any keys missing from your translation files:
+
+```bash
+npm run i18n:scan
+```
+
+Run this after adding new `tr()` calls to ensure all locales are complete.
+
+---
+
+## Switching Locale
+
+```javascript
+import { I18nService } from 'native-document/i18n';
+
+// Set a specific locale
+I18nService.use('en');
+I18nService.use('fr');
+
+// From user action
+Button('English').nd.onClick(() => I18nService.use('en'))
+Button('Français').nd.onClick(() => I18nService.use('fr'))
+```
+
+The locale is initialized at app startup via `I18nService.use()`:
+
+```javascript
+// In your app entry point (e.g. main.js)
+I18nService.use(navigator.language.split('-')[0] || 'en');
+Observable.setLocale(I18nService.current);
+```
+
+---
+
+## Best Practices
+
+1. Always call `Observable.setLocale()` before using `.format()` - ideally at app startup
+2. Use `I18nService.current` when using the CLI template
+3. Use nested keys in translation files to organize by feature: `errors.required`, `nav.home`
+4. Run `npm run i18n:scan` after adding new translations
+5. Use `Observable.format('plural', { singular, plural })` for count-based strings instead of manual logic
+
+---
+
+## Next Steps
+
+- **[Observables](./observables.md)** - Full `.format()` reference
+- **[State Management](./state-management.md)** - The built-in `locale` store
+- **[CLI](./cli.md)** - Project setup with i18n pre-configured

package/docs/index.md

@@ -0,0 +1,76 @@
+---
+layout: home
+
+hero:
+  name: NativeDocument
+  text: The declarative rendering of SwiftUI. The power of pure JavaScript.
+  tagline: No Virtual DOM. No proprietary syntax. No hook rules. Just modern, performant, predictable Vanilla JS.
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /getting-started
+    - theme: alt
+      text: GitHub
+      link: https://github.com/afrocodeur/native-document
+
+features:
+  - icon: ⚡
+    title: Surgical Reactivity
+    details: Your component function runs exactly once. When data changes, NativeDocument updates the exact DOM node in the background. Declarative expressiveness with Vanilla JS performance.
+
+  - icon: 🧠
+    title: Zero Cognitive Load
+    details: No complex mental model to maintain. No dependency arrays. No hook order rules. Your JavaScript closures stay intact and your execution flow is perfectly linear.
+
+  - icon: 🧩
+    title: Natural Component Communication
+    details: A child component is a living object, not a black box. Fluid, transparent parent-child communication without forwardRef, defineExpose, or global state overhead.
+
+  - icon: 🇬🇧
+    title: Fluent UI Logic
+    details: Express your rendering conditions as naturally as a sentence in English. When(isAdmin).show(AdminPanel).otherwise(UserPanel) - pure JS, readable at a glance.
+
+  - icon: 🚀
+    title: Official CLI
+    details: Scaffold a complete project in one command. nd create my-app. Default and feature-based architectures, i18n, routing and store pre-configured.
+
+  - icon: 🌲
+    title: True Tree-Shaking
+    details: Only bundle what you use. NativeDocument is designed for bundlers - Vite, Webpack, Rollup. Every import is individually tree-shakeable.
+---
+
+## Tired of fighting your framework?
+
+Building a modern UI should not require constant mental gymnastics. Sound familiar?
+
+- **Wild re-renders** - One variable changes and your entire component (or app) recalculates. The larger the app, the more the Virtual DOM weighs on memory.
+- **Hook prison** - Juggling `useEffect` order, managing infinite dependency arrays, hunting memory leaks.
+- **Magic syntax** - Learning pseudo-HTML or depending on a mystical compiler just to display a list or a condition.
+
+---
+
+## The proof is in the code
+
+```javascript
+import { $, Div, Button, Span } from 'native-document';
+
+export function Counter() {
+    const count = $(0);
+
+    return Div({ class: 'counter-card' }, [
+        Span(['Count: ', count]),
+        Button('Increment').nd.onClick(() => count.$value++)
+    ]);
+}
+```
+
+No JSX. No compiler. No rules. Just JavaScript.
+
+---
+
+## Ready to lighten your code?
+
+```bash
+npm install -g @native-document/cli
+nd create my-awesome-app
+```

package/docs/lifecycle-events.md

@@ -1,117 +1,185 @@
+---
+title: Lifecycle Events
+description: Execute code when elements are added to or removed from the DOM using mounted, unmounted, beforeUnmount, destroyOnUnmount, and destroy hooks
+---
+
 # Lifecycle Events
 
-NativeDocument provides lifecycle hooks that let you execute code when elements are added to or removed from the DOM. This is essential for setup, cleanup, and managing resources.
+NativeDocument provides lifecycle hooks that let you execute code when elements are added to or removed from the DOM. This is essential for setup, cleanup, and managing external resources.
+
+---
 
-## Basic Lifecycle Hooks
+## `mounted(callback)`
 
-### mounted() - Element Added to DOM
+Fires when the element is added to the DOM:
 
 ```javascript
-const myComponent = Div("Hello World")
-  .nd.mounted(element => {
-    console.log("Element is now in the DOM!", element);
-    // Setup code here
-  });
+const myComponent = Div('Hello World')
+    .nd
+    .mounted(element => {
+        console.log('In the DOM:', element);
+    });
 
-document.body.appendChild(myComponent); // Triggers mounted callback
+document.body.appendChild(myComponent); // triggers mounted
 ```
 
-### unmounted() - Element Removed from DOM
+### Auto-focus example
 
 ```javascript
-const myComponent = Div("Temporary content")
-  .nd.unmounted(element => {
-    console.log("Element removed from DOM!", element);
-    // Cleanup external resources only
-    // Element can be re-injected later
-  });
-
-// Later, when element is removed
-myComponent.remove(); // Triggers unmounted callback
+const searchInput = Input({ placeholder: 'Search...' })
+    .nd
+    .mounted(element => {
+        element.focus();
+    });
 ```
 
-## Combined Lifecycle Management
-
-```javascript
-const timer = Div("Timer: 0")
-  .nd.lifecycle({
-    mounted(element) {
-      console.log("Timer started");
-      element.intervalId = setInterval(() => {
-        element.textContent = `Timer: ${Date.now()}`;
-      }, 1000);
-    },
-    unmounted(element) {
-      console.log("Timer stopped");
-      clearInterval(element.intervalId);
-    }
-  });
-```
+---
 
-## Practical Examples
+## `unmounted(callback)`
 
-### Auto-focus Input Field
+Fires when the element is removed from the DOM. Only clean up **external resources** here - do not clean up observables unless the element is permanently destroyed:
 
 ```javascript
-const focusInput = Input({ placeholder: "Auto-focused" })
-  .nd.mounted(element => {
-      element.focus();
-  });
+const myComponent = Div('Content')
+    .nd
+    .unmounted(element => {
+        clearInterval(element.timerId);
+        element.websocket?.close();
+
+        // Do NOT call observable.cleanup() here
+        // unless the element will never be re-injected
+    });
 ```
 
-### Event Listener Cleanup
+### External event listener cleanup
 
 ```javascript
+function MyButton() {
+    const handler = () => console.log('Global click');
 
-const MyButton = function() {
-    const handler = () => console.log("Global click detected");
-    return Button("Click me")
-        .nd.mounted(button => {
+    return Button('Click me')
+        .nd
+        .mounted(el => {
             document.addEventListener('click', handler);
         })
-        .nd.unmounted(button => {
-            // Clean up external listeners, but keep observables intact
+        .unmounted(el => {
             document.removeEventListener('click', handler);
-            // DON'T cleanup observables unless element won't be reused
         });
 }
 ```
 
-### Observable Management Warning
+---
+
+## `lifecycle({ mounted, unmounted })`
+
+Configure both hooks at once:
 
 ```javascript
-const reusableComponent = Div()
-  .nd.unmounted(element => {
-    // AVOID: Don't cleanup observables if element might be re-injected
-    // myObservable.cleanup(); // Only do this if element is permanently destroyed
-    
-    // GOOD: Only cleanup external resources
-    clearInterval(element.timerId);
-    element.websocket?.close();
-  });
-
-// Element can be safely re-appended later
-document.body.appendChild(reusableComponent);
+const timer = Div('Timer: 0')
+    .nd
+    .lifecycle({
+        mounted(element) {
+            element.intervalId = setInterval(() => {
+                element.textContent = `Timer: ${Date.now()}`;
+            }, 1000);
+        },
+        unmounted(element) {
+            clearInterval(element.intervalId);
+        }
+    });
 ```
 
-## Next Steps
+---
+
+## `beforeUnmount(id, callback)`
 
-Now that you understand lifecycle events, explore these related topics:
+Registers an async callback that runs **before** the element is removed from the DOM. Useful for exit animations or saving data before removal.
 
-- **[NDElement](native-document-element.md)** - Native Document Element
-- **[Extending NDElement](extending-native-document-element.md)** - Custom Methods Guide
-- **[Advanced Components](advanced-components.md)** - Template caching and singleton views
-- **[Args Validation](validation.md)** - Function Argument Validation
-- **[Memory Management](memory-management.md)** - Memory management
-- **[Anchor](anchor.md)** - Anchor
+Multiple callbacks can be registered using different IDs - they all run sequentially before the element is removed:
 
-## Utilities
+```javascript
+Div('Content')
+    .nd
+    .beforeUnmount('save', async el => {
+        await saveData();
+    })
+    .beforeUnmount('animate', async el => {
+        await playExitAnimation(el);
+    });
+```
+
+The element's `remove()` method is patched to be async when `beforeUnmount` is used - all callbacks are awaited before the element is actually removed:
 
-- **[Cache](docs/utils/cache.md)** - Lazy initialization and singleton patterns
-- **[NativeFetch](docs/utils/native-fetch.md)** - HTTP client with interceptors
-- **[Filters](docs/utils/filters.md)** - Data filtering helpers
+```javascript
+const modal = Div({ class: 'modal' }, 'Content')
+    .nd
+    .beforeUnmount('fade-out', async el => {
+        el.style.opacity = '0';
+        await new Promise(resolve => setTimeout(resolve, 300));
+    });
+
+await modal.nd.remove();
+```
 
+> The `id` parameter lets you register multiple `beforeUnmount` callbacks and also allows replacing a specific one by re-using the same id.
 
+---
 
+## `destroyOnUnmount()`
+
+Registers an `unmounted` callback that calls `destroy()` automatically. Use when the element will **never** be re-injected into the DOM:
+
+```javascript
+const widget = Div('Content')
+    .nd
+    .mounted(el => {
+        el.intervalId = setInterval(() => doWork(), 1000);
+    })
+    .destroyOnUnmount();
+```
 
+> Do not use `destroyOnUnmount()` on elements that may be temporarily removed and re-appended (e.g. inside `ShowIf` with `shouldKeepInCache: true`). Use explicit `unmounted()` + `mounted()` pairs in that case.
+
+---
+
+## `destroy()`
+
+Aborts the element's internal `AbortController`, clears all lifecycle observers, and removes all `beforeUnmount` callbacks. The element's `$element` reference is set to `null`:
+
+```javascript
+const el = Div('Temporary content')
+    .nd
+    .beforeUnmount('animate', async () => { /* ... */ });
+
+el.nd.destroy();
+```
+
+`destroy()` is called internally by `destroyOnUnmount()`. You rarely need to call it directly.
+
+---
+
+## Element Reuse
+
+Elements can be removed and re-appended safely. Observables bound to the element remain intact through remove/re-append cycles:
+
+```javascript
+const reusable = Div('Content')
+    .nd
+    .mounted(el => console.log('Mounted'))
+    .unmounted(el => {
+        clearInterval(el.timerId);
+    });
+
+document.body.appendChild(reusable); // "Mounted"
+reusable.nd.remove();                // "Unmounted"
+document.body.appendChild(reusable); // "Mounted" again
+```
+
+---
+
+## Next Steps
 
+- **[NDElement](./native-document-element.md)** - Full `.nd` API reference
+- **[Memory Management](./memory-management.md)** - When and how to clean up observables
+- **[Extending NDElement](./extending-native-document-element.md)** - Custom methods guide
+- **[Advanced Components](./advanced-components.md)** - Template caching and singleton views