native-document 1.0.168 → 1.0.172

package/src/core/wrappers/prototypes/nd-element-extensions.js

@@ -1,110 +1,174 @@
 import ObservableItem from '../../data/ObservableItem';
-import {NDElement} from '../NDElement';
+import { NDElement } from '../NDElement';
 import TemplateBinding from '../TemplateBinding';
-import {ElementCreator} from '../ElementCreator';
+import { ElementCreator } from '../ElementCreator';
 import PluginsManager from '../../utils/plugins-manager';
 import ObservableChecker from '../../data/ObservableChecker';
+import MemoryManager from '../../data/MemoryManager';
 
 
-NDElement.$getChild = ElementCreator.getChild;
+
+const OBS_PATTERN = /({{obs:\d+}})/;
+const OBS_ID_PATTERN = /\d+/;
+
 
 /**
- * Converts a string to a reactive text node.
+ * Parses a string containing Observable placeholders and returns an array
+ * of strings and Observable instances.
  *
- * @returns {Text} Static text node containing the string value
+ * Placeholders are generated automatically when an ObservableItem is interpolated
+ * in a template string via its toString() method.
+ *
+ * @returns {Array<string|ObservableItem>} Mixed array of static strings and resolved Observables
+ * @example
+ * const name = Observable('John');
+ * const count = Observable(5);
+ *
+ * `Hello ${name}, count: ${count}`.toNdChildren()
+ * // → ['Hello ', ObservableItem(John), ', count: ', ObservableItem(5)]
  */
-String.prototype.toNdElement = function () {
-    return ElementCreator.createStaticTextNode(null, this);
-};
+Object.defineProperty(String.prototype, 'toNdChildren', {
+    value: function() {
+        return this.split(OBS_PATTERN).filter(Boolean).map((item) => {
+            if(OBS_PATTERN.test(item)) {
+                const id = item.match(OBS_ID_PATTERN)[0];
+                return MemoryManager.getObservableById(Number(id));
+            }
+            return item;
+        });
+    },
+    writable: true,
+    configurable: true,
+    enumerable: false,
+});
 
 /**
- * Converts a number to a static text node.
+ * Registers a non-enumerable toNdElement method on a prototype.
  *
- * @returns {Text} Static text node containing the number as a string
+ * @param {object} target - The prototype to extend
+ * @param {Function} fn - The toNdElement implementation
  */
-Number.prototype.toNdElement = function () {
-    return ElementCreator.createStaticTextNode(null, this.toString());
+const defineToNdElement = (target, fn) => {
+    Object.defineProperty(target, 'toNdElement', {
+        value: fn,
+        writable: true,
+        configurable: true,
+        enumerable: false,
+    });
 };
 
 /**
- * Returns the element itself (identity for DOM compatibility).
+ * Marks a prototype as a valid NativeDocument child node.
  *
- * @returns {Element} this
+ * @param {object} target - The prototype to mark
  */
-Element.prototype.toNdElement = function () {
-    return this;
+const defineValidNdChild = (target) => {
+    Object.defineProperty(target, '__$isValidNdChild', {
+        value: true,
+        writable: true,
+        configurable: true,
+        enumerable: false,
+    });
 };
 
 /**
- * Returns the text node itself (identity for DOM compatibility).
+ * Marks a prototype as a native DOM node.
+ * Faster alternative to instanceof Node for hot paths.
  *
- * @returns {Text} this
+ * @param {object} target - The prototype to mark
  */
-Text.prototype.toNdElement = function () {
-    return this;
+const defineNativeNode = (target) => {
+    Object.defineProperty(target, '__$isNativeNode', {
+        value: true,
+        writable: true,
+        configurable: true,
+        enumerable: false,
+    });
 };
 
+NDElement.$getChild = ElementCreator.getChild;
+
+// -- __$isNativeNode ----------------------------------------------------------
+
+defineNativeNode(Element.prototype);
+defineNativeNode(Text.prototype);
+defineNativeNode(Comment.prototype);
+defineNativeNode(Document.prototype);
+defineNativeNode(DocumentFragment.prototype);
+
+// -- __$isValidNdChild --------------------------------------------------------
+
+defineValidNdChild(String.prototype);
+defineValidNdChild(Number.prototype);
+defineValidNdChild(Boolean.prototype);
+defineValidNdChild(Array.prototype);
+defineValidNdChild(Element.prototype);
+defineValidNdChild(Text.prototype);
+defineValidNdChild(Comment.prototype);
+defineValidNdChild(DocumentFragment.prototype);
+defineValidNdChild(NDElement.prototype);
+defineValidNdChild(ObservableItem.prototype);
+defineValidNdChild(ObservableChecker.prototype);
+defineValidNdChild(TemplateBinding.prototype);
+defineValidNdChild(Function.prototype);
+
+// -- toNdElement --------------------------------------------------------------
+
 /**
- * Returns the comment node itself (identity for DOM compatibility).
+ * Converts a string to a static text node.
  *
- * @returns {Comment} this
+ * @returns {Text}
  */
-Comment.prototype.toNdElement = function () {
-    return this;
-};
+defineToNdElement(String.prototype, function () {
+    return ElementCreator.createStaticTextNodeWithoutParent(this);
+});
 
 /**
- * Returns the document itself (identity for DOM compatibility).
+ * Converts a number to a static text node.
  *
- * @returns {Document} this
+ * @returns {Text}
  */
-Document.prototype.toNdElement = function () {
-    return this;
-};
+defineToNdElement(Number.prototype, function () {
+    return ElementCreator.createStaticTextNodeWithoutParent(this.toString());
+});
 
 /**
- * Returns the document fragment itself (identity for DOM compatibility).
+ * Returns the DOM node itself (identity).
  *
- * @returns {DocumentFragment} this
+ * @returns {Element|Text|Comment|Document|DocumentFragment}
  */
-DocumentFragment.prototype.toNdElement = function () {
-    return this;
-};
+defineToNdElement(Element.prototype, function () { return this; });
+defineToNdElement(Text.prototype, function () { return this; });
+defineToNdElement(Comment.prototype, function () { return this; });
+defineToNdElement(Document.prototype, function () { return this; });
+defineToNdElement(DocumentFragment.prototype, function () { return this; });
 
 /**
- * Converts the ObservableItem to a reactive text node that updates automatically when the value changes.
+ * Converts an ObservableItem to a reactive text node that updates when the value changes.
  *
- * @returns {Text} Reactive text node bound to this observable
+ * @returns {Text}
  */
-ObservableItem.prototype.toNdElement = function () {
-    return ElementCreator.createObservableNode(null, this);
-};
+defineToNdElement(ObservableItem.prototype, function () {
+    return ElementCreator.createObservableNodeWithoutParent(this);
+});
 
 ObservableChecker.prototype.toNdElement = ObservableItem.prototype.toNdElement;
 
 /**
- * Converts the NDElement to its underlying HTMLElement (or ghost DOM fragment if ghostDom was used).
+ * Returns the underlying HTMLElement of this NDElement.
  *
- * @returns {HTMLElement|DocumentFragment} The underlying DOM node
+ * @returns {HTMLElement|DocumentFragment}
  */
-NDElement.prototype.toNdElement = function () {
-    const element = this.$element ?? this.$build?.() ?? this.build?.() ?? null;
-    if(this.$attachements) {
-        if(!this.$attachements.contains(this.$element)) {
-            this.$attachements.append(this.$element);
-        }
-        return this.$attachements;
-    }
-    return element;
-};
+defineToNdElement(NDElement.prototype, function () {
+    return this.$element;
+});
 
 /**
- * Converts the array to a DocumentFragment containing all elements.
- * Each item is processed through ElementCreator.getChild().
+ * Converts the array to a DocumentFragment containing all child elements.
  *
- * @returns {DocumentFragment} Fragment containing all array children
+ * @returns {DocumentFragment}
  */
-Array.prototype.toNdElement = function () {
+defineToNdElement(Array.prototype, function () {
     const fragment = document.createDocumentFragment();
     for(let i = 0, length = this.length; i < length; i++) {
         const child = ElementCreator.getChild(this[i]);
@@ -112,27 +176,26 @@ Array.prototype.toNdElement = function () {
         fragment.appendChild(child);
     }
     return fragment;
-};
+});
 
 /**
  * Calls the function and converts its return value to a DOM node.
- * Used internally by ElementCreator to process function-based children.
  *
- * @returns {Node} The DOM node returned by the function
+ * @returns {Node}
  */
-Function.prototype.toNdElement = function () {
+defineToNdElement(Function.prototype, function () {
     const child = this;
     if(process.env.NODE_ENV === 'development') {
         PluginsManager.emit('BeforeProcessComponent', child);
     }
     return ElementCreator.getChild(child());
-};
+});
 
 /**
- * Converts the TemplateBinding to a hydratable DOM node for use in TemplateCloner.
+ * Converts the TemplateBinding to a hydratable DOM node.
  *
- * @returns {Node} Hydratable node
+ * @returns {Node}
  */
-TemplateBinding.prototype.toNdElement = function () {
+defineToNdElement(TemplateBinding.prototype, function () {
     return ElementCreator.createHydratableNode(null, this);
-};
+});

package/src/ui/components/accordion/AccordionItemRender.js

@@ -1,18 +1,26 @@
 import {Div, Span, ShowIf} from '../../../core/elements';
 
+// [a11y] ID counter for aria-controls
+let _accordionIdCounter = 0;
+
 export default function AccordionItemRender($desc, instance) {
     const props = instance.getEditableProps();
 
     props.class.add('accordion-item');
     props.class.add({'is-disabled': $desc.disabled});
 
-    const header = buildHeader($desc, instance);
-    const content = buildContent($desc, instance);
+    // [a11y] Generate unique IDs for aria-controls / aria-labelledby
+    const accordionId = ++_accordionIdCounter;
+    const headerId    = `accordion-header-${accordionId}`;
+    const panelId     = `accordion-panel-${accordionId}`;
+
+    const header = buildHeader($desc, instance, headerId, panelId);
+    const content = buildContent($desc, instance, headerId, panelId);
 
     return Div(instance.resolveProps(), [header, content]);
 }
 
-const buildHeader = ($desc, instance) => {
+const buildHeader = ($desc, instance, headerId, panelId) => {
     if($desc.renderHeader) {
         return $desc.renderHeader($desc, instance);
     }
@@ -27,7 +35,13 @@ const buildHeader = ($desc, instance) => {
         buildIndicator($desc),
     ];
 
-    const header = Div({class: 'accordion-header'}, content);
+    const header = Div({
+        class: 'accordion-header',
+        id: headerId,
+        // [a11y] aria-expanded reactive, aria-controls points to panel
+        'aria-expanded': $desc.expanded.transform((v) => String(v)),
+        'aria-controls': panelId,
+    }, content);
 
     if(!$desc.disabled?.val()) {
         header.nd.onClick(() => {
@@ -50,14 +64,22 @@ const buildIndicator = ($desc) => {
     }, '▾');
 };
 
-const buildContent = ($desc, instance) => {
+const buildContent = ($desc, instance, headerId, panelId) => {
+    // [a11y] role=region + aria-labelledby on panel
+    const panelProps = {
+        class: 'accordion-content',
+        id: panelId,
+        role: 'region',
+        'aria-labelledby': headerId,
+    };
+
     if($desc.renderContent) {
         return ShowIf($desc.expanded, () =>
-            Div({class: 'accordion-content'}, $desc.renderContent($desc, instance)),
+            Div(panelProps, $desc.renderContent($desc, instance)),
         );
     }
 
     return ShowIf($desc.expanded, () =>
-        Div({class: 'accordion-content'}, $desc.content),
+        Div(panelProps, $desc.content),
     );
 };

package/src/ui/components/alert/AlertRender.js

@@ -10,6 +10,12 @@ export default function AlertRender($desc, instance) {
     props.class.add('is-' + ($desc.variant || 'info'));
     props.class.add('is-' + ($desc.appearance || 'bordered'));
 
+    // [a11y] aria-live: assertive for error/warning, polite for others
+    const ariaLive = ($desc.variant === 'error' || $desc.variant === 'danger' || $desc.variant === 'warning')
+        ? 'assertive'
+        : 'polite';
+    props['aria-live'] = ariaLive;
+
     const content = [];
 
     if($desc.showIcon && $desc.icon) {

package/src/ui/components/breadcrumb/BreadcrumbRender.js

@@ -6,6 +6,9 @@ export default function BreadcrumbRender($desc, instance) {
     const props = instance.getEditableProps();
     props.class.add('breadcrumb');
 
+    // [a11y] aria-label on nav
+    props['aria-label'] = (typeof $desc.label === 'string') ? $desc.label : 'Breadcrumb';
+
     return Nav(instance.resolveProps(),
         OrderedList({ class: 'breadcrumb-list' },
             ForEachArray($desc.items, (item) => buildItem(item, $desc, instance)),
@@ -40,5 +43,10 @@ const buildItem = (item, $desc, instance) => {
 
     content.push(buildSeparator($desc));
 
-    return ListItem({class: 'breadcrumb-item'}, content);
+    // [a11y] aria-current on last item (no href = current page)
+    const isCurrent = !item.href;
+    return ListItem({
+        class: 'breadcrumb-item',
+        ...( isCurrent ? { 'aria-current': 'page' } : {} ),
+    }, content);
 };

package/src/ui/components/button/ButtonRender.js

@@ -36,6 +36,9 @@ export default function ButtonRender($desc, instance) {
         ...instance.resolveProps(),
         type:     $desc.type || 'button',
         disabled: $desc.disabled,
+        // [a11y] aria-busy and aria-disabled
+        ...($desc.loading  ? { 'aria-busy':     $desc.loading  } : {}),
+        ...($desc.disabled ? { 'aria-disabled': $desc.disabled } : {}),
     }, content);
 }
 

package/src/ui/components/contextmenu/ContextmenuRender.js

@@ -3,6 +3,7 @@ import {createPortal} from '../../../core/elements/anchor/anchor';
 import {computePosition, flip, shift} from '@floating-ui/dom';
 
 import './contextmenu.css';
+import {ariaTrigger} from '../../utils/aria';
 
 export default function ContextMenuRender($desc, instance) {
     const $positionX = instance.$description.positionX, $positionY = instance.$description.positionY;
@@ -19,6 +20,7 @@ export default function ContextMenuRender($desc, instance) {
     createPortal(container, {name: 'context-menu'});
 
     if($desc.trigger && instance) {
+        ariaTrigger($desc.trigger, $desc.isOpen, 'menu');
         contextMenuHandler($desc.trigger, instance);
     }
 

package/src/ui/components/dropdown/DropdownRender.js

@@ -4,9 +4,12 @@ import {createFilter} from '../../../core/utils/filters';
 import {normalizeDropdownItem} from '../../../components/dropdown/helpers';
 
 import './dropdown.css';
+import {ariaTrigger} from '../../utils/aria';
 
 export default function DropdownRender($desc, instance) {
     $desc.content = buildDropdownContent($desc, instance);
+    ariaTrigger($desc.trigger, $desc.isOpen, 'listbox');
+
 
     return PopoverRender($desc, instance, 'dropdown');
 }

package/src/ui/components/dropdown/item/DropdownItemRender.js

@@ -5,7 +5,12 @@ export default function DropdownItemRender($desc, instance) {
     const props = instance.getEditableProps();
 
     props.class.add('dropdown-item');
-    // props.class.add({ 'is-disabled': $desc.disabled, 'is-selected': $desc.selected });
+    props.class.add({ 'is-disabled': $desc.disabled, 'is-selected': $desc.selected });
+
+    if($desc.selected != null) {
+        props['aria-selected'] = $desc.selected;
+    }
+
 
     const content = [];
     if($desc.renderContent) {

package/src/ui/components/form/FieldCollectionRender.js

@@ -7,6 +7,10 @@ export default function FieldCollectionRender($desc, instance) {
     const props = instance.getEditableProps();
 
     props.class.add('field-collection');
+    // [a11y] aria-label if provided
+    if($desc.label) {
+        props['aria-label'] = $desc.label;
+    }
 
     const $items     = $desc.value;
     const $itemsMap  = new WeakMap();

package/src/ui/components/form/fields/CheckboxFieldRender.js

@@ -25,6 +25,7 @@ export default function CheckboxFieldRender($desc, instance) {
 }
 
 const buildCheckbox = ($desc, instance) => {
+    const isRequired = $desc.rules?.some(rule => rule.fn?.name === 'required');
     const input = Input({
         class:    'field-checkbox',
         type:     'checkbox',
@@ -32,6 +33,9 @@ const buildCheckbox = ($desc, instance) => {
         id:       $desc.id || $desc.name,
         disabled: $desc.disabled,
         checked:  $desc.checked,
+        // [a11y] aria-required, aria-invalid
+        ...(isRequired      ? { 'aria-required': 'true'        } : {}),
+        ...($desc.hasErrors ? { 'aria-invalid':  $desc.hasErrors } : {}),
         ...($desc.elementsProps.input || {}),
     });
 

package/src/ui/components/form/fields/CheckboxGroupFieldRender.js

@@ -85,8 +85,12 @@ const buildOptions = ($desc, instance) => {
         ]);
     };
 
+    const isRequired = $desc.rules?.some(rule => rule.fn?.name === 'required');
     return Div({
         class: 'field-checkbox-group is-' + ($desc.layout || 'vertical'),
+        // [a11y] role=group, aria-required
+        role:  'group',
+        ...( isRequired ? { 'aria-required': 'true' } : {} ),
         ...($desc.elementsProps.wrapper || {}),
     }, ForEachArray($desc.options, buildItem));
 };

package/src/ui/components/form/fields/RadioFieldRender.js

@@ -70,8 +70,12 @@ const buildOptions = ($desc, instance) => {
         ]);
     };
 
+    const isRequired = $desc.rules?.some(rule => rule.fn?.name === 'required');
     return Div({
         class: 'field-radio-group is-' + ($desc.layout || 'vertical'),
+        // [a11y] role=radiogroup, aria-required
+        role: 'radiogroup',
+        ...( isRequired ? { 'aria-required': 'true' } : {} ),
         ...($desc.elementsProps.wrapper || {}),
     }, ForEachArray($options, buildOption));
 };

package/src/ui/components/form/fields/RangeFieldRender.js

@@ -66,6 +66,10 @@ const buildInput = ($desc, instance) => {
         step: $desc.step ?? 1,
         disabled: $desc.disabled,
         value: $desc.value,
+        // [a11y] aria-valuemin, aria-valuemax, aria-valuenow
+        'aria-valuemin': String($desc.min ?? 0),
+        'aria-valuemax': String($desc.max ?? 100),
+        ...($desc.value?.__$Observable ? { 'aria-valuenow': $desc.value.transform((v) => String(v)) } : { 'aria-valuenow': String($desc.value ?? 0) }),
         ...($desc.elementsProps.input || {}),
     });
 

package/src/ui/components/form/fields/SelectFieldRender.js

@@ -61,8 +61,13 @@ const buildSelectWrapper = ($desc, instance) => {
     }
     triggerOptions.push(Span({class: 'select-field-chevron'}, '▾'));
 
+    const isRequired = $desc.rules?.some(rule => rule.fn?.name === 'required');
     const trigger = Div({
         class: {'field-input select-field-trigger': true, 'has-tags': isTags},
+        // [a11y] aria-haspopup, aria-expanded, aria-required
+        'aria-haspopup':  'listbox',
+        'aria-expanded':  'false',
+        ...( isRequired ? { 'aria-required': 'true' } : {} ),
         ...($desc.elementsProps.input || {}),
     }, [
         valueDisplay,

package/src/ui/components/form/fields/SliderFieldRender.js

@@ -7,6 +7,9 @@ export default function SliderRender($desc, instance) {
     const props = instance.getEditableProps();
 
     props.class.add('slider');
+    // [a11y] aria-valuemin, aria-valuemax
+    props['aria-valuemin'] = String($desc.min ?? 0);
+    props['aria-valuemax'] = String($desc.max ?? 100);
     props.class.add({
         'is-vertical':  $desc.vertical,
         'is-reverse':   $desc.reverse,

package/src/ui/components/icon/material/MaterialIconRender.js

@@ -0,0 +1,71 @@
+import './material.css';
+import MAP from './material.map.js';
+import { Span } from '../../../../core/elements';
+
+const SIZES = {
+    small:      16,
+    medium:     24,
+    large:      32,
+    extraLarge: 48,
+};
+
+// Variant -> CSS class
+// Material Icons uses the class as the font-family selector
+const VARIANT_CLASS = {
+    fill:     'material-icons',
+    regular:  'material-icons',
+    outline:  'material-icons-outlined',
+    round:    'material-icons-round',
+    sharp:    'material-icons-sharp',
+    twoTone:  'material-icons-two-tone',
+};
+
+/**
+ * Renders a Google Material Icon as a <span> element using CSS webfont ligatures.
+ * The icon name is the text content of the element — Material Icons uses ligatures.
+ *
+ * Variants: fill/regular (default), outline, round, sharp, twoTone
+ * Each variant requires its own CSS - see material.css.
+ *
+ * @param {object} $desc
+ * @param {string} $desc.name
+ * @param {'fill'|'regular'|'outline'|'round'|'sharp'|'twoTone'|Observable<string>|null} $desc.variant
+ * @param {'small'|'medium'|'large'|'extraLarge'|number|Observable<string|number>|null} $desc.size
+ * @param {string|Observable<string>|null} $desc.color
+ * @returns {HTMLElement}
+ */
+export default function MaterialIconRender($desc) {
+    const materialName = MAP[$desc.name] ?? $desc.name;
+    const style        = {};
+
+    let className;
+
+    if($desc.variant?.__$Observable) {
+        className = $desc.variant.transform((variant) => {
+            return VARIANT_CLASS[variant] ?? VARIANT_CLASS.fill;
+        });
+    } else {
+        className = VARIANT_CLASS[$desc.variant] ?? VARIANT_CLASS.fill;
+    }
+
+    if($desc.size?.__$Observable) {
+        style.fontSize = $desc.size.transform((size) => {
+            const px = typeof size === 'number' ? size : (SIZES[size] ?? SIZES.medium);
+            return `${px}px`;
+        });
+    } else {
+        const px = typeof $desc.size === 'number' ? $desc.size : (SIZES[$desc.size] ?? SIZES.medium);
+        style.fontSize = `${px}px`;
+    }
+
+    if($desc.color) {
+        style.color = $desc.color;
+    }
+
+    // Material Icons uses ligatures — the icon name is the text content
+    return Span({
+        'aria-hidden': 'true',
+        class:         className,
+        style,
+    }, materialName);
+}

package/src/ui/components/icon/material/material.css

@@ -0,0 +1,15 @@
+/*
+ * Google Material Icons webfont
+ * Install : npm install material-icons
+ *
+ * Import only the variants you need.
+ */
+/*@import 'material-icons/iconfont/filled.css';*/
+
+/*
+ * Uncomment the variants 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';  */