decantr 0.9.0

package/types/css.d.ts

@@ -0,0 +1,149 @@
+// Auto-generated by tools/dts-gen.js — do not edit manually
+declare module 'decantr/css' {
+  /**
+   * Compose atomic CSS class names. Injects styles on first use.
+   */
+  export function css(...classes: string[]): string;
+
+  /**
+   * Define a custom atomic CSS class.
+   */
+  export function define(name: string, declaration: string): void;
+
+  /**
+   * Get all generated CSS as a string.
+   */
+  export function extractCSS(): string;
+
+  /**
+   * Clear all injected styles.
+   */
+  export function reset(): void;
+
+  /**
+   * Sanitize a string for safe use in HTML attributes.
+   */
+  export function sanitize(str: string): string;
+
+  // ── Style API (visual personality) ──
+
+  /**
+   * Set the active visual style.
+   */
+  export function setStyle(id: string): void;
+
+  /**
+   * Get the active style ID.
+   */
+  export function getStyle(): string;
+
+  /**
+   * Get list of registered styles.
+   */
+  export function getStyleList(): Array<{ id: string; name: string }>;
+
+  interface StyleDefinition {
+    id: string;
+    name: string;
+    seed: Record<string, string>;
+    personality: Record<string, string>;
+    typography?: Record<string, string>;
+    overrides?: { light?: Record<string, string>; dark?: Record<string, string> };
+    components?: string;
+  }
+
+  /**
+   * Register a custom style.
+   */
+  export function registerStyle(style: StyleDefinition): void;
+
+  /**
+   * Merge a Map of plugin-provided styles into the registry.
+   * Used by the plugin system to wire addon styles without individual registerStyle calls.
+   */
+  export function mergePluginStyles(pluginStyles: Map<string, StyleDefinition>): void;
+
+  // ── Mode API (light/dark) ──
+
+  /**
+   * Set the color mode.
+   */
+  export function setMode(mode: 'light' | 'dark' | 'auto'): void;
+
+  /**
+   * Get the current mode setting.
+   */
+  export function getMode(): 'light' | 'dark' | 'auto';
+
+  /**
+   * Get the resolved mode (always 'light' or 'dark', never 'auto').
+   */
+  export function getResolvedMode(): 'light' | 'dark';
+
+  /**
+   * Register callback for resolved mode changes. Returns unsubscribe function.
+   */
+  export function onModeChange(fn: (mode: 'light' | 'dark') => void): () => void;
+
+  // ── Legacy / backward compat ──
+
+  /**
+   * Combines setStyle + setMode. Accepts legacy theme IDs.
+   */
+  export function setTheme(id: string, mode?: string): void;
+
+  /**
+   * Get the current theme object (backward compat).
+   */
+  export function getTheme(): Record<string, any>;
+
+  /**
+   * Get theme metadata.
+   */
+  export function getThemeMeta(): Record<string, any>;
+
+  /**
+   * Get list of available themes.
+   */
+  export function getThemeList(): Array<Record<string, any>>;
+
+  /**
+   * Register a theme (backward compat wrapper for registerStyle).
+   */
+  export function registerTheme(theme: Record<string, any>): void;
+
+  /**
+   * Get complete CSS for the active style's theme layer.
+   */
+  export function getActiveCSS(): string;
+
+  /**
+   * Reset to defaults (clean + light).
+   */
+  export function resetStyles(): void;
+
+  /**
+   * Enable/disable JS animations globally.
+   */
+  export function setAnimations(enabled: boolean): void;
+
+  /**
+   * Get a signal getter for the current animations-enabled state.
+   */
+  export function getAnimations(): () => boolean;
+
+  /** Responsive breakpoint widths. */
+  export const BREAKPOINTS: Record<string, number>;
+
+  /** Container query widths. */
+  export const CQ_WIDTHS: number[];
+
+  // ── Atom type hints ──
+  // Pseudo-class prefixes: _h: (hover), _f: (focus), _fv: (focus-visible), _a: (active), _fw: (focus-within)
+  // Ring utilities: _ring0, _ring1, _ring2, _ring4, _ringPrimary, _ringAccent, _ringBorder
+  // Transition shortcuts: _transColors, _transOpacity, _transTransform, _transShadow
+  // Text wrapping: _textBalance, _textPretty
+  // Prose: _prose (maps to d-prose class for nested typography)
+  // Divide: _divideY, _divideX (maps to d-divide-y, d-divide-x classes)
+  // Scroll: _scrollSmooth
+}

package/types/data.d.ts

@@ -0,0 +1,238 @@
+// Auto-generated by tools/dts-gen.js — do not edit manually
+declare module 'decantr/data' {
+  // ─── Query ────────────────────────────────────────────────
+
+  interface QueryOptions<T> {
+    staleTime?: number;
+    cacheTime?: number;
+    retry?: number;
+    refetchInterval?: number;
+    refetchOnWindowFocus?: boolean;
+    enabled?: () => boolean;
+    select?: (data: any) => T;
+    initialData?: T;
+    placeholderData?: T;
+  }
+
+  interface QueryResult<T> {
+    data: () => T | undefined;
+    status: () => 'idle' | 'loading' | 'success' | 'error';
+    error: () => Error | null;
+    isLoading: () => boolean;
+    isStale: () => boolean;
+    isFetching: () => boolean;
+    refetch: () => Promise<void>;
+    setData: (value: T) => void;
+  }
+
+  export function createQuery<T>(
+    key: string | (() => string),
+    fetcher: (context: { key: string; signal: AbortSignal }) => Promise<T>,
+    options?: QueryOptions<T>
+  ): QueryResult<T>;
+
+  interface InfiniteQueryOptions<T> extends QueryOptions<T> {
+    getNextPageParam: (lastPage: T, allPages: T[]) => any | undefined;
+  }
+
+  interface InfiniteQueryResult<T> {
+    pages: () => T[];
+    allItems: () => any[];
+    hasNextPage: () => boolean;
+    fetchNextPage: () => Promise<void>;
+    isFetchingNextPage: () => boolean;
+    refetch: () => Promise<void>;
+  }
+
+  export function createInfiniteQuery<T>(
+    key: string | (() => string),
+    fetcher: (context: { key: string; pageParam: any; signal: AbortSignal }) => Promise<T>,
+    options?: InfiniteQueryOptions<T>
+  ): InfiniteQueryResult<T>;
+
+  interface MutationOptions<TData, TVariables, TContext> {
+    onMutate?: (variables: TVariables) => TContext | Promise<TContext>;
+    onSuccess?: (data: TData, variables: TVariables, context: TContext) => void;
+    onError?: (error: Error, variables: TVariables, context: TContext) => void;
+    onSettled?: (data: TData | undefined, error: Error | null, variables: TVariables, context: TContext) => void;
+  }
+
+  interface MutationResult<TData, TVariables> {
+    mutate: (variables: TVariables) => void;
+    mutateAsync: (variables: TVariables) => Promise<TData>;
+    isLoading: () => boolean;
+    error: () => Error | null;
+    data: () => TData | undefined;
+    reset: () => void;
+  }
+
+  export function createMutation<TData = any, TVariables = any, TContext = any>(
+    mutationFn: (variables: TVariables) => Promise<TData>,
+    options?: MutationOptions<TData, TVariables, TContext>
+  ): MutationResult<TData, TVariables>;
+
+  interface QueryClient {
+    invalidate: (keyPrefix: string) => void;
+    prefetch: <T>(key: string, fetcher: (context: { key: string; signal: AbortSignal }) => Promise<T>) => Promise<void>;
+    setCache: (key: string, data: any) => void;
+    getCache: (key: string) => any | undefined;
+    clear: () => void;
+  }
+
+  export const queryClient: QueryClient;
+
+  // ─── Entity ───────────────────────────────────────────────
+
+  interface EntityStore<T> {
+    addMany: (entities: T[]) => void;
+    upsert: (entity: T) => void;
+    update: (id: any, partial: Partial<T>) => void;
+    remove: (id: any) => void;
+    clear: () => void;
+    get: (id: any) => () => T | undefined;
+    all: () => T[];
+    count: () => number;
+    filter: (predicate: (entity: T) => boolean) => () => T[];
+    sorted: (comparator: (a: T, b: T) => number) => () => T[];
+    paginated: (opts: { page: number; size: number }) => () => T[];
+  }
+
+  export function createEntityStore<T>(options: { getId: (entity: T) => any }): EntityStore<T>;
+
+  // ─── URL State ────────────────────────────────────────────
+
+  interface Parser<T> {
+    parse: (value: string) => T;
+    serialize: (value: T) => string;
+  }
+
+  interface URLSignalOptions<T> {
+    defaultValue?: T;
+    push?: boolean;
+  }
+
+  export function createURLSignal<T>(
+    key: string,
+    parser: Parser<T>,
+    options?: URLSignalOptions<T>
+  ): [() => T, (value: T) => void];
+
+  export function createURLStore<T extends Record<string, any>>(
+    schema: { [K in keyof T]: { parser: Parser<T[K]>; defaultValue: T[K] } }
+  ): { [K in keyof T as `${string & K}`]: () => T[K] } & { [K in keyof T as `set${Capitalize<string & K>}`]: (value: T[K]) => void } & { values: () => T; reset: () => void };
+
+  export const parsers: {
+    string: Parser<string>;
+    integer: Parser<number>;
+    float: Parser<number>;
+    boolean: Parser<boolean>;
+    json: Parser<any>;
+    date: Parser<Date>;
+    enum: <T extends string>(values: T[]) => Parser<T>;
+  };
+
+  // ─── Realtime ─────────────────────────────────────────────
+
+  interface WebSocketOptions {
+    reconnectDelay?: number;
+    maxRetries?: number;
+    buffer?: boolean;
+    parse?: (data: any) => any;
+    protocols?: string[];
+  }
+
+  interface WebSocketResult {
+    lastMessage: () => any;
+    messages: () => any[];
+    status: () => 'connecting' | 'open' | 'closed' | 'reconnecting';
+    send: (data: any) => void;
+    close: () => void;
+    reconnect: () => void;
+    on: (handler: (message: any) => void) => () => void;
+  }
+
+  export function createWebSocket(url: string, options?: WebSocketOptions): WebSocketResult;
+
+  interface EventSourceOptions {
+    events?: string[];
+    withCredentials?: boolean;
+  }
+
+  interface EventSourceResult {
+    lastEvent: () => { type: string; data: any } | null;
+    status: () => 'connecting' | 'open' | 'closed';
+    close: () => void;
+    on: (eventType: string, handler: (data: any) => void) => () => void;
+  }
+
+  export function createEventSource(url: string, options?: EventSourceOptions): EventSourceResult;
+
+  // ─── Persistence ──────────────────────────────────────────
+
+  interface PersistedOptions {
+    storage?: 'local' | 'session';
+    serialize?: (value: any) => string;
+    deserialize?: (value: string) => any;
+  }
+
+  export function createPersisted<T>(
+    key: string,
+    init: T,
+    options?: PersistedOptions
+  ): [() => T, (value: T | ((prev: T) => T)) => void];
+
+  interface IndexedDBStore {
+    get: <T>(key: string) => Promise<T | undefined>;
+    set: (key: string, value: any) => Promise<void>;
+    delete: (key: string) => Promise<void>;
+    getAll: <T>() => Promise<T[]>;
+    clear: () => Promise<void>;
+  }
+
+  export function createIndexedDB(dbName: string, storeName: string): IndexedDBStore;
+
+  export function createCrossTab<T>(
+    channel: string,
+    signal: [() => T, (value: T) => void]
+  ): () => void;
+
+  interface OfflineQueueOptions {
+    process: (item: any) => Promise<void>;
+    persist?: boolean;
+    key?: string;
+    retryDelay?: number;
+  }
+
+  interface OfflineQueue {
+    add: (item: any) => void;
+    pending: () => any[];
+    isOnline: () => boolean;
+    flush: () => Promise<void>;
+  }
+
+  export function createOfflineQueue(options: OfflineQueueOptions): OfflineQueue;
+
+  // ─── Worker ───────────────────────────────────────────────
+
+  interface WorkerSignalResult {
+    result: () => any;
+    busy: () => boolean;
+    error: () => Error | null;
+    send: (data: any) => void;
+    terminate: () => void;
+  }
+
+  export function createWorkerSignal(worker: Worker): WorkerSignalResult;
+
+  interface WorkerQueryResult<T> {
+    data: () => T | undefined;
+    loading: () => boolean;
+    error: () => Error | null;
+    refetch: () => void;
+  }
+
+  export function createWorkerQuery<T>(
+    worker: Worker,
+    input: (() => any) | any
+  ): WorkerQueryResult<T>;
+}

package/types/form.d.ts

@@ -0,0 +1,164 @@
+// Auto-generated by tools/dts-gen.js — do not edit manually
+declare module 'decantr/form' {
+  // ── Validator Types ──
+
+  type SyncValidator = (value: any, allValues?: Record<string, any>) => string | null;
+  type AsyncValidator = (value: any, allValues?: Record<string, any>) => Promise<string | null>;
+
+  interface Validators {
+    /** Value must be truthy (non-empty). */
+    required(msg?: string): SyncValidator;
+    /** String length must be >= n. */
+    minLength(n: number, msg?: string): SyncValidator;
+    /** String length must be <= n. */
+    maxLength(n: number, msg?: string): SyncValidator;
+    /** Numeric value must be >= n. */
+    min(n: number, msg?: string): SyncValidator;
+    /** Numeric value must be <= n. */
+    max(n: number, msg?: string): SyncValidator;
+    /** Value must match regex pattern. */
+    pattern(regex: RegExp, msg?: string): SyncValidator;
+    /** Must be a valid email address. */
+    email(msg?: string): SyncValidator;
+    /** Value must equal another field's current value. */
+    match(fieldName: string, msg?: string): SyncValidator;
+    /** Custom synchronous validator. */
+    custom(fn: (value: any, allValues: Record<string, any>) => true | string, msg?: string): SyncValidator;
+    /** Async validator (auto-debounced 300ms). */
+    async(fn: (value: any, allValues: Record<string, any>) => Promise<true | string>, msg?: string): AsyncValidator;
+  }
+
+  export const validators: Validators;
+
+  // ── Field Instance ──
+
+  interface FieldInstance {
+    readonly name: string;
+    /** Signal getter for current value. */
+    value: () => any;
+    /** First error message or null. */
+    error: () => string | null;
+    /** All error messages. */
+    errors: () => string[];
+    /** Whether field has been blurred. */
+    touched: () => boolean;
+    /** Whether value differs from initial. */
+    dirty: () => boolean;
+    /** Whether field has no errors. */
+    valid: () => boolean;
+    /** Set a new value. */
+    setValue: (value: any) => void;
+    /** Mark as touched. */
+    setTouched: () => void;
+    /** Set an error manually. */
+    setError: (msg: string) => void;
+    /** Reset to initial value. */
+    reset: (value?: any) => void;
+    /** Run all validators. Returns true if valid. */
+    validate: () => Promise<boolean>;
+    /** Get binding props for Decantr form components. */
+    bind: () => { value: () => any; onchange: (v: any) => void; onblur: () => void; error: () => string | null };
+  }
+
+  // ── Field Array Instance ──
+
+  interface FieldArrayInstance {
+    /** Signal getter for array of items. */
+    items: () => any[];
+    /** Reactive item count. */
+    length: () => number;
+    /** Append a value to the end. */
+    append: (value: any) => void;
+    /** Prepend a value to the beginning. */
+    prepend: (value: any) => void;
+    /** Remove item at index. */
+    remove: (index: number) => void;
+    /** Move item from one index to another. */
+    move: (from: number, to: number) => void;
+    /** Swap two items by index. */
+    swap: (a: number, b: number) => void;
+    /** Replace item at index. */
+    replace: (index: number, value: any) => void;
+  }
+
+  // ── Form Instance ──
+
+  interface FieldConfig {
+    /** Initial value. */
+    value?: any;
+    /** Array of validator functions. */
+    validators?: Array<SyncValidator | AsyncValidator>;
+    /** Transform function applied on setValue. */
+    transform?: (raw: any) => any;
+  }
+
+  interface FormConfig {
+    /** Field definitions. */
+    fields: Record<string, FieldConfig>;
+    /** Submit handler. */
+    onSubmit?: (values: Record<string, any>, form: FormInstance) => void | Promise<void>;
+    /** Cross-field validation returning `{ fieldName: string[] }`. */
+    validate?: (values: Record<string, any>) => Record<string, string[]> | void;
+    /** When to trigger validation. Default: 'onBlur'. */
+    validateOn?: 'onChange' | 'onBlur' | 'onSubmit';
+  }
+
+  interface FormInstance {
+    /** Get or create a field by name. */
+    field: (name: string) => FieldInstance;
+    /** Proxy for field access via dot notation (form.fields.email). */
+    fields: Record<string, FieldInstance>;
+    /** Signal getter for all current values. */
+    values: () => Record<string, any>;
+    /** Signal getter for all errors `{ fieldName: string[] }`. */
+    errors: () => Record<string, string[]>;
+    /** Signal getter for overall form validity. */
+    isValid: () => boolean;
+    /** Signal getter for whether any field is dirty. */
+    isDirty: () => boolean;
+    /** Signal getter for submitting state. */
+    isSubmitting: () => boolean;
+    /** Signal getter for submitted state. */
+    isSubmitted: () => boolean;
+    /** Signal getter for submit count. */
+    submitCount: () => number;
+    /** Submit the form. */
+    submit: () => Promise<void>;
+    /** Reset all fields. */
+    reset: (values?: Record<string, any>) => void;
+    /** Set multiple field values at once. */
+    setValues: (partial: Record<string, any>) => void;
+    /** Set errors on multiple fields. */
+    setErrors: (errors: Record<string, string | string[]>) => void;
+    /** Run all validators. Returns true if valid. */
+    validate: () => Promise<boolean>;
+    /** Get or create a field array. */
+    fieldArray: (name: string) => FieldArrayInstance;
+    /** Watch a specific field for value changes. Returns unsubscribe. */
+    watch: (fieldName: string, callback: (value: any, prevValue: any) => void) => () => void;
+    /** Watch all fields for any change. Returns unsubscribe. */
+    watchAll: (callback: (values: Record<string, any>) => void) => () => void;
+  }
+
+  /**
+   * Create a reactive form instance.
+   */
+  export function createForm(config: FormConfig): FormInstance;
+
+  interface UseFormFieldResult {
+    value: () => any;
+    setValue: (value: any) => void;
+    error: () => string | null;
+    errors: () => string[];
+    touched: () => boolean;
+    dirty: () => boolean;
+    valid: () => boolean;
+    onBlur: () => void;
+    bind: () => { value: () => any; onchange: (v: any) => void; onblur: () => void; error: () => string | null };
+  }
+
+  /**
+   * Hook for binding a form field to a custom component.
+   */
+  export function useFormField(form: FormInstance, fieldName: string): UseFormFieldResult;
+}

package/types/i18n.d.ts

@@ -0,0 +1,51 @@
+// Auto-generated by tools/dts-gen.js — do not edit manually
+declare module 'decantr/i18n' {
+  /**
+   * Configuration for creating an i18n instance.
+   */
+  export interface I18nConfig {
+    /** Initial active locale (e.g. 'en', 'fr', 'ar'). */
+    locale: string;
+    /** Messages keyed by locale. Each locale maps keys to strings or nested objects. */
+    messages: Record<string, Record<string, any>>;
+    /** Fallback locale used when a key is missing in the active locale. */
+    fallbackLocale?: string;
+  }
+
+  /**
+   * An i18n instance returned by createI18n().
+   */
+  export interface I18nInstance {
+    /**
+     * Translate a key with optional interpolation and pluralization.
+     *
+     * - Dot notation: `t('nav.home')` resolves nested objects.
+     * - Interpolation: `t('hello', { name: 'World' })` replaces `{name}`.
+     * - Pluralization: `t('items', { count: 3 })` appends `_one`/`_other` suffix
+     *   via `Intl.PluralRules`.
+     * - Fallback chain: current locale -> fallback locale -> raw key.
+     */
+    t: (key: string, params?: Record<string, any>) => string;
+
+    /** Signal getter for the current locale. */
+    locale: () => string;
+
+    /** Set the active locale. Reactively updates all `t()` consumers. */
+    setLocale: (locale: string) => void;
+
+    /** Set the document direction attribute ('ltr' or 'rtl'). */
+    setDirection: (dir: 'ltr' | 'rtl') => void;
+
+    /** Merge additional messages into a locale at runtime. */
+    addMessages: (locale: string, messages: Record<string, any>) => void;
+  }
+
+  /**
+   * Create a reactive i18n instance.
+   *
+   * The returned `t()` function is reactive — it reads the internal locale
+   * signal, so any `createEffect` or `createMemo` that calls `t()` will
+   * re-run when the locale changes via `setLocale()`.
+   */
+  export function createI18n(config: I18nConfig): I18nInstance;
+}

package/types/icons.d.ts

@@ -0,0 +1,27 @@
+// Auto-generated by tools/dts-gen.js — do not edit manually
+declare module 'decantr/icons' {
+  /**
+   * Get SVG inner content for an icon by name.
+   */
+  export function getIconPath(name: string): string | null;
+
+  /**
+   * Register a custom icon (or override an existing one).
+   */
+  export function registerIcon(name: string, pathData: string): void;
+
+  /**
+   * Register multiple icons at once.
+   */
+  export function registerIcons(iconMap: Record<string, string>): void;
+
+  /**
+   * Check if an icon is available.
+   */
+  export function hasIcon(name: string): boolean;
+
+  /**
+   * Get all currently available icon names.
+   */
+  export function getIconNames(): string[];
+}

package/types/index.d.ts

@@ -0,0 +1,13 @@
+// Auto-generated by tools/dts-gen.js — do not edit manually
+// Master declaration file — re-exports all Decantr modules.
+
+/// <reference path="./core.d.ts" />
+/// <reference path="./state.d.ts" />
+/// <reference path="./router.d.ts" />
+/// <reference path="./css.d.ts" />
+/// <reference path="./tags.d.ts" />
+/// <reference path="./components.d.ts" />
+/// <reference path="./form.d.ts" />
+/// <reference path="./icons.d.ts" />
+/// <reference path="./chart.d.ts" />
+/// <reference path="./test.d.ts" />