native-document 1.0.169 → 1.0.173

package/CHANGELOG.md

@@ -11,6 +11,101 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.0.173] - 2026-06-18
+
+### Fixed
+
+- `ObservableItem` TypeScript definitions - `subscribe()` and `on()` no longer
+  typed as returning `Unsubscribe`; they return nothing in the actual
+  implementation. Use `.unsubscribe(callback)` / `.off(value, callback)` with
+  the same reference to remove a subscription.
+
+### Added
+
+- `ObservableItem` type definitions - `interceptMutations`, `clone`, `valueOf`
+- `ObservableItem` comparison helpers typed: `isEqualTo`, `isNotEqualTo`,
+  `isGreaterThan`, `isGreaterThanOrEqualTo`, `isLessThan`,
+  `isLessThanOrEqualTo`, `isBetween`, `isNull`, `isTruthy`, `isFalsy`,
+  `isStartingWith`, `isEndingWith`, `isMatchingPattern`, `isEmpty`,
+  `isNotEmpty`, `isIncludes`, `isIncludedIn`, `isOneOf`, `isHaving`
+- `ObservableItem` transform helpers typed: `toUpperCase`, `toLowerCase`,
+  `toTrimmed`, `toBoolean`, `toLiteral`, `toFormatted`, `toProperty`,
+  `toLength`, `toClamped`, `toPercent`
+- `ObservableArray` type definitions - `swapItems`, `insertAfter`, `sync`,
+  `clone`, `isNotEmpty`, `indexOf`, `includes`; `deepSubscribe` and `sync`
+  correctly typed to return `Unsubscribe`
+- `ObservableObject` type definitions - `$observables()` and `configs()` typed
+  as callable methods; `subscribe()` documented as deep-subscribing nested
+  observables and observable arrays
+- `ObservableResource` type definitions (previously entirely missing) -
+  `ResourceState`, `ObservableResourceConfig`, `data`, `error`, `state`,
+  `loading`, `fetch`, `refetch`, `mutate`, `into`, `apply`, `destroy`,
+  `isReady`, `isPending`, `isRefreshing`, `isErrored`, `isUnresolved`,
+  `onSuccess`, `onError`
+- `ObservableStatic` type definitions - `resource()`, `setLocale()`,
+  `useValueProperty()`
+
+---
+
+## [1.0.172] - 2026-06-15
+
+### Added
+
+- `Text(string)` - shorthand for `string.toNdChildren()`, parses Observable placeholders in template strings
+- `String.prototype.toNdChildren()` - splits a string containing `{{obs:N}}` placeholders into a mixed array of strings and resolved Observables
+- `ObservableItem.prototype.toString()` - auto-registers the Observable in MemoryManager and returns `{{obs:id}}`, enabling reactive interpolation via standard template literals
+- `NDElement.prototype.className(classes)` - adds static classes, bypasses AttributesWrapper
+- `NDElement.prototype.class(className, value)` - adds a reactive class binding, bypasses AttributesWrapper
+- `__$isNativeNode` flag on DOM prototypes (`Element`, `Text`, `Comment`, `Document`, `DocumentFragment`) - faster alternative to `instanceof Node`
+- `__$isValidNdChild` flag on all valid NdChild prototypes - single property check replaces multiple type guards
+- `defineToNdElement`, `defineValidNdChild`, `defineNativeNode` - non-enumerable prototype helpers in `nd-element-extensions`
+- camelCase variants added to `BOOLEAN_ATTRIBUTES` - removes `toLowerCase()` call on each attribute in the hot path
+
+### Changed
+
+- `ElementCreator.processChildren` and `getChild` - refactored for better performance
+- `nd-element-extensions` - all prototype extensions converted to non-enumerable `defineProperty`
+- `AttributesWrapper` - `options` defaults to `null` instead of `{}`, fixes truthy check issue
+- NDElement events - inline handler (`on*`) used when no existing handler and no options; falls back to `addEventListener` for subsequent handlers or when options are provided
+- `_prevent`, `_stop`, `_preventStop` - updated with same inline handler strategy
+
+---
+
+## [1.0.170] - 2026-06-10
+
+### Added
+
+- Vitest test suite - `vitest.config.js`, happy-dom environment, scripts `test`, `test:watch`, `test:ui`, `test:coverage`
+- 372 tests passing across 13 files - 0 failures, 0 todo
+
+#### Unit tests - core
+- `observable-item` - 48 cases: set, val, subscribe, on/off, once, toggle, reset, transform, equals, clone, cleanup, intercept, assocTrigger
+- `observable-array` - 48 cases: push, remove, clear, merge, swap, insertAfter, isIncludes, where, sync, clone, reset, deepSubscribe
+- `observable-object` - 30 cases: constructor, val, get, set, subscribe, keys, observables, reset, clone
+- `observable-resource` - 29 cases: states, fetch, refetch, mutate, abort, race condition, deps, onSuccess, onError, into, apply, destroy
+- `store` - 43 cases: create, createResettable, createComposed, use, follow, reset, delete, group, protected, createPersistent
+
+#### Unit tests - router
+- `route-matching` - 26 cases: exact path, params, typed params, custom validators, url(), metadata
+- `router-guards` - 14 cases: middleware execution, group middlewares, subscribe, resolve, currentState
+
+#### Unit tests - utils
+- `cache` - 12 cases: singleton, once, memoize
+- `filters` - 60 cases: equals, comparison, inArray, isEmpty, match, and/or/not, custom, string filters, date/time filters
+
+#### Integration tests - UI
+- `attributes-wrapper` - 22 cases: string, class map, style, Observable, boolean, aria attributes
+- `show-if` - 16 cases: static boolean, observable, factory child, HideIf, HideIfNot
+- `for-each-array` - 13 cases: static array, push, removeItem, clear, set, swap, index observable, order preservation
+- `lifecycle` - 11 cases: mounted, unmounted, destroy, destroyOnUnmount
+
+### Fixed
+
+- `NDElement.prototype.destroy()` - guard against double call when `$element` is already null
+- `NDElement.prototype.destroy()` - disconnect lifecycle observer to prevent callbacks from firing after destroy
+
+---
+
 ## [1.0.169] - 2026-06-06
 
 ### Added
@@ -39,7 +134,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 #### UI (renders)
 - `CardRender` + `card.css` - Card renderer with 5 build slots and `layout(slots)` support
-- `ListRender` + `list.css` - `ForEachArray($desc.items)` — items self-render
+- `ListRender` + `list.css` - `ForEachArray($desc.items)` - items self-render
 - `ListItemRender` + `list-item.css` - reactive checkbox, select indicator, swipe gesture with pointer events, auto-close and stopPropagation
 - `ListGroupRender` + `list-group.css` - collapsible group with reactive chevron via `Switch`
 - `ListDividerRender` + `list-divider.css`
@@ -181,7 +276,10 @@ Entries use the following categories:
 
 ---
 
-[Unreleased]: https://github.com/afrocodeur/native-document/compare/v1.0.169...HEAD
+[Unreleased]: https://github.com/afrocodeur/native-document/compare/v1.0.173...HEAD
+[1.0.173]: https://github.com/afrocodeur/native-document/compare/v1.0.172...v1.0.173
+[1.0.172]: https://github.com/afrocodeur/native-document/compare/v1.0.170...v1.0.172
+[1.0.170]: https://github.com/afrocodeur/native-document/compare/v1.0.169...v1.0.170
 [1.0.169]: https://github.com/afrocodeur/native-document/compare/v1.0.167...v1.0.169
 [1.0.167]: https://github.com/afrocodeur/native-document/compare/v1.0.166...v1.0.167
 [1.0.166]: https://github.com/afrocodeur/native-document/releases/tag/v1.0.166

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/index.d.ts

@@ -18,4 +18,4 @@ export declare const Observable: ObservableStatic;
 export declare const $: ObservableStatic;
 export declare const obs: ObservableStatic;
 export declare const Store: StoreStatic;
-export declare const Router: RouterStatic;
+// export declare const Router: RouterStatic;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "native-document",
-  "version": "1.0.169",
+  "version": "1.0.173",
   "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/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);

package/src/components/icon/Icon.js

@@ -20,6 +20,7 @@ export function Icon(name, props = {}) {
         size:    null,
         ...props,
     };
+    this.aria = { 'aria-hidden': 'true' };
 }
 
 BaseComponent.extends(Icon);

package/src/components/list/ListItem.js

@@ -49,6 +49,7 @@ export default function ListItem(props = {}) {
         render:          null,
         props,
     };
+    this.aria = { 'role': 'listitem', 'tabindex': '-1' };
 }
 
 BaseComponent.extends(ListItem);

package/src/components/menu/Menu.js

@@ -53,6 +53,9 @@ export default function Menu(props = {}) {
         props,
     };
 
+
+    this.aria = { 'role': 'menu' };
+
 }
 
 BaseComponent.extends(Menu);

package/src/components/menu/MenuDivider.js

@@ -19,6 +19,7 @@ export default function MenuDivider(props = {}) {
     this.$description = {
         props,
     };
+    this.aria = { 'role': 'separator' };
 }
 
 BaseComponent.extends(MenuDivider);

package/src/components/menu/MenuGroup.js

@@ -39,6 +39,7 @@ export default function MenuGroup(label, props = {}) {
         collapsableClosedIcon: null,
         props,
     };
+    this.aria = { 'role': 'group' };
 }
 
 HasMenuItem.components.MenuGroup = MenuGroup;

package/src/components/menu/MenuItem.js

@@ -51,6 +51,7 @@ export default function MenuItem(props = {}) {
         visibility: null,
         props,
     };
+    this.aria = { 'role': 'menuitem', 'tabindex': '-1' };
 
 }
 

package/src/components/menu/MenuLink.js

@@ -21,6 +21,7 @@ export default function MenuLink(props = {}) {
         return new MenuLink(props);
     }
     MenuItem.call(this, props);
+    this.aria = { 'role': 'menuitem' };
 }
 
 MenuLink.prototype = Object.create(MenuItem.prototype);

package/src/components/modal/Modal.js

@@ -67,6 +67,10 @@ export default function Modal(content, props = {}) {
         variant: null,
         props,
     };
+    this.aria = {
+        'role': 'dialog',
+        'aria-modal': 'true'
+    };
 }
 
 BaseComponent.extends(Modal);

package/src/components/pagination/Pagination.js

@@ -50,6 +50,7 @@ export default function Pagination(props = {}) {
         render: null,
         props,
     };
+    this.aria = { 'role': 'navigation', 'aria-label': 'Pagination' };
 
     this.$element = null;
 }

package/src/components/popover/Popover.js

@@ -64,6 +64,7 @@ export default function Popover(content, props = {}) {
         includeTriggerIntoGhost: true,
         props,
     };
+    this.aria = { 'role': 'tooltip' };
 
     this.$element = null;
 

package/src/components/popover/PopoverFooter.js

@@ -24,6 +24,7 @@ export default function PopoverFooter(content, config = {}) {
         render: null,
         ...config,
     };
+    this.aria = {  };
 }
 
 BaseComponent.extends(PopoverFooter);

package/src/components/popover/PopoverHeader.js

@@ -25,6 +25,7 @@ export default function PopoverHeader(content, config = {}) {
         render: null,
         ...config,
     };
+    this.aria = { 'role': 'heading' };
 }
 
 BaseComponent.extends(PopoverHeader);

package/src/components/progress/Progress.js

@@ -50,6 +50,11 @@ export default function Progress(props = {}) {
         borderRadiusType: null,
         props,
     };
+    this.aria = {
+        'role': 'progressbar',
+        'aria-valuemin': '0',
+        'aria-valuemax': '100'
+    };
 }
 
 BaseComponent.extends(Progress);

package/src/components/skeleton/Skeleton.js

@@ -42,6 +42,10 @@ export default function Skeleton(props = {}) {
         repeat: null,
         props,
     };
+    this.aria = {
+        'aria-busy': 'true',
+        'aria-live': 'polite'
+    };
 }
 
 BaseComponent.extends(Skeleton);

package/src/components/slider/Slider.js

@@ -61,6 +61,7 @@ export default function Slider(name, props = {}) {
         renderThumb:   null,
         props,
     };
+    this.aria = { 'role': 'slider', 'tabindex': '0' };
 }
 
 Slider.prototype = Object.create(Field.prototype);

package/src/components/spacer/Spacer.js

@@ -9,6 +9,7 @@ export default function Spacer(props = {}) {
         type: 'spacer',
         props,
     };
+    this.aria = { 'aria-hidden': 'true' };
 }
 BaseComponent.extends(Spacer);
 

package/src/components/spinner/Spinner.js

@@ -42,6 +42,7 @@ export default function Spinner(props = {}) {
         fullScreenOverlay: null,
         props,
     };
+    this.aria = { 'role': 'status', 'aria-label': 'Loading' };
 }
 
 Spinner.defaultTemplate = null;

package/src/components/splitter/Splitter.js

@@ -33,6 +33,7 @@ export default function Splitter(props = {}) {
         render: null,
         props,
     };
+    this.aria = { 'role': 'group' };
 
     this.$element = null;
 }

package/src/components/splitter/SplitterGutter.js

@@ -33,6 +33,10 @@ export default function SplitterGutter(leftPanel, rightPanel, props = {}) {
         isDragging: $(false),
         props,
     };
+    this.aria = {
+        'role': 'separator',
+        'aria-orientation': 'horizontal',
+    };
 }
 
 BaseComponent.extends(SplitterGutter);
@@ -62,6 +66,7 @@ SplitterGutter.use = function(template) {
 SplitterGutter.prototype.vertical = function() {
     this.$description.orientation = 'vertical';
     this.$description.cursor = 'row-resize';
+    this.aria['aria-orientation'] = 'vertical';
     return this;
 };
 
@@ -71,6 +76,7 @@ SplitterGutter.prototype.vertical = function() {
 SplitterGutter.prototype.horizontal = function() {
     this.$description.orientation = 'horizontal';
     this.$description.cursor = 'col-resize';
+    this.aria['aria-orientation'] = 'horizontal';
     return this;
 };