native-document 1.0.166 → 1.0.168

package/docs/validation.md

@@ -1,129 +1,122 @@
-# Validation
+---
+title: Args Validation
+description: Runtime argument validation with ArgTypes and withValidation - catch type errors early in development
+---
 
-NativeDocument provides a comprehensive runtime validation system that helps catch errors early and ensures function arguments meet expected types and constraints.
+# Args Validation
+
+NativeDocument provides a runtime argument validation system that helps catch type errors early. It is only active in development mode - in production, `ArgTypes` is an empty object and `withValidation` is a no-op.
 
 ## Function Argument Validation
 
-### Using .args() Method
+### `.args()` method
+
+`.args()` is available on any function. It returns a new function that validates arguments before calling the original:
 
 ```javascript
-// Original function
+import { ArgTypes } from 'native-document';
+
 function createUser(name, age, email) {
     console.log(`Creating user: ${name}, ${age}, ${email}`);
 }
 
-// .args() returns a function that validates arguments before calling original
 const createUserWithValidation = createUser.args(
     ArgTypes.string('name'),
-    ArgTypes.number('age'), 
+    ArgTypes.number('age'),
     ArgTypes.string('email')
 );
 
-// Usage
-createUserWithValidation("John", 25, "john@example.com"); // Valid - calls original function
-createUserWithValidation("John", "25", "john@example.com"); // Throws validation error
+createUserWithValidation('John', 25, 'john@example.com'); // valid
+createUserWithValidation('John', '25', 'john@example.com'); // throws
 ```
 
-### WithValidation Wrapper (Equivalent)
+### `withValidation(fn, argSchema, fnName?)` - equivalent
 
 ```javascript
-// These two approaches are equivalent:
+import { ArgTypes, withValidation } from 'native-document';
 
-// Method 1: Using .args()
-const createUserWithValidation1 = createUser.args(
-    ArgTypes.string('name'),
-    ArgTypes.number('age'),
-    ArgTypes.string('email')
-);
-
-// Method 2: Using withValidation()
-const createUserWithValidation2 = withValidation(createUser, [
+const createUserWithValidation = withValidation(createUser, [
     ArgTypes.string('name'),
     ArgTypes.number('age'),
     ArgTypes.string('email')
 ], 'createUser');
-
-// Both return a function that validates arguments before calling the original
 ```
 
+---
+
 ## ArgTypes Reference
 
-### Basic Types
+### Basic types
 
 ```javascript
-ArgTypes.string('name')          // Must be string
-ArgTypes.number('age')           // Must be number  
-ArgTypes.boolean('isActive')     // Must be boolean
-ArgTypes.function('callback')    // Must be function
-ArgTypes.object('config')        // Must be object
-ArgTypes.objectNotNull('data')   // Must be object and not null
+ArgTypes.string('name')        // Must be string
+ArgTypes.number('age')         // Must be number
+ArgTypes.boolean('isActive')   // Must be boolean
+ArgTypes.function('callback')  // Must be function
+ArgTypes.object('config')      // Must be object
+ArgTypes.objectNotNull('data') // Must be object and not null
 ```
 
-### NativeDocument Types
+### NativeDocument types
 
 ```javascript
-ArgTypes.observable('state')     // Must be Observable instance
-ArgTypes.element('domNode')      // Must be HTML element
-ArgTypes.children('content')     // Valid children (elements, strings, numbers, observables)
-ArgTypes.attributes('attrs')     // Valid attributes object
+ArgTypes.observable('state')   // Must be an Observable instance
+ArgTypes.element('domNode')    // Must be an HTML element
+ArgTypes.children('content')   // Valid children (elements, strings, numbers, observables)
+ArgTypes.attributes('attrs')   // Valid attributes object
 ```
 
-### Optional Arguments
+### Optional arguments
 
 ```javascript
 function greet(name, greeting) {
     return `${greeting || 'Hello'} ${name}`;
 }
 
-// Create function with argument validation
-const greetWithValidation = greet.args(
+const greetSafe = greet.args(
     ArgTypes.string('name'),
     ArgTypes.optional(ArgTypes.string('greeting'))
 );
 
-greetWithValidation("John");           // Valid - greeting is optional
-greetWithValidation("John", "Hi");     // Valid
-greetWithValidation("John", 123);      // Error - greeting must be string if provided
+greetSafe('John');        // valid - greeting is optional
+greetSafe('John', 'Hi'); // valid
+greetSafe('John', 123);  // throws - greeting must be string if provided
 ```
 
-### OneOf Validation
+### `oneOf` - union types
 
 ```javascript
-function setTheme(theme, config) {
-    // Implementation
-}
+function setTheme(theme, config) { /* ... */ }
 
-// Create function with argument validation
-const setThemeWithValidation = setTheme.args(
-    ArgTypes.oneOf('theme', 
+const setThemeSafe = setTheme.args(
+    ArgTypes.oneOf('theme',
         ArgTypes.string('theme'),
         ArgTypes.object('theme')
     ),
     ArgTypes.object('config')
 );
 
-setThemeWithValidation("dark", {});      // Valid - string theme
-setThemeWithValidation({name: "custom"}, {}); // Valid - object theme  
-setThemeWithValidation(123, {});         // Error - must be string or object
+setThemeSafe('dark', {});          // valid - string
+setThemeSafe({ name: 'custom' }, {}); // valid - object
+setThemeSafe(123, {});             // throws - must be string or object
 ```
 
+---
+
 ## Error Handling
 
-### Validation Errors
+### Validation errors
 
 ```javascript
-function processData(items, callback) {
-    // Implementation  
-}
+function processData(items, callback) { /* ... */ }
 
-// Create function with argument validation
-const processDataWithValidation = processData.args(
+const processDataSafe = processData.args(
     ArgTypes.children('items'),
     ArgTypes.function('callback')
 );
 
 try {
-    processDataWithValidation("invalid", "not a function");
+    processDataSafe('invalid', 'not a function');
 } catch (error) {
     console.log(error.message);
     // "Argument validation failed
@@ -132,69 +125,74 @@ try {
 }
 ```
 
-### Error Boundary Pattern
-
-```javascript
-// Original function with argument validation
-const createUserWithValidation = createUser.args(
-    ArgTypes.string('name'),
-    ArgTypes.number('age'),
-    ArgTypes.string('email')
-);
+### Error boundary
 
-// Add error boundary to validation function
-const safeCreateUser = createUserWithValidation.errorBoundary((error) => {
-    console.error("User creation failed:", error.message);
-    return null; // Return fallback value
-});
+Combine with `.errorBoundary()` to handle validation errors gracefully instead of throwing:
 
-// Won't throw, returns null on validation error
-const result = safeCreateUser("John", "invalid age", "email");
+```javascript
+const safeCreateUser = createUser
+    .args(
+        ArgTypes.string('name'),
+        ArgTypes.number('age'),
+        ArgTypes.string('email')
+    )
+    .errorBoundary((error) => {
+        console.error('User creation failed:', error.message);
+        return null;
+    });
+
+const result = safeCreateUser('John', 'invalid age', 'email'); // returns null, no throw
 ```
 
-## Custom Validation
+---
 
-### Creating Custom ArgTypes
+## Custom ArgTypes
+
+Create reusable validators for domain-specific types:
 
 ```javascript
-// Custom validator for email format
 const emailType = (name) => ({
     name,
     type: 'email',
-    validate: (value) => {
-        return typeof value === 'string' && /\S+@\S+\.\S+/.test(value);
-    }
+    validate: (value) => typeof value === 'string' && /\S+@\S+\.\S+/.test(value)
 });
 
-function registerUser(email, password) {
-    // Implementation
-}
+const positiveInt = (name) => ({
+    name,
+    type: 'positiveInt',
+    validate: (value) => Number.isInteger(value) && value > 0
+});
+
+function registerUser(email, age) { /* ... */ }
 
 registerUser.args(
     emailType('email'),
-    ArgTypes.string('password')
+    positiveInt('age')
 );
 ```
 
+---
+
 ## Best Practices
 
-1. **Validate early** - Add validation to public functions and components
-2. **Use descriptive names** - Make error messages clear with good argument names
-3. **Combine with error boundaries** - Handle validation errors gracefully
-4. **Validate complex objects** - Use ArgTypes.objectNotNull for required objects
-5. **Make optional explicit** - Use ArgTypes.optional() for clarity
-6. **Custom validators** - Create reusable validators for domain-specific types
+1. Add validation to all public functions and component factories
+2. Use descriptive argument names - they appear in error messages
+3. Use `ArgTypes.objectNotNull()` for required objects - `ArgTypes.object()` accepts `null`
+4. Use `ArgTypes.optional()` explicitly - makes the API contract clear
+5. Create custom validators for domain types (email, URL, positive number, etc.)
+6. Combine with `.errorBoundary()` to avoid uncaught errors in production
+
+---
 
 ## Next Steps
 
-- **[Lifecycle Events](lifecycle-events.md)** - Validate lifecycle callback arguments
-- **[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
-- **[Memory Management](memory-management.md)** - Debugging memory issues with validation
+- **[NDElement](./native-document-element.md)** - Native Document Element
+- **[Extending NDElement](./extending-native-document-element.md)** - Custom methods guide
+- **[Memory Management](./memory-management.md)** - Debugging memory issues
+- **[Advanced Components](./advanced-components.md)** - Template caching and singleton views
 
 ## Utilities
 
-- **[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
+- **[Cache](./cache.md)** - Lazy initialization and singleton patterns
+- **[NativeFetch](./native-fetch.md)** - HTTP client with interceptors
+- **[Filters](./filters.md)** - Data filtering helpers

package/docs/vitepress-conventions.md

@@ -0,0 +1,219 @@
+# VitePress Conventions for NativeDocument Docs
+
+## Frontmatter
+
+Every markdown file must start with a frontmatter block:
+
+```yaml
+---
+title: Page Title
+description: One sentence description for SEO and sidebar tooltip
+---
+```
+
+Special pages:
+- Home page (`index.md`) uses the `layout: home` frontmatter with hero and features blocks
+- API reference pages can add `outline: deep` to show all heading levels in the right sidebar
+
+---
+
+## Folder & File Structure
+
+```
+docs/
+├── index.md                        # Home page (layout: home)
+├── getting-started.md
+├── core-concepts.md
+├── observables.md
+├── elements.md
+├── conditional-rendering.md
+├── list-rendering.md
+├── routing.md
+├── state-management.md
+├── lifecycle-events.md
+├── native-document-element.md
+├── extending-native-document-element.md
+├── advanced-components.md
+├── validation.md
+├── memory-management.md
+├── anchor.md
+├── svg-elements.md
+├── i18n.md
+├── components/
+│   ├── index.md
+│   ├── getting-started.md
+│   ├── traits.md
+│   ├── layout.md
+│   ├── accordion.md
+│   ├── alert.md
+│   ├── avatar.md
+│   ├── breadcrumb.md
+│   ├── button.md
+│   ├── context-menu.md
+│   ├── data-table.md
+│   ├── dropdown.md
+│   ├── file.md
+│   ├── form-fields.md
+│   ├── checkbox-radio.md
+│   ├── select.md
+│   ├── menu.md
+│   ├── modal.md
+│   ├── slider-stepper.md
+│   ├── splitter.md
+│   ├── switch.md
+│   ├── tabs.md
+│   ├── toast.md
+│   └── tooltip.md
+└── utils/
+    ├── cache.md
+    ├── native-fetch.md
+    └── filters.md
+```
+
+---
+
+## Internal Links
+
+VitePress resolves links relative to the current file.
+Always use `.md` extension — VitePress strips it at build time.
+
+```markdown
+<!-- From docs/readme.md or docs/getting-started.md -->
+[Observables](./observables.md)
+[Cache](./utils/cache.md)
+[Components](./components/index.md)
+
+<!-- From docs/components/accordion.md -->
+[Getting Started](./getting-started.md)          <!-- components/getting-started.md -->
+[Observables](../observables.md)                 <!-- docs/observables.md -->
+[Cache](../utils/cache.md)                       <!-- docs/utils/cache.md -->
+```
+
+Never use absolute paths (`/docs/...`) or paths without `.md`.
+
+---
+
+## `.vitepress/config.js` — Sidebar & Nav
+
+```javascript
+// .vitepress/config.js
+export default {
+    title: 'NativeDocument',
+    description: 'A reactive JavaScript framework that preserves native DOM simplicity',
+    themeConfig: {
+        nav: [
+            { text: 'Guide',      link: '/getting-started' },
+            { text: 'Components', link: '/components/' },
+            { text: 'Utilities',  link: '/utils/cache' },
+        ],
+        sidebar: {
+            '/components/': [
+                {
+                    text: 'Components',
+                    items: [
+                        { text: 'Overview',          link: '/components/' },
+                        { text: 'Getting Started',   link: '/components/getting-started' },
+                        { text: 'Traits',            link: '/components/traits' },
+                        { text: 'Layout',            link: '/components/layout' },
+                        { text: 'Accordion',         link: '/components/accordion' },
+                        { text: 'Alert & Feedback',  link: '/components/alert' },
+                        { text: 'Avatar',            link: '/components/avatar' },
+                        { text: 'Breadcrumb',        link: '/components/breadcrumb' },
+                        { text: 'Button',            link: '/components/button' },
+                        { text: 'Context Menu',      link: '/components/context-menu' },
+                        { text: 'Data Table',        link: '/components/data-table' },
+                        { text: 'Dropdown',          link: '/components/dropdown' },
+                        { text: 'File Upload',       link: '/components/file' },
+                        { text: 'Form Fields',       link: '/components/form-fields' },
+                        { text: 'Checkbox & Radio',  link: '/components/checkbox-radio' },
+                        { text: 'Select',            link: '/components/select' },
+                        { text: 'Menu',              link: '/components/menu' },
+                        { text: 'Modal & Popover',   link: '/components/modal' },
+                        { text: 'Slider & Stepper',  link: '/components/slider-stepper' },
+                        { text: 'Splitter',          link: '/components/splitter' },
+                        { text: 'Switch',            link: '/components/switch' },
+                        { text: 'Tabs',              link: '/components/tabs' },
+                        { text: 'Toast',             link: '/components/toast' },
+                        { text: 'Tooltip',           link: '/components/tooltip' },
+                    ]
+                }
+            ],
+            '/utils/': [
+                {
+                    text: 'Utilities',
+                    items: [
+                        { text: 'Cache',         link: '/utils/cache' },
+                        { text: 'NativeFetch',   link: '/utils/native-fetch' },
+                        { text: 'Filters',       link: '/utils/filters' },
+                    ]
+                }
+            ],
+            '/': [
+                {
+                    text: 'Guide',
+                    items: [
+                        { text: 'Getting Started',        link: '/getting-started' },
+                        { text: 'Core Concepts',          link: '/core-concepts' },
+                        { text: 'Observables',            link: '/observables' },
+                        { text: 'Elements',               link: '/elements' },
+                        { text: 'Conditional Rendering',  link: '/conditional-rendering' },
+                        { text: 'List Rendering',         link: '/list-rendering' },
+                        { text: 'Routing',                link: '/routing' },
+                        { text: 'State Management',       link: '/state-management' },
+                        { text: 'Lifecycle Events',       link: '/lifecycle-events' },
+                        { text: 'NDElement',              link: '/native-document-element' },
+                        { text: 'Extending NDElement',    link: '/extending-native-document-element' },
+                        { text: 'Advanced Components',    link: '/advanced-components' },
+                        { text: 'Args Validation',        link: '/validation' },
+                        { text: 'Memory Management',      link: '/memory-management' },
+                        { text: 'Anchor',                 link: '/anchor' },
+                        { text: 'SVG Elements',           link: '/svg-elements' },
+                        { text: 'i18n & Formatting',      link: '/i18n' },
+                    ]
+                }
+            ]
+        },
+        socialLinks: [
+            { icon: 'github', link: 'https://github.com/afrocodeur/native-document' }
+        ]
+    }
+}
+```
+
+---
+
+## Page Template
+
+Every doc page follows this structure:
+
+```markdown
+---
+title: Page Title
+description: One sentence description
+---
+
+# Page Title
+
+Brief intro paragraph.
+
+## Section
+
+Content.
+
+## Next Steps
+
+- [Link to related page](./related.md)
+- [Another link](./other.md)
+```
+
+---
+
+## Rules Applied to All Files
+
+1. Every file starts with frontmatter (`title` + `description`)
+2. All internal links use relative paths with `.md` extension
+3. No `docs/` prefix in any link (files are already inside `docs/`)
+4. Utility links: `./utils/cache.md`, `./utils/native-fetch.md`, `./utils/filters.md`
+5. Component links from guide pages: `./components/index.md`
+6. Component links from component pages: `../observables.md` to go up to guide
+7. The "Next Steps" section at the bottom of each page replaces the old flat link lists

package/package.json

@@ -1,7 +1,30 @@
 {
   "name": "native-document",
-  "version": "1.0.166",
-  "sideEffects":  [
+  "version": "1.0.168",
+  "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",
@@ -14,17 +37,16 @@
     "**/observable.prototypes.js",
     "**/observable.is-to.js"
   ],
-  "main": "index.js",
-  "type": "module",
   "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"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "description": "",
+  "dependencies": {
+    "@floating-ui/dom": "^1.7.6",
+    "i18next": "^25.8.0"
+  },
   "devDependencies": {
     "@babel/parser": "^7.28.5",
     "@babel/traverse": "^7.28.5",
@@ -38,8 +60,7 @@
     "rollup": "^4.53.3",
     "rollup-plugin-postcss": "^4.0.2"
   },
-  "dependencies": {
-    "@floating-ui/dom": "^1.7.6",
-    "i18next": "^25.8.0"
+  "engines": {
+    "node": ">=18.0.0"
   }
-}
+}