@qorejs/qore 0.7.0 → 0.7.2

package/dist/src/dom/app.d.ts

@@ -0,0 +1,38 @@
+import { dynamic, fragment, h, list, renderResponse, show, text } from './dom.js';
+import { batch, computed, effect, signal, untrack } from '../core/signal.js';
+import { response } from '../core/response.js';
+import { from, mapStream, scanStream, stream } from '../core/stream.js';
+import type { MountTarget, MountView, QoreChild, QoreElement } from './types.js';
+export interface AppContext<Props extends Record<string, unknown>> {
+    app: QoreApp<Props>;
+    root: QoreElement;
+    props: Props;
+    signal: typeof signal;
+    computed: typeof computed;
+    effect: typeof effect;
+    batch: typeof batch;
+    untrack: typeof untrack;
+    stream: typeof stream;
+    from: typeof from;
+    mapStream: typeof mapStream;
+    scanStream: typeof scanStream;
+    response: typeof response;
+    h: typeof h;
+    text: typeof text;
+    dynamic: typeof dynamic;
+    show: typeof show;
+    list: typeof list;
+    fragment: typeof fragment;
+    renderResponse: typeof renderResponse;
+    onCleanup(handler: (() => void) | null | undefined): (() => void) | null | undefined;
+}
+export type AppSetupResult = QoreChild | {
+    view?: MountView;
+    onMount?: (root: QoreElement) => void;
+};
+export interface QoreApp<Props extends Record<string, unknown>> {
+    mount(target: MountTarget, props?: Props): QoreElement;
+    unmount(): QoreApp<Props>;
+    readonly root: QoreElement | null;
+}
+export declare function createApp<Props extends Record<string, unknown> = Record<string, unknown>>(setup: (context: AppContext<Props>) => AppSetupResult): QoreApp<Props>;

package/dist/src/dom/app.js

@@ -0,0 +1,102 @@
+import { dynamic, fragment, h, list, mount, renderResponse, show, text } from './dom.js';
+import { batch, computed, effect, signal, untrack } from '../core/signal.js';
+import { response } from '../core/response.js';
+import { from, mapStream, scanStream, stream } from '../core/stream.js';
+// Resolve a CSS selector or direct node into the root mount target.
+function resolveTarget(target) {
+    if (typeof document === 'undefined') {
+        throw new Error('Qore app mounting requires a browser-like environment');
+    }
+    if (typeof target === 'string') {
+        const element = document.querySelector(target);
+        if (!element) {
+            throw new Error(`Qore could not find a mount target for selector: ${target}`);
+        }
+        return element;
+    }
+    return target;
+}
+// Create a tiny application shell around Qore's lower-level primitives.
+export function createApp(setup) {
+    let dispose = null;
+    let mountedRoot = null;
+    let cleanupHandlers = [];
+    const app = {
+        // Mount the app, provide framework primitives to setup, and render the resulting view.
+        mount(target, props = {}) {
+            const root = resolveTarget(target);
+            app.unmount();
+            cleanupHandlers = [];
+            mountedRoot = root;
+            // Expose the core runtime pieces so an app can stay entirely within Qore primitives.
+            const context = {
+                app,
+                root,
+                props,
+                signal,
+                computed,
+                effect,
+                batch,
+                untrack,
+                stream,
+                from,
+                mapStream,
+                scanStream,
+                response,
+                h,
+                text,
+                dynamic,
+                show,
+                list,
+                fragment,
+                renderResponse,
+                onCleanup(handler) {
+                    if (typeof handler === 'function') {
+                        cleanupHandlers.push(handler);
+                    }
+                    return handler;
+                }
+            };
+            // Allow setup to return either a raw view or an object with lifecycle hooks.
+            const result = setup(context);
+            const lifecycleResult = result && typeof result === 'object'
+                ? result
+                : null;
+            const view = lifecycleResult && 'view' in lifecycleResult
+                ? lifecycleResult.view
+                : result;
+            const onMount = lifecycleResult?.onMount ?? null;
+            dispose = mount(root, view);
+            if (typeof onMount === 'function') {
+                onMount(root);
+            }
+            return root;
+        },
+        // Tear down the mounted tree and any user-registered cleanup handlers.
+        unmount() {
+            if (dispose) {
+                const stop = dispose;
+                dispose = null;
+                stop();
+            }
+            for (let index = cleanupHandlers.length - 1; index >= 0; index -= 1) {
+                try {
+                    const cleanup = cleanupHandlers[index];
+                    if (cleanup) {
+                        cleanup();
+                    }
+                }
+                catch {
+                    // Ignore user cleanup errors so the app can still unmount.
+                }
+            }
+            cleanupHandlers = [];
+            mountedRoot = null;
+            return app;
+        },
+        get root() {
+            return mountedRoot;
+        }
+    };
+    return app;
+}

package/dist/src/dom/dom.d.ts

@@ -0,0 +1,13 @@
+import type { ResponseState } from '../core/response.js';
+import type { MountTarget, MountView, QoreDocumentFragment, QoreElement, QoreChild, QoreComponent, QoreText, ReactiveValue, ResponseViews } from './types.js';
+export declare function fragment(...children: QoreChild[]): QoreDocumentFragment;
+export declare function dynamic<T>(source: ReactiveValue<T>, render?: (value: T) => QoreChild): QoreDocumentFragment;
+export declare function show<T>(source: ReactiveValue<T>, render?: (value: T) => QoreChild, fallback?: QoreChild | ((value: T) => QoreChild)): QoreDocumentFragment;
+export declare function list<T>(source: ReactiveValue<Iterable<T> | ArrayLike<T> | null | undefined>, render: (item: T, index: number) => QoreChild, options?: {
+    fallback?: QoreChild | ((items: T[]) => QoreChild);
+}): QoreDocumentFragment;
+export declare function renderResponse<TChunk, TValue>(responseState: ResponseState<TChunk, TValue>, views?: ResponseViews<TChunk, TValue>): QoreDocumentFragment;
+export declare function h(tag: string, props?: Record<string, unknown> | null, ...children: QoreChild[]): QoreElement;
+export declare function h<TProps extends Record<string, unknown>>(tag: QoreComponent<TProps>, props?: TProps | null, ...children: QoreChild[]): QoreChild;
+export declare function text(valueOrGetter: ReactiveValue<unknown>): QoreText;
+export declare function mount(root: MountTarget, view: MountView): () => QoreElement;

package/dist/src/dom/dom.js

@@ -0,0 +1,197 @@
+import { effect } from '../core/signal.js';
+import { bindProp } from './properties.js';
+import { isReactiveValue, resolveAccessor, resolveTemplate } from './reactive.js';
+import { pickResponseTemplate, readResponseState } from './response-view.js';
+import { ROOT_CLEANUP, assertDocument, createScope, disposeScope, registerCleanup, withScope } from './scope.js';
+function isDomNode(value) {
+    return typeof Node !== 'undefined' && value instanceof Node;
+}
+// Convert supported child types into concrete nodes that can be inserted into the DOM.
+function materializeChild(buffer, child) {
+    if (Array.isArray(child)) {
+        for (const entry of child) {
+            materializeChild(buffer, entry);
+        }
+        return;
+    }
+    if (child == null || child === false || child === true) {
+        return;
+    }
+    if (isReactiveValue(child)) {
+        buffer.push(dynamic(child));
+        return;
+    }
+    if (isDomNode(child)) {
+        buffer.push(child);
+        return;
+    }
+    if (typeof child === 'string' || typeof child === 'number' || typeof child === 'bigint') {
+        buffer.push(document.createTextNode(String(child)));
+        return;
+    }
+    throw new TypeError(`Unsupported Qore child: ${typeof child}. Use strings, numbers, DOM nodes, arrays, or reactive getters.`);
+}
+// Flatten any child payload into a linear list of nodes.
+function materialize(value) {
+    const nodes = [];
+    materializeChild(nodes, value);
+    return nodes;
+}
+// Append normalized child content to a parent node or fragment.
+function appendChild(parent, child) {
+    for (const node of materialize(child)) {
+        parent.appendChild(node);
+    }
+}
+// Remove every node between the two markers of a dynamic region.
+function clearRange(start, end) {
+    let current = start.nextSibling;
+    while (current && current !== end) {
+        const next = current.nextSibling;
+        current.remove();
+        current = next;
+    }
+}
+// Replace a dynamic region without recreating its boundary markers.
+function replaceRange(start, end, nextValue) {
+    const parent = end.parentNode;
+    if (!parent) {
+        return;
+    }
+    clearRange(start, end);
+    for (const node of materialize(nextValue)) {
+        parent.insertBefore(node, end);
+    }
+}
+// Allow mount targets to be passed as selectors or direct nodes.
+function resolveRoot(root) {
+    if (typeof root === 'string') {
+        const element = document.querySelector(root);
+        if (!element) {
+            throw new Error(`Qore could not find a mount target for selector: ${root}`);
+        }
+        return element;
+    }
+    return root;
+}
+// Build a fragment from a variadic list of children.
+export function fragment(...children) {
+    assertDocument();
+    const node = document.createDocumentFragment();
+    for (const child of children) {
+        appendChild(node, child);
+    }
+    return node;
+}
+// Render a live region between comment markers and refresh it when the source changes.
+export function dynamic(source, render = (value) => value) {
+    assertDocument();
+    const start = document.createComment('qore-dynamic-start');
+    const end = document.createComment('qore-dynamic-end');
+    const node = document.createDocumentFragment();
+    node.append(start, end);
+    let childScope = null;
+    const stop = effect(() => {
+        const nextValue = resolveAccessor(source);
+        disposeScope(childScope);
+        childScope = createScope();
+        const renderedValue = withScope(childScope, () => resolveTemplate(render, nextValue));
+        replaceRange(start, end, renderedValue);
+    });
+    registerCleanup(() => {
+        stop();
+        disposeScope(childScope);
+    });
+    return node;
+}
+// Conditionally render one branch or a fallback from a truthy source.
+export function show(source, render, fallback = null) {
+    const truthyView = render === undefined
+        ? (value) => value
+        : render;
+    return dynamic(source, (value) => value
+        ? resolveTemplate(truthyView, value)
+        : resolveTemplate(fallback, value));
+}
+// Render a list reactively, or a fallback when the collection is empty.
+export function list(source, render, options = {}) {
+    const { fallback = null } = options;
+    return dynamic(source, (value) => {
+        const items = value == null
+            ? []
+            : Array.isArray(value)
+                ? value
+                : Array.from(value);
+        if (items.length === 0) {
+            return resolveTemplate(fallback, items);
+        }
+        return items.map((item, index) => render(item, index));
+    });
+}
+// Render response state through status-aware template overrides.
+export function renderResponse(responseState, views = {}) {
+    return dynamic(() => readResponseState(responseState), (state) => {
+        const template = pickResponseTemplate(state.status, views);
+        if (template !== undefined) {
+            return resolveTemplate(template, state);
+        }
+        if (state.status === 'error') {
+            return state.error?.message ?? 'Qore response failed.';
+        }
+        return state.value;
+    });
+}
+export function h(tag, props = null, ...children) {
+    assertDocument();
+    if (typeof tag === 'function') {
+        return tag({
+            ...(props ?? {}),
+            children
+        });
+    }
+    const element = document.createElement(tag);
+    if (props) {
+        for (const [key, value] of Object.entries(props)) {
+            bindProp(element, key, value);
+        }
+    }
+    for (const child of children) {
+        appendChild(element, child);
+    }
+    return element;
+}
+// Create a text node and keep it in sync with a reactive getter when necessary.
+export function text(valueOrGetter) {
+    assertDocument();
+    const node = document.createTextNode('');
+    if (isReactiveValue(valueOrGetter)) {
+        const stop = effect(() => {
+            const nextValue = resolveAccessor(valueOrGetter);
+            node.textContent = nextValue == null ? '' : String(nextValue);
+        });
+        registerCleanup(stop);
+        return node;
+    }
+    node.textContent = valueOrGetter == null ? '' : String(valueOrGetter);
+    return node;
+}
+// Mount a view into a root element and return a disposer for its reactive scope.
+export function mount(root, view) {
+    assertDocument();
+    const target = resolveRoot(root);
+    target[ROOT_CLEANUP]?.();
+    const scope = createScope();
+    const content = withScope(scope, () => typeof view === 'function' ? view() : view);
+    target.replaceChildren();
+    appendChild(target, content);
+    const dispose = () => {
+        if (target[ROOT_CLEANUP] === dispose) {
+            delete target[ROOT_CLEANUP];
+        }
+        disposeScope(scope);
+        target.replaceChildren();
+        return target;
+    };
+    target[ROOT_CLEANUP] = dispose;
+    return dispose;
+}

package/dist/src/dom/properties.d.ts

@@ -0,0 +1,3 @@
+type DomPropertyTarget = HTMLElement;
+export declare function bindProp(element: DomPropertyTarget, key: string, value: unknown): void;
+export {};

package/dist/src/dom/properties.js

@@ -0,0 +1,147 @@
+import { effect, isSignal } from '../core/signal.js';
+import { isReactiveValue, resolveAccessor } from './reactive.js';
+import { registerCleanup } from './scope.js';
+// Normalize class payloads so callers can pass strings, arrays, or object maps.
+function normalizeClassName(value) {
+    if (Array.isArray(value)) {
+        return value
+            .map((entry) => normalizeClassName(entry))
+            .filter(Boolean)
+            .join(' ');
+    }
+    if (value && typeof value === 'object') {
+        return Object.entries(value)
+            .filter(([, active]) => Boolean(active))
+            .map(([className]) => className)
+            .join(' ');
+    }
+    if (value == null || value === false) {
+        return '';
+    }
+    return String(value);
+}
+// Apply styles from either a raw string or a property map.
+function setStyleValue(element, value) {
+    element.style.cssText = '';
+    if (typeof value === 'string') {
+        element.style.cssText = value;
+        return;
+    }
+    if (!value || typeof value !== 'object') {
+        if (value == null || value === false) {
+            element.removeAttribute('style');
+        }
+        return;
+    }
+    const styleRecord = element.style;
+    for (const [property, propertyValue] of Object.entries(value)) {
+        styleRecord[property] = propertyValue == null || propertyValue === false
+            ? ''
+            : String(propertyValue);
+    }
+}
+// Centralize DOM property and attribute writes behind one compatibility layer.
+function setDomProperty(element, key, value) {
+    const attributeName = key === 'className' ? 'class' : key;
+    const domRecord = element;
+    if (key === 'className' || key === 'class') {
+        element.className = normalizeClassName(value);
+        return;
+    }
+    if (key === 'style') {
+        setStyleValue(element, value);
+        return;
+    }
+    if (value == null || value === false) {
+        if (key in element && key !== 'list' && key !== 'form') {
+            try {
+                if (typeof domRecord[key] === 'boolean') {
+                    domRecord[key] = false;
+                }
+                else if (key === 'value') {
+                    domRecord[key] = '';
+                }
+                else {
+                    domRecord[key] = '';
+                }
+            }
+            catch {
+                // Ignore readonly DOM properties and fall back to attribute cleanup.
+            }
+        }
+        element.removeAttribute(attributeName);
+        return;
+    }
+    if (value === true) {
+        if (key in element && key !== 'list' && key !== 'form') {
+            try {
+                domRecord[key] = true;
+            }
+            catch {
+                // Fall through to attribute mode.
+            }
+        }
+        element.setAttribute(attributeName, '');
+        return;
+    }
+    if (key in element && key !== 'list' && key !== 'form') {
+        try {
+            domRecord[key] = value;
+            return;
+        }
+        catch {
+            // Fall back to setAttribute for readonly DOM properties.
+        }
+    }
+    element.setAttribute(attributeName, String(value));
+}
+// Bind events and only treat signal-like values as reactive handler containers.
+function bindEvent(element, key, handler) {
+    const eventName = key.slice(2).toLowerCase();
+    if (isSignal(handler)) {
+        let activeHandler = null;
+        const stop = effect(() => {
+            const nextHandler = handler();
+            if (activeHandler) {
+                element.removeEventListener(eventName, activeHandler);
+            }
+            activeHandler = typeof nextHandler === 'function' ? nextHandler : null;
+            if (activeHandler) {
+                element.addEventListener(eventName, activeHandler);
+            }
+        });
+        registerCleanup(() => {
+            stop();
+            if (activeHandler) {
+                element.removeEventListener(eventName, activeHandler);
+            }
+        });
+        return;
+    }
+    if (typeof handler === 'function') {
+        const listener = handler;
+        element.addEventListener(eventName, listener);
+        registerCleanup(() => element.removeEventListener(eventName, listener));
+    }
+}
+// Bind a prop key, upgrading reactive values into tracked effects when needed.
+export function bindProp(element, key, value) {
+    if (key === 'ref') {
+        if (typeof value === 'function') {
+            value(element);
+        }
+        return;
+    }
+    if (key.startsWith('on')) {
+        bindEvent(element, key, value);
+        return;
+    }
+    if (isReactiveValue(value)) {
+        const stop = effect(() => {
+            setDomProperty(element, key, resolveAccessor(value));
+        });
+        registerCleanup(stop);
+        return;
+    }
+    setDomProperty(element, key, value);
+}

package/dist/src/dom/reactive.d.ts

@@ -0,0 +1,6 @@
+import type { ReactiveValue, QoreTemplate } from './types.js';
+export declare function isReactiveValue<T>(value: ReactiveValue<T> | unknown): value is ReactiveValue<T>;
+export declare function resolveAccessor<T>(value: ReactiveValue<T>): T;
+export declare function resolveAccessor<T>(value: T): T;
+export declare function resolveTemplate<T>(template: QoreTemplate<T>, value: T): QoreTemplate<T>;
+export declare function resolveTemplate<T>(template: QoreTemplate<T> | undefined, value: T): QoreTemplate<T> | undefined;

package/dist/src/dom/reactive.js

@@ -0,0 +1,14 @@
+import { isSignal } from '../core/signal.js';
+// Treat signals and getters as reactive values the DOM layer should subscribe to.
+export function isReactiveValue(value) {
+    return isSignal(value) || typeof value === 'function';
+}
+export function resolveAccessor(value) {
+    if (isSignal(value) || typeof value === 'function') {
+        return value();
+    }
+    return value;
+}
+export function resolveTemplate(template, value) {
+    return typeof template === 'function' ? template(value) : template;
+}

package/dist/src/dom/response-view.d.ts

@@ -0,0 +1,4 @@
+import type { ResponseState, ResponseStatus } from '../core/response.js';
+import type { ResponseRenderState, ResponseViews } from './types.js';
+export declare function readResponseState<TChunk, TValue>(responseState: ResponseState<TChunk, TValue>): ResponseRenderState<TChunk, TValue>;
+export declare function pickResponseTemplate<TChunk, TValue>(status: ResponseStatus, views: ResponseViews<TChunk, TValue>): unknown;

package/dist/src/dom/response-view.js

@@ -0,0 +1,37 @@
+// Read a response into one plain object so templates can branch on status cleanly.
+export function readResponseState(responseState) {
+    return {
+        response: responseState,
+        status: responseState.status(),
+        value: responseState.value(),
+        error: responseState.error(),
+        chunks: responseState.chunks(),
+        startedAt: responseState.startedAt(),
+        finishedAt: responseState.finishedAt(),
+        pending: responseState.pending(),
+        streaming: responseState.streaming(),
+        completed: responseState.completed(),
+        failed: responseState.failed(),
+        aborted: responseState.aborted(),
+        chunkCount: responseState.chunkCount()
+    };
+}
+// Pick the best matching view override for the current response lifecycle state.
+export function pickResponseTemplate(status, views) {
+    switch (status) {
+        case 'idle':
+            return views.idle ?? views.pending ?? views.default;
+        case 'pending':
+            return views.pending ?? views.default;
+        case 'streaming':
+            return views.streaming ?? views.pending ?? views.default;
+        case 'completed':
+            return views.completed ?? views.default;
+        case 'error':
+            return views.error ?? views.default;
+        case 'aborted':
+            return views.aborted ?? views.default;
+        default:
+            return views.default;
+    }
+}

package/dist/src/dom/scope.d.ts

@@ -0,0 +1,10 @@
+import type { Cleanup } from '../core/signal-types.js';
+export declare const ROOT_CLEANUP: unique symbol;
+export interface Scope {
+    cleanups: Cleanup[];
+}
+export declare function assertDocument(): void;
+export declare function createScope(): Scope;
+export declare function withScope<T>(scope: Scope, fn: () => T): T;
+export declare function registerCleanup<T extends Cleanup | null | undefined>(cleanup: T): T;
+export declare function disposeScope(scope: Scope | null | undefined): void;

package/dist/src/dom/scope.js

@@ -0,0 +1,49 @@
+// Store mount cleanup directly on the root node so remounts can tear down old scopes.
+export const ROOT_CLEANUP = Symbol('qore.dom.cleanup');
+let activeScope = null;
+// Guard DOM helpers so they only run in browser-like environments.
+export function assertDocument() {
+    if (typeof document === 'undefined') {
+        throw new Error('Qore DOM APIs require a browser-like environment');
+    }
+}
+// A scope collects effect disposers created while rendering a subtree.
+export function createScope() {
+    return { cleanups: [] };
+}
+// Temporarily switch the active scope while a subtree is being materialized.
+export function withScope(scope, fn) {
+    const previousScope = activeScope;
+    activeScope = scope;
+    try {
+        return fn();
+    }
+    finally {
+        activeScope = previousScope;
+    }
+}
+// Register a cleanup callback on the currently active scope, if one exists.
+export function registerCleanup(cleanup) {
+    if (typeof cleanup === 'function' && activeScope) {
+        activeScope.cleanups.push(cleanup);
+    }
+    return cleanup;
+}
+// Dispose nested resources in reverse order so teardown mirrors setup.
+export function disposeScope(scope) {
+    if (!scope) {
+        return;
+    }
+    for (let index = scope.cleanups.length - 1; index >= 0; index -= 1) {
+        try {
+            const cleanup = scope.cleanups[index];
+            if (cleanup) {
+                cleanup();
+            }
+        }
+        catch {
+            // Ignore cleanup errors during teardown so the rest of the scope can unwind.
+        }
+    }
+    scope.cleanups.length = 0;
+}

package/dist/src/dom/types.d.ts

@@ -0,0 +1,34 @@
+import type { ResponseState, ResponseStatus } from '../core/response.js';
+import type { ReadonlySignal } from '../core/signal.js';
+export type QoreNode = Node;
+export type QoreElement = Element;
+export type QoreText = Text;
+export type QoreDocumentFragment = DocumentFragment;
+export type GlobalNode = QoreNode;
+export type GlobalElement = QoreElement;
+export type GlobalText = QoreText;
+export type GlobalDocumentFragment = QoreDocumentFragment;
+export type ReactiveValue<T> = T | ReadonlySignal<T> | (() => T);
+export type QoreChild = QoreNode | string | number | bigint | boolean | null | undefined | ReactiveValue<unknown> | QoreChild[];
+export type QoreTemplate<T> = QoreChild | ((value: T) => QoreChild);
+export interface ResponseRenderState<TChunk = unknown, TValue = unknown> {
+    response: ResponseState<TChunk, TValue>;
+    status: ResponseStatus;
+    value: TValue;
+    error: Error | null;
+    chunks: TChunk[];
+    startedAt: number | null;
+    finishedAt: number | null;
+    pending: boolean;
+    streaming: boolean;
+    completed: boolean;
+    failed: boolean;
+    aborted: boolean;
+    chunkCount: number;
+}
+export type ResponseViews<TChunk = unknown, TValue = unknown> = Partial<Record<ResponseStatus | 'default', QoreTemplate<ResponseRenderState<TChunk, TValue>>>>;
+export type QoreComponent<Props extends Record<string, unknown> = Record<string, unknown>> = (props: Props & {
+    children: QoreChild[];
+}) => QoreChild;
+export type MountTarget = string | QoreElement;
+export type MountView = QoreChild | (() => QoreChild);

package/dist/src/dom/types.js

@@ -0,0 +1 @@
+export {};