native-document 1.0.15 → 1.0.16-8.2

package/src/core/elements/control/switch.js

@@ -0,0 +1,141 @@
+import NativeDocumentError from '../../errors/NativeDocumentError';
+import Validator from '../../utils/validator';
+import Anchor from '../anchor/anchor';
+import {ElementCreator} from '../../wrappers/ElementCreator';
+
+
+
+/**
+ * Displays different content based on the current value of an observable.
+ * Like a switch statement for UI - shows the content corresponding to current value.
+ *
+ * @param {ObservableItem|ObservableChecker} $condition - Observable to watch
+ * @param {Object<string|number, NdChild|(() => NdChild)>} values - Map of values to their corresponding content
+ * @param {boolean} [shouldKeepInCache=true] - Whether to cache rendered views
+ * @returns {AnchorDocumentFragment & {add: Function, remove: Function}} Fragment with dynamic methods
+ * @example
+ * const status = Observable('idle');
+ * const view = Match(status, {
+ *   idle: Div({}, 'Ready'),
+ *   loading: Div({}, 'Loading...'),
+ *   error: Div({}, 'Error occurred')
+ * });
+ *
+ * // Dynamic addition
+ * view.add('success', Div({}, 'Success!'));
+ * view.remove('idle');
+ */
+export const Match = function($condition, values, shouldKeepInCache = true) {
+
+    if(!Validator.isObservable($condition)) {
+        throw new NativeDocumentError('Toggle : condition must be an Observable');
+    }
+
+    const anchor = Anchor('Match');
+    const cache = new Map();
+
+    const getItem = function(key) {
+        if(shouldKeepInCache && cache.has(key)) {
+            return cache.get(key);
+        }
+        let item = values[key];
+        if(!item) {
+            return null;
+        }
+        item = ElementCreator.getChild(item);
+        if(Validator.isFragment(item)) {
+            item = Array.from(item.children);
+        }
+        shouldKeepInCache && cache.set(key, item);
+        return item;
+    };
+
+    const defaultValue = $condition.val();
+    const defaultContent = getItem(defaultValue);
+    if(defaultContent) {
+        anchor.appendChild(defaultContent);
+    }
+
+    $condition.subscribe(value => {
+        const content = getItem(value);
+        anchor.remove();
+        if(content) {
+            anchor.appendChild(content);
+        }
+    });
+
+    return anchor.nd.with({
+        add(key, view, shouldFocusOn = false) {
+            values[key] = view;
+            if(shouldFocusOn) {
+                $condition.set(key);
+            }
+        },
+        remove(key) {
+            shouldKeepInCache && cache.delete(key);
+            $condition.set([...cache.keys()].at(-1) ?? '');
+            delete values[key];
+        },
+    });
+};
+
+
+/**
+ * Displays one of two views based on a boolean observable condition.
+ * Simplified version of Match for true/false cases.
+ *
+ * @param {ObservableItem<boolean>|ObservableChecker<boolean>} $condition - Boolean observable to watch
+ * @param {ValidChild} onTrue - Content to show when condition is true
+ * @param {ValidChild} onFalse - Content to show when condition is false
+ * @returns {AnchorDocumentFragment} Fragment managing the conditional content
+ * @example
+ * const isLoggedIn = Observable(false);
+ * Switch(isLoggedIn,
+ *   Div({}, 'Welcome back!'),
+ *   Div({}, 'Please login')
+ * );
+ */
+export const Switch = function ($condition, onTrue, onFalse) {
+    if(!Validator.isObservable($condition)) {
+        throw new NativeDocumentError('Toggle : condition must be an Observable');
+    }
+
+    return Match($condition.toBoolean(), {
+        true: onTrue,
+        false: onFalse,
+    });
+};
+
+/**
+ * Provides a fluent API for conditional rendering with show/otherwise pattern.
+ *
+ * @param {ObservableItem<boolean>|ObservableChecker<boolean>} $condition - Boolean observable to watch
+ * @returns {{show: Function, otherwise: Function}} Object with fluent methods
+ * @example
+ * const isLoading = Observable(false);
+ * When(isLoading)
+ *   .show(LoadingSpinner())
+ *   .otherwise(Content());
+ */
+export const When = function($condition) {
+    if(!Validator.isObservable($condition)) {
+        throw new NativeDocumentError('When : condition must be an Observable');
+    }
+
+    let $onTrue = null;
+    let $onFalse = null;
+
+    return {
+        show(onTrue) {
+            $onTrue = onTrue;
+            return this;
+        },
+        otherwise(onFalse) {
+            $onFalse = onFalse;
+            return Switch($condition, $onTrue, $onFalse);
+        },
+        toNdElement() {
+            return Switch($condition, $onTrue, $onFalse);
+        },
+    };
+};

package/src/core/elements/description-list.js

@@ -0,0 +1,19 @@
+import HtmlElementWrapper from '../wrappers/HtmlElementWrapper';
+
+/**
+ * Creates a `<dl>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLDListElement}
+ */
+export const Dl = HtmlElementWrapper('dl');
+
+/**
+ * Creates a `<dt>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
+export const Dt = HtmlElementWrapper('dt');
+
+/**
+ * Creates a `<dd>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
+export const Dd = HtmlElementWrapper('dd');

package/src/core/elements/form.js

@@ -0,0 +1,255 @@
+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', (el) => {
+
+    el.submit = function(action) {
+        if(typeof action === 'function') {
+            el.onSubmit((e) => {
+                e.preventDefault();
+                action(e);
+            });
+            return el;
+        }
+        this.setAttribute('action', action);
+        return el;
+    };
+    el.multipartFormData = function() {
+        this.setAttribute('enctype', 'multipart/form-data');
+        return el;
+    };
+    el.post = function(action) {
+        this.setAttribute('method', 'post');
+        this.setAttribute('action', action);
+        return el;
+    };
+    el.get = function(action) {
+        this.setAttribute('method', 'get');
+        this.setAttribute('action', action);
+    };
+    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');
+
+/**
+ * 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 });
+
+/**
+ * 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 });
+
+/**
+ * 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 });
+
+/**
+ * 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/fragment.js

@@ -0,0 +1,8 @@
+import HtmlElementWrapper from '../wrappers/HtmlElementWrapper';
+
+/**
+ * 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/html5-semantics.js

@@ -0,0 +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');
+
+/**
+ * Creates a `<footer>` element.
+ * @type {function(GlobalAttributes=, NdChild|NdChild[]=): HTMLElement}
+ */
+export const Footer = HtmlElementWrapper('footer');

package/src/core/elements/img.js

@@ -0,0 +1,59 @@
+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 });
+};
+
+/**
+ * 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;
+    const image = Img(defaultImage || defaultSrc, attributes);
+    const img = new Image();
+
+    img.onload = () => {
+        Validator.isFunction(callback) && callback(null, image);
+        image.src = Validator.isObservable(src) ? src.val() : src;
+    };
+    img.onerror = () => {
+        Validator.isFunction(callback) && callback(new NativeDocumentError('Image not found'));
+    };
+    if(Validator.isObservable(src)) {
+        src.subscribe(newSrc => {
+            img.src = newSrc;
+        });
+    }
+    img.src = defaultSrc;
+    return 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/{elements → core/elements}/index.js

@@ -1,8 +1,9 @@
-import HtmlElementWrapper from "../wrappers/HtmlElementWrapper";
+
 
 export * from './control/for-each';
 export * from './control/for-each-array';
 export * from './control/show-if';
+export * from './control/show-when';
 export * from './control/switch';
 export * from './content-formatter';
 export * from './description-list';
@@ -14,9 +15,8 @@ export * from './list';
 export * from './medias';
 export * from './meta-data';
 export * from './table';
-
-export const Fragment = HtmlElementWrapper('');
-
+export * from './svg';
+export * from './fragment';
 
 
 

package/src/core/elements/interactive.js

@@ -0,0 +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

@@ -0,0 +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;
+
+/**
+ * Alias for {@link UnorderedList}.
+ * @type {typeof UnorderedList}
+ */
+export const Ul = UnorderedList;

package/src/core/elements/medias.js

@@ -0,0 +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');