native-document 1.0.93 → 1.0.94

package/src/core/elements/form.js

@@ -1,6 +1,16 @@
 import HtmlElementWrapper from "../wrappers/HtmlElementWrapper";
 
 
+/**
+ * Creates a `<form>` element.
+ * Extended with fluent methods: `.submit()`, `.post()`, `.get()`, `.multipartFormData()`.
+ * @type {function(FormAttributes=, NdChild|NdChild[]=): HTMLFormElement & {
+ *   submit: (actionOrFn: string | ((e: SubmitEvent) => void)) => HTMLFormElement,
+ *   post: (action: string) => HTMLFormElement,
+ *   get: (action: string) => HTMLFormElement,
+ *   multipartFormData: () => HTMLFormElement,
+ * }}
+ */
 export const Form = HtmlElementWrapper('form', function(el) {
 
     el.submit = function(action) {
@@ -30,42 +40,216 @@ export const Form = HtmlElementWrapper('form', function(el) {
     return el;
 });
 
+/**
+ * Creates an `<input>` element.
+ * @type {function(InputAttributes=): HTMLInputElement}
+ */
 export const Input = HtmlElementWrapper('input');
 
+/**
+ * Creates a `<textarea>` element.
+ * @type {function(TextAreaAttributes=, NdChild|NdChild[]=): HTMLTextAreaElement}
+ */
 export const TextArea = HtmlElementWrapper('textarea');
+
+/**
+ * Alias for {@link TextArea}.
+ * @type {function(TextAreaAttributes=, NdChild|NdChild[]=): HTMLTextAreaElement}
+ */
 export const TextInput = TextArea;
 
+/**
+ * Creates a `<select>` element.
+ * @type {function(SelectAttributes=, NdChild|NdChild[]=): HTMLSelectElement}
+ */
 export const Select = HtmlElementWrapper('select');
-export const FieldSet = HtmlElementWrapper('fieldset', );
+
+/**
+ * Creates a `<fieldset>` element.
+ * @type {function(GlobalAttributes & { disabled?: Observable<boolean>|boolean }=, NdChild|NdChild[]=): HTMLFieldSetElement}
+ */
+export const FieldSet = HtmlElementWrapper('fieldset');
+
+/**
+ * Creates an `<option>` element.
+ * @type {function(OptionAttributes=, NdChild|NdChild[]=): HTMLOptionElement}
+ */
 export const Option = HtmlElementWrapper('option');
+
+/**
+ * Creates a `<legend>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLLegendElement}
+ */
 export const Legend = HtmlElementWrapper('legend');
+
+/**
+ * Creates a `<datalist>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLDataListElement}
+ */
 export const Datalist = HtmlElementWrapper('datalist');
+
+/**
+ * Creates an `<output>` element.
+ * @type {function(OutputAttributes=, NdChild|NdChild[]=): HTMLOutputElement}
+ */
 export const Output = HtmlElementWrapper('output');
+
+/**
+ * Creates a `<progress>` element.
+ * @type {function(ProgressAttributes=, NdChild|NdChild[]=): HTMLProgressElement}
+ */
 export const Progress = HtmlElementWrapper('progress');
+
+/**
+ * Creates a `<meter>` element.
+ * @type {function(MeterAttributes=, NdChild|NdChild[]=): HTMLMeterElement}
+ */
 export const Meter = HtmlElementWrapper('meter');
 
+/**
+ * Creates an `<input readonly>` element.
+ * @param {Omit<InputAttributes, 'type'|'readonly'|'readOnly'>} [attributes]
+ * @returns {HTMLInputElement}
+ */
 export const ReadonlyInput = (attributes) => Input({ readonly: true, ...attributes });
-export const HiddenInput = (attributes) => Input({type: 'hidden', ...attributes });
+
+/**
+ * Creates an `<input type="hidden">` element.
+ * @param {Omit<InputAttributes, 'type'>} [attributes]
+ * @returns {HTMLInputElement}
+ */
+export const HiddenInput = (attributes) => Input({ type: 'hidden', ...attributes });
+
+/**
+ * Creates an `<input type="file">` element.
+ * @param {Omit<InputAttributes, 'type'>} [attributes]
+ * @returns {HTMLInputElement}
+ */
 export const FileInput = (attributes) => Input({ type: 'file', ...attributes });
+
+/**
+ * Creates an `<input type="password">` element.
+ * @param {Omit<InputAttributes, 'type'>} [attributes]
+ * @returns {HTMLInputElement}
+ */
 export const PasswordInput = (attributes) => Input({ type: 'password', ...attributes });
+
+/**
+ * Creates an `<input type="checkbox">` element.
+ * @param {Omit<InputAttributes, 'type'>} [attributes]
+ * @returns {HTMLInputElement}
+ */
 export const Checkbox = (attributes) => Input({ type: 'checkbox', ...attributes });
+
+/**
+ * Creates an `<input type="radio">` element.
+ * @param {Omit<InputAttributes, 'type'>} [attributes]
+ * @returns {HTMLInputElement}
+ */
 export const Radio = (attributes) => Input({ type: 'radio', ...attributes });
 
+/**
+ * Creates an `<input type="range">` element.
+ * @param {Omit<InputAttributes, 'type'>} [attributes]
+ * @returns {HTMLInputElement}
+ */
 export const RangeInput = (attributes) => Input({ type: 'range', ...attributes });
+
+/**
+ * Creates an `<input type="color">` element.
+ * @param {Omit<InputAttributes, 'type'>} [attributes]
+ * @returns {HTMLInputElement}
+ */
 export const ColorInput = (attributes) => Input({ type: 'color', ...attributes });
+
+/**
+ * Creates an `<input type="date">` element.
+ * @param {Omit<InputAttributes, 'type'>} [attributes]
+ * @returns {HTMLInputElement}
+ */
 export const DateInput = (attributes) => Input({ type: 'date', ...attributes });
+
+/**
+ * Creates an `<input type="time">` element.
+ * @param {Omit<InputAttributes, 'type'>} [attributes]
+ * @returns {HTMLInputElement}
+ */
 export const TimeInput = (attributes) => Input({ type: 'time', ...attributes });
+
+/**
+ * Creates an `<input type="datetime-local">` element.
+ * @param {Omit<InputAttributes, 'type'>} [attributes]
+ * @returns {HTMLInputElement}
+ */
 export const DateTimeInput = (attributes) => Input({ type: 'datetime-local', ...attributes });
+
+/**
+ * Creates an `<input type="week">` element.
+ * @param {Omit<InputAttributes, 'type'>} [attributes]
+ * @returns {HTMLInputElement}
+ */
 export const WeekInput = (attributes) => Input({ type: 'week', ...attributes });
+
+/**
+ * Creates an `<input type="month">` element.
+ * @param {Omit<InputAttributes, 'type'>} [attributes]
+ * @returns {HTMLInputElement}
+ */
 export const MonthInput = (attributes) => Input({ type: 'month', ...attributes });
+
+/**
+ * Creates an `<input type="search">` element.
+ * @param {Omit<InputAttributes, 'type'>} [attributes]
+ * @returns {HTMLInputElement}
+ */
 export const SearchInput = (attributes) => Input({ type: 'search', ...attributes });
+
+/**
+ * Creates an `<input type="tel">` element.
+ * @param {Omit<InputAttributes, 'type'>} [attributes]
+ * @returns {HTMLInputElement}
+ */
 export const TelInput = (attributes) => Input({ type: 'tel', ...attributes });
+
+/**
+ * Creates an `<input type="url">` element.
+ * @param {Omit<InputAttributes, 'type'>} [attributes]
+ * @returns {HTMLInputElement}
+ */
 export const UrlInput = (attributes) => Input({ type: 'url', ...attributes });
+
+/**
+ * Creates an `<input type="email">` element.
+ * @param {Omit<InputAttributes, 'type'>} [attributes]
+ * @returns {HTMLInputElement}
+ */
 export const EmailInput = (attributes) => Input({ type: 'email', ...attributes });
-export const NumberInput = (attributes) => Input({ type: 'number', ...attributes });
 
+/**
+ * Creates an `<input type="number">` element.
+ * @param {Omit<InputAttributes, 'type'>} [attributes]
+ * @returns {HTMLInputElement}
+ */
+export const NumberInput = (attributes) => Input({ type: 'number', ...attributes });
 
+/**
+ * Creates a `<button>` element.
+ * @type {function(ButtonAttributes=, NdChild|NdChild[]=): HTMLButtonElement}
+ */
 export const Button = HtmlElementWrapper('button');
+
+/**
+ * Creates a `<button type="button">` element.
+ * @param {NdChild|NdChild[]} [child]
+ * @param {Omit<ButtonAttributes, 'type'>} [attributes]
+ * @returns {HTMLButtonElement}
+ */
 export const SimpleButton = (child, attributes) => Button(child, { type: 'button', ...attributes });
-export const SubmitButton = (child, attributes) => Button(child, { type: 'submit', ...attributes });
 
+/**
+ * Creates a `<button type="submit">` element.
+ * @param {NdChild|NdChild[]} [child]
+ * @param {Omit<ButtonAttributes, 'type'>} [attributes]
+ * @returns {HTMLButtonElement}
+ */
+export const SubmitButton = (child, attributes) => Button(child, { type: 'submit', ...attributes });

package/src/core/elements/html5-semantics.js

@@ -1,12 +1,55 @@
 import HtmlElementWrapper from "../wrappers/HtmlElementWrapper";
 
+/**
+ * Creates a `<main>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const Main = HtmlElementWrapper('main');
+
+/**
+ * Creates a `<section>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const Section = HtmlElementWrapper('section');
+
+/**
+ * Creates an `<article>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const Article = HtmlElementWrapper('article');
+
+/**
+ * Creates an `<aside>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const Aside = HtmlElementWrapper('aside');
+
+/**
+ * Creates a `<nav>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const Nav = HtmlElementWrapper('nav');
+
+/**
+ * Creates a `<figure>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const Figure = HtmlElementWrapper('figure');
+
+/**
+ * Creates a `<figcaption>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const FigCaption = HtmlElementWrapper('figcaption');
 
+/**
+ * Creates a `<header>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const Header = HtmlElementWrapper('header');
-export const Footer = HtmlElementWrapper('footer');
+
+/**
+ * Creates a `<footer>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
+export const Footer = HtmlElementWrapper('footer');

package/src/core/elements/img.js

@@ -2,18 +2,30 @@ import HtmlElementWrapper from "../wrappers/HtmlElementWrapper"
 import Validator from "../utils/validator";
 import NativeDocumentError from "../errors/NativeDocumentError";
 
+/**
+ * Creates an `<img>` element.
+ * @type {function(ImgAttributes=): HTMLImageElement}
+ */
 export const BaseImage = HtmlElementWrapper('img');
+
+/**
+ * Creates an `<img>` element.
+ * @param {Observable<string>|string} src
+ * @param {Omit<ImgAttributes, 'src'>} [attributes]
+ * @returns {HTMLImageElement}
+ */
 export const Img = function(src, attributes) {
     return BaseImage({ src, ...attributes });
 };
 
 /**
- *
- * @param {string} src
- * @param {string|null} defaultImage
- * @param {Object} attributes
- * @param {?Function} callback
- * @returns {Image}
+ * Creates an `<img>` that loads asynchronously, showing a placeholder until the image is ready.
+ * Supports reactive `src` — automatically updates when the observable changes.
+ * @param {Observable<string>|string} src                                        - Final image URL
+ * @param {string|null}               defaultImage                               - Placeholder shown while loading
+ * @param {Omit<ImgAttributes, 'src'>} attributes
+ * @param {(error: NativeDocumentError|null, img: HTMLImageElement) => void} [callback]
+ * @returns {HTMLImageElement}
  */
 export const AsyncImg = function(src, defaultImage, attributes, callback) {
     const defaultSrc = Validator.isObservable(src) ? src.val() : src;
@@ -37,10 +49,10 @@ export const AsyncImg = function(src, defaultImage, attributes, callback) {
 };
 
 /**
- *
- * @param {string} src
- * @param {Object} attributes
- * @returns {Image}
+ * Creates an `<img loading="lazy">` element.
+ * @param {Observable<string>|string}          src
+ * @param {Omit<ImgAttributes, 'src'|'loading'>} [attributes]
+ * @returns {HTMLImageElement}
  */
 export const LazyImg = function(src, attributes) {
     return Img(src, { ...attributes, loading: 'lazy' });

package/src/core/elements/index.js

@@ -16,6 +16,11 @@ export * from './medias';
 export * from './meta-data';
 export * from './table';
 
+/**
+ * Creates an empty `DocumentFragment` wrapper.
+ * Useful for grouping elements without adding a DOM node.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): DocumentFragment}
+ */
 export const Fragment = HtmlElementWrapper('');
 
 

package/src/core/elements/interactive.js

@@ -1,7 +1,25 @@
 import HtmlElementWrapper from "../wrappers/HtmlElementWrapper";
 
-
+/**
+ * Creates a `<details>` element.
+ * @type {function(DetailsAttributes=, NdChild|NdChild[]=): HTMLDetailsElement}
+ */
 export const Details = HtmlElementWrapper('details');
+
+/**
+ * Creates a `<summary>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const Summary = HtmlElementWrapper('summary');
+
+/**
+ * Creates a `<dialog>` element.
+ * @type {function(DialogAttributes=, NdChild|NdChild[]=): HTMLDialogElement}
+ */
 export const Dialog = HtmlElementWrapper('dialog');
+
+/**
+ * Creates a `<menu>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLMenuElement}
+ */
 export const Menu = HtmlElementWrapper('menu');

package/src/core/elements/list.js

@@ -1,10 +1,37 @@
 import HtmlElementWrapper from "../wrappers/HtmlElementWrapper";
 
+/**
+ * Creates an `<ol>` element.
+ * @type {function(OlAttributes=, NdChild|NdChild[]=): HTMLOListElement}
+ */
 export const OrderedList = HtmlElementWrapper('ol');
+
+/**
+ * Creates a `<ul>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLUListElement}
+ */
 export const UnorderedList = HtmlElementWrapper('ul');
+
+/**
+ * Creates a `<li>` element.
+ * @type {function(GlobalAttributes & { value?: number }=, NdChild|NdChild[]=): HTMLLIElement}
+ */
 export const ListItem = HtmlElementWrapper('li');
 
+/**
+ * Alias for {@link ListItem}.
+ * @type {typeof ListItem}
+ */
 export const Li = ListItem;
+
+/**
+ * Alias for {@link OrderedList}.
+ * @type {typeof OrderedList}
+ */
 export const Ol = OrderedList;
-export const Ul = UnorderedList;
 
+/**
+ * Alias for {@link UnorderedList}.
+ * @type {typeof UnorderedList}
+ */
+export const Ul = UnorderedList;

package/src/core/elements/medias.js

@@ -1,8 +1,37 @@
 import HtmlElementWrapper from "../wrappers/HtmlElementWrapper";
 
+/**
+ * Creates an `<audio>` element.
+ * @type {function(AudioAttributes=, NdChild|NdChild[]=): HTMLAudioElement}
+ */
 export const Audio = HtmlElementWrapper('audio');
+
+/**
+ * Creates a `<video>` element.
+ * @type {function(VideoAttributes=, NdChild|NdChild[]=): HTMLVideoElement}
+ */
 export const Video = HtmlElementWrapper('video');
+
+/**
+ * Creates a `<source>` element.
+ * @type {function(SourceAttributes=): HTMLSourceElement}
+ */
 export const Source = HtmlElementWrapper('source');
+
+/**
+ * Creates a `<track>` element.
+ * @type {function(TrackAttributes=): HTMLTrackElement}
+ */
 export const Track = HtmlElementWrapper('track');
+
+/**
+ * Creates a `<canvas>` element.
+ * @type {function(CanvasAttributes=, NdChild|NdChild[]=): HTMLCanvasElement}
+ */
 export const Canvas = HtmlElementWrapper('canvas');
+
+/**
+ * Creates an `<svg>` element.
+ * @type {function(SvgAttributes=, NdChild|NdChild[]=): SVGSVGElement}
+ */
 export const Svg = HtmlElementWrapper('svg');

package/src/core/elements/meta-data.js

@@ -1,9 +1,43 @@
 import HtmlElementWrapper from "../wrappers/HtmlElementWrapper";
 
+/**
+ * Creates a `<time>` element.
+ * @type {function(TimeAttributes=, NdChild|NdChild[]=): HTMLTimeElement}
+ */
 export const Time = HtmlElementWrapper('time');
+
+/**
+ * Creates a `<data>` element.
+ * @type {function(GlobalAttributes & { value?: Observable<string>|string }=, NdChild|NdChild[]=): HTMLDataElement}
+ */
 export const Data = HtmlElementWrapper('data');
+
+/**
+ * Creates an `<address>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const Address = HtmlElementWrapper('address');
+
+/**
+ * Creates a `<kbd>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const Kbd = HtmlElementWrapper('kbd');
+
+/**
+ * Creates a `<samp>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const Samp = HtmlElementWrapper('samp');
+
+/**
+ * Creates a `<var>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
 export const Var = HtmlElementWrapper('var');
+
+/**
+ * Creates a `<wbr>` element.
+ * @type {function(GlobalAttributes=): HTMLElement}
+ */
 export const Wbr = HtmlElementWrapper('wbr');

package/src/core/elements/table.js

@@ -1,14 +1,73 @@
 import HtmlElementWrapper from "../wrappers/HtmlElementWrapper";
 
+/**
+ * Creates a `<caption>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLTableCaptionElement}
+ */
 export const Caption = HtmlElementWrapper('caption');
+
+/**
+ * Creates a `<table>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLTableElement}
+ */
 export const Table = HtmlElementWrapper('table');
+
+/**
+ * Creates a `<thead>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLTableSectionElement}
+ */
 export const THead = HtmlElementWrapper('thead');
+
+/**
+ * Creates a `<tfoot>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLTableSectionElement}
+ */
 export const TFoot = HtmlElementWrapper('tfoot');
+
+/**
+ * Creates a `<tbody>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLTableSectionElement}
+ */
 export const TBody = HtmlElementWrapper('tbody');
+
+/**
+ * Creates a `<tr>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLTableRowElement}
+ */
 export const Tr = HtmlElementWrapper('tr');
+
+/**
+ * Alias for {@link Tr}.
+ * @type {typeof Tr}
+ */
 export const TRow = Tr;
+
+/**
+ * Creates a `<th>` element.
+ * @type {function(ThAttributes=, NdChild|NdChild[]=): HTMLTableCellElement}
+ */
 export const Th = HtmlElementWrapper('th');
+
+/**
+ * Alias for {@link Th}.
+ * @type {typeof Th}
+ */
 export const THeadCell = Th;
+
+/**
+ * Alias for {@link Th}.
+ * @type {typeof Th}
+ */
 export const TFootCell = Th;
+
+/**
+ * Creates a `<td>` element.
+ * @type {function(TdAttributes=, NdChild|NdChild[]=): HTMLTableCellElement}
+ */
 export const Td = HtmlElementWrapper('td');
+
+/**
+ * Alias for {@link Td}.
+ * @type {typeof Td}
+ */
 export const TBodyCell = Td;

package/src/core/utils/helpers.js

@@ -75,7 +75,12 @@ export const trim = function(str, char) {
 }
 
 export const deepClone = (value, onObservableFound) => {
-    // Primitives
+    try {
+        if(window.structuredClone !== undefined) {
+            return window.structuredClone(value);
+        }
+    } catch (e){}
+
     if (value === null || typeof value !== 'object') {
         return value;
     }
@@ -99,7 +104,7 @@ export const deepClone = (value, onObservableFound) => {
     // Objects
     const cloned = {};
     for (const key in value) {
-        if (value.hasOwnProperty(key)) {
+        if (Object.hasOwn(value, key)) {
             cloned[key] = deepClone(value[key]);
         }
     }

package/src/core/utils/memoize.js

@@ -3,7 +3,7 @@
 export const once = (fn) => {
     let result = null;
     return (...args) => {
-        if(result) {
+        if(result != null) {
             return result;
         }
         result = fn(...args);

package/src/core/wrappers/HtmlElementWrapper.js

@@ -28,10 +28,10 @@ function createHtmlElement($tagName, customWrapper, _attributes, _children = nul
 /**
  *
  * @param {string} name
- * @param {?Function} customWrapper
+ * @param {?Function=} customWrapper
  * @returns {Function}
  */
-export default function HtmlElementWrapper(name, customWrapper) {
+export default function HtmlElementWrapper(name, customWrapper = null) {
     return createHtmlElement.bind(null, name, customWrapper);
 };
 

package/src/core/wrappers/NDElement.js

@@ -195,7 +195,7 @@ NDElement.extend = function(methods) {
     ]);
 
     for (const name in methods) {
-        if (!methods.hasOwnProperty(name)) {
+        if (!Object.hasOwn(methods, name)) {
             continue;
         }
 

package/src/core/wrappers/TemplateCloner.js

@@ -51,7 +51,7 @@ const $hydrateFn = function(hydrateFunction, targetType, element, property) {
     hydrationState[targetType][property] = hydrateFunction;
 }
 
-const bindAttachMethods = function(node, bindDingData, data) {
+const bindAttachMethods = (node, bindDingData, data) => {
     if(!bindDingData.attach) {
         return null;
     }