@haiyue/ui 0.1.1 → 0.2.1

package/dist/core/selection.js

@@ -0,0 +1,93 @@
+import { equalData, snapshot } from './data.js';
+import { HYUIError, hyKey, hyValidateProps } from './validation.js';
+/** Controlled Select/Tabs semantics. Views report user actions, never delayed setter echoes. */
+export class HYSelectionController {
+    key;
+    emit;
+    #props;
+    #view;
+    #off;
+    #applying = false;
+    #disposed = false;
+    #choosing = false;
+    #generation = 0;
+    #transaction = 0;
+    #lastApplied;
+    constructor(key, props, emit) {
+        this.key = key;
+        this.emit = emit;
+        hyKey(key);
+        this.update(props);
+    }
+    update(props) {
+        if (this.#disposed)
+            return;
+        hyValidateProps('Select', props, { key: this.key });
+        if (equalData(props, this.#props))
+            return;
+        this.#props = snapshot(props);
+        this.#generation++;
+        this.#apply();
+    }
+    #apply() {
+        if (!this.#view || this.#disposed || equalData(this.#lastApplied, this.#props))
+            return;
+        this.#applying = true;
+        try {
+            this.#view.apply(this.#props);
+            this.#lastApplied = this.#props;
+        }
+        finally {
+            this.#applying = false;
+        }
+    }
+    attach(view) {
+        if (this.#disposed || this.#view)
+            throw new HYUIError('lifecycle', 'Selection disposed or already attached', { key: this.key });
+        this.#view = view;
+        this.#off = view.listen((value, reason = 'pointer') => this.choose(value, reason));
+        this.#apply();
+    }
+    choose(value, reason = 'pointer') {
+        if (this.#disposed || this.#applying || this.#choosing || this.#props.disabled)
+            return false;
+        const option = this.#props.options.find(item => item.value === value);
+        if (!option || option.disabled || value === this.#props.value)
+            return false;
+        this.#lastApplied = undefined;
+        this.#choosing = true;
+        const transaction = ++this.#transaction;
+        try {
+            this.emit({ type: 'valueChange', key: this.key, value, reason, transaction });
+            if (this.#disposed)
+                return false;
+            this.emit({ type: 'commit', key: this.key, value, reason, transaction });
+            return true;
+        }
+        finally {
+            this.#choosing = false;
+            this.#apply();
+        }
+    }
+    async pick(open, reason = 'pointer') {
+        if (this.#disposed || this.#props.disabled)
+            return false;
+        const generation = ++this.#generation;
+        const value = await open();
+        if (this.#disposed || generation !== this.#generation || value === null)
+            return false;
+        return this.choose(value, reason);
+    }
+    cancel() { this.#generation++; }
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        this.cancel();
+        const off = this.#off;
+        this.#off = undefined;
+        this.#view = undefined;
+        off?.();
+    }
+}
+//# sourceMappingURL=selection.js.map

package/dist/core/text.d.ts

@@ -0,0 +1,31 @@
+import type { HYReason, HYTextProps, HYUIEvent } from './types.js';
+export interface HYTextViewState {
+    readonly props: HYTextProps;
+    readonly value: string;
+    readonly composing: boolean;
+}
+export interface HYTextView {
+    apply(state: HYTextViewState): void;
+}
+/** Local draft/IME state only. The application accepts or rejects commit through props/revision. */
+export declare class HYTextController {
+    #private;
+    readonly key: string;
+    private readonly emit;
+    readonly multiline: boolean;
+    constructor(key: string, props: HYTextProps, emit: (event: HYUIEvent) => void, multiline?: boolean, revision?: number);
+    get value(): string;
+    get composing(): boolean;
+    update(props: HYTextProps, revision?: number): void;
+    attach(view: HYTextView): void;
+    input(value: string, reason?: HYReason): boolean;
+    compositionStart(reason?: HYReason): boolean;
+    compositionEnd(value: string, reason?: HYReason): boolean;
+    commit(reason?: HYReason): boolean;
+    /** The adapter supplies wasComposing from its native event; confirmation Enter never submits. */
+    enter(wasComposing?: boolean): boolean;
+    focus(reason?: HYReason): void;
+    blur(reason?: HYReason): void;
+    cancel(reason?: HYReason): void;
+    dispose(): void;
+}

package/dist/core/text.js

@@ -0,0 +1,154 @@
+import { equalData, snapshot } from './data.js';
+import { HYUIError, hyKey, hyValidateProps } from './validation.js';
+/** Local draft/IME state only. The application accepts or rejects commit through props/revision. */
+export class HYTextController {
+    key;
+    emit;
+    multiline;
+    #props;
+    #revision = -1;
+    #draft = '';
+    #composing = false;
+    #pending;
+    #transaction = 0;
+    #active = 0;
+    #disposed = false;
+    #applying = false;
+    #view;
+    #applied;
+    constructor(key, props, emit, multiline = false, revision = 0) {
+        this.key = key;
+        this.emit = emit;
+        this.multiline = multiline;
+        hyKey(key);
+        this.update(props, revision);
+    }
+    get value() { return this.#draft; }
+    get composing() { return this.#composing; }
+    update(props, revision = this.#revision) {
+        if (this.#disposed)
+            return;
+        hyValidateProps(this.multiline ? 'TextArea' : 'TextInput', props, { key: this.key });
+        if (!Number.isSafeInteger(revision) || revision < 0)
+            throw new HYUIError('invalid-props', 'Invalid application revision', { key: this.key });
+        if (revision < this.#revision)
+            return;
+        const changed = !this.#props || props.value !== this.#props.value;
+        if (this.#props && changed && revision === this.#revision)
+            throw new HYUIError('invalid-props', 'Changed accepted value requires a newer revision', { key: this.key });
+        this.#props = snapshot(props);
+        this.#revision = revision;
+        if (changed) {
+            if (this.#composing)
+                this.#pending = { value: props.value, revision };
+            else {
+                this.#draft = props.value;
+                this.#active = 0;
+                this.#pending = undefined;
+            }
+        }
+        if (props.disabled || props.readOnly) {
+            if (this.#pending)
+                this.#draft = this.#pending.value;
+            this.#composing = false;
+            this.#pending = undefined;
+            this.#active = 0;
+        }
+        // Reapplying the accepted value never discards an unaccepted draft or its selection.
+        this.#apply();
+    }
+    attach(view) {
+        if (this.#view || this.#disposed)
+            throw new HYUIError('lifecycle', 'Text disposed or already attached', { key: this.key });
+        this.#view = view;
+        this.#apply();
+    }
+    #apply() {
+        if (!this.#view || this.#disposed)
+            return;
+        const state = snapshot({ props: this.#props, value: this.#draft, composing: this.#composing });
+        if (equalData(state, this.#applied))
+            return;
+        this.#applying = true;
+        try {
+            this.#view.apply(state);
+            this.#applied = state;
+        }
+        finally {
+            this.#applying = false;
+        }
+    }
+    #enabled() { return !this.#disposed && !this.#applying && !this.#props.disabled && !this.#props.readOnly; }
+    #send(type, reason, value) {
+        if (this.#disposed)
+            return;
+        this.emit({ key: this.key, type, reason, transaction: this.#active, composing: this.#composing, ...(value === undefined ? {} : { value }) });
+    }
+    input(value, reason = 'keyboard') {
+        if (!this.#enabled() || typeof value !== 'string' || value === this.#draft)
+            return false;
+        this.#draft = value;
+        this.#active ||= ++this.#transaction;
+        this.#send(this.#composing ? 'compositionUpdate' : 'valueChange', reason, value);
+        this.#apply();
+        return true;
+    }
+    compositionStart(reason = 'keyboard') {
+        if (!this.#enabled() || this.#composing)
+            return false;
+        this.#composing = true;
+        this.#active ||= ++this.#transaction;
+        this.#send('compositionStart', reason);
+        return true;
+    }
+    compositionEnd(value, reason = 'keyboard') {
+        if (this.#disposed || this.#applying || !this.#composing || typeof value !== 'string')
+            return false;
+        this.#draft = value;
+        this.#composing = false;
+        this.#send('compositionEnd', reason, value);
+        this.#send('valueChange', reason, value);
+        if (this.#pending) {
+            // A newer authoritative update wins; an acceptance during emit can supersede it.
+            if (this.#pending.revision === this.#revision)
+                this.#draft = this.#pending.value;
+            this.#pending = undefined;
+            this.#active = 0;
+        }
+        this.#apply();
+        return true;
+    }
+    commit(reason = 'keyboard') {
+        if (!this.#enabled() || this.#composing || !this.#active)
+            return false;
+        const transaction = this.#active;
+        this.#active = 0;
+        if (this.#draft === this.#props.value)
+            return false;
+        this.emit({ key: this.key, type: 'commit', value: this.#draft, reason, transaction, composing: false });
+        this.#apply();
+        return true;
+    }
+    /** The adapter supplies wasComposing from its native event; confirmation Enter never submits. */
+    enter(wasComposing = false) { return !this.multiline && !wasComposing && this.commit('keyboard'); }
+    focus(reason = 'keyboard') { if (!this.#disposed && !this.#applying)
+        this.#send('focus', reason); }
+    blur(reason = 'keyboard') {
+        if (this.#disposed || this.#applying)
+            return;
+        this.commit(reason);
+        this.#send('blur', reason);
+    }
+    cancel(reason = 'keyboard') {
+        if (this.#disposed || this.#applying)
+            return;
+        this.#draft = this.#props.value;
+        this.#composing = false;
+        this.#pending = undefined;
+        this.#send('cancel', reason);
+        this.#active = 0;
+        this.#apply();
+    }
+    dispose() { this.#disposed = true; this.#view = undefined; this.#pending = undefined; this.#active = 0; }
+}
+//# sourceMappingURL=text.js.map

package/dist/core/types.d.ts

@@ -0,0 +1,250 @@
+/** Portable UI protocol 1, additive G03 schema 1.1. No platform imports. */
+export type HYNodeKey = string;
+export type HYDispose = () => void;
+export type HYReason = 'pointer' | 'keyboard' | 'accessibility';
+export interface HYOption {
+    readonly value: string;
+    readonly label: string;
+    readonly disabled?: boolean;
+}
+export interface HYSelectionProps {
+    readonly value: string;
+    readonly options: readonly HYOption[];
+    readonly disabled?: boolean;
+}
+export interface HYSelectionEvent {
+    readonly type: 'valueChange' | 'commit';
+    readonly key: HYNodeKey;
+    readonly value: string;
+    readonly reason: HYReason;
+    readonly transaction: number;
+}
+export interface HYSelectionView {
+    apply(props: HYSelectionProps): void;
+    listen(listener: (value: string, reason?: HYReason) => void): HYDispose;
+}
+export interface HYStore<S, A> {
+    getSnapshot(): Readonly<S>;
+    dispatch(action: A): void;
+    subscribe<T>(select: (state: Readonly<S>) => T, notify: (value: T) => void, equal?: (a: T, b: T) => boolean): HYDispose;
+    transaction(run: () => void): void;
+    dispose(): void;
+}
+export interface HYCancelSignal {
+    readonly aborted: boolean;
+    onAbort(callback: () => void): HYDispose;
+}
+export interface HYRequestContext {
+    readonly session: string;
+    readonly revision: number;
+    readonly request: number;
+    readonly signal: HYCancelSignal;
+}
+export type HYLength = number | 'auto';
+export interface HYLayout {
+    readonly width?: HYLength;
+    readonly height?: HYLength;
+    readonly minWidth?: number;
+    readonly maxWidth?: number;
+    readonly minHeight?: number;
+    readonly maxHeight?: number;
+    readonly padding?: readonly [number, number, number, number];
+    readonly gap?: number;
+    readonly grow?: number;
+    readonly align?: 'start' | 'center' | 'end' | 'stretch';
+    readonly columns?: readonly (number | 'auto' | {
+        readonly grow: number;
+    })[];
+    readonly rows?: readonly (number | 'auto' | {
+        readonly grow: number;
+    })[];
+    readonly row?: number;
+    readonly column?: number;
+    readonly clip?: boolean;
+}
+export interface HYAccessibility {
+    readonly label: string;
+    readonly description?: string;
+    readonly error?: string;
+    readonly role?: 'button' | 'text' | 'textbox' | 'checkbox' | 'tab' | 'dialog' | 'image' | 'slider' | 'list' | 'tree';
+}
+export interface HYCommonProps {
+    readonly layout?: HYLayout;
+    readonly a11y?: HYAccessibility;
+    readonly visible?: boolean;
+}
+export interface HYTextProps {
+    readonly value: string;
+    readonly disabled?: boolean;
+    readonly readOnly?: boolean;
+    readonly placeholder?: string;
+    readonly secure?: boolean;
+}
+export interface HYResource {
+    readonly id: string;
+    readonly alt: string;
+}
+export interface HYComponentProps {
+    Row: HYCommonProps;
+    Column: HYCommonProps;
+    Grid: HYCommonProps;
+    Overlay: HYCommonProps;
+    Scroll: HYCommonProps & {
+        readonly axis: 'horizontal' | 'vertical';
+    };
+    Text: HYCommonProps & {
+        readonly text: string;
+        readonly wrap?: boolean;
+    };
+    Image: HYCommonProps & {
+        readonly resource: HYResource;
+        readonly fit?: 'contain' | 'cover';
+    };
+    Icon: HYCommonProps & {
+        readonly resource: HYResource;
+        readonly systemName?: string;
+    };
+    Button: HYCommonProps & {
+        readonly text: string;
+        readonly disabled?: boolean;
+        readonly busy?: boolean;
+    };
+    Checkbox: HYCommonProps & {
+        readonly checked: boolean;
+        readonly disabled?: boolean;
+        readonly text: string;
+    };
+    RadioGroup: HYCommonProps & HYSelectionProps;
+    Rate: HYCommonProps & {
+        readonly value: number;
+        readonly count: number;
+        readonly disabled?: boolean;
+        readonly readOnly?: boolean;
+    };
+    Badge: HYCommonProps & {
+        readonly text: string;
+    };
+    Divider: HYCommonProps & {
+        readonly text?: string;
+    };
+    Toggle: HYCommonProps & {
+        readonly checked: boolean;
+        readonly disabled?: boolean;
+    };
+    Select: HYCommonProps & HYSelectionProps;
+    Tabs: HYCommonProps & HYSelectionProps;
+    TextInput: HYCommonProps & HYTextProps;
+    TextArea: HYCommonProps & Omit<HYTextProps, 'secure'>;
+    Slider: HYCommonProps & {
+        readonly value: number;
+        readonly min: number;
+        readonly max: number;
+        readonly step: number;
+        readonly disabled?: boolean;
+    };
+    Dialog: HYCommonProps & {
+        readonly open: boolean;
+        readonly title: string;
+        readonly dismissible?: boolean;
+    };
+    FormGroup: HYCommonProps & {
+        readonly label: string;
+        readonly error?: string;
+    };
+    PlatformView: HYCommonProps & {
+        readonly slot: string;
+        readonly resourceId: string;
+    };
+}
+export type HYComponentKind = keyof HYComponentProps;
+export type HYNode = {
+    [K in HYComponentKind]: {
+        readonly key: HYNodeKey;
+        readonly kind: K;
+        readonly props: Readonly<HYComponentProps[K]>;
+        readonly source?: HYSourceLocation;
+        readonly requires?: readonly HYFeature[];
+        readonly children?: readonly HYNode[];
+        readonly slots?: Readonly<Record<string, readonly HYNode[]>>;
+    };
+}[HYComponentKind];
+export interface HYUIEvent {
+    readonly key: HYNodeKey;
+    readonly type: 'activate' | 'valueChange' | 'commit' | 'cancel' | 'focus' | 'blur' | 'compositionStart' | 'compositionUpdate' | 'compositionEnd';
+    readonly value?: string | number | boolean;
+    readonly reason: HYReason;
+    readonly transaction: number;
+    readonly composing?: boolean;
+}
+export type HYMutation = {
+    readonly type: 'create';
+    readonly node: HYNode;
+} | {
+    readonly type: 'update';
+    readonly node: HYNode;
+} | {
+    readonly type: 'insert' | 'move';
+    readonly key: HYNodeKey;
+    readonly parent: HYNodeKey | null;
+    readonly before: HYNodeKey | null;
+    readonly slot?: string;
+} | {
+    readonly type: 'remove';
+    readonly key: HYNodeKey;
+};
+export interface HYCapabilities {
+    readonly contract: 1;
+    readonly backend: 'web' | 'nativescript' | 'desktop';
+    readonly components: readonly HYComponentKind[];
+    readonly features: readonly string[];
+}
+export interface HYRenderer {
+    readonly capabilities: HYCapabilities;
+    mount(emit: (event: HYUIEvent) => void): void;
+    commit(revision: number, mutations: readonly HYMutation[]): void;
+    focus(key: HYNodeKey): void;
+    suspend(): void;
+    resume(): void;
+    dispose(): void;
+}
+export interface HYPlatformView {
+    mount(): void;
+    update(resourceId: string): void;
+    layout(bounds: {
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+        readonly height: number;
+        readonly scale: number;
+    }): void;
+    visible(value: boolean): void;
+    focus(): void;
+    dispose(): void;
+}
+export interface HYTheme {
+    readonly color: Readonly<Record<'text' | 'muted' | 'surface' | 'input' | 'accent' | 'danger' | 'border' | 'focus', string>>;
+    readonly fontSize: number;
+    readonly lineHeight: number;
+    readonly gap: number;
+    readonly radius: number;
+}
+export interface HYSourceLocation {
+    readonly file: string;
+    readonly line?: number;
+}
+export type HYFeature = 'text.composition' | 'text.selection' | 'text.secure' | 'accessibility' | 'icons.system' | 'layout.rtl' | 'theme.highContrast' | 'motion.reduced';
+export interface HYDiagnosticContext {
+    readonly key?: string;
+    readonly property?: string;
+    readonly source?: HYSourceLocation;
+    readonly operation?: string;
+    readonly revision?: number;
+}
+export type HYDiagnosticCode = 'invalid-props' | 'duplicate-key' | 'capability' | 'lifecycle' | 'renderer';
+export interface HYBounds {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    readonly scale: number;
+}

package/dist/core/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/validation.d.ts

@@ -0,0 +1,24 @@
+import type { HYCapabilities, HYComponentKind, HYComponentProps, HYDiagnosticCode, HYDiagnosticContext, HYFeature, HYNode, HYSourceLocation } from './types.js';
+export declare class HYUIError extends Error {
+    readonly code: HYDiagnosticCode;
+    readonly context: Readonly<HYDiagnosticContext>;
+    constructor(code: HYDiagnosticCode, message: string, context?: HYDiagnosticContext, cause?: unknown);
+}
+export declare const HY_FEATURES: readonly HYFeature[];
+export declare const HY_COMPONENTS: readonly HYComponentKind[];
+export declare function hyValidateCapabilities(capabilities: HYCapabilities): void;
+export declare function hySupports(capabilities: HYCapabilities, feature: HYFeature): boolean;
+/** Internal immutable hand-off. Mutable and merely shallow-frozen inputs are always validated. */
+export declare function snapshotValidatedProps<K extends HYComponentKind>(kind: K, props: HYComponentProps[K], context: HYDiagnosticContext, capabilities: HYCapabilities): HYComponentProps[K];
+export declare function hyValidateProps<K extends HYComponentKind>(kind: K, props: HYComponentProps[K], context?: HYDiagnosticContext, capabilities?: HYCapabilities): void;
+/** Escaped, stable backend key. Author keys are unique across all slots of one parent. */
+export declare function hyKey(...parts: readonly string[]): string;
+export declare function hyValidateNode(node: HYNode, capabilities?: HYCapabilities): HYNode;
+export declare function hyNode<K extends HYComponentKind>(kind: K, key: string, props: HYComponentProps[K], content?: {
+    readonly children?: readonly HYNode[];
+    readonly slots?: Readonly<Record<string, readonly HYNode[]>>;
+    readonly source?: HYSourceLocation;
+    readonly requires?: readonly HYFeature[];
+}): Extract<HYNode, {
+    kind: K;
+}>;