dalila 1.5.13 → 1.7.0

package/dist/components/ui/ui-types.d.ts

@@ -0,0 +1,175 @@
+import type { Signal } from "../../core/signal.js";
+export interface DialogOptions {
+    closeOnBackdrop?: boolean;
+    closeOnEscape?: boolean;
+}
+export interface Dialog {
+    open: Signal<boolean>;
+    show(): void;
+    close(): void;
+    toggle(): void;
+    _attachTo(el: HTMLDialogElement): void;
+}
+export type DrawerSide = "right" | "left" | "bottom";
+export interface DrawerOptions extends DialogOptions {
+    side?: DrawerSide;
+}
+export interface Drawer extends Dialog {
+    side: Signal<DrawerSide>;
+}
+export type ToastVariant = "success" | "error" | "warning" | "info";
+export type ToastPosition = "top-right" | "top-left" | "bottom-right" | "bottom-left" | "top-center" | "bottom-center";
+export interface ToastItem {
+    id: string;
+    variant: ToastVariant;
+    title: string;
+    text?: string;
+    variantClass: string;
+    icon: string;
+}
+export interface ToastOptions {
+    position?: ToastPosition;
+    duration?: number;
+    maxToasts?: number;
+}
+export interface Toast {
+    items: Signal<ToastItem[]>;
+    activeVariant: Signal<ToastVariant | "idle">;
+    containerClass: Signal<string>;
+    show(variant: ToastVariant, title: string, text?: string, duration?: number): string;
+    success(title: string, text?: string): string;
+    error(title: string, text?: string): string;
+    warning(title: string, text?: string): string;
+    info(title: string, text?: string): string;
+    dismiss(id: string): void;
+    clear(): void;
+}
+export interface TabsOptions {
+    initial?: string;
+    orientation?: "horizontal" | "vertical";
+}
+export interface Tabs {
+    active: Signal<string>;
+    select(tabId: string): void;
+    isActive(tabId: string): boolean;
+    handleClick(ev: Event): void;
+    _attachTo(el: HTMLElement): void;
+}
+export interface TabBindings {
+    tabClass: Signal<string>;
+    selected: Signal<string>;
+    visible: Signal<boolean>;
+}
+export interface DropdownOptions {
+    closeOnSelect?: boolean;
+}
+export interface Dropdown {
+    open: Signal<boolean>;
+    toggle(ev?: Event): void;
+    close(): void;
+    select(ev?: Event): void;
+    _attachTo(el: HTMLElement): void;
+}
+export interface ComboboxOption {
+    value: string;
+    label: string;
+}
+export interface ComboboxOptions {
+    options: ComboboxOption[];
+    placeholder?: string;
+    name?: string;
+}
+export interface Combobox {
+    open: Signal<boolean>;
+    query: Signal<string>;
+    value: Signal<string>;
+    label: Signal<string>;
+    filtered: Signal<ComboboxOption[]>;
+    highlightedIndex: Signal<number>;
+    show(): void;
+    close(): void;
+    toggle(): void;
+    handleInput(ev: Event): void;
+    handleSelect(ev: Event): void;
+    handleKeydown(ev: KeyboardEvent): void;
+    _attachTo(el: HTMLElement): void;
+}
+export interface AccordionOptions {
+    single?: boolean;
+    initial?: string[];
+}
+export interface Accordion {
+    openItems: Signal<Set<string>>;
+    toggle(itemId: string): void;
+    open(itemId: string): void;
+    close(itemId: string): void;
+    isOpen(itemId: string): Signal<boolean>;
+    _attachTo(el: HTMLElement): void;
+}
+export interface CalendarDay {
+    date: number;
+    month: "prev" | "current" | "next";
+    fullDate: Date;
+    isToday: boolean;
+    isSelected: boolean;
+    disabled: boolean;
+}
+export interface CalendarOptions {
+    initial?: Date;
+    min?: Date;
+    max?: Date;
+    dayLabels?: string[];
+    monthLabels?: string[];
+}
+export interface Calendar {
+    year: Signal<number>;
+    month: Signal<number>;
+    selected: Signal<Date | null>;
+    title: Signal<string>;
+    days: Signal<CalendarDay[]>;
+    dayLabels: string[];
+    prev(): void;
+    next(): void;
+    select(date: Date): void;
+    handleDayClick(ev: Event): void;
+}
+export interface DropzoneOptions {
+    accept?: string;
+    multiple?: boolean;
+    maxFiles?: number;
+    maxSize?: number;
+}
+export interface Dropzone {
+    dragging: Signal<boolean>;
+    files: Signal<File[]>;
+    browse(): void;
+    handleClick(): void;
+    handleDragover(ev: DragEvent): void;
+    handleDragleave(): void;
+    handleDrop(ev: DragEvent): void;
+    _attachTo(el: HTMLElement): void;
+}
+export type PopoverPlacement = "top" | "bottom" | "left" | "right" | "top-start" | "bottom-start";
+export interface PopoverOptions {
+    placement?: PopoverPlacement;
+    gap?: number;
+    viewportPadding?: number;
+}
+export interface Popover {
+    open: Signal<boolean>;
+    placement: Signal<PopoverPlacement>;
+    show(): void;
+    hide(): void;
+    toggle(): void;
+    position(trigger: HTMLElement, popoverEl: HTMLElement): void;
+    _attachTo(trigger: HTMLElement, popoverEl: HTMLElement): void;
+}
+export interface TabsMount {
+    api: Tabs;
+    bindings: [string, string][];
+}
+export interface PopoverMount {
+    api: Popover;
+    triggerId?: string;
+    panelId?: string;
+}

package/dist/components/ui/ui-types.js

@@ -0,0 +1 @@
+export {};

package/dist/components/ui/validate.d.ts

@@ -0,0 +1,7 @@
+export declare function validateDialogOptions(opts: Record<string, unknown>): void;
+export declare function validateDrawerOptions(opts: Record<string, unknown>): void;
+export declare function validateToastOptions(opts: Record<string, unknown>): void;
+export declare function validatePopoverOptions(opts: Record<string, unknown>): void;
+export declare function validateDropzoneOptions(opts: Record<string, unknown>): void;
+export declare function validateCalendarOptions(opts: Record<string, unknown>): void;
+export declare function validateComboboxOptions(opts: Record<string, unknown>): void;

package/dist/components/ui/validate.js

@@ -0,0 +1,71 @@
+// ── Prop Validation ─────────────────────────────────────────────────
+const VALID_TOAST_POSITIONS = new Set([
+    "top-right", "top-left", "bottom-right", "bottom-left", "top-center", "bottom-center",
+]);
+const VALID_POPOVER_PLACEMENTS = new Set([
+    "top", "bottom", "left", "right", "top-start", "bottom-start",
+]);
+const VALID_DRAWER_SIDES = new Set(["right", "left", "bottom"]);
+function warn(component, message) {
+    console.warn(`[Dalila] ${component}: ${message}`);
+}
+function warnInvalidType(component, prop, expected, got) {
+    warn(component, `"${prop}" expected ${expected}, got ${typeof got} (${String(got)})`);
+}
+export function validateDialogOptions(opts) {
+    if (opts.closeOnBackdrop !== undefined && typeof opts.closeOnBackdrop !== "boolean") {
+        warnInvalidType("createDialog", "closeOnBackdrop", "boolean", opts.closeOnBackdrop);
+    }
+    if (opts.closeOnEscape !== undefined && typeof opts.closeOnEscape !== "boolean") {
+        warnInvalidType("createDialog", "closeOnEscape", "boolean", opts.closeOnEscape);
+    }
+}
+export function validateDrawerOptions(opts) {
+    validateDialogOptions(opts);
+    if (opts.side !== undefined && !VALID_DRAWER_SIDES.has(opts.side)) {
+        warn("createDrawer", `"side" must be one of "right"|"left"|"bottom", got "${String(opts.side)}"`);
+    }
+}
+export function validateToastOptions(opts) {
+    if (opts.position !== undefined && !VALID_TOAST_POSITIONS.has(opts.position)) {
+        warn("createToast", `"position" must be a valid ToastPosition, got "${String(opts.position)}"`);
+    }
+    if (opts.duration !== undefined && (typeof opts.duration !== "number" || opts.duration < 0)) {
+        warn("createToast", `"duration" must be a number >= 0, got ${String(opts.duration)}`);
+    }
+    if (opts.maxToasts !== undefined && (typeof opts.maxToasts !== "number" || opts.maxToasts <= 0)) {
+        warn("createToast", `"maxToasts" must be a number > 0, got ${String(opts.maxToasts)}`);
+    }
+}
+export function validatePopoverOptions(opts) {
+    if (opts.placement !== undefined && !VALID_POPOVER_PLACEMENTS.has(opts.placement)) {
+        warn("createPopover", `"placement" must be a valid PopoverPlacement, got "${String(opts.placement)}"`);
+    }
+    if (opts.gap !== undefined && (typeof opts.gap !== "number" || opts.gap < 0)) {
+        warn("createPopover", `"gap" must be a number >= 0, got ${String(opts.gap)}`);
+    }
+    if (opts.viewportPadding !== undefined && (typeof opts.viewportPadding !== "number" || opts.viewportPadding < 0)) {
+        warn("createPopover", `"viewportPadding" must be a number >= 0, got ${String(opts.viewportPadding)}`);
+    }
+}
+export function validateDropzoneOptions(opts) {
+    if (opts.maxFiles !== undefined && (typeof opts.maxFiles !== "number" || opts.maxFiles <= 0)) {
+        warn("createDropzone", `"maxFiles" must be a number > 0, got ${String(opts.maxFiles)}`);
+    }
+    if (opts.maxSize !== undefined && (typeof opts.maxSize !== "number" || opts.maxSize <= 0)) {
+        warn("createDropzone", `"maxSize" must be a number > 0, got ${String(opts.maxSize)}`);
+    }
+}
+export function validateCalendarOptions(opts) {
+    const min = opts.min;
+    const max = opts.max;
+    if (min && max && min > max) {
+        warn("createCalendar", `"min" must be before "max"`);
+    }
+}
+export function validateComboboxOptions(opts) {
+    const options = opts.options;
+    if (!Array.isArray(options) || options.length === 0) {
+        warn("createCombobox", `"options" must be a non-empty array`);
+    }
+}

package/dist/form/form-types.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Type utilities for path-based access
+ */
+export type FieldErrors = Record<string, string>;
+export interface FormSubmitContext {
+    signal: AbortSignal;
+}
+export interface FormOptions<T> {
+    /**
+     * Default values for the form.
+     * Can be a static object, a function returning values, or a promise.
+     */
+    defaultValues?: Partial<T> | (() => Partial<T>) | (() => Promise<Partial<T>>);
+    /**
+     * Custom parser for FormData → T.
+     * If not provided, uses the built-in parser with dot/bracket notation.
+     */
+    parse?: (formEl: HTMLFormElement, fd: FormData) => T;
+    /**
+     * Client-side validation function.
+     * Returns { fieldErrors?, formError? } or just fieldErrors.
+     */
+    validate?: (data: T) => FieldErrors | {
+        fieldErrors?: FieldErrors;
+        formError?: string;
+    } | void;
+    /**
+     * When to run validation:
+     * - "submit" (default): only on submit
+     * - "blur": on field blur after first submit
+     * - "change": on every change after first submit
+     */
+    validateOn?: 'submit' | 'blur' | 'change';
+    /**
+     * Transform server errors into form errors.
+     * Useful for mapping backend error formats to field paths.
+     */
+    transformServerErrors?: (error: unknown) => {
+        fieldErrors?: FieldErrors;
+        formError?: string;
+    } | void;
+}
+export interface Form<T> {
+    /**
+     * Creates a submit handler that:
+     * - prevents default
+     * - collects FormData
+     * - parses to T
+     * - validates (if configured)
+     * - calls handler with data and AbortSignal
+     * - cancels previous submit if re-submitted
+     */
+    handleSubmit(handler: (data: T, ctx: FormSubmitContext) => Promise<unknown> | unknown): (ev: SubmitEvent) => void;
+    /**
+     * Reset form to initial/new defaults
+     */
+    reset(nextDefaults?: Partial<T>): void;
+    /**
+     * Set error for a specific field
+     */
+    setError(path: string, message: string): void;
+    /**
+     * Set form-level error
+     */
+    setFormError(message: string): void;
+    /**
+     * Clear errors (all or by prefix)
+     */
+    clearErrors(prefix?: string): void;
+    /**
+     * Get error message for a field
+     */
+    error(path: string): string | null;
+    /**
+     * Get form-level error
+     */
+    formError(): string | null;
+    /**
+     * Check if field has been touched
+     */
+    touched(path: string): boolean;
+    /**
+     * Check if field is dirty (value differs from default)
+     */
+    dirty(path: string): boolean;
+    /**
+     * Check if form is currently submitting
+     */
+    submitting(): boolean;
+    /**
+     * Get submit count
+     */
+    submitCount(): number;
+    /**
+     * Focus first error field (or specific field)
+     */
+    focus(path?: string): void;
+    /**
+     * Internal: register a field element
+     * @internal
+     */
+    _registerField(path: string, element: HTMLElement): () => void;
+    /**
+     * Internal: get form element
+     * @internal
+     */
+    _getFormElement(): HTMLFormElement | null;
+    /**
+     * Internal: set form element
+     * @internal
+     */
+    _setFormElement(form: HTMLFormElement): void;
+    /**
+     * Create or get a field array
+     */
+    fieldArray<TItem = unknown>(path: string): FieldArray<TItem>;
+}
+export interface FieldArrayItem<T = unknown> {
+    key: string;
+    value?: T;
+}
+export interface FieldArray<TItem = unknown> {
+    /**
+     * Get array of items with stable keys
+     */
+    fields(): FieldArrayItem<TItem>[];
+    /**
+     * Append item(s) to the end
+     */
+    append(value: TItem | TItem[]): void;
+    /**
+     * Remove item by key
+     */
+    remove(key: string): void;
+    /**
+     * Remove item by index
+     */
+    removeAt(index: number): void;
+    /**
+     * Insert item at index
+     */
+    insert(index: number, value: TItem): void;
+    /**
+     * Move item from one index to another
+     */
+    move(fromIndex: number, toIndex: number): void;
+    /**
+     * Swap two items by index
+     */
+    swap(indexA: number, indexB: number): void;
+    /**
+     * Replace entire array
+     */
+    replace(values: TItem[]): void;
+    /**
+     * Update a specific item by key
+     */
+    update(key: string, value: TItem): void;
+    /**
+     * Update a specific item by index
+     */
+    updateAt(index: number, value: TItem): void;
+    /**
+     * Clear all items
+     */
+    clear(): void;
+    /**
+     * Get current length
+     */
+    length(): number;
+    /**
+     * Internal: translate index-based path to key-based path
+     * @internal
+     */
+    _translatePath(path: string): string | null;
+    /**
+     * Internal: get current index for a key
+     * @internal
+     */
+    _getIndex(key: string): number;
+}

package/dist/form/form-types.js

@@ -0,0 +1,4 @@
+/**
+ * Type utilities for path-based access
+ */
+export {};

package/dist/form/form.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Dalila Forms - DOM-first reactive form management
+ *
+ * Design principles:
+ * - Values live in the DOM (uncontrolled by default)
+ * - Meta-state in memory (errors, touched, dirty, submitting)
+ * - Declarative HTML via directives
+ * - Scope-safe with automatic cleanup
+ * - Race-safe submits with AbortController
+ * - Field arrays with stable keys
+ */
+import type { Form, FormOptions } from './form-types.js';
+/**
+ * Symbol to mark handlers that have been wrapped by handleSubmit().
+ * Used by bindForm to avoid double-wrapping.
+ */
+export declare const WRAPPED_HANDLER: unique symbol;
+/**
+ * Parse FormData into a nested object structure.
+ *
+ * Supports:
+ * - Simple fields: "email" → { email: "..." }
+ * - Nested objects: "user.name" → { user: { name: "..." } }
+ * - Arrays: "phones[0].number" → { phones: [{ number: "..." }] }
+ * - Checkboxes: single = boolean, multiple = array of values
+ * - Select multiple: array of selected values
+ * - Radio: single value
+ * - Files: File object
+ *
+ * ## Checkbox Parsing Contract
+ *
+ * HTML FormData omits unchecked checkboxes entirely. To resolve this ambiguity,
+ * parseFormData() inspects the DOM to distinguish between "field missing" vs "checkbox unchecked".
+ *
+ * ### Single Checkbox (one input with unique name)
+ * When there is exactly ONE checkbox with a given name:
+ * - Checked (with or without value) → `true`
+ * - Unchecked → `false`
+ * - Value attribute is ignored (always returns boolean)
+ *
+ * Example:
+ * ```html
+ * <input type="checkbox" name="agree" />
+ * ```
+ * Result: `{ agree: false }` (unchecked) or `{ agree: true }` (checked)
+ *
+ * ### Multiple Checkboxes (same name, multiple inputs)
+ * When there are MULTIPLE checkboxes with the same name:
+ * - Result is ALWAYS an array
+ * - Some checked → `["value1", "value2"]`
+ * - None checked → `[]`
+ * - One checked → `["value1"]` (still an array!)
+ *
+ * Example:
+ * ```html
+ * <input type="checkbox" name="colors" value="red" checked />
+ * <input type="checkbox" name="colors" value="blue" />
+ * <input type="checkbox" name="colors" value="green" checked />
+ * ```
+ * Result: `{ colors: ["red", "green"] }`
+ *
+ * ### Edge Cases
+ * - Radio buttons: Unchecked radio → field absent (standard HTML behavior)
+ * - Select multiple: Always returns array (like multiple checkboxes)
+ *
+ * @param form - The form element to parse (used for DOM inspection)
+ * @param fd - FormData instance from the form
+ * @returns Parsed form data with nested structure
+ */
+export declare function parseFormData<T = unknown>(form: HTMLFormElement, fd: FormData): T;
+export declare function createForm<T = unknown>(options?: FormOptions<T>): Form<T>;