domma-js 0.3.1-alpha → 0.7.0-alpha

package/assets/types/icons.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Domma Icons Module - TypeScript Declarations
+ * SVG icon library with categories and rendering
+ */
+
+export type IconCategory =
+    | 'ui'
+    | 'navigation'
+    | 'media'
+    | 'communication'
+    | 'files'
+    | 'social'
+    | 'status'
+    | 'commerce';
+
+export interface IconDefinition {
+    /** SVG path or full SVG content */
+    svg: string;
+    /** Icon category */
+    category?: IconCategory;
+    /** Icon tags for search */
+    tags?: string[];
+    /** ViewBox dimensions */
+    viewBox?: string;
+}
+
+export interface RenderOptions {
+    /** Icon size in pixels or CSS value */
+    size?: number | string;
+    /** Icon colour */
+    color?: string;
+    /** Additional CSS class */
+    className?: string;
+    /** Additional inline styles */
+    style?: Record<string, string>;
+    /** Accessible label */
+    ariaLabel?: string;
+    /** Custom attributes */
+    attrs?: Record<string, string>;
+}
+
+export interface Icons {
+    /**
+     * Render an icon as an SVG element
+     * @param name - Icon name
+     * @param options - Render options
+     * @returns SVG element or null if not found
+     */
+    render(name: string, options?: RenderOptions): SVGElement | null;
+
+    /**
+     * Get icon as HTML string
+     * @param name - Icon name
+     * @param options - Render options
+     * @returns SVG HTML string or empty string if not found
+     */
+    html(name: string, options?: RenderOptions): string;
+
+    /**
+     * Inject icon into a DOM element
+     * @param selector - Target element selector or element
+     * @param name - Icon name
+     * @param options - Render options
+     * @returns The target element or null
+     */
+    inject(selector: string | HTMLElement, name: string, options?: RenderOptions): HTMLElement | null;
+
+    /**
+     * Scan DOM for icon placeholders and inject icons
+     * @param container - Container to scan (default: document)
+     * @param attribute - Data attribute to look for (default: 'data-icon')
+     * @returns Number of icons injected
+     */
+    scan(container?: HTMLElement | Document, attribute?: string): number;
+
+    /**
+     * Register a custom icon
+     * @param name - Icon name
+     * @param definition - Icon definition (SVG string or full definition)
+     */
+    register(name: string, definition: string | IconDefinition): void;
+
+    /**
+     * Unregister an icon
+     * @param name - Icon name
+     * @returns true if icon was removed
+     */
+    unregister(name: string): boolean;
+
+    /**
+     * Check if an icon exists
+     * @param name - Icon name
+     * @returns true if icon exists
+     */
+    has(name: string): boolean;
+
+    /**
+     * Get icon definition
+     * @param name - Icon name
+     * @returns Icon definition or undefined
+     */
+    get(name: string): IconDefinition | undefined;
+
+    /**
+     * List all icon names
+     * @param category - Optional category filter
+     * @returns Array of icon names
+     */
+    list(category?: IconCategory): string[];
+
+    /**
+     * List all categories
+     * @returns Array of category names
+     */
+    listCategories(): IconCategory[];
+
+    /**
+     * Get total icon count
+     * @param category - Optional category filter
+     * @returns Number of icons
+     */
+    count(category?: IconCategory): number;
+
+    /**
+     * Search icons by name or tags
+     * @param query - Search query
+     * @returns Array of matching icon names
+     */
+    search(query: string): string[];
+
+    /**
+     * Create an SVG sprite sheet
+     * @param icons - Array of icon names (default: all icons)
+     * @returns SVG sprite element
+     */
+    createSprite(icons?: string[]): SVGElement;
+
+    /**
+     * Use an icon from a sprite sheet
+     * @param name - Icon name
+     * @param options - Render options
+     * @returns SVG use element HTML string
+     */
+    use(name: string, options?: RenderOptions): string;
+}
+
+export declare const icons: Icons;

package/assets/types/index.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Domma - Dynamic Object Manipulation & Modeling API
+ * TypeScript Declaration File
+ *
+ * A lightweight, zero-dependency JavaScript framework combining
+ * jQuery-style DOM manipulation, Lodash utilities, and modern UI components.
+ */
+
+// Re-export all module types
+export * from './dom';
+export * from './utils';
+export * from './dates';
+export * from './models';
+export * from './config';
+export * from './elements';
+export * from './tables';
+export * from './storage';
+export * from './http';
+export * from './theme';
+export * from './icons';
+
+// Import types for the main Domma object
+import {dom, DommaCollection} from './dom';
+import {Utils, utils} from './utils';
+import {Dates, dates, DommaDate} from './dates';
+import {Model, models, Models} from './models';
+import {configEngine, SelectorConfig, SetupConfig} from './config';
+import {Elements, elements} from './elements';
+import {Tables, tables} from './tables';
+import {Storage, storage} from './storage';
+import {Http, http} from './http';
+import {Theme, theme} from './theme';
+import {Icons, icons} from './icons';
+
+// ============================================
+// Main Domma Interface
+// ============================================
+
+export interface DommaStatic {
+    /**
+     * Create a DommaCollection from a selector, element, or collection
+     * @param selector - CSS selector, element, NodeList, or array of elements
+     * @param context - Optional context element or document
+     * @returns DommaCollection instance
+     */
+    (selector: string | HTMLElement | NodeList | HTMLCollection | HTMLElement[] | DommaCollection, context?: Document | HTMLElement): DommaCollection;
+
+    /**
+     * Execute callback when DOM is ready
+     * @param callback - Function to execute when DOM is ready
+     */
+    (callback: () => void): void;
+
+    /** DOM manipulation module */
+    dom: typeof dom;
+
+    /** Utility functions (Lodash-compatible) */
+    utils: Utils;
+
+    /** Date manipulation (Moment.js-style) */
+    dates: Dates;
+
+    /** Reactive models & pub/sub */
+    models: Models;
+
+    /** UI components */
+    elements: Elements;
+
+    /** DataTable functionality */
+    tables: Tables;
+
+    /** localStorage wrapper */
+    storage: Storage;
+
+    /** HTTP client */
+    http: Http;
+
+    /** Theme system */
+    theme: Theme;
+
+    /** Icon library */
+    icons: Icons;
+
+    // ============================================
+    // ConfigEngine Methods ($.setup, $.config, etc.)
+    // ============================================
+
+    /**
+     * Process configuration for selectors
+     * @param config - Configuration object keyed by selector
+     */
+    setup(config: SetupConfig): void;
+
+    /**
+     * Update configuration for a selector
+     * @param selector - CSS selector
+     * @param changes - Changes to merge into existing config
+     * @returns The merged configuration
+     */
+    update(selector: string, changes: Partial<SelectorConfig>): SelectorConfig;
+
+    /**
+     * Retrieve configuration for a selector or all selectors
+     * @param selector - Optional selector to get config for
+     * @returns Configuration object or null if not found
+     */
+    config(): Record<string, SelectorConfig>;
+
+    config(selector: string): SelectorConfig | null;
+
+    /**
+     * Reset/destroy configuration for a selector or all selectors
+     * @param selector - Optional selector to reset
+     */
+    reset(selector?: string): void;
+
+    // ============================================
+    // Static Utilities
+    // ============================================
+
+    /** Check if value is a DommaCollection */
+    isDomma(value: any): value is DommaCollection;
+
+    /** Domma version string */
+    version: string;
+
+    /** No-conflict mode - restore previous $ */
+    noConflict(): DommaStatic;
+}
+
+// ============================================
+// Global Declarations
+// ============================================
+
+declare global {
+    /**
+     * Domma - Main entry point
+     * jQuery-compatible DOM selection and manipulation
+     */
+    const Domma: DommaStatic;
+
+    /**
+     * $ - Alias for Domma
+     * jQuery-compatible selector function
+     */
+    const $: DommaStatic;
+
+    /**
+     * _ - Alias for Domma.utils
+     * Lodash-compatible utility functions
+     */
+    const _: Utils;
+
+    /**
+     * M - Alias for Domma.models
+     * Reactive models and pub/sub events
+     */
+    const M: Models;
+
+    /**
+     * D - Alias for Domma.dates
+     * Moment.js-style date manipulation
+     */
+    const D: Dates;
+
+    /**
+     * S - Alias for Domma.storage
+     * localStorage wrapper
+     */
+    const S: Storage;
+}
+
+// ============================================
+// Default Export
+// ============================================
+
+declare const Domma: DommaStatic;
+export default Domma;
+
+// Named exports for ES modules
+export {
+    Domma,
+    dom,
+    utils,
+    dates,
+    models,
+    elements,
+    tables,
+    storage,
+    http,
+    theme,
+    icons,
+    configEngine,
+    DommaCollection,
+    DommaDate,
+    Model
+};

package/assets/types/models.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Domma Models Module - TypeScript Declarations
+ * Pub/Sub events and reactive data binding
+ */
+
+export type TypeValidator = (value: any) => boolean;
+
+export interface FieldDefinition {
+    type?: 'string' | 'number' | 'boolean' | 'array' | 'object' | 'date' | 'any';
+    default?: any;
+    required?: boolean;
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: RegExp;
+    validate?: (value: any) => boolean | string;
+}
+
+export interface Schema {
+    [field: string]: FieldDefinition;
+}
+
+export interface ValidationResult {
+    valid: boolean;
+    errors: Array<{ field: string; error: string }>;
+}
+
+export interface ModelOptions {
+    persist?: string;
+    autoSave?: boolean;
+}
+
+export interface ChangeEvent {
+    field: string;
+    newValue: any;
+    oldValue: any;
+    model: Model;
+}
+
+export type ChangeCallback = (event: ChangeEvent) => void;
+export type FieldChangeCallback = (newValue: any, oldValue: any, model: Model) => void;
+export type UnsubscribeFn = () => void;
+
+export interface BindingOptions {
+    format?: (value: any) => any;
+    parse?: (value: any) => any;
+    twoWay?: boolean;
+}
+
+/**
+ * Reactive Model class
+ */
+export declare class Model {
+    constructor(schema: Schema, data?: Record<string, any>, options?: ModelOptions);
+
+    /** Get field value or all data */
+    get(): Record<string, any>;
+    get(field: string): any;
+
+    /** Set field value(s) */
+    set(field: string, value: any): Model;
+    set(data: Record<string, any>): Model;
+
+    /** Validate all fields */
+    validate(): ValidationResult;
+
+    /** Get model data as JSON */
+    toJSON(): Record<string, any>;
+
+    /** Subscribe to any change */
+    onChange(callback: ChangeCallback): UnsubscribeFn;
+
+    /** Subscribe to specific field change */
+    onFieldChange(field: string, callback: FieldChangeCallback): UnsubscribeFn;
+
+    /** Reset model to initial data */
+    reset(clearStorage?: boolean): Model;
+
+    /** Destroy model and cleanup */
+    destroy(clearStorage?: boolean): void;
+
+    // Persistence Methods
+
+    /** Manually save model to localStorage */
+    save(): boolean;
+
+    /** Manually load model from localStorage */
+    load(): boolean;
+
+    /** Clear persisted data from localStorage */
+    clearStorage(): boolean;
+
+    /** Get the persistence key */
+    getPersistKey(): string | null;
+
+    /** Check if model is persisted */
+    isPersisted(): boolean;
+}
+
+export interface Store {
+    /** Get current state */
+    getState(): Record<string, any>;
+
+    /** Update state with partial updates */
+    setState(updates: Record<string, any>): void;
+
+    /** Subscribe to state changes */
+    subscribe(listener: (state: Record<string, any>, oldState: Record<string, any>) => void): UnsubscribeFn;
+
+    /** Reset state to initial or new state */
+    reset(newState?: Record<string, any>): void;
+}
+
+export interface TypeValidators {
+    string: TypeValidator;
+    number: TypeValidator;
+    boolean: TypeValidator;
+    array: TypeValidator;
+    object: TypeValidator;
+    date: TypeValidator;
+    any: TypeValidator;
+}
+
+export interface Models {
+    // ============================================
+    // Pub/Sub Event System
+    // ============================================
+
+    /** Subscribe to an event */
+    subscribe(event: string, callback: (data: any) => void): UnsubscribeFn;
+
+    /** Alias for subscribe */
+    on(event: string, callback: (data: any) => void): UnsubscribeFn;
+
+    /** Unsubscribe from an event */
+    unsubscribe(event: string, callback: (data: any) => void): void;
+
+    /** Alias for unsubscribe */
+    off(event: string, callback: (data: any) => void): void;
+
+    /** Publish an event */
+    publish(event: string, data?: any): void;
+
+    /** Alias for publish */
+    emit(event: string, data?: any): void;
+
+    /** Subscribe to an event once */
+    once(event: string, callback: (data: any) => void): UnsubscribeFn;
+
+    /** Clear event listeners */
+    clear(event?: string): void;
+
+    // ============================================
+    // Model Creation
+    // ============================================
+
+    /** Create a new reactive model */
+    create(schema: Schema, initialData?: Record<string, any>, options?: ModelOptions): Model;
+
+    // ============================================
+    // Type Validators
+    // ============================================
+
+    types: TypeValidators;
+
+    // ============================================
+    // DOM Binding
+    // ============================================
+
+    /** Bind a model field to DOM element(s) */
+    bind(model: Model, field: string, selector: string | HTMLElement, options?: BindingOptions): UnsubscribeFn;
+
+    // ============================================
+    // Store (Simple State Management)
+    // ============================================
+
+    /** Get or create a named store */
+    store(name: string, initialState?: Record<string, any>): Store;
+
+    /** Get an existing store */
+    getStore(name: string): Store | undefined;
+
+    /** Remove a store */
+    removeStore(name: string): void;
+}
+
+export declare const models: Models;

package/assets/types/storage.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Domma Storage Module - TypeScript Declarations
+ * localStorage wrapper with auto-serialisation and key prefixing
+ */
+
+export interface Storage {
+    /**
+     * Get a value from storage
+     * @param key - The storage key
+     * @param defaultValue - Default value if key doesn't exist
+     * @returns The stored value or default
+     */
+    get<T = any>(key: string, defaultValue?: T): T;
+
+    /**
+     * Set a value in storage
+     * @param key - The storage key
+     * @param value - The value to store (auto-serialised)
+     * @returns true if successful
+     */
+    set(key: string, value: any): boolean;
+
+    /**
+     * Remove a key from storage
+     * @param key - The storage key
+     * @returns true if successful
+     */
+    remove(key: string): boolean;
+
+    /**
+     * Check if a key exists in storage
+     * @param key - The storage key
+     * @returns true if key exists
+     */
+    has(key: string): boolean;
+
+    /**
+     * Clear all storage (within prefix)
+     * @returns true if successful
+     */
+    clear(): boolean;
+
+    /**
+     * Get all storage keys (within prefix)
+     * @returns Array of keys
+     */
+    keys(): string[];
+
+    /**
+     * Get the number of stored items (within prefix)
+     * @returns Number of items
+     */
+    size(): number;
+
+    /**
+     * Get total storage size in bytes
+     * @returns Size in bytes
+     */
+    totalSize(): number;
+
+    /**
+     * Get all stored data as an object
+     * @returns Object with all key-value pairs
+     */
+    getAll(): Record<string, any>;
+
+    /**
+     * Set multiple values at once
+     * @param data - Object with key-value pairs
+     * @returns true if all successful
+     */
+    setAll(data: Record<string, any>): boolean;
+
+    /**
+     * Check if localStorage is available
+     * @returns true if available
+     */
+    isAvailable(): boolean;
+
+    /**
+     * Set the key prefix
+     * @param prefix - Prefix string for all keys
+     */
+    setPrefix(prefix: string): void;
+
+    /**
+     * Get the current key prefix
+     * @returns Current prefix
+     */
+    getPrefix(): string;
+}
+
+export declare const storage: Storage;