@smartnet360/svelte-components 0.0.37 → 0.0.39

package/dist/core/Settings/store.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Settings Store Factory
+ *
+ * Creates reactive stores for settings management with automatic persistence.
+ * Each consuming app creates its own store instance with its schema and namespace.
+ *
+ * Supports hierarchical access with TypeScript autocomplete:
+ * $settings.appearance.theme
+ * $settings.editor.fontSize
+ */
+import type { SettingsSchema } from './types';
+/**
+ * Type helper to infer settings structure from schema
+ * Converts schema into nested type: { segment: { field: value } }
+ */
+export type InferSettingsType<T extends SettingsSchema> = {
+    [K in T['segments'][number]['id']]: {
+        [F in Extract<T['segments'][number], {
+            id: K;
+        }>['fields'][number] as F['id']]: F['defaultValue'];
+    };
+};
+/**
+ * Create a settings store instance with hierarchical access
+ *
+ * @param schema - The settings schema defining all fields
+ * @param namespace - Unique namespace for localStorage isolation (e.g., 'myApp')
+ * @returns A reactive store with hierarchical access: $settings.segment.field
+ *
+ * @example
+ * ```ts
+ * const settings = createSettingsStore(mySchema, 'myApp');
+ *
+ * // In Svelte components with full autocomplete:
+ * $settings.appearance.theme     // ✅ TypeScript autocomplete works!
+ * $settings.editor.fontSize      // ✅ Nested access
+ *
+ * // Update values:
+ * settings.update('appearance', 'theme', 'dark')
+ * settings.updateSegment('appearance', { theme: 'dark', ... })
+ * ```
+ */
+export declare function createSettingsStore<T extends SettingsSchema>(schema: T, namespace: string): {
+    subscribe: (this: void, run: import("svelte/store").Subscriber<InferSettingsType<T>>, invalidate?: () => void) => import("svelte/store").Unsubscriber;
+    update: (segmentId: string, fieldId: string, value: any) => void;
+    updateSegment: (segmentId: string, values: Record<string, any>) => void;
+    reset: (segmentId: string, fieldId: string) => void;
+    resetSegment: (segmentId: string) => void;
+    resetAll: () => void;
+    getValues: () => InferSettingsType<T>;
+};
+/**
+ * Helper to create a flat map of field ID -> field definition
+ * Useful for quick lookups when rendering or validating
+ */
+export declare function createFieldMap(schema: SettingsSchema): Map<any, any>;

package/dist/core/Settings/store.js

@@ -0,0 +1,184 @@
+/**
+ * Settings Store Factory
+ *
+ * Creates reactive stores for settings management with automatic persistence.
+ * Each consuming app creates its own store instance with its schema and namespace.
+ *
+ * Supports hierarchical access with TypeScript autocomplete:
+ * $settings.appearance.theme
+ * $settings.editor.fontSize
+ */
+import { writable, get } from 'svelte/store';
+/**
+ * Extract default values from schema in hierarchical structure
+ * Returns: { segment: { field: value } }
+ */
+function extractDefaults(schema) {
+    const defaults = {};
+    for (const segment of schema.segments) {
+        defaults[segment.id] = {};
+        for (const field of segment.fields) {
+            defaults[segment.id][field.id] = field.defaultValue;
+        }
+    }
+    return defaults;
+}
+/**
+ * Load saved settings from localStorage (SSR-safe)
+ * Supports hierarchical structure
+ */
+function loadFromStorage(namespace, defaults) {
+    if (typeof window === 'undefined')
+        return defaults;
+    try {
+        const storageKey = `${namespace}:settings`;
+        const saved = localStorage.getItem(storageKey);
+        if (saved) {
+            const parsed = JSON.parse(saved);
+            // Deep merge with defaults to ensure new fields appear
+            const merged = {};
+            for (const segmentId in defaults) {
+                merged[segmentId] = {
+                    ...defaults[segmentId],
+                    ...(parsed[segmentId] || {})
+                };
+            }
+            return merged;
+        }
+    }
+    catch (error) {
+        console.error('Failed to load settings from localStorage:', error);
+    }
+    return defaults;
+}
+/**
+ * Save settings to localStorage (SSR-safe)
+ */
+function saveToStorage(namespace, values) {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        const storageKey = `${namespace}:settings`;
+        localStorage.setItem(storageKey, JSON.stringify(values));
+    }
+    catch (error) {
+        console.error('Failed to save settings to localStorage:', error);
+    }
+}
+/**
+ * Create a settings store instance with hierarchical access
+ *
+ * @param schema - The settings schema defining all fields
+ * @param namespace - Unique namespace for localStorage isolation (e.g., 'myApp')
+ * @returns A reactive store with hierarchical access: $settings.segment.field
+ *
+ * @example
+ * ```ts
+ * const settings = createSettingsStore(mySchema, 'myApp');
+ *
+ * // In Svelte components with full autocomplete:
+ * $settings.appearance.theme     // ✅ TypeScript autocomplete works!
+ * $settings.editor.fontSize      // ✅ Nested access
+ *
+ * // Update values:
+ * settings.update('appearance', 'theme', 'dark')
+ * settings.updateSegment('appearance', { theme: 'dark', ... })
+ * ```
+ */
+export function createSettingsStore(schema, namespace) {
+    // Extract defaults from schema (hierarchical structure)
+    const defaults = extractDefaults(schema);
+    // Load initial values (defaults + any saved values)
+    const initialValues = loadFromStorage(namespace, defaults);
+    const { subscribe, set: setStore, update: updateStore } = writable(initialValues);
+    // Subscribe to changes and persist to localStorage
+    subscribe((values) => {
+        saveToStorage(namespace, values);
+    });
+    /**
+     * Update a single field value
+     * @param segmentId - The segment ID (e.g., 'appearance')
+     * @param fieldId - The field ID (e.g., 'theme')
+     * @param value - The new value
+     */
+    function update(segmentId, fieldId, value) {
+        updateStore((current) => ({
+            ...current,
+            [segmentId]: {
+                ...current[segmentId],
+                [fieldId]: value
+            }
+        }));
+    }
+    /**
+     * Update multiple fields in a segment at once
+     * @param segmentId - The segment ID
+     * @param values - Partial segment values
+     */
+    function updateSegment(segmentId, values) {
+        updateStore((current) => ({
+            ...current,
+            [segmentId]: {
+                ...current[segmentId],
+                ...values
+            }
+        }));
+    }
+    /**
+     * Reset a single field to its default value
+     * @param segmentId - The segment ID
+     * @param fieldId - The field ID
+     */
+    function reset(segmentId, fieldId) {
+        const defaultValue = defaults[segmentId]?.[fieldId];
+        if (defaultValue !== undefined) {
+            update(segmentId, fieldId, defaultValue);
+        }
+    }
+    /**
+     * Reset an entire segment to defaults
+     * @param segmentId - The segment ID
+     */
+    function resetSegment(segmentId) {
+        if (defaults[segmentId]) {
+            updateStore((current) => ({
+                ...current,
+                [segmentId]: { ...defaults[segmentId] }
+            }));
+        }
+    }
+    /**
+     * Reset all settings to their default values
+     */
+    function resetAll() {
+        setStore({ ...defaults });
+    }
+    /**
+     * Get a snapshot of current values (non-reactive)
+     */
+    function getValues() {
+        return get({ subscribe });
+    }
+    return {
+        subscribe,
+        update,
+        updateSegment,
+        reset,
+        resetSegment,
+        resetAll,
+        getValues
+    };
+}
+/**
+ * Helper to create a flat map of field ID -> field definition
+ * Useful for quick lookups when rendering or validating
+ */
+export function createFieldMap(schema) {
+    const map = new Map();
+    for (const segment of schema.segments) {
+        for (const field of segment.fields) {
+            map.set(field.id, field);
+        }
+    }
+    return map;
+}

package/dist/core/Settings/types.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Settings System Type Definitions
+ *
+ * Defines the schema structure for the data-driven settings component.
+ * Schemas are passed in from consuming applications.
+ */
+/**
+ * Base field definition shared by all field types
+ */
+export interface BaseFieldDefinition {
+    /** Unique identifier for the field */
+    id: string;
+    /** Display label for the field */
+    label: string;
+    /** Optional description/help text */
+    description?: string;
+    /** Optional tooltip shown on hover */
+    tooltip?: string;
+    /** Whether the field is disabled */
+    disabled?: boolean;
+    /** Condition for field visibility (function that receives all settings) */
+    visibleIf?: (settings: Record<string, any>) => boolean;
+}
+/**
+ * Boolean toggle field (checkbox/switch)
+ */
+export interface BooleanFieldDefinition extends BaseFieldDefinition {
+    type: 'boolean';
+    defaultValue: boolean;
+}
+/**
+ * Text input field
+ */
+export interface TextFieldDefinition extends BaseFieldDefinition {
+    type: 'text';
+    defaultValue: string;
+    /** Input placeholder text */
+    placeholder?: string;
+    /** Maximum character length */
+    maxLength?: number;
+    /** Validation pattern (regex) */
+    pattern?: string;
+}
+/**
+ * Number input field
+ */
+export interface NumberFieldDefinition extends BaseFieldDefinition {
+    type: 'number';
+    defaultValue: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    /** Unit label (e.g., "px", "ms", "%") */
+    unit?: string;
+}
+/**
+ * Range slider field
+ */
+export interface RangeFieldDefinition extends BaseFieldDefinition {
+    type: 'range';
+    defaultValue: number;
+    min: number;
+    max: number;
+    step?: number;
+    /** Whether to show the current value */
+    showValue?: boolean;
+    /** Unit label (e.g., "px", "ms", "%") */
+    unit?: string;
+}
+/**
+ * Color picker field
+ */
+export interface ColorFieldDefinition extends BaseFieldDefinition {
+    type: 'color';
+    defaultValue: string;
+}
+/**
+ * Select dropdown field
+ */
+export interface SelectFieldDefinition extends BaseFieldDefinition {
+    type: 'select';
+    defaultValue: string | number;
+    options: Array<{
+        value: string | number;
+        label: string;
+        description?: string;
+    }>;
+}
+/**
+ * Radio button group field
+ */
+export interface RadioFieldDefinition extends BaseFieldDefinition {
+    type: 'radio';
+    defaultValue: string | number;
+    options: Array<{
+        value: string | number;
+        label: string;
+        description?: string;
+    }>;
+}
+/**
+ * Custom field that renders a provided Svelte component
+ */
+export interface CustomFieldDefinition extends BaseFieldDefinition {
+    type: 'custom';
+    defaultValue: any;
+    /** The Svelte component to render */
+    component: any;
+    /** Additional props to pass to the custom component */
+    componentProps?: Record<string, any>;
+}
+/**
+ * Union type of all field definitions
+ */
+export type FieldDefinition = BooleanFieldDefinition | TextFieldDefinition | NumberFieldDefinition | RangeFieldDefinition | ColorFieldDefinition | SelectFieldDefinition | RadioFieldDefinition | CustomFieldDefinition;
+/**
+ * A segment groups related settings fields under a card/section
+ */
+export interface SegmentDefinition {
+    /** Unique identifier for the segment */
+    id: string;
+    /** Display title for the card/section */
+    title: string;
+    /** Optional description for the segment */
+    description?: string;
+    /** Optional icon (emoji or icon class) */
+    icon?: string;
+    /** Whether the segment starts collapsed */
+    collapsed?: boolean;
+    /** Array of field definitions in this segment */
+    fields: FieldDefinition[];
+}
+/**
+ * Complete settings schema passed to the Settings component
+ */
+export interface SettingsSchema {
+    /** Array of setting segments (cards) */
+    segments: SegmentDefinition[];
+    /** Optional schema version for migration support */
+    version?: string;
+}
+/**
+ * The live settings values (flat key-value pairs)
+ */
+export type SettingsValues = Record<string, any>;
+/**
+ * Store interface for settings
+ */
+export interface SettingsStore {
+    /** Subscribe to settings changes */
+    subscribe: (callback: (value: SettingsValues) => void) => () => void;
+    /** Update a single setting value */
+    set: (key: string, value: any) => void;
+    /** Update multiple settings at once */
+    update: (values: Partial<SettingsValues>) => void;
+    /** Reset a single setting to default */
+    reset: (key: string) => void;
+    /** Reset all settings to defaults */
+    resetAll: () => void;
+    /** Get current values snapshot */
+    getValues: () => SettingsValues;
+}

package/dist/core/Settings/types.js

@@ -0,0 +1,7 @@
+/**
+ * Settings System Type Definitions
+ *
+ * Defines the schema structure for the data-driven settings component.
+ * Schemas are passed in from consuming applications.
+ */
+export {};

package/dist/core/index.d.ts

@@ -1,4 +1,5 @@
 export * from './Desktop/index.js';
 export * from './Charts/index.js';
 export * from './TreeView/index.js';
+export * from './Settings/index.js';
 export * from './logger/index.js';

package/dist/core/index.js

@@ -6,5 +6,7 @@ export * from './Desktop/index.js';
 export * from './Charts/index.js';
 // TreeView generic hierarchical component
 export * from './TreeView/index.js';
+// Settings system - data-driven settings component
+export * from './Settings/index.js';
 // Logger utility for debugging and monitoring
 export * from './logger/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@smartnet360/svelte-components",
-	"version": "0.0.37",
+	"version": "0.0.39",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && npm run prepack",