@haiyue/ui 0.1.1 → 0.2.1

package/dist/portable/page.js

@@ -0,0 +1,361 @@
+import { HYUIError, hyValidateCapabilities, hyValidateNode, hyValidateProps, snapshotValidatedProps } from '../core/validation.js';
+import { equalData, snapshot } from '../core/data.js';
+import { diff, flatten } from './tree.js';
+const interactive = new Set(['Button', 'Toggle', 'Select', 'Tabs', 'TextInput', 'TextArea', 'Slider', 'PlatformView']);
+/** A synchronous, bounded page reconciler. It owns bindings/rendering, never the application store. */
+export class HYPage {
+    options;
+    #renderer;
+    #capabilities;
+    #status = 'new';
+    #revision = 0;
+    #epoch = 0;
+    #depth = 0;
+    #committing = false;
+    #desired = new Map();
+    #rendered = new Map();
+    // Undefined means topology may have changed; otherwise only these props
+    // need comparison. Keep tree order deterministic across grouped updates.
+    #updates;
+    #order = new Map();
+    #subscriptions = new Set();
+    #focused;
+    #boundStores = new Set();
+    #openers = new Map();
+    #cancelTransaction = 0;
+    constructor(renderer, options = {}) {
+        this.options = options;
+        hyValidateCapabilities(renderer.capabilities);
+        this.#renderer = renderer;
+        this.#capabilities = snapshot(renderer.capabilities);
+    }
+    get status() { return this.#status; }
+    get revision() { return this.#revision; }
+    get capabilities() { return this.#capabilities; }
+    #assertMutable() {
+        if (this.#status === 'disposed' || this.#committing)
+            throw new HYUIError('lifecycle', 'Page disposed or inside renderer commit');
+    }
+    mount(root) {
+        if (this.#status !== 'new')
+            throw new HYUIError('lifecycle', 'Page may only mount once');
+        this.#desired = flatten(hyValidateNode(root, this.#capabilities));
+        this.#mountRenderer();
+        this.#flush();
+    }
+    #mountRenderer() {
+        const epoch = ++this.#epoch;
+        this.#committing = true;
+        try {
+            this.#renderer.mount(event => { if (epoch === this.#epoch)
+                this.#event(event); });
+            this.#status = 'mounted';
+        }
+        catch (cause) {
+            this.#fault(cause, 'mount');
+        }
+        finally {
+            this.#committing = false;
+        }
+    }
+    render(root) {
+        this.#assertMutable();
+        if (this.#status === 'new')
+            throw new HYUIError('lifecycle', 'Mount the page before render');
+        this.#desired = flatten(hyValidateNode(root, this.#capabilities));
+        this.#updates = undefined;
+        this.#flush();
+    }
+    setProps(key, kind, props) {
+        this.#assertMutable();
+        const entry = this.#desired.get(key);
+        if (!entry || entry.node.kind !== kind)
+            throw new HYUIError('invalid-props', 'Binding target missing or kind changed', { key });
+        const context = { key, ...(entry.node.source ? { source: entry.node.source } : {}) };
+        const accepted = snapshotValidatedProps(kind, props, context, this.#capabilities);
+        if (equalData(entry.node.props, props))
+            return;
+        const next = new Map(this.#desired);
+        next.set(key, { ...entry, node: Object.freeze({ ...entry.node, props: accepted }) });
+        this.#desired = next;
+        this.#updates?.add(key);
+        this.#flush();
+    }
+    transaction(run) {
+        this.#assertMutable();
+        const before = this.#desired, updates = this.#updates && new Set(this.#updates);
+        this.#depth++;
+        try {
+            const result = run();
+            if (result && typeof result.then === 'function')
+                throw new HYUIError('lifecycle', 'Page transactions must be synchronous');
+        }
+        catch (cause) {
+            this.#desired = before;
+            this.#updates = updates;
+            throw cause;
+        }
+        finally {
+            this.#depth--;
+        }
+        this.#flush();
+    }
+    /** One store subscription: a store transaction produces one final page batch across all bindings. */
+    bind(store, bindings) {
+        this.#assertMutable();
+        if (this.#boundStores.has(store))
+            throw new HYUIError('lifecycle', 'Group all bindings for one store in a single bind call');
+        const definitions = [...bindings];
+        if (new Set(definitions.map(b => b.key)).size !== definitions.length)
+            throw new HYUIError('duplicate-key', 'Duplicate binding target');
+        const select = (state) => definitions.map(b => b.select(state));
+        const equal = (a, b) => a.every((p, i) => (definitions[i].equal ?? equalData)(p, b[i]));
+        let applied = [];
+        const apply = (props) => {
+            if (this.#status === 'disposed')
+                return;
+            this.transaction(() => definitions.forEach((binding, i) => {
+                const node = this.#desired.get(binding.key)?.node;
+                // A grouped subscription does not make every binding dirty. Reuse a
+                // previously validated result only while its target is still unchanged.
+                // External render/setProps and failed transactions invalidate this path.
+                if (node === applied[i] && node && equalData(node.props, props[i]))
+                    return;
+                this.setProps(binding.key, binding.kind, props[i]);
+            }));
+            applied = definitions.map(binding => this.#desired.get(binding.key)?.node);
+        };
+        apply(select(store.getSnapshot()));
+        let live = true;
+        const unsubscribe = store.subscribe(select, values => { if (live)
+            apply(values); }, equal);
+        const dispose = () => { if (!live)
+            return; live = false; this.#subscriptions.delete(dispose); this.#boundStores.delete(store); unsubscribe(); };
+        this.#boundStores.add(store);
+        this.#subscriptions.add(dispose);
+        // Also captures synchronous changes caused by mount/update hooks before subscription began.
+        try {
+            apply(select(store.getSnapshot()));
+        }
+        catch (cause) {
+            dispose();
+            throw cause;
+        }
+        return dispose;
+    }
+    #fault(cause, operation, key) {
+        this.#status = 'faulted';
+        const context = cause instanceof HYUIError ? cause.context : {};
+        throw new HYUIError('renderer', 'Renderer failed; rebuild required', {
+            key: key ?? this.#desired.keys().next().value ?? '<root>', operation, ...context,
+            revision: operation === 'commit' || operation === 'mount' ? this.#revision + 1 : this.#revision,
+        }, cause);
+    }
+    #flush() {
+        if (this.#depth || this.#status !== 'mounted' || this.#committing)
+            return;
+        const next = this.#desired, previous = this.#rendered;
+        if (next === previous)
+            return;
+        const topology = this.#updates === undefined;
+        const mutations = topology ? diff(previous, next)
+            : Object.freeze([...this.#updates].sort((a, b) => this.#order.get(a) - this.#order.get(b)).flatMap(key => {
+                const node = next.get(key).node;
+                return equalData(previous.get(key).node.props, node.props) ? [] : [Object.freeze({ type: 'update', node })];
+            }));
+        const focusChanged = topology || mutations.some(m => {
+            if (m.type !== 'update')
+                return true;
+            const a = previous.get(m.node.key).node.props, b = m.node.props;
+            return a.visible !== b.visible || ('disabled' in a && a.disabled) !== ('disabled' in b && b.disabled)
+                || ('busy' in a && a.busy) !== ('busy' in b && b.busy)
+                || (m.node.kind === 'Dialog' && ('open' in a && a.open) !== m.node.props.open)
+                || (m.node.kind === 'Tabs' && ('value' in a && a.value) !== m.node.props.value);
+        });
+        if (!mutations.length) {
+            this.#rendered = next;
+            this.#updates = new Set();
+            return;
+        }
+        this.#committing = true;
+        try {
+            this.#renderer.commit(this.#revision + 1, mutations);
+        }
+        catch (cause) {
+            this.#fault(cause, 'commit');
+        }
+        finally {
+            this.#committing = false;
+        }
+        this.#rendered = next;
+        this.#revision++;
+        this.#updates = new Set();
+        if (topology)
+            this.#order = new Map([...next.keys()].map((key, index) => [key, index]));
+        if (focusChanged)
+            this.#restoreFocus(previous);
+    }
+    #available(key, tree = this.#rendered) {
+        if (!key)
+            return false;
+        let entry = tree.get(key);
+        if (!entry)
+            return false;
+        while (entry) {
+            const p = entry.node.props;
+            if (p.visible === false || ('disabled' in p && p.disabled) || ('busy' in p && p.busy) || (entry.node.kind === 'Dialog' && !entry.node.props.open))
+                return false;
+            const parent = entry.parent === null ? undefined : tree.get(entry.parent);
+            if (parent?.node.kind === 'Tabs' && entry.slot !== parent.node.props.value)
+                return false;
+            entry = parent;
+        }
+        return true;
+    }
+    #dialogs(tree) {
+        return [...tree].filter(([key, entry]) => entry.node.kind === 'Dialog' && entry.node.props.open && this.#available(key, tree)).map(([key]) => key);
+    }
+    #inside(key, parent) { return key === parent || key.startsWith(`${parent}/`); }
+    #dialogTarget(key) {
+        return [...this.#rendered].find(([id, entry]) => this.#inside(id, key) && interactive.has(entry.node.kind) && this.#available(id))?.[0] ?? key;
+    }
+    #restoreFocus(previous) {
+        const oldDialogs = this.#dialogs(previous), dialogs = this.#dialogs(this.#rendered);
+        const newDialogs = dialogs.filter(key => !oldDialogs.includes(key));
+        for (const key of newDialogs)
+            this.#openers.set(key, this.#focused);
+        const top = dialogs.at(-1);
+        const closed = oldDialogs.filter(key => !dialogs.includes(key));
+        if (newDialogs.length || (top && (!this.#focused || !this.#inside(this.#focused, top))))
+            this.focus(this.#dialogTarget(top));
+        else if (this.#focused && !this.#available(this.#focused)) {
+            const opener = closed.slice().reverse().map(key => this.#openers.get(key)).find(key => this.#available(key));
+            const target = top ? this.#dialogTarget(top) : opener ?? (this.#available(this.options.defaultFocus) ? this.options.defaultFocus : this.#rendered.keys().next().value);
+            if (target)
+                this.focus(target);
+            else
+                this.#focused = undefined;
+        }
+        for (const key of closed)
+            this.#openers.delete(key);
+    }
+    focus(key) {
+        if (this.#status !== 'mounted' || this.#committing || !this.#available(key))
+            return false;
+        const top = this.#dialogs(this.#rendered).at(-1);
+        if (top && !this.#inside(key, top))
+            return false;
+        this.#committing = true;
+        try {
+            this.#renderer.focus(key);
+            this.#focused = key;
+        }
+        catch (cause) {
+            this.#fault(cause, 'focus', key);
+        }
+        finally {
+            this.#committing = false;
+        }
+        return true;
+    }
+    #event(event) {
+        if (this.#committing || this.#status !== 'mounted' || !this.#available(event.key))
+            return;
+        const top = this.#dialogs(this.#rendered).at(-1);
+        if (top && !this.#inside(event.key, top))
+            return;
+        if (event.type === 'focus')
+            this.#focused = event.key;
+        this.options.onEvent?.(Object.freeze({ ...event }));
+    }
+    /** The shell chooses this single system-back owner. A modal consumes even a non-dismissible back. */
+    back(reason = 'keyboard') {
+        if (this.#status !== 'mounted' || this.#committing)
+            return false;
+        const key = this.#dialogs(this.#rendered).at(-1);
+        if (!key)
+            return false;
+        const node = this.#rendered.get(key).node;
+        if (node.kind === 'Dialog' && node.props.dismissible !== false)
+            this.#event({ key, type: 'cancel', reason, transaction: ++this.#cancelTransaction });
+        return true;
+    }
+    suspend() {
+        if (this.#status !== 'mounted' || this.#committing)
+            return;
+        this.#status = 'suspended';
+        try {
+            this.#renderer.suspend();
+        }
+        catch (cause) {
+            this.#fault(cause, 'suspend');
+        }
+    }
+    resume() {
+        if (this.#status !== 'suspended')
+            return;
+        try {
+            this.#renderer.resume();
+        }
+        catch (cause) {
+            this.#fault(cause, 'resume');
+        }
+        this.#status = 'mounted';
+        this.#flush();
+    }
+    /** Replaces the failed backend, preserving latest requested data and existing store bindings. */
+    rebuild(renderer) {
+        if (this.#status !== 'faulted')
+            throw new HYUIError('lifecycle', 'Only a faulted page may rebuild');
+        if (renderer === this.#renderer)
+            throw new HYUIError('lifecycle', 'Rebuild needs a fresh renderer');
+        hyValidateCapabilities(renderer.capabilities);
+        for (const [key, entry] of this.#desired) {
+            hyValidateProps(entry.node.kind, entry.node.props, { key }, renderer.capabilities);
+            for (const feature of entry.node.requires ?? [])
+                if (!renderer.capabilities.features.includes(feature))
+                    throw new HYUIError('capability', `Missing capability ${feature}`, { key });
+        }
+        ++this.#epoch;
+        this.#renderer.dispose();
+        this.#renderer = renderer;
+        this.#capabilities = snapshot(renderer.capabilities);
+        this.#rendered = new Map();
+        this.#updates = undefined;
+        this.#order.clear();
+        this.#focused = undefined;
+        this.#openers.clear();
+        this.#mountRenderer();
+        this.#flush();
+    }
+    dispose() {
+        if (this.#status === 'disposed')
+            return;
+        this.#status = 'disposed';
+        ++this.#epoch;
+        const errors = [];
+        for (const unsubscribe of this.#subscriptions)
+            try {
+                unsubscribe();
+            }
+            catch (cause) {
+                errors.push(cause);
+            }
+        this.#subscriptions.clear();
+        try {
+            this.#renderer.dispose();
+        }
+        catch (cause) {
+            errors.push(cause);
+        }
+        this.#updates = undefined;
+        this.#order.clear();
+        this.#desired = new Map();
+        this.#rendered = new Map();
+        this.#openers.clear();
+        this.#focused = undefined;
+        if (errors.length)
+            throw new AggregateError(errors, 'Page cleanup failed');
+    }
+}
+//# sourceMappingURL=page.js.map

package/dist/portable/theme.d.ts

@@ -0,0 +1,19 @@
+import type { HYTheme } from '../core/types.js';
+export declare const HY_THEME_TOKENS: Readonly<{
+    readonly text: "--hy-text-color";
+    readonly muted: "--hy-secondary-text-color";
+    readonly surface: "--hy-surface-color";
+    readonly input: "--hy-input-bg-color";
+    readonly accent: "--hy-accent-color";
+    readonly danger: "--hy-invalid-border-color";
+    readonly border: "--hy-border-color";
+    readonly focus: "--hy-focus-ring-color";
+    readonly fontSize: "--hy-font-size";
+    readonly lineHeight: "--hy-line-height";
+    readonly gap: "--hy-gap";
+    readonly radius: "--hy-radius";
+}>;
+export type HYThemeVariables = Readonly<Record<(typeof HY_THEME_TOKENS)[keyof typeof HY_THEME_TOKENS], string>>;
+export declare function hyNativeTheme(theme: HYTheme, fontScale?: number): HYTheme;
+/** Returns data for an adapter to apply; importing it never creates a stylesheet. */
+export declare function hyThemeVariables(theme: HYTheme, fontScale?: number): HYThemeVariables;

package/dist/portable/theme.js

@@ -0,0 +1,40 @@
+import { HYUIError } from '../core/validation.js';
+import { snapshot } from '../core/data.js';
+export const HY_THEME_TOKENS = Object.freeze({
+    text: '--hy-text-color', muted: '--hy-secondary-text-color', surface: '--hy-surface-color', input: '--hy-input-bg-color',
+    accent: '--hy-accent-color', danger: '--hy-invalid-border-color', border: '--hy-border-color', focus: '--hy-focus-ring-color',
+    fontSize: '--hy-font-size', lineHeight: '--hy-line-height', gap: '--hy-gap', radius: '--hy-radius',
+});
+export function hyNativeTheme(theme, fontScale = 1) {
+    const bad = (property) => { throw new HYUIError('invalid-props', 'Invalid portable theme value', { property }); };
+    if (!theme || typeof theme !== 'object')
+        bad('theme');
+    for (const key of Object.keys(theme))
+        if (!['color', 'fontSize', 'lineHeight', 'gap', 'radius'].includes(key))
+            bad(key);
+    if (!Number.isFinite(fontScale) || fontScale <= 0)
+        bad('fontScale');
+    for (const key of ['fontSize', 'lineHeight', 'gap', 'radius']) {
+        if (!Number.isFinite(theme[key]) || theme[key] < 0 || ((key === 'fontSize' || key === 'lineHeight') && theme[key] === 0))
+            bad(key);
+    }
+    for (const key of ['text', 'muted', 'surface', 'input', 'accent', 'danger', 'border', 'focus']) {
+        if (typeof theme.color?.[key] !== 'string' || !/^#[\da-f]{6}([\da-f]{2})?$/i.test(theme.color[key]))
+            bad(`color.${key}`);
+    }
+    for (const key of Object.keys(theme.color))
+        if (!['text', 'muted', 'surface', 'input', 'accent', 'danger', 'border', 'focus'].includes(key))
+            bad(`color.${key}`);
+    if (!Number.isFinite(theme.fontSize * fontScale) || !Number.isFinite(theme.lineHeight * fontScale))
+        bad('fontScale');
+    return snapshot({ color: { ...theme.color }, fontSize: theme.fontSize * fontScale, lineHeight: theme.lineHeight * fontScale, gap: theme.gap, radius: theme.radius });
+}
+/** Returns data for an adapter to apply; importing it never creates a stylesheet. */
+export function hyThemeVariables(theme, fontScale = 1) {
+    const data = hyNativeTheme(theme, fontScale);
+    return Object.freeze(Object.fromEntries([
+        ...Object.entries(data.color).map(([key, value]) => [HY_THEME_TOKENS[key], value]),
+        ...['fontSize', 'lineHeight', 'gap', 'radius'].map(key => [HY_THEME_TOKENS[key], `${data[key]}px`]),
+    ]));
+}
+//# sourceMappingURL=theme.js.map

package/dist/portable/tree.d.ts

@@ -0,0 +1,10 @@
+import type { HYMutation, HYNode } from '../core/types.js';
+export interface Entry {
+    readonly node: HYNode;
+    readonly parent: string | null;
+    readonly slot?: string;
+}
+export type Tree = ReadonlyMap<string, Entry>;
+export declare function flatten(root: HYNode): Tree;
+/** Returns a deterministic batch. Removing an ancestor releases descendants exactly once. */
+export declare function diff(previous: Tree, next: Tree): readonly HYMutation[];

package/dist/portable/tree.js

@@ -0,0 +1,96 @@
+import { hyKey } from '../core/validation.js';
+import { equalData } from '../core/data.js';
+export function flatten(root) {
+    const entries = new Map();
+    const walk = (node, path, parent, slot) => {
+        const nextPath = [...path, node.key], key = hyKey(...nextPath);
+        const { children, slots, ...shallow } = node;
+        entries.set(key, { node: Object.freeze({ ...shallow, key }), parent, ...(slot === undefined ? {} : { slot }) });
+        for (const child of children ?? [])
+            walk(child, nextPath, key);
+        for (const [name, list] of Object.entries(slots ?? {}))
+            for (const child of list)
+                walk(child, nextPath, key, name);
+    };
+    walk(root, [], null);
+    return entries;
+}
+function group(entry) { return JSON.stringify([entry.parent, entry.slot ?? null]); }
+function groups(tree) {
+    const result = new Map();
+    for (const [key, entry] of tree) {
+        const id = group(entry);
+        if (!result.has(id))
+            result.set(id, []);
+        result.get(id).push(key);
+    }
+    return result;
+}
+/** Returns a deterministic batch. Removing an ancestor releases descendants exactly once. */
+export function diff(previous, next) {
+    // Bound props preserve topology. Avoid building/serializing sibling groups
+    // for these updates; keep the general reconciler for insert/move/remove.
+    if (previous.size === next.size) {
+        const entries = previous.entries(), updates = [];
+        let sameStructure = true;
+        for (const [key, entry] of next) {
+            const [oldKey, old] = entries.next().value;
+            if (oldKey !== key || old.parent !== entry.parent || old.slot !== entry.slot || old.node.kind !== entry.node.kind) {
+                sameStructure = false;
+                break;
+            }
+            if (old !== entry && !equalData(old.node.props, entry.node.props))
+                updates.push(Object.freeze({ type: 'update', node: entry.node }));
+        }
+        if (sameStructure)
+            return Object.freeze(updates);
+    }
+    const mutations = [];
+    const removed = new Set();
+    for (const [key, old] of previous) {
+        if ((old.parent !== null && removed.has(old.parent)) || !next.has(key) || next.get(key).node.kind !== old.node.kind)
+            removed.add(key);
+    }
+    for (const [key, old] of previous)
+        if (removed.has(key) && (old.parent === null || !removed.has(old.parent)))
+            mutations.push({ type: 'remove', key });
+    const created = new Set();
+    for (const [key, entry] of next) {
+        const old = previous.get(key);
+        if (!old || removed.has(key)) {
+            created.add(key);
+            mutations.push({ type: 'create', node: entry.node });
+        }
+        else if (!equalData(old.node.props, entry.node.props))
+            mutations.push({ type: 'update', node: entry.node });
+    }
+    const oldGroups = groups(new Map([...previous].filter(([key]) => !removed.has(key))));
+    // Drop cross-slot entries from their old location before placing them in their new group.
+    for (const list of oldGroups.values())
+        for (let i = list.length - 1; i >= 0; i--) {
+            const key = list[i];
+            if (next.has(key) && group(previous.get(key)) !== group(next.get(key)))
+                list.splice(i, 1);
+        }
+    for (const [id, ordered] of groups(next)) {
+        const current = oldGroups.get(id) ?? [];
+        // The common props-only path never searches sibling positions.
+        if (current.length === ordered.length && current.every((key, index) => key === ordered[index]))
+            continue;
+        let before = null;
+        for (let i = ordered.length - 1; i >= 0; i--) {
+            const key = ordered[i], entry = next.get(key);
+            const at = current.indexOf(key), successor = at < 0 ? undefined : (current[at + 1] ?? null);
+            if (at < 0 || successor !== before) {
+                mutations.push({ type: created.has(key) ? 'insert' : 'move', key, parent: entry.parent, before,
+                    ...(entry.slot === undefined ? {} : { slot: entry.slot }) });
+                if (at >= 0)
+                    current.splice(at, 1);
+                current.splice(before === null ? current.length : current.indexOf(before), 0, key);
+            }
+            before = key;
+        }
+    }
+    return Object.freeze(mutations.map(mutation => Object.freeze(mutation)));
+}
+//# sourceMappingURL=tree.js.map

package/dist/range.d.ts

@@ -32,6 +32,9 @@ export declare class HYRange extends HTMLElement {
     set step(value: number);
     get value(): number;
     set value(value: number);
+    get controlled(): boolean;
+    set controlled(value: boolean);
+    private _acceptedValue;
     get range(): boolean;
     set range(value: boolean);
     get lowerValue(): number;

package/dist/range.js

@@ -17,7 +17,7 @@ export class HYRange extends HTMLElement {
     static get observedAttributes() {
         return [
             'min', 'max', 'step', 'value', 'range', 'lower-value', 'upper-value',
-            'disabled', 'show-value', 'aria-label',
+            'disabled', 'show-value', 'aria-label', 'controlled',
         ];
     }
     constructor() {
@@ -147,11 +147,11 @@ export class HYRange extends HTMLElement {
     set min(value) { this.setAttribute('min', String(finiteOr(value, DEFAULT_MIN))); }
     get max() {
         const value = Number(this.getAttribute('max'));
-        return Number.isFinite(value) && value > this.min ? value : Math.max(DEFAULT_MAX, this.min + DEFAULT_MAX);
+        return Number.isFinite(value) && (value > this.min || (this.controlled && value === this.min)) ? value : Math.max(DEFAULT_MAX, this.min + DEFAULT_MAX);
     }
     set max(value) {
         const next = finiteOr(value, DEFAULT_MAX);
-        this.setAttribute('max', String(next > this.min ? next : this.min + DEFAULT_MAX));
+        this.setAttribute('max', String(next > this.min || (this.controlled && next === this.min) ? next : this.min + DEFAULT_MAX));
     }
     get step() {
         const value = Number(this.getAttribute('step'));
@@ -161,8 +161,13 @@ export class HYRange extends HTMLElement {
         const next = finiteOr(value, DEFAULT_STEP);
         this.setAttribute('step', String(next > 0 ? next : DEFAULT_STEP));
     }
-    get value() { return this._normalize(Number(this.getAttribute('value') ?? this.min)); }
-    set value(value) { this.setAttribute('value', String(this._normalize(value))); }
+    get value() { return this._acceptedValue(Number(this.getAttribute('value') ?? this.min)); }
+    set value(value) { this.setAttribute('value', String(this._acceptedValue(value))); }
+    get controlled() { return this.hasAttribute('controlled'); }
+    set controlled(value) { this.toggleAttribute('controlled', value); }
+    _acceptedValue(value) {
+        return this.controlled ? Math.max(this.min, Math.min(this.max, finiteOr(value, this.min))) : this._normalize(value);
+    }
     get range() { return this.hasAttribute('range'); }
     set range(value) { this.toggleAttribute('range', Boolean(value)); }
     get lowerValue() {
@@ -262,6 +267,10 @@ export class HYRange extends HTMLElement {
         const changed = this._dragStartValue !== this._serializedValue();
         const handle = this._activeHandle;
         this._stopDrag();
+        if (this.controlled && event.type === 'pointercancel') {
+            this._dispatchValueEvent('value-cancel', handle);
+            return;
+        }
         if (changed)
             this._dispatchValueEvent('value-change', handle);
     };
@@ -359,6 +368,8 @@ export class HYRange extends HTMLElement {
         return this._normalize(Number(this.getAttribute('lower-value') ?? this.min));
     }
     _toPercent(value) {
+        if (this.max === this.min)
+            return 0;
         return (value - this.min) / (this.max - this.min) * 100;
     }
     _formatValue(value) {

package/dist/rate.d.ts

@@ -0,0 +1,46 @@
+export interface HYRateChangeDetail {
+    readonly value: number;
+}
+export interface HYRateHoverChangeDetail {
+    readonly value: number | null;
+}
+/** Accessible star rating with optional half-step pointer and keyboard selection. */
+export declare class HYRate extends HTMLElement {
+    private readonly _group;
+    private _value;
+    private _hoverValue;
+    private _tooltips;
+    private _reflecting;
+    static get observedAttributes(): string[];
+    constructor();
+    connectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    get value(): number;
+    set value(value: number);
+    get count(): number;
+    set count(value: number);
+    get allowHalf(): boolean;
+    set allowHalf(value: boolean);
+    get allowClear(): boolean;
+    set allowClear(value: boolean);
+    get disabled(): boolean;
+    set disabled(value: boolean);
+    get readOnly(): boolean;
+    set readOnly(value: boolean);
+    get character(): string;
+    set character(value: string);
+    get tooltips(): readonly string[];
+    set tooltips(value: readonly string[]);
+    private _normalize;
+    private _reflectValue;
+    private _render;
+    private _updateVisuals;
+    private _pointerValue;
+    private _handlePointerMove;
+    private _handleClick;
+    private _handleKeydown;
+    private _setHover;
+    private _commit;
+    private _valueText;
+}
+export declare function defineRateComponents(): void;