@sakoa/ui 0.1.0

package/dist/composables/useDebounce.d.ts

@@ -0,0 +1,150 @@
+import { Ref, MaybeRef } from 'vue';
+export interface DebounceOptions {
+    /** Execute immediately on first call, then debounce subsequent calls */
+    immediate?: boolean;
+    /** Maximum time to wait before forcing execution */
+    maxWait?: number;
+}
+export interface ThrottleOptions {
+    /** Execute on the leading edge */
+    leading?: boolean;
+    /** Execute on the trailing edge */
+    trailing?: boolean;
+}
+export interface DebouncedFn<T extends (...args: any[]) => any> {
+    /** The debounced function */
+    (...args: Parameters<T>): void;
+    /** Cancel any pending execution */
+    cancel: () => void;
+    /** Immediately execute any pending call */
+    flush: () => void;
+    /** Whether there's a pending execution */
+    isPending: () => boolean;
+}
+export interface ThrottledFn<T extends (...args: any[]) => any> {
+    /** The throttled function */
+    (...args: Parameters<T>): void;
+    /** Cancel any pending execution */
+    cancel: () => void;
+    /** Whether there's a pending execution */
+    isPending: () => boolean;
+}
+export interface UseDebounceReturn<T> {
+    /** The debounced value */
+    value: Ref<T>;
+    /** Cancel any pending update */
+    cancel: () => void;
+    /** Immediately apply pending value */
+    flush: () => void;
+    /** Whether there's a pending update */
+    isPending: Ref<boolean>;
+}
+export interface UseThrottleReturn<T> {
+    /** The throttled value */
+    value: Ref<T>;
+    /** Cancel any pending update */
+    cancel: () => void;
+    /** Whether there's a pending update */
+    isPending: Ref<boolean>;
+}
+/**
+ * Debounce a value - the returned value updates after the specified delay
+ * when the source value stops changing.
+ *
+ * @example
+ * // Basic usage
+ * const searchTerm = ref('')
+ * const debouncedSearch = useDebounce(searchTerm, 300)
+ *
+ * // Use debouncedSearch.value for API calls
+ * watch(debouncedSearch.value, (value) => {
+ *   fetchResults(value)
+ * })
+ *
+ * @example
+ * // With max wait
+ * const { value, cancel, flush } = useDebounce(inputValue, 500, { maxWait: 2000 })
+ */
+export declare function useDebounce<T>(value: MaybeRef<T>, delay?: MaybeRef<number>, options?: DebounceOptions): UseDebounceReturn<T>;
+/**
+ * Create a debounced function that delays invoking until after the specified
+ * milliseconds have elapsed since the last call.
+ *
+ * @example
+ * // Basic usage
+ * const debouncedSearch = useDebounceFn(() => {
+ *   console.log('Searching...')
+ * }, 300)
+ *
+ * // Call it multiple times - only executes once after 300ms of inactivity
+ * debouncedSearch()
+ * debouncedSearch()
+ * debouncedSearch()
+ *
+ * @example
+ * // With immediate option
+ * const debouncedSave = useDebounceFn(
+ *   (data) => saveData(data),
+ *   1000,
+ *   { immediate: true }
+ * )
+ *
+ * @example
+ * // With max wait
+ * const debouncedResize = useDebounceFn(
+ *   () => recalculateLayout(),
+ *   200,
+ *   { maxWait: 1000 }
+ * )
+ */
+export declare function useDebounceFn<T extends (...args: any[]) => any>(fn: T, delay?: MaybeRef<number>, options?: DebounceOptions): DebouncedFn<T>;
+/**
+ * Throttle a value - the returned value updates at most once per specified interval.
+ *
+ * @example
+ * // Basic usage
+ * const scrollY = ref(0)
+ * const throttledScroll = useThrottle(scrollY, 100)
+ *
+ * // Updates at most every 100ms
+ * window.addEventListener('scroll', () => {
+ *   scrollY.value = window.scrollY
+ * })
+ *
+ * @example
+ * // With options
+ * const { value } = useThrottle(mousePosition, 50, {
+ *   leading: true,
+ *   trailing: false
+ * })
+ */
+export declare function useThrottle<T>(value: MaybeRef<T>, delay?: MaybeRef<number>, options?: ThrottleOptions): UseThrottleReturn<T>;
+/**
+ * Create a throttled function that only invokes at most once per specified interval.
+ *
+ * @example
+ * // Basic usage
+ * const throttledScroll = useThrottleFn(() => {
+ *   console.log('Scrolled!')
+ * }, 100)
+ *
+ * window.addEventListener('scroll', throttledScroll)
+ *
+ * @example
+ * // Leading only (execute immediately, then wait)
+ * const throttledClick = useThrottleFn(
+ *   () => handleClick(),
+ *   1000,
+ *   { leading: true, trailing: false }
+ * )
+ *
+ * @example
+ * // Trailing only (wait, then execute)
+ * const throttledResize = useThrottleFn(
+ *   () => recalculate(),
+ *   200,
+ *   { leading: false, trailing: true }
+ * )
+ */
+export declare function useThrottleFn<T extends (...args: any[]) => any>(fn: T, delay?: MaybeRef<number>, options?: ThrottleOptions): ThrottledFn<T>;
+export default useDebounce;

package/dist/composables/useDialog.d.ts

@@ -0,0 +1,118 @@
+import { Component } from 'vue';
+export type DialogVariant = 'default' | 'danger' | 'warning' | 'success' | 'info';
+export interface ConfirmOptions {
+    /** Dialog title */
+    title: string;
+    /** Dialog description/message */
+    description?: string;
+    /** Confirm button text */
+    confirmText?: string;
+    /** Cancel button text */
+    cancelText?: string;
+    /** Dialog variant (affects confirm button style) */
+    variant?: DialogVariant;
+    /** Icon name */
+    icon?: string | boolean;
+    /** Close on backdrop click */
+    closeOnBackdrop?: boolean;
+    /** Close on escape key */
+    closeOnEscape?: boolean;
+}
+export interface PromptOptions extends ConfirmOptions {
+    /** Input placeholder */
+    placeholder?: string;
+    /** Default input value */
+    defaultValue?: string;
+    /** Whether input is required */
+    required?: boolean;
+    /** Input type */
+    inputType?: 'text' | 'password' | 'email' | 'number' | 'textarea';
+    /** Minimum length for input */
+    minLength?: number;
+    /** Maximum length for input */
+    maxLength?: number;
+    /** Custom validation function */
+    validate?: (value: string) => string | true;
+}
+export interface AlertOptions extends Omit<ConfirmOptions, 'cancelText'> {
+    /** Button text */
+    buttonText?: string;
+}
+export interface CustomDialogOptions<T = unknown> {
+    /** Dialog title (optional for custom component) */
+    title?: string;
+    /** Custom component to render */
+    component: Component;
+    /** Props to pass to the component */
+    props?: Record<string, unknown>;
+    /** Close on backdrop click */
+    closeOnBackdrop?: boolean;
+    /** Close on escape key */
+    closeOnEscape?: boolean;
+    /** Modal size */
+    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+}
+export interface DialogInstance {
+    /** Unique dialog ID */
+    id: string;
+    /** Dialog type */
+    type: 'confirm' | 'prompt' | 'alert' | 'custom';
+    /** Whether dialog is open */
+    isOpen: boolean;
+    /** Resolve function */
+    resolve: (value: unknown) => void;
+    /** Reject function */
+    reject: (reason?: unknown) => void;
+}
+/**
+ * Dialog composable for programmatic dialogs
+ *
+ * @example
+ * const dialog = useDialog()
+ *
+ * // Confirm dialog
+ * const confirmed = await dialog.confirm({
+ *   title: 'Delete Item',
+ *   description: 'Are you sure?',
+ *   variant: 'danger'
+ * })
+ *
+ * // Prompt dialog
+ * const name = await dialog.prompt({
+ *   title: 'Enter Name',
+ *   placeholder: 'John Doe'
+ * })
+ *
+ * // Alert dialog
+ * await dialog.alert({
+ *   title: 'Success',
+ *   description: 'Operation completed!'
+ * })
+ */
+export declare function useDialog(): {
+    confirm: (options: ConfirmOptions) => Promise<boolean>;
+    prompt: (options: PromptOptions) => Promise<string | null>;
+    alert: (options: AlertOptions) => Promise<void>;
+    custom: <T = unknown>(options: CustomDialogOptions<T>) => Promise<T | null>;
+    closeAll: () => void;
+    dialogs: Readonly<import('vue').Ref<readonly {
+        readonly id: string;
+        readonly type: "confirm" | "prompt" | "alert" | "custom";
+        readonly isOpen: boolean;
+        readonly resolve: (value: unknown) => void;
+        readonly reject: (reason?: unknown) => void;
+    }[], readonly {
+        readonly id: string;
+        readonly type: "confirm" | "prompt" | "alert" | "custom";
+        readonly isOpen: boolean;
+        readonly resolve: (value: unknown) => void;
+        readonly reject: (reason?: unknown) => void;
+    }[]>>;
+};
+/** Shorthand for confirm dialog */
+export declare function confirm(options: ConfirmOptions | string): Promise<boolean>;
+/** Shorthand for prompt dialog */
+export declare function prompt(options: PromptOptions | string): Promise<string | null>;
+/** Shorthand for alert dialog */
+export declare function alertDialog(options: AlertOptions | string): Promise<void>;
+export default useDialog;

package/dist/composables/useForm.d.ts

@@ -0,0 +1,204 @@
+import { Ref, ComputedRef, WatchStopHandle } from 'vue';
+export type ValidationRule<T = unknown> = (value: T, formData?: Record<string, unknown>) => string | true;
+export type AsyncValidationRule<T = unknown> = (value: T, formData?: Record<string, unknown>) => Promise<string | true>;
+export interface FieldConfig<T = unknown> {
+    rules?: (ValidationRule<T> | AsyncValidationRule<T>)[];
+    validateOn?: 'input' | 'blur' | 'submit';
+    /** Debounce delay in ms for async validations (default: 300) */
+    debounce?: number;
+    /** Field dependencies - revalidate this field when these fields change */
+    deps?: string[];
+    /** Whether to persist this field (default: true). Set to false to exclude from persistence */
+    persist?: boolean;
+}
+export interface FieldState<T = unknown> {
+    value: Ref<T>;
+    error: Ref<string>;
+    touched: Ref<boolean>;
+    dirty: Ref<boolean>;
+    valid: ComputedRef<boolean>;
+    validate: () => Promise<boolean>;
+    reset: () => void;
+}
+/** Mapped type for type-safe field access */
+export type TypedFields<TValues extends Record<string, unknown>> = {
+    [K in keyof TValues]: FieldState<TValues[K]>;
+};
+/** Persistence options for form state */
+export interface PersistOptions {
+    /** Storage key for the form data */
+    key: string;
+    /** Storage type: 'localStorage' or 'sessionStorage' (default: 'localStorage') */
+    storage?: 'localStorage' | 'sessionStorage';
+    /** Debounce delay for saving in ms (default: 500) */
+    debounce?: number;
+}
+/** Zod-like schema interface for type inference */
+export interface ZodLikeSchema<T = unknown> {
+    safeParse: (data: unknown) => {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            errors: Array<{
+                path: (string | number)[];
+                message: string;
+            }>;
+        };
+    };
+    shape?: Record<string, unknown>;
+}
+/** Form state returned by useForm composable */
+export interface FormState<TValues extends Record<string, unknown> = Record<string, unknown>> {
+    /** Type-safe field access */
+    fields: TypedFields<TValues>;
+    errors: ComputedRef<Record<string, string>>;
+    valid: ComputedRef<boolean>;
+    dirty: ComputedRef<boolean>;
+    touched: ComputedRef<boolean>;
+    validate: () => Promise<boolean>;
+    reset: (values?: Partial<TValues>) => void;
+    getValues: () => TValues;
+    isSubmitting: Ref<boolean>;
+    submitError: Ref<string | null>;
+    submitCount: Ref<number>;
+    isSubmitSuccessful: Ref<boolean>;
+    setValue: <K extends keyof TValues>(name: K, value: TValues[K]) => void;
+    setValues: (values: Partial<TValues>) => void;
+    getFieldValue: <K extends keyof TValues>(name: K) => TValues[K];
+    setError: (name: keyof TValues, error: string) => void;
+    clearError: (name: keyof TValues) => void;
+    clearErrors: () => void;
+    resetField: (name: keyof TValues) => void;
+    setFieldTouched: (name: keyof TValues, touched?: boolean) => void;
+    setFieldDirty: (name: keyof TValues, dirty?: boolean) => void;
+    handleSubmit: <TResult = void>(onSubmit: (values: TValues) => Promise<TResult> | TResult, onError?: (error: unknown) => void) => () => Promise<TResult | undefined>;
+    watchForm: (callback: (values: TValues) => void) => WatchStopHandle;
+    watchField: <K extends keyof TValues>(name: K, callback: (value: TValues[K], oldValue: TValues[K]) => void) => WatchStopHandle;
+    clearPersisted: () => void;
+}
+/** Options for useForm composable */
+export interface UseFormOptions<TValues extends Record<string, unknown> = Record<string, unknown>> {
+    /** Initial values for form fields */
+    initialValues?: Partial<TValues>;
+    /** Field configurations with validation rules */
+    fields?: {
+        [K in keyof TValues]?: FieldConfig<TValues[K]>;
+    };
+    /** Zod schema for validation (alternative to fields.rules) */
+    schema?: ZodLikeSchema<TValues>;
+    /** Global debounce delay for async validations (default: 300ms) */
+    debounceDelay?: number;
+    /** Validation mode: 'onChange' | 'onBlur' | 'onSubmit' | 'all' (default: 'onChange') */
+    mode?: 'onChange' | 'onBlur' | 'onSubmit' | 'all';
+    /** Persistence options for auto-saving form state */
+    persist?: PersistOptions;
+}
+/** Required field validator */
+export declare const required: (msg?: string) => ValidationRule;
+/** Minimum length validator */
+export declare const minLength: (min: number, msg?: string) => ValidationRule;
+/** Maximum length validator */
+export declare const maxLength: (max: number, msg?: string) => ValidationRule;
+/** Minimum value validator (for numbers) */
+export declare const min: (minVal: number, msg?: string) => ValidationRule;
+/** Maximum value validator (for numbers) */
+export declare const max: (maxVal: number, msg?: string) => ValidationRule;
+/** Email format validator */
+export declare const email: (msg?: string) => ValidationRule;
+/** URL format validator */
+export declare const url: (msg?: string) => ValidationRule;
+/** Regex pattern validator */
+export declare const pattern: (regex: RegExp, msg?: string) => ValidationRule;
+/** Match another field validator */
+export declare const sameAs: (fieldName: string, msg?: string) => ValidationRule;
+/** Contain uppercase letter */
+export declare const hasUppercase: (msg?: string) => ValidationRule;
+/** Contain lowercase letter */
+export declare const hasLowercase: (msg?: string) => ValidationRule;
+/** Contain digit */
+export declare const hasDigit: (msg?: string) => ValidationRule;
+/** Contain special character */
+export declare const hasSpecial: (msg?: string) => ValidationRule;
+/** Alphanumeric only */
+export declare const alphanumeric: (msg?: string) => ValidationRule;
+/** Numeric only */
+export declare const numeric: (msg?: string) => ValidationRule;
+/**
+ * Create a custom validator from a boolean function
+ * @example custom((v) => v.length > 5, 'Too short')
+ * @example custom(async (v) => await checkUsername(v), 'Username taken')
+ */
+export declare const custom: (fn: (value: unknown, formData?: Record<string, unknown>) => boolean | Promise<boolean>, msg?: string) => ValidationRule | AsyncValidationRule;
+/** Password strength levels */
+export declare enum PasswordStrength {
+    /** 6+ chars */
+    WEAK = "weak",
+    /** 8+ chars, 1 uppercase, 1 number */
+    MEDIUM = "medium",
+    /** 10+ chars, 1 uppercase, 1 lowercase, 1 number, 1 special */
+    STRONG = "strong",
+    /** 12+ chars, 2 uppercase, 2 lowercase, 2 numbers, 1 special */
+    VERY_STRONG = "very_strong"
+}
+/** Password strength validator with configurable levels */
+export declare const passwordStrength: (strength?: PasswordStrength, msg?: string) => ValidationRule;
+/** Check if value is different from another field */
+export declare const different: (fieldName: string, msg?: string) => ValidationRule;
+/** Check if value is in a list of allowed values */
+export declare const oneOf: <T>(allowed: T[], msg?: string) => ValidationRule;
+/** Check if value is NOT in a list of disallowed values */
+export declare const notOneOf: <T>(disallowed: T[], msg?: string) => ValidationRule;
+/**
+ * Comprehensive form management composable with validation, submission handling,
+ * and reactive state management.
+ *
+ * @example
+ * const form = useForm({
+ *   initialValues: { email: '', password: '' },
+ *   fields: {
+ *     email: { rules: [required(), email()] },
+ *     password: { rules: [required(), minLength(8)] }
+ *   }
+ * })
+ *
+ * // With Zod schema
+ * const form = useForm({
+ *   schema: z.object({
+ *     email: z.string().email(),
+ *     password: z.string().min(8)
+ *   })
+ * })
+ *
+ * const onSubmit = form.handleSubmit(async (values) => {
+ *   await api.login(values)
+ * })
+ */
+export declare function useForm<TValues extends Record<string, unknown> = Record<string, unknown>>(options: UseFormOptions<TValues>): FormState<TValues>;
+export interface SimpleFieldBinding {
+    modelValue: unknown;
+    error: string;
+    'onUpdate:modelValue': (value: unknown) => void;
+    onBlur: () => void;
+}
+/** Create bindings for a field to use with v-bind on SInput */
+export declare function createFieldBindings(field: FieldState): SimpleFieldBinding;
+/**
+ * Helper to get field bindings for use with FormField scoped slots
+ * Returns reactive bindings that automatically sync with form validation
+ */
+export declare function useFormFieldBindings(field: FieldState | null): {
+    modelValue: ComputedRef<undefined>;
+    error: ComputedRef<string>;
+    'onUpdate:modelValue': () => void;
+    onBlur: () => void;
+    onInput: () => void;
+} | {
+    modelValue: Ref<unknown, unknown>;
+    error: Ref<string, string>;
+    'onUpdate:modelValue': (value: unknown) => void;
+    onBlur: () => void;
+    onInput: () => void;
+};
+export default useForm;

package/dist/composables/useHotkey.d.ts

@@ -0,0 +1,128 @@
+import { MaybeRef, Ref } from 'vue';
+export type ModifierKey = 'ctrl' | 'alt' | 'shift' | 'meta';
+export type KeyCombo = string;
+export interface HotkeyOptions {
+    /** Target element to attach the listener to (default: window) */
+    target?: MaybeRef<HTMLElement | Window | Document | null>;
+    /** Prevent default browser behavior */
+    preventDefault?: boolean;
+    /** Stop event propagation */
+    stopPropagation?: boolean;
+    /** Whether the hotkey is enabled */
+    enabled?: MaybeRef<boolean>;
+    /** Event to listen for */
+    event?: 'keydown' | 'keyup';
+    /** Only trigger when focused on specific element types */
+    scope?: 'global' | 'input' | 'non-input';
+    /** Whether to use capture phase */
+    capture?: boolean;
+    /** Repeat while key is held down */
+    repeat?: boolean;
+}
+export interface HotkeyHandler {
+    (event: KeyboardEvent): void;
+}
+export interface UseHotkeyReturn {
+    /** Stop listening for the hotkey */
+    stop: () => void;
+    /** Start listening for the hotkey */
+    start: () => void;
+    /** Whether the listener is currently active */
+    isActive: boolean;
+}
+export interface ParsedHotkey {
+    key: string;
+    ctrl: boolean;
+    alt: boolean;
+    shift: boolean;
+    meta: boolean;
+}
+/**
+ * Register a keyboard hotkey handler.
+ *
+ * @example
+ * // Basic usage
+ * useHotkey('ctrl+k', () => {
+ *   openCommandPalette()
+ * })
+ *
+ * @example
+ * // With options
+ * useHotkey('ctrl+s', () => {
+ *   saveDocument()
+ * }, {
+ *   preventDefault: true,
+ *   stopPropagation: true
+ * })
+ *
+ * @example
+ * // Multiple modifiers
+ * useHotkey('ctrl+shift+s', () => {
+ *   saveAsDocument()
+ * })
+ *
+ * @example
+ * // Scoped to element
+ * const editorRef = ref<HTMLElement>()
+ *
+ * useHotkey('escape', () => {
+ *   closeEditor()
+ * }, {
+ *   target: editorRef
+ * })
+ *
+ * @example
+ * // Only when not in input
+ * useHotkey('/', () => {
+ *   focusSearch()
+ * }, {
+ *   scope: 'non-input'
+ * })
+ *
+ * @example
+ * // Mac-style command key
+ * useHotkey('meta+c', () => {
+ *   copy()
+ * })
+ * // Or use 'cmd' alias
+ * useHotkey('cmd+v', () => {
+ *   paste()
+ * })
+ */
+export declare function useHotkey(combo: KeyCombo, handler: HotkeyHandler, options?: HotkeyOptions): UseHotkeyReturn;
+/**
+ * Register multiple hotkeys at once.
+ *
+ * @example
+ * useHotkeys({
+ *   'ctrl+s': () => save(),
+ *   'ctrl+z': () => undo(),
+ *   'ctrl+shift+z': () => redo(),
+ *   'escape': () => close()
+ * }, {
+ *   preventDefault: true
+ * })
+ */
+export declare function useHotkeys(bindings: Record<KeyCombo, HotkeyHandler>, options?: HotkeyOptions): UseHotkeyReturn;
+/**
+ * Create a hotkey handler that can be used with v-on.
+ *
+ * @example
+ * const onKeyDown = createHotkeyHandler({
+ *   'enter': () => submit(),
+ *   'escape': () => cancel()
+ * })
+ *
+ * // Use in template: @keydown="onKeyDown"
+ */
+export declare function createHotkeyHandler(bindings: Record<KeyCombo, HotkeyHandler>, options?: Omit<HotkeyOptions, 'target' | 'enabled'>): (event: KeyboardEvent) => void;
+/**
+ * Check if a hotkey combo is currently pressed.
+ * Useful for detecting held keys.
+ *
+ * @example
+ * const isCtrlPressed = useKeyPressed('ctrl')
+ * const isShiftCtrlK = useKeyPressed('ctrl+shift+k')
+ */
+export declare function useKeyPressed(combo: KeyCombo): Ref<boolean>;
+export default useHotkey;