native-document 1.0.168 → 1.0.172

package/docs/components/icons.md

@@ -0,0 +1,321 @@
+---
+title: Icons
+description: Adapter-based icon system with chainable API and support for Tabler, Phosphor, and Google Material Icons
+---
+
+# Icons
+
+NativeDocument provides an adapter-based icon system. Icon names are semantic and stable - switching from one icon library to another requires changing only the adapter and the CSS import.
+
+```javascript
+// Usage - always via the Icon namespace
+Icon.search.fill()
+Icon.star.fill().large()
+Icon.arrowRight.bold().color('red')
+Icon.user.fill().size(32)
+```
+
+---
+
+## Setup
+
+### 1. Register the adapter
+
+In your app entry point (`main.js`):
+
+```javascript
+import { Icon }         from 'native-document/icons';
+import TablerIconRender from 'native-document/ui/icon/tabler';
+
+Icon.use(TablerIconRender, {
+    variant: 'outline',  // default variant
+    size:    'medium',   // default size: small | medium | large | extraLarge
+});
+```
+
+### 2. Import the CSS
+
+In the same entry point, import the icon font alongside your theme:
+
+```javascript
+// main.js
+import 'native-document/src/ui/theme.scss';
+import '@tabler/icons-webfont/dist/tabler-icons.css';
+```
+
+---
+
+## Methods
+
+### Variants
+
+| Method | Sets variant to |
+|---|---|
+| `.thin()` | `'thin'` |
+| `.light()` | `'light'` |
+| `.regular()` | `'regular'` |
+| `.bold()` | `'bold'` |
+| `.fill()` | `'fill'` |
+| `.duotone()` | `'duotone'` |
+| `.variant(name)` | any custom string |
+
+### Sizes
+
+| Method | Sets size to |
+|---|---|
+| `.small()` | `'small'` - 16px |
+| `.medium()` | `'medium'` - 24px |
+| `.large()` | `'large'` - 32px |
+| `.extraLarge()` | `'extraLarge'` - 48px |
+| `.size(value)` | number in px or named string |
+
+### Other
+
+| Method | Parameters | Description |
+|---|---|---|
+| `.color(value)` | `value: string` | CSS color value |
+| `.weight(value)` | `value: string` | Stroke weight (adapter-dependent) |
+
+All methods accept `Observable` values - the icon updates automatically when the observable changes:
+
+```javascript
+const isDark = Observable(false);
+
+Icon.star
+    .variant(isDark.transform((d) => d ? 'fill' : 'outline'))
+    .color(isDark.transform((d) => d ? 'gold' : 'currentColor'))
+```
+
+---
+
+## Available icons
+
+> The standard set covers the most common use cases. Each adapter maps these names to its own icon names - not every icon exists in every library.
+
+### Navigation
+`Icon.arrowLeft`, `Icon.arrowRight`, `Icon.arrowUp`, `Icon.arrowDown`, `Icon.chevronLeft`, `Icon.chevronRight`, `Icon.chevronUp`, `Icon.chevronDown`, `Icon.home`, `Icon.menu`, `Icon.close`, `Icon.back`, `Icon.forward`, `Icon.expand`, `Icon.collapse`, `Icon.fullscreen`, `Icon.fullscreenExit`
+
+### Actions
+`Icon.search`, `Icon.filter`, `Icon.sort`, `Icon.edit`, `Icon.delete`, `Icon.add`, `Icon.remove`, `Icon.save`, `Icon.copy`, `Icon.download`, `Icon.upload`, `Icon.share`, `Icon.refresh`, `Icon.more`, `Icon.settings`, `Icon.drag`, `Icon.resize`, `Icon.undo`, `Icon.redo`, `Icon.scan`, `Icon.print`, `Icon.import`, `Icon.export`
+
+### Feedback
+`Icon.check`, `Icon.checkCircle`, `Icon.error`, `Icon.warning`, `Icon.info`, `Icon.help`, `Icon.loading`, `Icon.success`
+
+### User
+`Icon.user`, `Icon.userCircle`, `Icon.users`, `Icon.lock`, `Icon.unlock`, `Icon.eye`, `Icon.eyeOff`, `Icon.bell`, `Icon.notification`
+
+### Files & Media
+`Icon.file`, `Icon.folder`, `Icon.image`, `Icon.document`, `Icon.attachment`, `Icon.link`, `Icon.externalLink`, `Icon.play`, `Icon.pause`, `Icon.stop`, `Icon.mute`, `Icon.sound`, `Icon.video`, `Icon.camera`
+
+### Interface
+`Icon.grid`, `Icon.list`, `Icon.calendar`, `Icon.clock`, `Icon.tag`, `Icon.tags`, `Icon.qrCode`, `Icon.barcode`
+
+### Text editing
+`Icon.bold`, `Icon.italic`, `Icon.underline`, `Icon.strikethrough`, `Icon.alignLeft`, `Icon.alignCenter`, `Icon.alignRight`, `Icon.alignJustify`, `Icon.orderedList`, `Icon.unorderedList`, `Icon.indent`, `Icon.outdent`, `Icon.scissors`, `Icon.fontColor`, `Icon.highlight`
+
+### Data & charts
+`Icon.barChart`, `Icon.lineChart`, `Icon.pieChart`, `Icon.areaChart`, `Icon.table`, `Icon.database`
+
+### Commerce & finance
+`Icon.shoppingCart`, `Icon.creditCard`, `Icon.wallet`, `Icon.bank`, `Icon.gift`, `Icon.percentage`, `Icon.dollar`, `Icon.euro`
+
+### Communication
+`Icon.mail`, `Icon.message`, `Icon.comment`, `Icon.phone`
+
+### System & dev
+`Icon.cloud`, `Icon.cloudUpload`, `Icon.cloudDownload`, `Icon.api`, `Icon.code`, `Icon.bug`, `Icon.tool`, `Icon.robot`
+
+### Location
+`Icon.map`, `Icon.compass`, `Icon.global`, `Icon.location`
+
+### Shapes & objects
+`Icon.star`, `Icon.heart`, `Icon.flag`, `Icon.trophy`, `Icon.medal`, `Icon.rocket`, `Icon.fire`, `Icon.thunder`, `Icon.smile`, `Icon.frown`, `Icon.like`, `Icon.dislike`, `Icon.safety`, `Icon.key`
+
+---
+
+## Custom icons
+
+Create your own renderer that wraps the base adapter. Use NativeDocument elements for reactive support:
+
+```javascript
+import { Img, Span, ShowIf } from 'native-document/elements';
+import TablerIconRender from 'native-document/ui/icon/tabler/TablerIconRender';
+
+function MyIconRender($desc) {
+    // Handle your custom icons
+    if ($desc.name === 'logo' || $desc.name === 'dashboard') {
+        const size = $desc.size?.__$Observable
+            ? $desc.size.transform((s) => typeof s === 'number' ? `${s}px` : `${SIZES[s] ?? 24}px`)
+            : `${typeof $desc.size === 'number' ? $desc.size : 24}px`;
+
+        return Img({
+            src: `/icons/${$desc.name}.svg`,
+            'aria-hidden': 'true',
+            style: {
+                width:  size,
+                height: size,
+                color:  $desc.color ?? 'currentColor',
+            },
+        });
+    }
+
+    // Fall back to Tabler for everything else
+    return TablerIconRender($desc);
+}
+
+Icon.use(MyIconRender, { size: 'medium' });
+```
+
+---
+
+## Adapters
+
+### Tabler Icons
+
+> Outline and filled variants - the standard set covers the most common icons from Tabler's library.
+
+**Install**
+
+```bash
+npm install @tabler/icons-webfont
+```
+
+**main.js**
+
+```javascript
+import { Icon }         from 'native-document/icons';
+import TablerIconRender from 'native-document/ui/icon/tabler';
+import 'native-document/src/ui/theme.scss';
+import '@tabler/icons-webfont/dist/tabler-icons.css';
+
+// Uncomment to enable .fill() variant
+// import '@tabler/icons-webfont/dist/tabler-icons-filled.css';
+
+Icon.use(TablerIconRender, { variant: 'outline', size: 'medium' });
+```
+
+**Supported variants**
+
+| Variant | Description | Required CSS |
+|---|---|---|
+| `outline` (default) | Stroked icons | `tabler-icons.css` |
+| `fill` | Filled icons | `tabler-icons-filled.css` |
+
+**Example**
+
+```javascript
+Icon.search              // outline, medium
+Icon.search.fill()       // filled
+Icon.star.fill().large() // filled, 32px
+```
+
+---
+
+### Phosphor Icons
+
+> 6 weights - the standard set covers the most common icons from Phosphor's library.
+
+**Install**
+
+```bash
+npm install @phosphor-icons/web
+```
+
+**main.js**
+
+```javascript
+import { Icon }           from 'native-document/icons';
+import PhosphorIconRender from 'native-document/ui/icon/phosphor';
+import 'native-document/src/ui/theme.scss';
+
+// Check the exact path in your node_modules/@phosphor-icons/web/ directory
+import '@phosphor-icons/web/src/regular/style.css';
+
+// Import only the weights you need
+// import '@phosphor-icons/web/src/thin/style.css';
+// import '@phosphor-icons/web/src/light/style.css';
+// import '@phosphor-icons/web/src/bold/style.css';
+// import '@phosphor-icons/web/src/fill/style.css';
+// import '@phosphor-icons/web/src/duotone/style.css';
+
+Icon.use(PhosphorIconRender, { variant: 'regular', size: 'medium' });
+```
+
+> The CSS path may vary depending on the installed version. If you get a resolve error, run `ls node_modules/@phosphor-icons/web/` to find the correct path.
+
+**Supported variants**
+
+| Variant | Description | Required CSS |
+|---|---|---|
+| `thin` | Thinnest stroke | `thin/style.css` |
+| `light` | Light stroke | `light/style.css` |
+| `regular` (default) | Standard stroke | `regular/style.css` |
+| `bold` | Bold stroke | `bold/style.css` |
+| `fill` | Filled | `fill/style.css` |
+| `duotone` | Two-tone | `duotone/style.css` |
+
+**Example**
+
+```javascript
+Icon.search                // regular, medium
+Icon.search.bold()         // bold
+Icon.star.fill().large()   // filled, 32px
+Icon.heart.duotone()       // duotone
+```
+
+---
+
+### Google Material Icons
+
+> Filled, outlined, round, sharp, two-tone - the standard set covers the most common icons from Material's library.
+
+**Install**
+
+```bash
+npm install material-icons
+```
+
+**main.js**
+
+```javascript
+import { Icon }           from 'native-document/icons';
+import MaterialIconRender from 'native-document/ui/icon/material';
+import 'native-document/src/ui/theme.scss';
+import 'material-icons/iconfont/filled.css';
+
+// Import only the styles you need
+// import 'material-icons/iconfont/outlined.css';
+// import 'material-icons/iconfont/round.css';
+// import 'material-icons/iconfont/sharp.css';
+// import 'material-icons/iconfont/two-tone.css';
+
+Icon.use(MaterialIconRender, { variant: 'fill', size: 'medium' });
+```
+
+**Supported variants**
+
+| Variant | Description | Required CSS |
+|---|---|---|
+| `fill` / `regular` (default) | Filled icons | `filled.css` |
+| `outline` | Outlined icons | `outlined.css` |
+| `round` | Rounded icons | `round.css` |
+| `sharp` | Sharp corners | `sharp.css` |
+| `twoTone` | Two-tone icons | `two-tone.css` |
+
+> Material Icons uses **ligatures** - the icon name is the text content of the element, converted to an icon by the font. This is handled automatically by the renderer.
+
+**Example**
+
+```javascript
+Icon.search                       // filled, medium
+Icon.search.variant('outline')    // outlined
+Icon.star.large()                 // filled, 32px
+```
+
+---
+
+## Next Steps
+
+- **[Components Overview](./index.md)** - BaseComponent and renderer pattern
+- **[Getting Started](./getting-started.md)** - Register default renderers
+- **[Theming](../theming.md)** - CSS tokens reference

package/docs/vitepress-conventions.md

@@ -75,7 +75,7 @@ docs/
 ## Internal Links
 
 VitePress resolves links relative to the current file.
-Always use `.md` extension — VitePress strips it at build time.
+Always use `.md` extension - VitePress strips it at build time.
 
 ```markdown
 <!-- From docs/readme.md or docs/getting-started.md -->
@@ -93,7 +93,7 @@ Never use absolute paths (`/docs/...`) or paths without `.md`.
 
 ---
 
-## `.vitepress/config.js` — Sidebar & Nav
+## `.vitepress/config.js` - Sidebar & Nav
 
 ```javascript
 // .vitepress/config.js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "native-document",
-  "version": "1.0.168",
+  "version": "1.0.172",
   "description": "A reactive JavaScript framework that preserves native DOM simplicity without sacrificing modern features",
   "author": "AfroCodeur <https://github.com/afrocodeur>",
   "license": "MIT",
@@ -41,7 +41,11 @@
     "build": "rollup --config rollup.config.js",
     "build:watch": "rollup --config rollup.config.js --watch",
     "lint": "eslint ./src",
-    "lint:fix": "eslint ./src --fix"
+    "lint:fix": "eslint ./src --fix",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
     "@floating-ui/dom": "^1.7.6",
@@ -53,14 +57,17 @@
     "@rollup/plugin-alias": "^5.1.1",
     "@rollup/plugin-replace": "^6.0.2",
     "@rollup/plugin-terser": "^0.4.4",
+    "@vitest/coverage-v8": "^4.1.8",
     "eslint": "^9.33.0",
     "eslint-plugin-jsdoc": "^62.5.4",
+    "happy-dom": "^20.10.2",
     "magic-string": "^0.30.21",
     "postcss": "^8.5.12",
     "rollup": "^4.53.3",
-    "rollup-plugin-postcss": "^4.0.2"
+    "rollup-plugin-postcss": "^4.0.2",
+    "vitest": "^4.1.8"
   },
   "engines": {
     "node": ">=18.0.0"
   }
-}
+}

package/src/components/BaseComponent.js

@@ -181,6 +181,12 @@ BaseComponent.prototype.getEditableProps = function() {
             class: classPropertyAccumulator(rawProps.class || {}),
             style: cssPropertyAccumulator(rawProps.style || {}),
         };
+
+        if (this.aria) {
+            for (const key in this.aria) {
+                this.$editableProps[resolveAriaKey(key)] = this.aria[key];
+            }
+        }
     }
 
     return this.$editableProps;
@@ -244,4 +250,40 @@ BaseComponent.prototype.context = function(context) {
     return this;
 };
 
-BaseComponent.prototype.visibility = BaseComponent.prototype.showIf;
+BaseComponent.prototype.visibility = BaseComponent.prototype.showIf;
+
+//------------------------------------------------------------------------------
+//--Component Aria -------------------------------------------------------------
+//------------------------------------------------------------------------------
+const ARIA_NO_PREFIX = new Set(['role', 'id', 'tabindex']);
+
+/**
+ * @param {string} key
+ * @returns {string}
+ */
+const resolveAriaKey = (key) =>
+    ARIA_NO_PREFIX.has(key) || key.startsWith('aria-') ? key : `aria-${key}`;
+
+/**
+ * Override or extend aria attributes on the root element.
+ * Automatically prefixes keys with 'aria-' unless they are in ARIA_NO_PREFIX.
+ *
+ * @example
+ * Modal()
+ *     .setAria({ label: 'Confirmation dialog' })
+ *     .setAria({ describedby: 'modal-desc' })
+ *
+ * @param {Record<string, string|boolean|Observable>} attrs
+ * @returns {this}
+ */
+BaseComponent.prototype.setAria = function(attrs) {
+    if (!this.aria) {
+        this.aria = {};
+    }
+    for (const key in attrs) {
+        this.aria[resolveAriaKey(key)] = attrs[key];
+    }
+    return this;
+};
+
+

package/src/components/accordion/Accordion.js

@@ -36,6 +36,7 @@ export default function Accordion(props = {}) {
         renderIndicator: null,
         props,
     };
+    this.aria = {};
 }
 
 BaseComponent.extends(Accordion);

package/src/components/accordion/AccordionItem.js

@@ -41,6 +41,7 @@ export default function AccordionItem(props = {}) {
         disabled: $(false),
         props,
     };
+    this.aria = { 'tabindex': '0' };
 }
 
 BaseComponent.extends(AccordionItem);

package/src/components/alert/Alert.js

@@ -44,6 +44,10 @@ export default function Alert(content, props = {}) {
         actions: [],
         props,
     };
+    this.aria = {
+        'role': 'alert',
+        'aria-live': 'assertive'
+    };
 }
 
 Alert.defaultTemplate = null;

package/src/components/avatar/Avatar.js

@@ -42,6 +42,7 @@ export default function Avatar(source, props = {}) {
         render: null,
         props,
     };
+    this.aria = { 'role': 'img' };
 }
 
 BaseComponent.extends(Avatar);

package/src/components/avatar/AvatarGroup.js

@@ -31,6 +31,7 @@ export default function AvatarGroup(props = {}) {
         props,
     };
 
+    this.aria = { 'role': 'group' };
 };
 
 BaseComponent.extends(AvatarGroup);

package/src/components/badge/Badge.js

@@ -36,6 +36,7 @@ export default function Badge(content, props = {}) {
         content,
         props,
     };
+    this.aria = {};
 }
 
 BaseComponent.extends(Badge);

package/src/components/breadcrumb/BreadCrumb.js

@@ -21,6 +21,10 @@ export default function Breadcrumb(props = {}) {
         renderItem: null,
         props,
     };
+    this.aria = {
+        'role': 'navigation',
+        'aria-label': 'Breadcrumb'
+    };
 }
 
 BaseComponent.extends(Breadcrumb);

package/src/components/button/Button.js

@@ -55,6 +55,7 @@ export default function Button(label, props = {}) {
         outline: null,
         props,
     };
+    this.aria = { 'role': 'button' };
 
     this.$element = null;
 }

package/src/components/card/Card.js

@@ -45,6 +45,7 @@ export default function Card(props = {}) {
         layout:        null,
         props,
     };
+    this.aria = {};
 }
 
 BaseComponent.extends(Card);

package/src/components/context-menu/ContextMenu.js

@@ -35,6 +35,8 @@ export default function ContextMenu(props = {}) {
         trigger: null,
         data: null,
     });
+
+    this.aria = { 'role': 'menu' };
 }
 
 BaseComponent.extends(ContextMenu);

package/src/components/context-menu/ContextMenuGroup.js

@@ -13,6 +13,8 @@ export default function ContextMenuGroup(label, config) {
     }
 
     MenuGroup.call(this, label, config);
+
+    this.aria = { 'role': 'group' };
 }
 
 

package/src/components/context-menu/ContextMenuItem.js

@@ -12,6 +12,8 @@ export default function ContextMenuItem(config) {
     }
 
     MenuItem.call(this, config);
+
+    this.aria = { 'role': 'menuitem' };
 }
 
 

package/src/components/divider/Divider.js

@@ -41,6 +41,8 @@ export default function Divider(label, props = {}) {
         trailing: null,
         props,
     };
+
+    this.aria = { 'role': 'separator' };
 }
 
 BaseComponent.extends(Divider);

package/src/components/dropdown/Dropdown.js

@@ -66,6 +66,7 @@ export default function Dropdown(props = {}) {
         includeTriggerIntoGhost: true,
         props,
     };
+    this.aria = { 'role': 'listbox' };
 }
 
 BaseComponent.extends(Dropdown);

package/src/components/dropdown/DropdownDivider.js

@@ -18,6 +18,7 @@ export default function DropdownDivider(props = {}) {
         type: 'divider',
         props,
     };
+    this.aria = { 'role': 'separator' };
 }
 
 BaseComponent.extends(DropdownDivider);

package/src/components/dropdown/DropdownGroup.js

@@ -27,6 +27,7 @@ export default function DropdownGroup(props) {
     Object.assign(this.$description, {
         items: $.array([]),
     });
+    this.aria = { 'role': 'group' };
 }
 
 BaseComponent.extends(DropdownGroup, DropdownItem);

package/src/components/dropdown/DropdownItem.js

@@ -38,6 +38,7 @@ export default function DropdownItem(props = {}) {
         renderContent: null,
         props,
     };
+    this.aria = { 'role': 'option', 'tabindex': '-1' };
 };
 
 BaseComponent.extends(DropdownItem);

package/src/components/dropdown/DropdownTrigger.js

@@ -26,6 +26,7 @@ export default function DropdownTrigger(config) {
         isOpen: null,
         ...config,
     };
+    this.aria = { 'aria-haspopup': 'listbox' };
 }
 
 BaseComponent.extends(DropdownTrigger);

package/src/components/form/FormControl.js

@@ -47,6 +47,7 @@ export default function FormControl(props) {
         isValid:         $(false),
         props,
     };
+    this.aria = { 'role': 'form' };
 }
 
 FormControl.defaultTemplate = null;

package/src/components/form/field/Field.js

@@ -64,6 +64,7 @@ export default function Field(name, type, props) {
         slots: {},
         props,
     };
+    this.aria = { 'role': 'group' };
 
     this.$description.errors.intercept((nextValue) => nextValue === null ? [] : nextValue);
 }

package/src/components/form/field/types/FileField.js

@@ -13,7 +13,7 @@ import FileItemPreview from '../../field/types/file-field-mode/FileItemPreview';
  *     .accept(['application/pdf', 'image/png'])
  *     .maxSize(5 * 1024 * 1024, 'Max 5MB per file')
  *     .maxFiles(3, 'Max 3 files')
- *     .mode('dropzone')
+ *     .mode(FileDropzoneMode())
  *     .onFileAdd((file) => console.log('added', file.name))
  *     .onFileRemove((file) => console.log('removed', file.name));
  *
@@ -54,7 +54,7 @@ FileField.defaultTemplate = null;
  *     label: NdChild|null,
  *     accept: string|null,
  *     multiple: boolean,
- *     mode: 'native'|'dropzone'|'button'|'wall'|'avatar'|null,
+ *     mode: FileNativeMode|FileAvatarMode|FileDropzoneMode|FileUploadButtonMode|FileWallMode|null,
  *     files: Observable<FileItemPreview[]>,
  *     fileIcons: Array<(file: File) => NdChild>,
  *     disabled: boolean|Observable<boolean>,
@@ -91,7 +91,7 @@ FileField.prototype.multiple = function(enabled = true) {
 };
 
 /**
- * @param {'native'|'dropzone'|'button'|'wall'|'avatar'} mode
+ * @param {FileNativeMode|FileAvatarMode|FileDropzoneMode|FileUploadButtonMode|FileWallMode|null} mode
  * @returns {this}
  */
 FileField.prototype.mode = function(mode) {

package/src/components/form/field/types/StringField.js

@@ -26,7 +26,7 @@ import {Validation} from '../../validation/Validation';
  */
 export default function StringField(name, type = 'text', props = {}) {
     if(!(this instanceof StringField)) {
-        return new StringField(name, props);
+        return new StringField(name, type, props);
     }
 
     Field.call(this, name, type, props);