@vobs/ui 0.1.0

package/dist/complex-inputs.d.ts

@@ -0,0 +1,300 @@
+/** @license MIT
+ * Copyright (c) 2026 vobsjs
+ * @vobs/ui
+ */
+import { type UiAttributes, type UiControlSize, type UiDensity, type UiDomPlan } from './primitives.js';
+export interface ComboboxOption {
+    readonly id: string;
+    readonly value: string;
+    readonly label: string;
+    readonly disabled?: boolean;
+}
+export interface ComboboxPlanOptions {
+    readonly id: string;
+    readonly options: readonly ComboboxOption[];
+    readonly inputValue: string;
+    readonly activeId?: string;
+    readonly selectedValue?: string;
+    readonly open?: boolean;
+    readonly disabled?: boolean;
+    readonly required?: boolean;
+    readonly invalid?: boolean;
+    readonly labelId?: string;
+    readonly describedBy?: string;
+    readonly placeholder?: string;
+    readonly className?: string;
+    readonly attrs?: UiAttributes;
+}
+export interface ComboboxPlans {
+    readonly root: UiDomPlan<'div'>;
+    readonly input: UiDomPlan<'input'>;
+    readonly listbox: UiDomPlan<'ul'>;
+    readonly options: readonly UiDomPlan<'li'>[];
+}
+export interface CascaderOption {
+    readonly id: string;
+    readonly value: string;
+    readonly label: string;
+    readonly disabled?: boolean;
+    readonly children?: readonly CascaderOption[];
+}
+export interface CascaderPlanOptions {
+    readonly id: string;
+    readonly options: readonly CascaderOption[];
+    readonly open?: boolean;
+    readonly activePath?: readonly string[];
+    readonly selectedValue?: string;
+    readonly disabled?: boolean;
+    readonly required?: boolean;
+    readonly invalid?: boolean;
+    readonly labelId?: string;
+    readonly describedBy?: string;
+    readonly placeholder?: string;
+    readonly className?: string;
+    readonly attrs?: UiAttributes;
+}
+export interface CascaderPlans {
+    readonly root: UiDomPlan<'div'>;
+    readonly trigger: UiDomPlan<'button'>;
+    readonly popup: UiDomPlan<'div'>;
+    readonly columns: readonly UiDomPlan<'div'>[];
+    readonly options: readonly UiDomPlan<'button'>[];
+}
+export type CascaderRemoteState = 'empty' | 'error' | 'filtered' | 'loading' | 'ready';
+export type CascaderPermissionState = 'allowed' | 'restricted';
+export type CascaderVirtualState = 'full' | 'windowed';
+export type CascaderPersistenceState = 'dirty' | 'restored' | 'synced' | 'unbound';
+export interface CascaderAdvancedStateContractOptions {
+    readonly options: readonly CascaderOption[];
+    readonly query?: string;
+    readonly loading?: boolean;
+    readonly error?: string;
+    readonly resultCount?: number;
+    readonly allowedIds?: readonly string[];
+    readonly deniedIds?: readonly string[];
+    readonly disabledReasons?: Readonly<Record<string, string>>;
+    readonly visibleIds?: readonly string[];
+    readonly totalNodeCount?: number;
+    readonly virtualStart?: number;
+    readonly virtualEnd?: number;
+    readonly estimatedRowHeight?: number;
+    readonly currentValue?: string;
+    readonly persistedValue?: string;
+    readonly dirty?: boolean;
+    readonly restored?: boolean;
+}
+export interface CascaderOptionStateContract {
+    readonly id: string;
+    readonly visible: boolean;
+    readonly allowed: boolean;
+    readonly reason: string;
+    readonly attrs: UiAttributes;
+}
+export interface CascaderAdvancedStateContract {
+    readonly remoteState: CascaderRemoteState;
+    readonly permissionState: CascaderPermissionState;
+    readonly virtualState: CascaderVirtualState;
+    readonly persistenceState: CascaderPersistenceState;
+    readonly query: string;
+    readonly resultCount: number | undefined;
+    readonly deniedIds: readonly string[];
+    readonly visibleIds: readonly string[];
+    readonly totalNodeCount: number;
+    readonly virtualStart: number;
+    readonly virtualEnd: number;
+    readonly currentValue: string;
+    readonly persistedValue: string;
+    readonly optionContracts: readonly CascaderOptionStateContract[];
+    readonly attrs: UiAttributes;
+}
+export type DateTimeFieldKind = 'date' | 'datetime' | 'time';
+export interface DateTimeFieldPlanOptions {
+    readonly id: string;
+    readonly kind: DateTimeFieldKind;
+    readonly value?: string;
+    readonly name?: string;
+    readonly min?: string;
+    readonly max?: string;
+    readonly step?: number;
+    readonly disabled?: boolean;
+    readonly readonly?: boolean;
+    readonly required?: boolean;
+    readonly invalid?: boolean;
+    readonly labelId?: string;
+    readonly describedBy?: string;
+    readonly placeholder?: string;
+    readonly density?: UiDensity;
+    readonly size?: UiControlSize;
+    readonly className?: string;
+    readonly attrs?: UiAttributes;
+}
+export interface DateTimeFieldPlans {
+    readonly root: UiDomPlan<'div'>;
+    readonly input: UiDomPlan<'input'>;
+}
+export type UploadFileState = 'done' | 'error' | 'pending' | 'uploading';
+export type UploadTransportState = 'complete' | 'disabled' | 'empty' | 'error' | 'partial' | 'pending' | 'retrying' | 'uploading';
+export interface UploadFileItem {
+    readonly id: string;
+    readonly name: string;
+    readonly size?: number;
+    readonly type?: string;
+    readonly state?: UploadFileState;
+    readonly message?: string;
+    readonly progress?: number;
+    readonly retryCount?: number;
+    readonly retryable?: boolean;
+    readonly serverError?: string;
+}
+export interface UploadCandidateFile {
+    readonly name: string;
+    readonly type?: string;
+}
+export interface UploadPlanOptions {
+    readonly id: string;
+    readonly files?: readonly UploadFileItem[];
+    readonly name?: string;
+    readonly accept?: string;
+    readonly multiple?: boolean;
+    readonly disabled?: boolean;
+    readonly required?: boolean;
+    readonly invalid?: boolean;
+    readonly dragActive?: boolean;
+    readonly label?: string;
+    readonly labelId?: string;
+    readonly describedBy?: string;
+    readonly className?: string;
+    readonly attrs?: UiAttributes;
+}
+export interface UploadPlans {
+    readonly root: UiDomPlan<'div'>;
+    readonly input: UiDomPlan<'input'>;
+    readonly dropzone: UiDomPlan<'label'>;
+    readonly fileList: UiDomPlan<'ul'>;
+    readonly files: readonly UiDomPlan<'li'>[];
+}
+export interface UploadTransportStateContractOptions {
+    readonly files?: readonly UploadFileItem[];
+    readonly disabled?: boolean;
+    readonly maxRetries?: number;
+    readonly retryingIds?: ReadonlySet<string> | readonly string[];
+    readonly serverErrors?: Readonly<Record<string, string | readonly string[] | undefined>>;
+}
+export interface UploadTransportFileContract {
+    readonly id: string;
+    readonly state: UploadFileState;
+    readonly progress: number;
+    readonly retryCount: number;
+    readonly retrying: boolean;
+    readonly retryable: boolean;
+    readonly canRetry: boolean;
+    readonly serverErrors: readonly string[];
+    readonly attrs: UiAttributes;
+}
+export interface UploadTransportStateContract {
+    readonly state: UploadTransportState;
+    readonly disabled: boolean;
+    readonly fileCount: number;
+    readonly pendingCount: number;
+    readonly uploadingCount: number;
+    readonly doneCount: number;
+    readonly errorCount: number;
+    readonly retryableCount: number;
+    readonly serverErrorCount: number;
+    readonly retryingIds: readonly string[];
+    readonly progress: number;
+    readonly files: readonly UploadTransportFileContract[];
+    readonly attrs: UiAttributes;
+}
+export declare function createComboboxPlans(options: ComboboxPlanOptions): ComboboxPlans;
+export declare function createUploadPlans(options: UploadPlanOptions): UploadPlans;
+export declare function createUploadTransportStateContract(options?: UploadTransportStateContractOptions): UploadTransportStateContract;
+export declare function createCascaderPlans(options: CascaderPlanOptions): CascaderPlans;
+export declare function createCascaderAdvancedStateContract(options: CascaderAdvancedStateContractOptions): CascaderAdvancedStateContract;
+export declare function createDateTimeFieldPlans(options: DateTimeFieldPlanOptions): DateTimeFieldPlans;
+export declare function formatDateInputValue(value: Date): string;
+export declare function formatTimeInputValue(value: Date, includeSeconds?: boolean): string;
+export declare function formatDateTimeInputValue(value: Date, includeSeconds?: boolean): string;
+export declare function parseDateInputValue(value: string): Date | undefined;
+export declare function parseTimeInputValue(value: string): Date | undefined;
+export declare function parseDateTimeInputValue(value: string): Date | undefined;
+export declare function clampDateTimeInputValue(value: string, min: string | undefined, max: string | undefined): string;
+export declare function formatUploadFileSize(bytes: number): string;
+export declare function isUploadFileAccepted(file: UploadCandidateFile, accept: string | undefined): boolean;
+export declare function filterAutocompleteOptions(options: readonly ComboboxOption[], query: string, limit?: number): readonly ComboboxOption[];
+export declare function getNextComboboxOptionId(options: readonly ComboboxOption[], activeId: string | undefined, key: string): string | undefined;
+export declare function getCascaderColumns(options: readonly CascaderOption[], activePath?: readonly string[]): readonly (readonly CascaderOption[])[];
+export declare function findCascaderPathByValue(options: readonly CascaderOption[], value: string | undefined): readonly CascaderOption[];
+export declare function findCascaderPathById(options: readonly CascaderOption[], id: string | undefined): readonly CascaderOption[];
+export declare function getNextCascaderOptionId(options: readonly CascaderOption[], activeId: string | undefined, key: string): string | undefined;
+export declare function shouldOpenCascaderForKey(key: string): boolean;
+export declare function shouldSelectCascaderOption(key: string): boolean;
+export declare function shouldCloseCascaderForKey(key: string): boolean;
+export declare function shouldOpenComboboxForKey(key: string): boolean;
+export declare function shouldSelectComboboxOption(key: string): boolean;
+export declare function shouldCloseComboboxForKey(key: string): boolean;
+/**
+ * Color Picker plans — native color input + swatch preview + value text.
+ * Spec source: common enterprise-backend component set (no UIStyle spec, this is an out-of-spec component).
+ */
+export interface ColorPickerPlans {
+    readonly root: UiDomPlan<'div'>;
+    readonly input: UiDomPlan<'input'>;
+    readonly preview: UiDomPlan<'span'>;
+    readonly value: UiDomPlan<'span'>;
+}
+export interface ColorPickerPlanOptions {
+    readonly id: string;
+    /** Current color value (#rrggbb). */
+    readonly value?: string;
+    readonly disabled?: boolean;
+    readonly className?: string;
+    readonly attrs?: UiAttributes;
+}
+export declare function createColorPickerPlans(options: ColorPickerPlanOptions): ColorPickerPlans;
+/**
+ * Transfer plans — source list / direction actions / target list.
+ * Spec source: common enterprise-backend component set (permission/allocation scenarios; no UIStyle spec, this is an out-of-spec component).
+ */
+export interface TransferPlans {
+    readonly root: UiDomPlan<'div'>;
+    readonly source: UiDomPlan<'div'>;
+    readonly sourceList: UiDomPlan<'ul'>;
+    readonly actions: UiDomPlan<'div'>;
+    readonly toRight: UiDomPlan<'button'>;
+    readonly toLeft: UiDomPlan<'button'>;
+    readonly target: UiDomPlan<'div'>;
+    readonly targetList: UiDomPlan<'ul'>;
+}
+export interface TransferPlanOptions {
+    readonly id: string;
+    readonly className?: string;
+    readonly attrs?: UiAttributes;
+}
+export declare function createTransferPlans(options: TransferPlanOptions): TransferPlans;
+/**
+ * Mask Input plans — a text field constrained by a format placeholder (phone/date/amount/custom).
+ * Spec source: user-defined requirement (high-frequency formatted input in enterprise backends).
+ * Mask semantics: # = digit placeholder, other characters = literal separators (e.g. '###-####' with input 1381234 → 138-1234).
+ */
+export type MaskInputKind = 'amount' | 'custom' | 'date' | 'phone';
+export interface MaskInputPlans {
+    readonly root: UiDomPlan<'div'>;
+    readonly input: UiDomPlan<'input'>;
+}
+export interface MaskInputPlanOptions {
+    readonly id: string;
+    /** Mask kind (phone/date/amount have built-in formats; custom uses the mask option). */
+    readonly kind?: MaskInputKind;
+    /** Custom mask: '###-####' style. */
+    readonly mask?: string;
+    readonly value?: string;
+    readonly placeholder?: string;
+    readonly disabled?: boolean;
+    readonly readonly?: boolean;
+    readonly invalid?: boolean;
+    readonly className?: string;
+    readonly attrs?: UiAttributes;
+}
+export declare function resolveMaskInputMask(kind: MaskInputKind | undefined, mask: string | undefined): string;
+export declare function createMaskInputPlans(options: MaskInputPlanOptions): MaskInputPlans;