@neovici/cosmoz-utils 6.25.1 → 6.27.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/directives/overflow.d.ts

@@ -0,0 +1,27 @@
+import { type ElementPart } from 'lit-html';
+import { AsyncDirective } from 'lit-html/async-directive.js';
+/**
+ * The directive expects this css. Adopt it on your component, set the
+ * class `cz-overflow-band` on the band slot, and give it a `max-height`
+ * to match one row.
+ */
+export declare const overflowStyle: CSSStyleSheet;
+/**
+ * The directive marks the elements that overflow with "[overflowing]"
+ * and reports the full list via `onOverflow`. The effect relies mainly
+ * on css flex wrapping, so make sure to use the accompanying stylesheet
+ * (or match in your own css).
+ */
+export interface OverflowConfig {
+    onOverflow: (overflowing: Set<HTMLElement>) => void;
+}
+declare class OverflowDirective extends AsyncDirective {
+    #private;
+    _slot?: HTMLSlotElement;
+    _onOverflow?: (overflowing: Set<HTMLElement>) => void;
+    render(config: OverflowConfig): symbol;
+    update(part: ElementPart, [config]: [OverflowConfig]): symbol;
+    disconnected(): void;
+}
+export declare const overflow: (config: OverflowConfig) => import("lit-html/directive.js").DirectiveResult<typeof OverflowDirective>;
+export {};

package/dist/directives/overflow.js

@@ -0,0 +1,121 @@
+import { css } from '@pionjs/pion';
+import { noChange } from 'lit-html';
+import { AsyncDirective, directive } from 'lit-html/async-directive.js';
+import { sheet } from '../sheet.js';
+/**
+ * The directive expects this css. Adopt it on your component, set the
+ * class `cz-overflow-band` on the band slot, and give it a `max-height`
+ * to match one row.
+ */
+export const overflowStyle = sheet(css `
+	slot.cz-overflow-band {
+		display: flex;
+		flex-wrap: wrap;
+		align-items: flex-start;
+		overflow: clip;
+	}
+
+	::slotted([overflowing]) {
+		visibility: hidden;
+	}
+`);
+const members = (slot) => slot.assignedElements({ flatten: true });
+const stable = (a, b) => a != null &&
+    b != null &&
+    a.size === b.size &&
+    [...b].every((el) => a.has(el));
+class OverflowDirective extends AsyncDirective {
+    _slot;
+    _onOverflow;
+    #clipped = new Map();
+    #last;
+    #observer;
+    #classify = (entries) => {
+        entries.forEach((entry) => {
+            const member = entry.target;
+            this.#clipped.set(member, entry.boundingClientRect.height > 0 &&
+                entry.intersectionRect.height === 0);
+        });
+        this.#flush();
+    };
+    #observe = (member) => {
+        this.#observer?.unobserve(member);
+        this.#observer?.observe(member);
+    };
+    #flush = () => {
+        if (!this._slot) {
+            return;
+        }
+        const current = members(this._slot);
+        current.forEach((member) => {
+            const on = this.#clipped.get(member) === true;
+            if (on === member.hasAttribute('overflowing')) {
+                return;
+            }
+            if (on) {
+                member.setAttribute('overflowing', '');
+            }
+            else {
+                member.removeAttribute('overflowing');
+            }
+        });
+        // a member that left the slot: forget it, stop watching it,
+        // remove the mark
+        this.#clipped.forEach((_, member) => {
+            if (current.includes(member)) {
+                return;
+            }
+            this.#clipped.delete(member);
+            this.#observer?.unobserve(member);
+            if (member.hasAttribute('overflowing')) {
+                member.removeAttribute('overflowing');
+            }
+        });
+        const next = new Set(current.filter((member) => this.#clipped.get(member) === true));
+        if (stable(this.#last, next)) {
+            return;
+        }
+        this.#last = next;
+        this._onOverflow?.(next);
+    };
+    #onSlotChange = () => this.#arm();
+    #arm = () => {
+        if (!this.#observer || !this._slot) {
+            return;
+        }
+        for (const member of members(this._slot)) {
+            this.#observe(member);
+        }
+        this.#flush();
+    };
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    render(config) {
+        return noChange;
+    }
+    update(part, [config]) {
+        this._onOverflow = config.onOverflow;
+        const slot = part.element;
+        if (this._slot !== slot) {
+            this._slot?.removeEventListener('slotchange', this.#onSlotChange);
+            this.#observer?.disconnect();
+            this.#observer = undefined;
+            this._slot = slot;
+            slot.addEventListener('slotchange', this.#onSlotChange);
+        }
+        this.#observer ??= new IntersectionObserver(this.#classify, {
+            root: this._slot,
+            threshold: [0, 1],
+        });
+        this.#arm();
+        return noChange;
+    }
+    disconnected() {
+        this._slot?.removeEventListener('slotchange', this.#onSlotChange);
+        this._slot = undefined;
+        this.#observer?.disconnect();
+        this.#observer = undefined;
+        this.#clipped.clear();
+        this.#last = undefined;
+    }
+}
+export const overflow = directive(OverflowDirective);

package/package.json

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