native-document 1.0.15 → 1.0.16-8.1

package/index.js

@@ -1,18 +1,24 @@
-export { default as HtmlElementWrapper } from './src/wrappers/HtmlElementWrapper'
-export { ElementCreator } from './src/wrappers/ElementCreator'
 
-import './src/utils/prototypes.js';
 
-export * from './src/utils/plugins-manager';
-export * from './src/utils/args-types';
-export * from './src/utils/validator'
-export * from './src/data/Observable';
-export * from './src/data/observable-helpers/array';
-export * from './src/data/observable-helpers/batch';
-export * from './src/data/observable-helpers/object';
-export * from './src/data/observable-helpers/computed';
-export * from './src/data/Store';
+export { default as HtmlElementWrapper, createTextNode } from './src/core/wrappers/HtmlElementWrapper'
+export { ElementCreator } from './src/core/wrappers/ElementCreator';
+export { NDElement } from './src/core/wrappers/NDElement';
+export { TemplateCloner, useCache } from './src/core/wrappers/template-cloner/TemplateCloner';
+export { SingletonView, useSingleton } from './src/core/wrappers/SingletonView';
+export { default as PluginsManager } from './src/core/utils/plugins-manager';
+export { default as Validator } from './src/core/utils/validator';
+
+export { Formatters } from "./src/core/utils/formatters";
+export {default as ShortcutManager} from "./src/core/utils/shortcut-manager";
+
+export * from './src/core/utils/property-accumulator';
+export * from './src/core/utils/args-types';
+export * from './src/core/utils/memoize';
+export * from './src/core/data/Observable';
+export * from './src/core/data/Store';
+
 import * as elements from './elements';
 import * as router from './router';
+import * as utils from './utils';
 
-export { elements, router};
+export { elements, router, utils };

package/package.json

@@ -1,16 +1,66 @@
 {
   "name": "native-document",
-  "version": "1.0.15",
-  "main": "index.js",
+  "version": "1.0.168.01",
+  "description": "A reactive JavaScript framework that preserves native DOM simplicity without sacrificing modern features",
+  "author": "AfroCodeur <https://github.com/afrocodeur>",
+  "license": "MIT",
+  "homepage": "https://github.com/afrocodeur/native-document#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/afrocodeur/native-document.git"
+  },
+  "bugs": {
+    "url": "https://github.com/afrocodeur/native-document/issues"
+  },
+  "keywords": [
+    "reactive",
+    "framework",
+    "dom",
+    "vanilla",
+    "javascript",
+    "observable",
+    "no-virtual-dom",
+    "ui"
+  ],
   "type": "module",
+  "main": "index.js",
+  "sideEffects": [
+    "index.js",
+    "elements.js",
+    "**/*.css",
+    "**/prototypes",
+    "**/NdPrototype.js",
+    "**/nd-element-extensions.js",
+    "**/nd-element.transition.extensions.js",
+    "**/attributes-extensions.js",
+    "**/bind-class-extensions.js",
+    "**/observable.prototypes.js",
+    "**/observable.is-to.js"
+  ],
   "scripts": {
-    "build": "rollup --config rollup.config.js --watch"
+    "build": "rollup --config rollup.config.js",
+    "build:watch": "rollup --config rollup.config.js --watch",
+    "lint": "eslint ./src",
+    "lint:fix": "eslint ./src --fix"
+  },
+  "dependencies": {
+    "@floating-ui/dom": "^1.7.6",
+    "i18next": "^25.8.0"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "description": "",
   "devDependencies": {
-    "@rollup/plugin-terser": "^0.4.4"
+    "@babel/parser": "^7.28.5",
+    "@babel/traverse": "^7.28.5",
+    "@rollup/plugin-alias": "^5.1.1",
+    "@rollup/plugin-replace": "^6.0.2",
+    "@rollup/plugin-terser": "^0.4.4",
+    "eslint": "^9.33.0",
+    "eslint-plugin-jsdoc": "^62.5.4",
+    "magic-string": "^0.30.21",
+    "postcss": "^8.5.12",
+    "rollup": "^4.53.3",
+    "rollup-plugin-postcss": "^4.0.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
   }
-}
+}

package/readme.md

@@ -1,8 +1,13 @@
+---
+title: NativeDocument
+description: A reactive JavaScript framework that preserves native DOM simplicity without sacrificing modern features
+---
+
 # NativeDocument
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Build Status](https://img.shields.io/badge/Build-Passing-brightgreen.svg)](#)
-[![Version](https://img.shields.io/badge/Version-1.0.0-orange.svg)](#)
+[![Version](https://img.shields.io/badge/Version-1.0.161-orange.svg)](#)
 [![Bundle Size](https://img.shields.io/badge/Bundle%20Size-~25kb-green.svg)](#)
 
 > **A reactive JavaScript framework that preserves native DOM simplicity without sacrificing modern features**
@@ -11,14 +16,16 @@ NativeDocument combines the familiarity of vanilla JavaScript with the power of
 
 ## Why NativeDocument?
 
+> **Note**: NativeDocument works best with a bundler (Vite, Webpack, Rollup) for tree-shaking and optimal bundle size. The CDN version includes all features.
+
 ### **Instant Start**
 ```html
-<script src="https://cdn.jsdelivr.net/gh/afrocodeur/native-document@latest/dist/native-document.min.js"></script>
+<script src="https://cdn.jsdelivr.net/gh/afrocodeur/native-document/dist/native-document.min.js"></script>
 ```
 
 ### **Familiar API**
 ```javascript
-import { Div, Button, Observable } from 'native-document/src/elements';
+import { Div, Button } from 'native-document/elements';
 import { Observable } from 'native-document';
 
 // CDN
@@ -28,41 +35,58 @@ import { Observable } from 'native-document';
 const count = Observable(0);
 
 const App = Div({ class: 'app' }, [
-    Div([ 'Count ', count]),
-    // OR Div(`Count ${count}`),
-    Button('Increment').nd.onClick(() => count.set(count.val() + 1))
+    Div(['Count ', count]),
+    Button('Increment').nd
+        .onClick(() => count.$value++)
 ]);
 
 document.body.appendChild(App);
 ```
 
 ### **Complete Features**
-- **Native reactivity** with observables
-- **Global store** for state management
-- **Built-in conditional rendering**
-- **Full-featured router** (hash, history, memory modes)
+- **Native reactivity** with observables, computed values, and batched updates
+- **Global store** for state management with groups, persistence, and computed stores
+- **Built-in conditional rendering** (`ShowIf`, `Match`, `Switch`, `When`)
+- **Full-featured router** (hash, history, memory modes) with layouts and middlewares
+- **Headless UI components** with an optional rendering system (50+ components)
+- **Built-in i18n** via `tr()`, locale-aware `Observable.format()`, and `Formatters`
+- **Advanced data filtering** with composable filter helpers
+- **Official CLI** for scaffolding projects, pages, components, and services
 - **Advanced debugging system**
-- **Automatic memory management** via FinalizationRegistry
+- **Automatic memory management** via `FinalizationRegistry`
+- **Tree-shaking** support — only bundle what you use
 
 ## Quick Installation
 
-### Option 1: CDN (Instant Start)
+### Option 1: CLI (Recommended)
+
+The fastest way to start a complete project:
+
+```bash
+npm install -g @native-document/cli
+
+nd create MyApp            # default structure
+nd create MyApp --feature  # feature-based architecture
+
+cd MyApp
+npm install
+npm start
+```
+
+> The CLI source is available at [github.com/afrocodeur/native-document-cli](https://github.com/afrocodeur/native-document-cli).
+
+See the **[CLI guide](./cli.md)** for all available commands (`nd create:page`, `nd create:component`, `nd create:service` and more).
+
+### Option 2: CDN (No build step)
 ```html
 <script src="https://cdn.jsdelivr.net/gh/afrocodeur/native-document@latest/dist/native-document.min.js"></script>
 <script>
-  const { Div, Observable } = NativeDocument.elements
+  const { Div } = NativeDocument.elements;
+  const { Observable } = NativeDocument;
   // Your code here
 </script>
 ```
 
-### Option 2: Vite Template (Complete Project)
-```bash
-npx degit afrocodeur/native-document-vite my-app
-cd my-app
-npm install
-npm run dev
-```
-
 ### Option 3: NPM/Yarn
 ```bash
 npm install native-document
@@ -73,16 +97,16 @@ yarn add native-document
 ## Quick Example
 
 ```javascript
-import { Div, Input, Button, ShowIf, ForEach } from 'native-document/src/elements'
-import { Observable } from 'native-document'
+import { Div, Input, Button, ShowIf, ForEach } from 'native-document/elements';
+import { Observable } from 'native-document';
 
 // CDN
 // const { Div, Input, Button, ShowIf, ForEach } = NativeDocument.elements;
 // const { Observable } = NativeDocument;
 
 // Reactive state
-const todos = Observable.array([])
-const newTodo = Observable('')
+const todos = Observable.array([]);
+const newTodo = Observable('');
 
 // Todo Component
 const TodoApp = Div({ class: 'todo-app' }, [
@@ -91,10 +115,11 @@ const TodoApp = Div({ class: 'todo-app' }, [
     Input({ placeholder: 'Add new task...', value: newTodo }),
 
     // Add button
-    Button('Add Todo').nd.onClick(() => {
+    Button('Add Todo').nd
+    .onClick(() => {
         if (newTodo.val().trim()) {
-            todos.push({ id: Date.now(), text: newTodo.val(), done: false })
-            newTodo.set('')
+            todos.push({ id: Date.now(), text: newTodo.val(), done: false });
+            newTodo.set('');
         }
     }),
 
@@ -103,17 +128,19 @@ const TodoApp = Div({ class: 'todo-app' }, [
         Div({ class: 'todo-item' }, [
             Input({ type: 'checkbox', checked: todo.done }),
             `${todo.text}`,
-            Button('Delete').nd.onClick(() => todos.splice(index.val(), 1))
-        ]), /*item key (string | callback) */(item) => item),
+            Button('Delete').nd
+    .onClick(() => todos.splice(index.val(), 1))
+        ]),
+        (item) => item.id // Key function — use unique identifier
+    ),
 
     // Empty state
-    ShowIf(
-        todos.check(list => list.length === 0),
+    ShowIf(todos.isEmpty(),
         Div({ class: 'empty' }, 'No todos yet!')
     )
 ]);
 
-document.body.appendChild(TodoApp)
+document.body.appendChild(TodoApp);
 ```
 
 ## Core Concepts
@@ -121,44 +148,77 @@ document.body.appendChild(TodoApp)
 ### Observables
 Reactive data that automatically updates the DOM:
 ```javascript
-import { Div } from 'native-document/src/elements'
-import { Observable } from 'native-document'
+import { Div } from 'native-document/elements';
+import { Observable } from 'native-document';
 
 // CDN
-// const { Div  } = NativeDocument.elements;
+// const { Div } = NativeDocument.elements;
 // const { Observable } = NativeDocument;
 
 const user = Observable({ name: 'John', age: 25 });
-const greeting = Observable.computed(() => `Hello ${user.$value.name}!`, [user])
-// Or const greeting = Observable.computed(() => `Hello ${user.val().name}!`, [user])
+const greeting = Observable.computed(() => `Hello ${user.val().name}!`, [user]);
 
 document.body.appendChild(Div(greeting));
 
-// user.name = 'Fausty'; // will not work
-// user.$value = { ...user.$value, name: ' Hermes!' }; // will work
-// user.set(data => ({ ...data, name: 'Hermes!' })); // will work
+// Direct mutation won't trigger updates
+// user.name = 'Fausty'; // Wrong!
+
+// These will trigger updates:
+user.$value = { ...user.$value, name: 'Hermes!' };
+user.set(data => ({ ...data, name: 'Hermes!' }));
 user.set({ ...user.val(), name: 'Hermes!' });
 ```
 
+### Formatting & i18n
+Format observable values reactively with built-in locale awareness.
+You must set a locale observable before using `Observable.format()`:
+
+```javascript
+import { Observable } from 'native-document';
+import { tr } from 'native-document/i18n';
+
+// Set the locale first — formats react to it automatically
+const $locale = Observable('fr');
+Observable.setLocale($locale);
+
+const price = Observable(4999);
+const date  = Observable(Date.now());
+
+export function PriceDisplay() {
+    return Div([
+        Div(price.format('currency', { currency: 'USD' })),
+        Div(date.format('date', { dateStyle: 'long' })),
+        Button('Switch to English').nd
+    .onClick(() => $locale.set('en'))
+    ]);
+}
+
+// Built-in format types: currency, number, percent, date, time, datetime, relative, plural
+
+// Translation helper
+P(tr('welcome_message'))
+```
+
 ### Elements
 Familiar HTML element creation with reactive bindings:
 ```javascript
-import { Div, Button } from 'native-document/src/elements'
-import { Observable } from 'native-document'
+import { Div, Button } from 'native-document/elements';
+import { Observable } from 'native-document';
 
 // CDN
-// const { Div, Button  } = NativeDocument.elements;
+// const { Div, Button } = NativeDocument.elements;
 // const { Observable } = NativeDocument;
 
-const App  = function() {
-    const isVisible = Observable(true)
-    
+const App = function() {
+    const isVisible = Observable(true);
+
     return Div([
         Div({
-            class: { 'hidden': isVisible.check(v => !v) },
-            style: { opacity: isVisible.check(v => v ? 1 : 0.2) }
+            class: { 'hidden': isVisible.isFalsy() },
+            style: { opacity: isVisible.format(v => v ? 1 : 0.2) }
         }, 'Content'),
-        Button('Toggle').nd.onClick(() => isVisible.set(v => !v)),
+        Button('Toggle').nd
+    .onClick(() => isVisible.toggle()),
     ]);
 };
 
@@ -168,13 +228,15 @@ document.body.appendChild(App());
 ### Conditional Rendering
 Built-in components for dynamic content:
 ```javascript
-ShowIf(user.check(u => u.isLoggedIn), 
-  Div('Welcome back!')
+import { ShowIf, Match, Switch, When } from 'native-document/elements';
+
+ShowIf(user.is(u => u.isLoggedIn),
+    Div('Welcome back!')
 )
 
 Match(theme, {
-  'dark': Div({ class: 'dark-mode' }),
-  'light': Div({ class: 'light-mode' })
+    'dark':  Div({ class: 'dark-mode' }),
+    'light': Div({ class: 'light-mode' })
 })
 
 Switch(condition, onTrue, onFalse)
@@ -184,41 +246,177 @@ When(condition)
     .otherwise(onFalse)
 ```
 
-## Documentation
+### List Rendering
+Efficient rendering of lists with automatic updates:
+```javascript
+import { ForEach, Div } from 'native-document/elements';
+import { Observable } from 'native-document';
 
-- **[Getting Started](docs/getting-started.md)** - Installation and first steps
-- **[Core Concepts](docs/core-concepts.md)** - Understanding the fundamentals
-- **[Observables](docs/observables.md)** - Reactive state management
-- **[Elements](docs/elements.md)** - Creating and composing UI
-- **[Conditional Rendering](docs/conditional-rendering.md)** - Dynamic content
-- **[List Rendering](docs/list-rendering.md)** - List Rendering
-- **[Routing](docs/routing.md)** - Navigation and URL management
-- **[State Management](docs/state-management.md)** - Global state patterns
-- **[Lifecycle Events](docs/lifecycle-events.md)** - Lifecycle events
-- **[Memory Management](docs/memory-management.md)** - Memory management
-- **[Anchor](docs/anchor.md)** - Anchor
-
-## Examples
-
-### Todo App
-```bash
-# Complete todo application with local storage
-git clone https://github.com/afrocodeur/native-document-examples
-cd examples/todo-app
+const items = Observable.array(['Apple', 'Banana', 'Cherry']);
+
+ForEach(items, (item, index) =>
+    Div([index, '. ', item])
+)
+
+// With object arrays — use a key function for efficient updates
+const users = Observable.array([
+    { id: 1, name: 'Alice' },
+    { id: 2, name: 'Bob' }
+]);
+
+ForEach(users, (user) =>
+    Div(user.name),
+    (user) => user.id  // Key for efficient updates
+)
 ```
 
-### SPA Router
-```bash
-# Single Page Application with routing
-cd examples/routing-spa
+### Routing
+Full-featured router with hash, history, and memory modes.
+Use `to` with a route name (string) or `{ name, params }` object. Use `href` for direct path links:
+
+```javascript
+import { Router, Link } from 'native-document/router';
+
+Router.create({ name: 'default', mode: 'history' }, (router) => {
+    router.group('', { layout: DefaultLayout }, () => {
+        router.add('/', HomePage);
+        router.add('/user/{id}', UserPage);
+        router.add('{*}', NotFoundPage);
+    });
+});
+
+// Named route link
+Link({ to: 'home' }, 'Home')
+
+// Named route with params
+Link({ to: { name: 'user', params: { id: 42 } } }, 'User Profile')
+
+// Direct path link
+Link({ href: '/about' }, 'About')
 ```
 
-### Reusable Components
-```bash
-# Component library patterns
-cd examples/components
+### State Management
+Global state with groups, persistence, and computed stores:
+```javascript
+import { Store } from 'native-document';
+
+// Simple store
+Store.create('theme', 'light');
+
+// Persistent store — survives page reloads
+Store.createPersistent('settings', { lang: 'en', darkMode: false });
+
+// Grouped stores — isolated namespaces
+const CartStore = Store.group('cart', (group) => {
+    group.create('items', []);
+    group.createComposed('total', () => {
+        return CartStore.get('items').val()
+            .reduce((sum, item) => sum + item.price * item.qty, 0);
+    }, ['items']);
+});
+
+// Access in components
+const items = CartStore.use('items');    // two-way reactive
+const total = CartStore.follow('total'); // read-only reactive
+```
+
+### Data Filters
+Composable filter helpers for `ObservableArray` only:
+
+```javascript
+import { Observable } from 'native-document';
+import { equals, greaterThan, lessThan, and, or, not } from 'native-document/filters';
+
+const users = Observable.array([
+    { name: 'Alice', age: 17, role: 'user'  },
+    { name: 'Bob',   age: 25, role: 'admin' },
+    { name: 'Carol', age: 32, role: 'user'  },
+]);
+
+// and — field must pass ALL conditions
+const youngAdults = users.where({
+    age: and(greaterThan(18), lessThan(30))
+});
+// → Bob (25)
+
+// or — field must pass AT LEAST ONE condition
+const adminOrEditor = users.where({
+    role: or(equals('admin'), equals('editor'))
+});
+// → Bob
+
+// not — inverts a filter
+const nonAdmins = users.where({
+    role: not(equals('admin'))
+});
+// → Alice, Carol
+
+// Cross-field logic — use the _ key with a plain function
+const adminsOrMinors = users.where({
+    _: (item) => item.role === 'admin' || item.age < 18
+});
+// → Alice (minor), Bob (admin)
 ```
 
+> `and`, `or`, and `not` work on **filter result objects** — they operate on a single field.
+> For cross-field logic use the `_` key with a plain function.
+> `.where()` returns a new live `ObservableArray` that re-filters automatically when the source changes.
+
+## Documentation
+
+- **[Getting Started](./getting-started.md)** — Installation and first steps
+- **[CLI](./cli.md)** — Scaffolding projects, pages, and components
+- **[Core Concepts](./core-concepts.md)** — Understanding the fundamentals
+- **[Observables](./observables.md)** — Reactive state management
+- **[Observable Resource](./observable-resource.md)** — Async data fetching
+- **[Elements](./elements.md)** — Creating and composing UI
+- **[Conditional Rendering](./conditional-rendering.md)** — Dynamic content
+- **[List Rendering](./list-rendering.md)** — ForEach and dynamic lists
+- **[Routing](./routing.md)** — Navigation and URL management
+- **[State Management](./state-management.md)** — Global state patterns
+- **[Lifecycle Events](./lifecycle-events.md)** — Lifecycle events
+- **[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
+- **[SVG Elements](./svg-elements.md)** — SVG wrapper functions
+- **[i18n & Formatting](./i18n.md)** — Locale-aware formatting and translations
+
+### Components
+
+- **[Components Overview](./components/index.md)** — Headless UI component system
+- **[Getting Started](./components/getting-started.md)** — First component and renderer setup
+- **[Traits](./components/traits.md)** — Draggable, Resizable, EventEmitter
+- **[Layout](./components/layout.md)** — Stack, Row, Col, Divider
+- **[Accordion](./components/accordion.md)**
+- **[Alert, Badge, Spinner, Skeleton, Progress](./components/alert.md)**
+- **[Avatar](./components/avatar.md)**
+- **[Breadcrumb](./components/breadcrumb.md)**
+- **[Button](./components/button.md)**
+- **[Context Menu](./components/context-menu.md)**
+- **[Data Table](./components/data-table.md)**
+- **[Dropdown](./components/dropdown.md)**
+- **[File Upload](./components/file.md)**
+- **[Form Fields](./components/form-fields.md)**
+- **[Checkbox & Radio](./components/checkbox-radio.md)**
+- **[Select](./components/select.md)**
+- **[Menu](./components/menu.md)**
+- **[Modal & Popover](./components/modal.md)**
+- **[Slider & Stepper](./components/slider-stepper.md)**
+- **[Splitter](./components/splitter.md)**
+- **[Switch](./components/switch.md)**
+- **[Tabs](./components/tabs.md)**
+- **[Toast](./components/toast.md)**
+- **[Tooltip](./components/tooltip.md)**
+
+### Utilities
+
+- **[Cache](./utils/cache.md)** — Lazy initialization and singleton patterns
+- **[NativeFetch](./utils/native-fetch.md)** — HTTP client with interceptors
+- **[Filters](./utils/filters.md)** — Data filtering helpers
+
 ## Key Features Deep Dive
 
 ### Performance Optimized
@@ -226,28 +424,34 @@ cd examples/components
 - Automatic batching of updates
 - Lazy evaluation of computed values
 - Efficient list rendering with keyed updates
+- Tree-shaking — only bundle what you use
 
 ### Developer Experience
 ```javascript
+import { ArgTypes } from 'native-document';
+
 // Built-in debugging
-Observable.debug.enable()
+Observable.debug.enable();
 
 // Argument validation
-const createUser = (function (name, age) {
-  // Auto-validates argument types
-}).args(ArgTypes.string('name'), ArgTypes.number('age'))
+const createUser = (function(name, age) {
+    // Auto-validates argument types in development
+}).args(ArgTypes.string('name'), ArgTypes.number('age'));
 
 // Error boundaries
-const AppWithBoundayError = App.errorBoundary(() => {
-    return Div('Error in the Create User component');
-})
+const SafeApp = App.errorBoundary((error, { caller, args }) => {
+    return Div({ class: 'error' }, [
+        'An error occurred: ',
+        error.message
+    ]);
+});
 
-document.body.appendChild(AppWithBoundayError());
+document.body.appendChild(SafeApp());
 ```
 
 ## Contributing
 
-We welcome contributions! Please see our [Contributing Guide](docs/contributing.md) for details.
+We welcome contributions! Please see our [Contributing Guide](./contributing.md) for details.
 
 ### Development Setup
 ```bash
@@ -287,11 +491,10 @@ Your support helps me:
 
 Thanks for your support! 🙏
 
-
 ## Acknowledgments
 
 Thanks to all contributors and the JavaScript community for inspiration.
 
 ---
 
-**Ready to build with native simplicity?** [Get Started →](docs/getting-started.md)
+**Ready to build with native simplicity?** [Get Started ->](./getting-started.md)