@neovici/cosmoz-utils 6.25.0 → 6.26.0

package/dist/directives/breakpoints.d.ts

@@ -0,0 +1,47 @@
+export interface Breakpoint {
+    /** Reflected as data-breakpoint when this breakpoint is the narrowest match. */
+    name?: string;
+    /** Matches when container width <= maxWidth. Omit for the base breakpoint (maxWidth ∞, always matches). */
+    maxWidth?: number;
+    /** Element property writes. */
+    props?: Record<string, unknown>;
+    /** Attribute writes; boolean true → empty string, false → removed. */
+    attrs?: Record<string, string | boolean>;
+}
+interface ManagedKey {
+    name: string;
+    /** How to write the key on the host. */
+    channel: 'prop' | 'attr';
+}
+interface Snapshot {
+    breakpoints: Breakpoint[];
+    keys: ManagedKey[];
+}
+/**
+ * Normalize breakpoints into a frozen snapshot.
+ * - exactly one breakpoint without maxWidth (the base, required)
+ * - keys declared in bounded breakpoints must also be declared in the base
+ *   breakpoint (every managed key gets a resting value, so exit is well-defined)
+ * - keys are the union across breakpoints, prop channel wins on conflicts
+ */
+export declare const normalize: (breakpoints: Breakpoint[]) => Snapshot;
+/**
+ * Container-width breakpoint directive for element parts: applies the
+ * narrowest matching breakpoint's `props`/`attrs` onto the host and
+ * reflects its `name` as `data-breakpoint`, driven by a ResizeObserver on
+ * the element.
+ *
+ * Exactly one base breakpoint (no `maxWidth`) is required and must declare
+ * every key used by bounded breakpoints — base values are the resting
+ * (exit) state. Snapshots are rebuilt only when `deps` change, so
+ * unrelated re-renders don't churn writes.
+ *
+ * ```js
+ * html`<my-list ${breakpoints(() => [
+ * 	{ name: 'mini', maxWidth: 480, props: { renderItem: renderMini } },
+ * 	{ props: { renderItem: null } },
+ * ], [renderMini])}></my-list>`
+ * ```
+ */
+export declare const breakpoints: (factory?: () => Breakpoint[], deps?: unknown[]) => unknown;
+export {};

package/dist/directives/breakpoints.js

@@ -0,0 +1,213 @@
+import { nothing } from 'lit-html';
+import { AsyncDirective, directive, PartType, } from 'lit-html/async-directive.js';
+const depsEqual = (a, b) => (a ?? []).length === (b ?? []).length &&
+    (a ?? []).every((v, i) => (b ?? [])[i] === v);
+const matches = (breakpoint, width) => breakpoint.maxWidth == null || width <= breakpoint.maxWidth;
+/**
+ * Normalize breakpoints into a frozen snapshot.
+ * - exactly one breakpoint without maxWidth (the base, required)
+ * - keys declared in bounded breakpoints must also be declared in the base
+ *   breakpoint (every managed key gets a resting value, so exit is well-defined)
+ * - keys are the union across breakpoints, prop channel wins on conflicts
+ */
+export const normalize = (breakpoints) => {
+    const base = breakpoints.filter((b) => b.maxWidth == null);
+    if (base.length !== 1) {
+        throw new Error(`breakpoints: exactly one breakpoint without maxWidth is required (the base), got ${base.length}`);
+    }
+    const sorted = [...breakpoints].sort((a, b) => (a.maxWidth ?? Infinity) - (b.maxWidth ?? Infinity));
+    const collect = (channel) => new Set(sorted.flatMap((b) => Object.keys(b[channel] ?? {})));
+    const propKeys = collect('props');
+    const attrKeys = collect('attrs');
+    const keys = [
+        ...[...propKeys].map((name) => ({ name, channel: 'prop' })),
+        ...[...attrKeys]
+            .filter((name) => !propKeys.has(name))
+            .map((name) => ({ name, channel: 'attr' })),
+    ];
+    const baseKeys = new Set([
+        ...Object.keys(base[0].props ?? {}),
+        ...Object.keys(base[0].attrs ?? {}),
+    ]);
+    const orphans = [...propKeys, ...attrKeys].filter((k) => !baseKeys.has(k));
+    if (orphans.length > 0) {
+        throw new Error(`breakpoints: key(s) [${orphans.join(', ')}] must also be declared in the base breakpoint (no maxWidth)`);
+    }
+    return { breakpoints: sorted, keys };
+};
+/**
+ * Pure: snapshot × width → resolved values. No host reads.
+ * Returns undefined when the width is not resolvable (no layout box, <= 0):
+ * the caller must hold last state instead of resolving — 0 would false-match
+ * the narrowest breakpoint.
+ */
+const compute = (snapshot, width) => {
+    if (width <= 0) {
+        return undefined;
+    }
+    const values = new Map();
+    for (const { name } of snapshot.keys) {
+        const breakpoint = snapshot.breakpoints.find((b) => matches(b, width) &&
+            (b.props?.[name] !== undefined || b.attrs?.[name] !== undefined));
+        if (!breakpoint) {
+            continue;
+        }
+        // Strict presence: null is a legitimate value (the exit path), so ??
+        // is wrong here — it would reduce a base `null` to "no opinion" and
+        // skip the write, stranding a previous breakpoint's override.
+        const value = breakpoint.props?.[name] !== undefined
+            ? breakpoint.props?.[name]
+            : breakpoint.attrs?.[name];
+        values.set(name, value);
+    }
+    const named = snapshot.breakpoints.find((b) => b.name && matches(b, width));
+    return { breakpointName: named?.name, values };
+};
+const applyValue = (el, key, value) => {
+    if (key.channel === 'prop') {
+        el[key.name] = value;
+        return;
+    }
+    if (typeof value === 'boolean') {
+        if (value) {
+            el.setAttribute(key.name, '');
+        }
+        else {
+            el.removeAttribute(key.name);
+        }
+        return;
+    }
+    el.setAttribute(key.name, String(value));
+};
+const sameResolved = (a, b) => {
+    if (!a || !b || a.breakpointName !== b.breakpointName) {
+        return false;
+    }
+    if (a.values.size !== b.values.size) {
+        return false;
+    }
+    for (const [k, v] of a.values) {
+        if (b.values.get(k) !== v) {
+            return false;
+        }
+    }
+    return true;
+};
+class BreakpointsDirective extends AsyncDirective {
+    _el;
+    _ro;
+    _snapshot;
+    _deps;
+    _resolved;
+    constructor(partInfo) {
+        super(partInfo);
+        if (partInfo.type !== PartType.ELEMENT) {
+            throw new Error('breakpoints directive must be used on an element');
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    render(_factory, _deps) {
+        return nothing;
+    }
+    update(part, [factory, deps]) {
+        if (this._el !== undefined && this._el !== part.element) {
+            this._teardown();
+            this._el = undefined;
+            this._resolved = undefined;
+        }
+        this._el ??= part.element;
+        if (this._snapshot === undefined || !depsEqual(deps, this._deps)) {
+            this._deps = deps;
+            this._snapshot = normalize(factory());
+            // Snapshot change invalidates the memo; re-resolve at current width.
+            this._resolved = undefined;
+            this._evaluate();
+        }
+        this._observe();
+        if (!this._ro) {
+            // update() can run before the element is connected (initial fixture
+            // render) or before layout gives it a box; retry on the next
+            // microtask so observation + first evaluation happen post-connect.
+            queueMicrotask(() => {
+                if (!this.isConnected) {
+                    return;
+                }
+                this._observe();
+                this._evaluate();
+            });
+        }
+        return nothing;
+    }
+    _observe() {
+        if (!this._el?.isConnected || this._ro) {
+            return;
+        }
+        this._ro = new ResizeObserver((entries) => {
+            this._evaluate(entries[0]?.contentRect.width ?? 0);
+        });
+        this._ro.observe(this._el);
+    }
+    _evaluate(measured) {
+        if (!this._el || !this._snapshot) {
+            return;
+        }
+        const width = measured === undefined
+            ? // No RO measurement yet (snapshot change outside an RO tick):
+                // measure synchronously to avoid a pre-breakpoint flash.
+                this._el.getBoundingClientRect().width
+            : measured;
+        const resolved = compute(this._snapshot, width);
+        if (resolved) {
+            this._apply(resolved);
+        }
+    }
+    _apply(resolved) {
+        const el = this._el;
+        if (sameResolved(this._resolved, resolved)) {
+            return; // RO churn / idempotent re-render — write nothing
+        }
+        for (const key of this._snapshot.keys) {
+            const value = resolved.values.get(key.name);
+            if (value === undefined) {
+                continue; // no breakpoint has an opinion — never write
+            }
+            applyValue(el, key, value);
+        }
+        if (resolved.breakpointName) {
+            el.setAttribute('data-breakpoint', resolved.breakpointName);
+        }
+        else {
+            el.removeAttribute('data-breakpoint');
+        }
+        this._resolved = resolved;
+    }
+    _teardown() {
+        this._ro?.disconnect();
+        this._ro = undefined;
+    }
+    disconnected() {
+        this._teardown();
+    }
+    reconnected() {
+        this._observe();
+    }
+}
+/**
+ * Container-width breakpoint directive for element parts: applies the
+ * narrowest matching breakpoint's `props`/`attrs` onto the host and
+ * reflects its `name` as `data-breakpoint`, driven by a ResizeObserver on
+ * the element.
+ *
+ * Exactly one base breakpoint (no `maxWidth`) is required and must declare
+ * every key used by bounded breakpoints — base values are the resting
+ * (exit) state. Snapshots are rebuilt only when `deps` change, so
+ * unrelated re-renders don't churn writes.
+ *
+ * ```js
+ * html`<my-list ${breakpoints(() => [
+ * 	{ name: 'mini', maxWidth: 480, props: { renderItem: renderMini } },
+ * 	{ props: { renderItem: null } },
+ * ], [renderMini])}></my-list>`
+ * ```
+ */
+export const breakpoints = directive(BreakpointsDirective);

package/dist/function.d.ts

@@ -6,5 +6,11 @@ export declare function constant(): () => undefined;
 export declare function constant<T>(v: T): () => T;
 export declare const constTrue: () => true, constUndefined: () => undefined, noop: () => undefined, identity: <T>(obj: T) => T, or: <A, F extends OrFn<A>>(...fns: F[]) => (...args: A[]) => boolean;
 export declare const once: <A extends Arr, R, F extends OnceFn<A, R> = OnceFn<A, R>>(fn: F, check?: OnceCheckFn<A>) => (...args: A) => any;
-export declare const invoke: <T, A extends unknown[]>(fn: T | ((...args: A) => T), ...args: A) => T;
+type Invoked<F> = F extends (...args: any[]) => infer R ? R : F;
+/**
+ * The args of a known function are checked against its tuple; for a
+ * value-or-function union the runtime dispatch decides the member, so
+ * the args cannot be typed.
+ */
+export declare const invoke: <F>(fn: F, ...args: F extends (...args: infer P) => unknown ? P : unknown[]) => Invoked<F>;
 export {};

package/dist/function.js

@@ -6,4 +6,11 @@ export const once = (fn, check = constTrue) => {
     let result;
     return (...args) => (result ??= check(args) ? fn(...args) : undefined);
 };
-export const invoke = (fn, ...args) => (typeof fn === 'function' ? fn(...args) : fn);
+/**
+ * The args of a known function are checked against its tuple; for a
+ * value-or-function union the runtime dispatch decides the member, so
+ * the args cannot be typed.
+ */
+export const invoke = (fn, ...args) => typeof fn === 'function'
+    ? fn(...args)
+    : fn;

package/dist/promise.d.ts

@@ -29,5 +29,5 @@ export declare const debounce$: <T extends unknown[], P>(fn: (...args: T) => P |
 export declare const share$: <T extends unknown[], P>(fn: (...args: T) => P | PromiseLike<P>) => (...args: T) => Promise<P>;
 export declare const log$: <T extends unknown[], P>(fn: (...args: T) => PromiseLike<P>) => (...args: T) => PromiseLike<P>;
 export declare const retry$: <T extends unknown[], P>(fn: (...args: T) => P | PromiseLike<P>, n: number) => (...args: T) => Promise<P>;
-export declare const invoke$: <T, A extends unknown[]>(fn: T | ((...args: A) => T | PromiseLike<T>), ...args: A) => Promise<Awaited<T> | Awaited<T>>;
+export declare const invoke$: <T, A extends unknown[]>(fn: T | ((...args: A) => T | PromiseLike<T>), ...args: A) => Promise<Awaited<T> | Awaited<T> | Awaited<T extends (...args: any[]) => infer R ? R : T>>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@neovici/cosmoz-utils",
-	"version": "6.25.0",
+	"version": "6.26.0",
 	"description": "Date, money and template management functions commonly needed in Cosmoz views.",
 	"keywords": [
 		"polymer",