hys-ui 0.1.1 → 0.3.0

package/dist/types/composables/cascader.d.ts

@@ -0,0 +1,195 @@
+import type { HysPopupTransition } from '../motion/popup';
+import type { CSSProperties, VNodeChild } from "vue";
+import { type HysTreeKey } from "./tree";
+import type { Placement } from "./useFloating";
+export type HysCascaderKey = HysTreeKey;
+export type HysCascaderPath = readonly HysCascaderKey[];
+export type HysCascaderValue = HysCascaderKey | HysCascaderPath | readonly HysCascaderPath[] | null;
+export interface HysCascaderDataNode<K extends HysCascaderKey = HysCascaderKey> {
+    label: string;
+    value: K;
+    children?: HysCascaderDataNode<K>[];
+    disabled?: boolean;
+    isLeaf?: boolean;
+    hasChildren?: boolean;
+}
+/** Original string-valued data shape remains available. */
+export type HysCascaderNode = HysCascaderDataNode<string>;
+export interface HysCascaderFieldNames {
+    value: string;
+    label: string;
+    children: string;
+    disabled: string;
+    leaf: string;
+    hasChildren: string;
+}
+export interface HysCascaderItem<N extends object = HysCascaderNode> {
+    path: HysCascaderKey[];
+    labels: string[];
+    nodes: N[];
+    node?: N;
+    value: HysCascaderKey;
+    label: string;
+    disabled: boolean;
+    missing: boolean;
+}
+export interface HysCascaderOptionContext<N extends object = HysCascaderNode> extends HysCascaderItem<N> {
+    node: N;
+    level: number;
+    leaf: boolean;
+    expanded: boolean;
+    checked: boolean;
+    indeterminate: boolean;
+    loading: boolean;
+}
+export interface HysCascaderLoadContext<N extends object = HysCascaderNode> {
+    signal: AbortSignal;
+    path: HysCascaderKey[];
+    nodes: N[];
+    level: number;
+}
+export interface HysCascaderChange<N extends object = HysCascaderNode> {
+    reason: "select" | "check" | "remove" | "clear" | "api";
+    node?: N;
+    items: HysCascaderItem<N>[];
+    paths: HysCascaderKey[][];
+    halfCheckedPaths: HysCascaderKey[][];
+    event?: Event;
+}
+export interface HysCascaderLocale {
+    panel: string;
+    search: string;
+    empty: string;
+    noMatch: string;
+    loading: string;
+    loadError: string;
+    retry: string;
+    clear: string;
+    close: string;
+    level: string;
+    expand: string;
+    remove: string;
+    more: string;
+    limit: string;
+}
+export interface HysCascaderProps<N extends object = HysCascaderNode, V extends HysCascaderValue = HysCascaderValue> {
+    popupTransition?: HysPopupTransition;
+    popupTransitionDuration?: number;
+    options: readonly N[];
+    modelValue?: V;
+    defaultValue?: V;
+    cacheData?: readonly N[];
+    fieldNames?: Partial<HysCascaderFieldNames>;
+    valueKey?: string | ((node: N) => HysCascaderKey);
+    disabledMethod?: (node: N, path: readonly N[]) => boolean;
+    leafMethod?: (node: N, path: readonly N[]) => boolean;
+    disabled?: boolean;
+    readonly?: boolean;
+    loading?: boolean;
+    size?: "sm" | "md" | "lg";
+    status?: "error" | "warning" | "success";
+    placeholder?: string;
+    ariaLabel?: string;
+    name?: string;
+    form?: string;
+    autofocus?: boolean;
+    multiple?: boolean;
+    emitPath?: boolean;
+    checkStrictly?: boolean;
+    changeOnSelect?: boolean;
+    showCheckedStrategy?: "child" | "parent" | "all";
+    checkOnClickNode?: boolean;
+    checkOnClickLeaf?: boolean;
+    showPrefix?: boolean;
+    showAllLevels?: boolean;
+    separator?: string;
+    displayRender?: (item: HysCascaderItem<N>) => VNodeChild;
+    clearable?: boolean;
+    clearValue?: HysCascaderValue;
+    removable?: boolean;
+    multipleLimit?: number;
+    maxTagCount?: number;
+    maxTagTextLength?: number;
+    filterable?: boolean;
+    searchValue?: string;
+    defaultSearchValue?: string;
+    searchPlaceholder?: string;
+    filterMethod?: (query: string, path: readonly N[]) => boolean;
+    searchSort?: (a: HysCascaderItem<N>, b: HysCascaderItem<N>, query: string) => number;
+    searchLimit?: number | false;
+    debounce?: number;
+    beforeFilter?: (query: string, context: {
+        signal: AbortSignal;
+    }) => boolean | Promise<boolean>;
+    retainSearch?: boolean;
+    clearSearchAfterSelect?: boolean;
+    expandTrigger?: "click" | "hover";
+    hoverDelay?: number;
+    expandedPath?: HysCascaderPath;
+    defaultExpandedPath?: HysCascaderPath;
+    loadChildren?: (node: N, context: HysCascaderLoadContext<N>) => Promise<readonly N[]>;
+    loadRoot?: (context: {
+        signal: AbortSignal;
+    }) => Promise<readonly N[]>;
+    inline?: boolean;
+    showFooter?: boolean;
+    open?: boolean;
+    defaultOpen?: boolean;
+    showOnFocus?: boolean;
+    popupMatchWidth?: boolean;
+    popupWidth?: number | string;
+    popupClass?: string;
+    popupStyle?: CSSProperties;
+    appendTo?: string | HTMLElement | false;
+    placement?: Placement;
+    columnWidth?: number | string;
+    listHeight?: number;
+    virtual?: boolean;
+    itemHeight?: number;
+    overscan?: number;
+    emptyText?: string;
+    noMatchText?: string;
+    loadingText?: string;
+    locale?: Partial<HysCascaderLocale>;
+    validateEvent?: boolean;
+}
+export interface HysCascaderInstance<N extends object = HysCascaderNode> {
+    readonly element: HTMLElement | undefined;
+    readonly open: boolean;
+    focus: () => void;
+    blur: () => void;
+    show: () => Promise<boolean>;
+    hide: (restoreFocus?: boolean) => void;
+    clear: () => Promise<boolean>;
+    clearCheckedNodes: () => Promise<boolean>;
+    removeTag: (path: HysCascaderPath | HysCascaderKey) => Promise<boolean>;
+    setValue: (value: HysCascaderValue) => Promise<boolean>;
+    filter: (query: string) => void;
+    getSelectedItems: () => HysCascaderItem<N>[];
+    getCheckedNodes: (leafOnly?: boolean) => N[];
+    getExpandedPath: () => HysCascaderKey[];
+    setExpandedPath: (path: HysCascaderPath) => Promise<boolean>;
+    reloadNode: (path: HysCascaderPath) => Promise<boolean>;
+    reloadRoot: () => Promise<boolean>;
+    scrollTo: (path: HysCascaderPath) => Promise<void>;
+}
+export interface CascaderEntry<N extends object> {
+    value: string;
+    label: string;
+    raw: N;
+    path: HysCascaderKey[];
+    labels: string[];
+    nodes: N[];
+    children?: CascaderEntry<N>[];
+    disabled: boolean;
+    isLeaf: boolean;
+    hasChildren: boolean;
+}
+export declare const cascaderToken: (path: HysCascaderPath) => string;
+export declare function cascaderPath(token: string): HysCascaderKey[];
+export declare const validCascaderPath: (path: unknown) => path is HysCascaderKey[];
+export declare const cascaderWords: HysCascaderLocale;
+export declare function cascaderEntries<N extends object>(options: readonly N[], props: HysCascaderProps<N>, parent?: CascaderEntry<N>): {
+    roots: CascaderEntry<N>[];
+    map: Map<string, CascaderEntry<N>>;
+};

package/dist/types/composables/choice.d.ts

@@ -0,0 +1,110 @@
+import type { ComputedRef, InjectionKey, Ref } from "vue";
+export type HysChoiceValue = string | number | boolean;
+export interface HysChoiceFieldNames {
+    label?: string;
+    value?: string;
+    disabled?: string;
+    indeterminate?: string;
+}
+export interface HysChoiceOption<T extends HysChoiceValue = HysChoiceValue> {
+    label: string;
+    value: T;
+    disabled?: boolean;
+    indeterminate?: boolean;
+    [key: string]: unknown;
+}
+export type HysChoiceDataOption<T extends HysChoiceValue = HysChoiceValue> = T | HysChoiceOption<T> | Record<string, unknown>;
+export interface HysCheckboxReject {
+    value?: HysChoiceValue;
+    checked?: boolean;
+    reason: "min" | "max" | "range";
+}
+export interface HysCheckboxChange {
+    value?: HysChoiceValue;
+    checked?: boolean;
+    source: "toggle" | "all" | "clear";
+}
+export interface HysCheckboxInstance {
+    input: HTMLInputElement | undefined;
+    checked: boolean;
+    focus: (options?: FocusOptions) => void;
+    blur: () => void;
+    toggle: () => Promise<boolean>;
+}
+export interface HysCheckboxGroupInstance {
+    values: HysChoiceValue[];
+    allChecked: boolean;
+    indeterminate: boolean;
+    focus: (value?: HysChoiceValue) => void;
+    blur: () => void;
+    checkAll: () => Promise<boolean>;
+    clear: () => Promise<boolean>;
+    toggle: (value: HysChoiceValue, checked?: boolean) => Promise<boolean>;
+}
+interface CheckboxRegistration {
+    input: Ref<HTMLInputElement | undefined>;
+    value: ComputedRef<HysChoiceValue | undefined>;
+    locked: ComputedRef<boolean>;
+    disabled: ComputedRef<boolean>;
+}
+export interface HysCheckboxGroupContext {
+    values: ComputedRef<HysChoiceValue[]>;
+    disabled: ComputedRef<boolean>;
+    readonly: ComputedRef<boolean>;
+    size: ComputedRef<"sm" | "md" | "lg">;
+    button: ComputedRef<boolean>;
+    border: ComputedRef<boolean>;
+    solid: ComputedRef<boolean>;
+    status: ComputedRef<string | undefined>;
+    form: ComputedRef<string | undefined>;
+    isLimited: (value: HysChoiceValue) => boolean;
+    toggle: (value: HysChoiceValue, checked: boolean) => Promise<boolean>;
+    register: (record: CheckboxRegistration) => () => void;
+}
+export declare const checkboxGroupKey: InjectionKey<HysCheckboxGroupContext>;
+export declare function isChoice(value: unknown): value is HysChoiceValue;
+export declare function choiceKey(value: HysChoiceValue): string;
+export declare function uniqueChoices(values: readonly unknown[]): HysChoiceValue[];
+export declare function choiceOptions<T extends HysChoiceValue>(source: readonly HysChoiceDataOption<T>[], fields?: HysChoiceFieldNames): HysChoiceOption<T>[];
+export interface HysRadioInstance {
+    input: HTMLInputElement | undefined;
+    checked: boolean;
+    focus: (options?: FocusOptions) => void;
+    blur: () => void;
+    select: () => Promise<boolean>;
+}
+export interface HysRadioGroupInstance {
+    value: HysChoiceValue | null;
+    focus: (value?: HysChoiceValue) => void;
+    blur: () => void;
+    select: (value: HysChoiceValue) => Promise<boolean>;
+}
+export interface HysRadioGroupContext {
+    value: ComputedRef<HysChoiceValue | null>;
+    disabled: ComputedRef<boolean>;
+    readonly: ComputedRef<boolean>;
+    required: ComputedRef<boolean>;
+    size: ComputedRef<"sm" | "md" | "lg">;
+    button: ComputedRef<boolean>;
+    border: ComputedRef<boolean>;
+    solid: ComputedRef<boolean>;
+    name: ComputedRef<string>;
+    form: ComputedRef<string | undefined>;
+    status: ComputedRef<string | undefined>;
+    select: (value: HysChoiceValue) => Promise<boolean>;
+    tabindex: (value: HysChoiceValue) => number;
+    register: (record: CheckboxRegistration) => () => void;
+}
+export declare const radioGroupKey: InjectionKey<HysRadioGroupContext>;
+export interface HysSwitchGuardContext {
+    signal: AbortSignal;
+}
+export interface HysSwitchInstance {
+    element: HTMLButtonElement | undefined;
+    checked: boolean;
+    pending: boolean;
+    focus: (options?: FocusOptions) => void;
+    blur: () => void;
+    toggle: () => Promise<boolean>;
+}
+export {};

package/dist/types/composables/choiceModel.d.ts

@@ -0,0 +1,11 @@
+import { type Ref } from "vue";
+export declare function useChoiceModel<V>(props: {
+    modelValue?: V;
+}, initial: () => V, equal?: (a: V, b: V) => boolean, invalidated?: () => void): {
+    current: import("vue").ComputedRef<V>;
+    commit: (value: V, update: (value: V) => void, change: (value: V) => void, notifyOnRequest?: boolean) => Promise<boolean>;
+    reset: () => void;
+    invalidate: () => void;
+    isLive: () => boolean;
+};
+export declare function useChoiceNativeReset(element: Ref<HTMLElement | undefined>, reset: () => void, sync?: () => void, formId?: () => string | undefined): void;

package/dist/types/composables/color.d.ts

@@ -0,0 +1,97 @@
+import type { CSSProperties, VNodeChild } from "vue";
+import type { HysPopupMotionProps } from "../motion/popup";
+import type { Placement } from "./useFloating";
+export type HysColorFormat = "hex" | "rgb" | "hsl" | "hsv";
+export interface HysColor {
+    h: number;
+    s: number;
+    v: number;
+    a: number;
+}
+export interface HysColorPickerProps extends HysPopupMotionProps {
+    modelValue?: string;
+    defaultValue?: string;
+    disabled?: boolean;
+    readonly?: boolean;
+    size?: "sm" | "md" | "lg";
+    label?: string;
+    ariaLabel?: string;
+    presets?: readonly string[];
+    clearable?: boolean;
+    showAlpha?: boolean;
+    format?: HysColorFormat;
+    immediate?: boolean;
+    showInput?: boolean;
+    showText?: boolean;
+    showPresets?: boolean;
+    inline?: boolean;
+    open?: boolean;
+    defaultOpen?: boolean;
+    placement?: Placement;
+    appendTo?: string | HTMLElement | false;
+    popupClass?: string;
+    popupStyle?: CSSProperties;
+    popupWidth?: number | string;
+    showFooter?: boolean;
+    confirmText?: string;
+    cancelText?: string;
+    clearText?: string;
+    status?: "error" | "warning" | "success";
+    error?: string;
+    name?: string;
+    form?: string;
+    tabindex?: number;
+    autofocus?: boolean;
+    validateEvent?: boolean;
+    inputProps?: Record<string, unknown>;
+}
+export interface HysColorPickerContext {
+    value: string;
+    draft: string;
+    color: Readonly<HysColor>;
+    disabled: boolean;
+    readonly: boolean;
+    valid: boolean;
+    dirty: boolean;
+    setColor: (value: string) => Promise<boolean>;
+    confirm: () => Promise<boolean>;
+    cancel: () => void;
+    clear: () => Promise<boolean>;
+    show: () => Promise<boolean>;
+    hide: () => Promise<boolean>;
+}
+export interface HysColorPickerSlots {
+    trigger?: (context: HysColorPickerContext) => VNodeChild;
+    header?: (context: HysColorPickerContext) => VNodeChild;
+    footer?: (context: HysColorPickerContext) => VNodeChild;
+    preset?: (context: {
+        value: string;
+        color: string;
+        selected: boolean;
+        disabled: boolean;
+    }) => VNodeChild;
+}
+export interface HysColorPickerInstance {
+    readonly element: HTMLElement | undefined;
+    readonly input: HTMLInputElement | undefined;
+    readonly panel: HTMLElement | undefined;
+    readonly value: string;
+    readonly draft: string;
+    readonly color: Readonly<HysColor>;
+    readonly open: boolean;
+    focus: (options?: FocusOptions) => void;
+    blur: () => void;
+    show: () => Promise<boolean>;
+    hide: () => Promise<boolean>;
+    confirm: () => Promise<boolean>;
+    cancel: () => void;
+    clear: () => Promise<boolean>;
+    setColor: (value: string) => Promise<boolean>;
+}
+export declare const colorClamp: (value: number, min?: number, max?: number) => number;
+export declare function colorFromRgb(r: number, g: number, b: number, a?: number): HysColor;
+export declare function colorRgb(c: HysColor): readonly [number, number, number];
+export declare function parseColor(value: string | undefined): HysColor | undefined;
+export declare function formatColor(color: HysColor, format?: HysColorFormat, alpha?: boolean): string;
+export declare const colorCss: (color: HysColor) => string;
+export declare function sameColor(a: HysColor | undefined, b: HysColor | undefined): boolean;

package/dist/types/composables/dataGrid.d.ts

@@ -0,0 +1,100 @@
+import type { HysPopupMotionProps } from "../motion/popup";
+export type HysDataGridKey = string | number;
+export type HysDataGridSort = {
+    key: string;
+    direction: "asc" | "desc";
+};
+export interface HysDataGridQuery {
+    page: number;
+    pageSize: number;
+    sort: HysDataGridSort[];
+    search: string;
+    filters: Record<string, string>;
+}
+export interface GridColumn<T extends object = Record<string, unknown>> {
+    key: string;
+    label: string;
+    field?: string | ((row: T) => unknown);
+    width?: number;
+    minWidth?: number;
+    maxWidth?: number;
+    sortable?: boolean;
+    sortMethod?: (a: T, b: T) => number;
+    filterable?: boolean;
+    filterMethod?: (value: string, row: T) => boolean;
+    hideable?: boolean;
+    resizable?: boolean;
+    reorderable?: boolean;
+    pinned?: "left" | "right";
+    align?: "left" | "center" | "right";
+    summary?: "sum" | "avg" | "min" | "max" | "count";
+    editable?: boolean;
+}
+export interface HysDataGridResult<T extends object> {
+    rows: readonly T[];
+    total: number;
+}
+export type HysDataGridLoader<T extends object> = (query: HysDataGridQuery, context: {
+    signal: AbortSignal;
+}) => Promise<HysDataGridResult<T>> | HysDataGridResult<T>;
+export interface HysDataGridProps<T extends object> extends HysPopupMotionProps {
+    columns: readonly GridColumn<T>[];
+    rows: readonly T[];
+    rowKey?: string | ((row: T, index: number) => HysDataGridKey);
+    page?: number;
+    pageSize?: number;
+    query?: HysDataGridQuery;
+    defaultQuery?: Partial<HysDataGridQuery>;
+    immediateQuery?: boolean;
+    serverMode?: boolean;
+    loadRows?: HysDataGridLoader<T>;
+    totalRows?: number;
+    storageKey?: string;
+    selectable?: boolean;
+    rowSelectable?: (row: T, index: number) => boolean;
+    selectedRowKeys?: readonly HysDataGridKey[];
+    defaultSelectedRowKeys?: readonly HysDataGridKey[];
+    reserveSelection?: boolean;
+    selectionType?: "checkbox" | "radio";
+    loading?: boolean;
+    emptyText?: string;
+    density?: "compact" | "normal" | "comfortable";
+    multiSort?: boolean;
+    stickyHeader?: boolean;
+    maxHeight?: number | string;
+    scrollToTopOnQuery?: boolean;
+    groupable?: boolean;
+    showSummary?: boolean;
+    summaryMethod?: (column: GridColumn<T>, rows: readonly T[]) => string | number;
+    treeMode?: boolean;
+    parentKey?: string;
+    editable?: boolean;
+}
+export interface HysDataGridInstance {
+    resetColumns(): void;
+    getQuery(): HysDataGridQuery;
+    setQuery(query: Partial<HysDataGridQuery>): void;
+    resetQuery(): void;
+    reload(): void;
+    getSelection(): HysDataGridKey[];
+    clearSelection(): void;
+    toggleRowSelection(key: HysDataGridKey, checked?: boolean): void;
+    scrollTo(options: ScrollToOptions): void;
+    scrollToRow(key: HysDataGridKey): boolean;
+}
+export type GridRow<T extends object> = {
+    row: T;
+    id: HysDataGridKey;
+    index: number;
+};
+export type GridTreeRow<T extends object> = GridRow<T> & {
+    depth: number;
+    hasChildren: boolean;
+};
+export declare const gridKey: (value: unknown) => value is HysDataGridKey;
+export declare const gridToken: (key: HysDataGridKey) => string;
+export declare const positiveInteger: (value: number | undefined, fallback: number) => number;
+export declare function gridField(row: object, path: string): unknown;
+export declare function gridValue<T extends object>(row: T, column: GridColumn<T>): unknown;
+export declare function gridRows<T extends object>(rows: readonly T[], rowKey: NonNullable<HysDataGridProps<T>["rowKey"]>, offset: number): GridRow<T>[];
+export declare function gridTree<T extends object>(rows: readonly GridRow<T>[], parentKey: string, expanded: ReadonlySet<HysDataGridKey>): GridTreeRow<T>[];