@stephen-netu/design-system 0.1.0 → 0.2.0

package/dist/s0-state/create-store.d.ts

@@ -0,0 +1,23 @@
+export interface PersistenceConfig {
+    key: string;
+    storage: 'localStorage' | 'IndexedDB';
+    serialize?: (value: unknown) => string;
+    deserialize?: (value: string) => unknown;
+}
+export interface StoreOptions<T> {
+    initial: T;
+    persist?: PersistenceConfig;
+    debug?: boolean;
+}
+interface Store<T> {
+    readonly value: T;
+    set(value: T): void;
+    update(fn: (value: T) => T): void;
+    subscribe(fn: (value: T) => void): () => void;
+}
+/**
+ * Create a reactive store using Svelte 5 runes
+ */
+export declare function createStore<T>(options: StoreOptions<T>): Store<T>;
+export {};
+//# sourceMappingURL=create-store.d.ts.map

package/dist/s0-state/create-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-store.d.ts","sourceRoot":"","sources":["../../src/s0-state/create-store.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,cAAc,GAAG,WAAW,CAAC;IACtC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC;IACvC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;CAC1C;AAED,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,UAAU,KAAK,CAAC,CAAC;IACf,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,GAAG,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACpB,MAAM,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IAClC,SAAS,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC/C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAyDjE"}

package/dist/s0-state/create-store.js

@@ -0,0 +1,58 @@
+// Base store factory using Svelte 5 runes
+// This provides reactive state management without Svelte 4's writable/readable
+/**
+ * Create a reactive store using Svelte 5 runes
+ */
+export function createStore(options) {
+    let value = $state(options.initial);
+    const subscribers = new Set();
+    // Handle persistence
+    if (options.persist) {
+        if (typeof window !== 'undefined' && options.persist.storage === 'localStorage') {
+            const stored = localStorage.getItem(options.persist.key);
+            if (stored) {
+                try {
+                    const deserialized = options.persist.deserialize
+                        ? options.persist.deserialize(stored)
+                        : JSON.parse(stored);
+                    value = deserialized;
+                }
+                catch (e) {
+                    console.warn('[store] Failed to deserialize stored value for key:', options.persist.key, e);
+                }
+            }
+            // Set up effect to persist changes.
+            // $effect.root() so this works whether createStore() is called at module
+            // level (outside any component) or inside a component.
+            $effect.root(() => {
+                $effect(() => {
+                    const serialized = options.persist.serialize
+                        ? options.persist.serialize(value)
+                        : JSON.stringify(value);
+                    localStorage.setItem(options.persist.key, serialized);
+                });
+            });
+        }
+    }
+    function set(newValue) {
+        value = newValue;
+        if (options.debug) {
+            console.log(`[store] Set:`, value);
+        }
+        subscribers.forEach(fn => fn(value));
+    }
+    function update(fn) {
+        set(fn(value));
+    }
+    function subscribe(fn) {
+        subscribers.add(fn);
+        fn(value); // Immediate call with current value
+        return () => subscribers.delete(fn);
+    }
+    return {
+        get value() { return value; },
+        set,
+        update,
+        subscribe,
+    };
+}

package/dist/s0-state/derived.d.ts

@@ -0,0 +1,13 @@
+export interface DerivedOptions<T> {
+    debug?: boolean;
+}
+export interface Derived<T> {
+    readonly value: T;
+    subscribe(fn: (value: T) => void): () => void;
+}
+/**
+ * Create a derived value from source stores.
+ * Must be called during component initialization (where $derived is valid).
+ */
+export declare function createDerived<T>(fn: () => T, options?: DerivedOptions<T>): Derived<T>;
+//# sourceMappingURL=derived.d.ts.map

package/dist/s0-state/derived.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derived.d.ts","sourceRoot":"","sources":["../../src/s0-state/derived.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,OAAO,CAAC,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,SAAS,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC/C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,EAAE,EAAE,MAAM,CAAC,EACX,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC,CAAC,CAAC,CAoBZ"}

package/dist/s0-state/derived.js

@@ -0,0 +1,25 @@
+// Derived store helpers
+// NOTE: $derived runes only work inside Svelte component context (.svelte files).
+// This module is meant to be used from .svelte.ts files or component <script> blocks.
+/**
+ * Create a derived value from source stores.
+ * Must be called during component initialization (where $derived is valid).
+ */
+export function createDerived(fn, options) {
+    const value = $derived(fn());
+    const subscribers = new Set();
+    if (options?.debug) {
+        $effect(() => {
+            console.log(`[derived] Value:`, value);
+        });
+    }
+    function subscribe(cb) {
+        subscribers.add(cb);
+        cb(value);
+        return () => subscribers.delete(cb);
+    }
+    return {
+        get value() { return value; },
+        subscribe,
+    };
+}

package/dist/s0-state/index.d.ts

@@ -0,0 +1,10 @@
+export { createStore } from './create-store';
+export { createDerived } from './derived';
+export type { StoreOptions, PersistenceConfig } from './create-store';
+export type { DerivedOptions } from './derived';
+export { createVirtualList, createVirtualGrid, createPreloader, calculateGridLayout, type VirtualListConfig, type VirtualItem, type VirtualList, type PreloaderConfig, type PreloaderState, } from './virtual';
+export { default as SyncStatus } from './SyncStatus.svelte';
+export type { SyncStatusState, SyncStatusAction } from './SyncStatus.svelte';
+export type { ModalData } from './modal-stack-store.svelte';
+export type { ThemeName } from './ThemeStore.svelte';
+//# sourceMappingURL=index.d.ts.map

package/dist/s0-state/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/s0-state/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACtE,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGhD,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,mBAAmB,EACnB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,WAAW,CAAC;AAGnB,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAC5D,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAG7E,YAAY,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAG5D,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/s0-state/index.js

@@ -0,0 +1,7 @@
+// S0 State — Store primitives using Svelte 5 runes
+export { createStore } from './create-store';
+export { createDerived } from './derived';
+// New from NNJAS port - Virtual scrolling
+export { createVirtualList, createVirtualGrid, createPreloader, calculateGridLayout, } from './virtual';
+// New from NNJAS port - Sync status component
+export { default as SyncStatus } from './SyncStatus.svelte';

package/dist/s0-state/modal-stack-store.svelte.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Modal Stack Store — Stack-based modal management for @kos/design-system.
+ *
+ * Manages a stack of modals (not just one). Opening a modal pushes onto the
+ * stack; closing pops. Enables "back" navigation when opening modals from
+ * within other modals.
+ *
+ * Adopted from Chronicler's modalStack.ts pattern (2026-05-25 investigation).
+ *
+ * Usage:
+ *   import { modalStackStore } from '@kos/design-system';
+ *
+ *   // Push a modal
+ *   modalStackStore.push({ id: 'confirm-delete', props: { itemId: 'abc' } });
+ *
+ *   // Pop (returns to previous modal, or closes all if stack is empty)
+ *   modalStackStore.pop();
+ *
+ *   // Close all modals
+ *   modalStackStore.closeAll();
+ *
+ *   // In component:
+ *   const activeModal = modalStackStore.active;
+ *   const stackDepth = modalStackStore.depth;
+ */
+export interface ModalData {
+    id: string;
+    props?: Record<string, unknown>;
+    onClose?: () => void;
+}
+declare class ModalStackStore {
+    private stack;
+    get active(): ModalData | null;
+    get depth(): number;
+    get all(): readonly ModalData[];
+    push(modal: ModalData): void;
+    pop(): void;
+    closeAll(): void;
+    removeById(id: string): void;
+}
+export declare const modalStackStore: ModalStackStore;
+export {};
+//# sourceMappingURL=modal-stack-store.svelte.d.ts.map

package/dist/s0-state/modal-stack-store.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modal-stack-store.svelte.d.ts","sourceRoot":"","sources":["../../src/s0-state/modal-stack-store.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB;AAED,cAAM,eAAe;IACnB,OAAO,CAAC,KAAK,CAA2B;IAExC,IAAI,MAAM,IAAI,SAAS,GAAG,IAAI,CAG7B;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,GAAG,IAAI,SAAS,SAAS,EAAE,CAE9B;IAED,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAI5B,GAAG,IAAI,IAAI;IAOX,QAAQ,IAAI,IAAI;IAMhB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;CAO7B;AAED,eAAO,MAAM,eAAe,iBAAwB,CAAC"}

package/dist/s0-state/modal-stack-store.svelte.js

@@ -0,0 +1,63 @@
+/**
+ * Modal Stack Store — Stack-based modal management for @kos/design-system.
+ *
+ * Manages a stack of modals (not just one). Opening a modal pushes onto the
+ * stack; closing pops. Enables "back" navigation when opening modals from
+ * within other modals.
+ *
+ * Adopted from Chronicler's modalStack.ts pattern (2026-05-25 investigation).
+ *
+ * Usage:
+ *   import { modalStackStore } from '@kos/design-system';
+ *
+ *   // Push a modal
+ *   modalStackStore.push({ id: 'confirm-delete', props: { itemId: 'abc' } });
+ *
+ *   // Pop (returns to previous modal, or closes all if stack is empty)
+ *   modalStackStore.pop();
+ *
+ *   // Close all modals
+ *   modalStackStore.closeAll();
+ *
+ *   // In component:
+ *   const activeModal = modalStackStore.active;
+ *   const stackDepth = modalStackStore.depth;
+ */
+class ModalStackStore {
+    stack = $state([]);
+    get active() {
+        if (this.stack.length === 0)
+            return null;
+        return this.stack[this.stack.length - 1];
+    }
+    get depth() {
+        return this.stack.length;
+    }
+    get all() {
+        return this.stack;
+    }
+    push(modal) {
+        this.stack = [...this.stack, modal];
+    }
+    pop() {
+        if (this.stack.length === 0)
+            return;
+        const closing = this.stack[this.stack.length - 1];
+        this.stack = this.stack.slice(0, -1);
+        closing.onClose?.();
+    }
+    closeAll() {
+        while (this.stack.length > 0) {
+            this.pop();
+        }
+    }
+    removeById(id) {
+        const idx = this.stack.findIndex(m => m.id === id);
+        if (idx === -1)
+            return;
+        const removing = this.stack[idx];
+        this.stack = this.stack.filter(m => m.id !== id);
+        removing.onClose?.();
+    }
+}
+export const modalStackStore = new ModalStackStore();

package/dist/s0-state/virtual.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Virtual Scrolling Utilities
+ *
+ * Generalized versions of NNJAS lazyLoad utilities for the LEAP design system.
+ * Provides virtual list calculations and preloading for performance-critical lists.
+ */
+export interface VirtualListConfig {
+    /** Total number of items */
+    itemCount: number;
+    /** Height of each item in pixels */
+    itemHeight: number;
+    /** Number of items to render outside visible area (for smoother scrolling) */
+    overscan: number;
+    /** Height of the container viewport */
+    containerHeight: number;
+}
+export interface VirtualItem {
+    index: number;
+    /** Offset from top of container in pixels */
+    offset: number;
+    /** Whether this item is currently visible */
+    isVisible: boolean;
+}
+export interface VirtualList {
+    /** Get visible items for a given scroll position */
+    getVisibleItems(scrollTop: number): VirtualItem[];
+    /** Total height of the virtual container */
+    totalHeight: number;
+}
+/**
+ * Create a virtual list calculator
+ *
+ * Efficiently calculates which items should be rendered based on scroll position.
+ * Use with fixed-height items (grid rows, list items).
+ *
+ * @example
+ * const virtualList = createVirtualList({
+ *   itemCount: 1000,
+ *   itemHeight: 50,
+ *   overscan: 5,
+ *   containerHeight: 400
+ * });
+ *
+ * // In scroll handler
+ * const visible = virtualList.getVisibleItems(scrollTop);
+ */
+export declare function createVirtualList<T>(config: VirtualListConfig): VirtualList;
+export interface PreloaderConfig {
+    /** Number of items/screens to preload ahead of visible area */
+    preloadAhead: number;
+    /** Number of items/screens to keep loaded behind visible area */
+    keepBehind?: number;
+}
+export interface PreloaderState<T> {
+    /** Items currently loaded */
+    loaded: Set<T>;
+    /** Items currently loading */
+    loading: Set<T>;
+    /** Items that should be unloaded */
+    toUnload: Set<T>;
+}
+/**
+ * Create a preloader for managing lazy-loaded content
+ *
+ * Tracks what should be loaded based on visible range and preload configuration.
+ *
+ * @example
+ * const preloader = createPreloader({ preloadAhead: 2 });
+ *
+ * // In effect
+ * $effect(() => {
+ *   const visibleIds = getVisibleItemIds();
+ *   const state = preloader.update(visibleIds);
+ *   // Load state.toLoad, unload state.toUnload
+ * });
+ */
+export declare function createPreloader<T extends string | number>(config: PreloaderConfig): {
+    /**
+     * Update preloader state based on currently visible items
+     * @param visibleIds - IDs of items currently visible
+     * @param allIds - All available item IDs (for calculating preload range)
+     * @returns State indicating what to load and unload
+     */
+    update(visibleIds: T[], allIds: T[]): {
+        toLoad: T[];
+        toUnload: T[];
+        loaded: Set<T>;
+        loading: Set<T>;
+    };
+    /** Mark an item as loading */
+    markLoading(id: T): void;
+    /** Mark an item as loaded (removes from loading, adds to loaded) */
+    markLoaded(id: T): void;
+    /** Mark an item as unloaded */
+    markUnloaded(id: T): void;
+    /** Get current state */
+    getState(): PreloaderState<T>;
+    /** Reset all state */
+    reset(): void;
+};
+/**
+ * Calculate grid layout for virtual scrolling
+ *
+ * Helper for grid-based virtual scrolling (masonry, card grids).
+ *
+ * @example
+ * const grid = calculateGridLayout({
+ *   totalItems: 100,
+ *   containerWidth: 800,
+   itemWidth: 150,
+ *   gap: 16
+ * });
+ * // grid.columns = 5, grid.rows = 20
+ */
+export declare function calculateGridLayout(config: {
+    totalItems: number;
+    containerWidth: number;
+    itemWidth: number;
+    gap: number;
+}): {
+    columns: number;
+    rows: number;
+    effectiveWidth: number;
+};
+/**
+ * Create a virtual grid calculator
+ *
+ * Specialized virtual list for grid layouts with fixed item sizes.
+ * Returns row-based virtual items that can be flattened to individual items.
+ *
+ * @example
+ * const virtualGrid = createVirtualGrid({
+ *   totalItems: 500,
+ *   columns: 5,
+ *   itemHeight: 120,
+ *   gap: 8,
+ *   overscan: 2,
+ *   containerHeight: 600
+ * });
+ */
+export declare function createVirtualGrid(config: {
+    totalItems: number;
+    columns: number;
+    itemHeight: number;
+    gap: number;
+    overscan: number;
+    containerHeight: number;
+}): {
+    getVisibleRows(scrollTop: number): VirtualItem[];
+    getItemsInRow(rowIndex: number): number[];
+    totalHeight: number;
+    totalRows: number;
+};
+//# sourceMappingURL=virtual.d.ts.map

package/dist/s0-state/virtual.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual.d.ts","sourceRoot":"","sources":["../../src/s0-state/virtual.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,iBAAiB;IAChC,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;IAClD,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,iBAAiB,GAAG,WAAW,CA2B3E;AAED,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,6BAA6B;IAC7B,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IACf,8BAA8B;IAC9B,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IAChB,oCAAoC;IACpC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;CAClB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,MAAM,EAAE,eAAe;IAM9E;;;;;OAKG;uBAEW,CAAC,EAAE,UACP,CAAC,EAAE,GACV;QAAE,MAAM,EAAE,CAAC,EAAE,CAAC;QAAC,QAAQ,EAAE,CAAC,EAAE,CAAC;QAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;QAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAA;KAAE;IAwClE,8BAA8B;oBACd,CAAC;IAIjB,oEAAoE;mBACrD,CAAC;IAKhB,+BAA+B;qBACd,CAAC;IAKlB,wBAAwB;gBACZ,cAAc,CAAC,CAAC,CAAC;IAQ7B,sBAAsB;;EAMzB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;CACb,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAS5D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;CACzB,GAAG;IACF,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;IACjD,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB,CA0CA"}

package/dist/s0-state/virtual.js

@@ -0,0 +1,207 @@
+/**
+ * Virtual Scrolling Utilities
+ *
+ * Generalized versions of NNJAS lazyLoad utilities for the LEAP design system.
+ * Provides virtual list calculations and preloading for performance-critical lists.
+ */
+/**
+ * Create a virtual list calculator
+ *
+ * Efficiently calculates which items should be rendered based on scroll position.
+ * Use with fixed-height items (grid rows, list items).
+ *
+ * @example
+ * const virtualList = createVirtualList({
+ *   itemCount: 1000,
+ *   itemHeight: 50,
+ *   overscan: 5,
+ *   containerHeight: 400
+ * });
+ *
+ * // In scroll handler
+ * const visible = virtualList.getVisibleItems(scrollTop);
+ */
+export function createVirtualList(config) {
+    const { itemCount, itemHeight, overscan, containerHeight } = config;
+    const totalHeight = itemCount * itemHeight;
+    return {
+        getVisibleItems(scrollTop) {
+            // Calculate visible range
+            const startIndex = Math.floor(scrollTop / itemHeight);
+            const visibleCount = Math.ceil(containerHeight / itemHeight);
+            // Add overscan
+            const renderStart = Math.max(0, startIndex - overscan);
+            const renderEnd = Math.min(itemCount, startIndex + visibleCount + overscan);
+            const items = [];
+            for (let i = renderStart; i < renderEnd; i++) {
+                items.push({
+                    index: i,
+                    offset: i * itemHeight,
+                    isVisible: i >= startIndex && i < startIndex + visibleCount
+                });
+            }
+            return items;
+        },
+        totalHeight
+    };
+}
+/**
+ * Create a preloader for managing lazy-loaded content
+ *
+ * Tracks what should be loaded based on visible range and preload configuration.
+ *
+ * @example
+ * const preloader = createPreloader({ preloadAhead: 2 });
+ *
+ * // In effect
+ * $effect(() => {
+ *   const visibleIds = getVisibleItemIds();
+ *   const state = preloader.update(visibleIds);
+ *   // Load state.toLoad, unload state.toUnload
+ * });
+ */
+export function createPreloader(config) {
+    const { preloadAhead, keepBehind = 1 } = config;
+    const loaded = new Set();
+    const loading = new Set();
+    return {
+        /**
+         * Update preloader state based on currently visible items
+         * @param visibleIds - IDs of items currently visible
+         * @param allIds - All available item IDs (for calculating preload range)
+         * @returns State indicating what to load and unload
+         */
+        update(visibleIds, allIds) {
+            const visibleSet = new Set(visibleIds);
+            // Calculate preload range indices
+            const visibleIndices = visibleIds
+                .map(id => allIds.indexOf(id))
+                .filter(i => i >= 0)
+                .sort((a, b) => a - b);
+            if (visibleIndices.length === 0) {
+                return { toLoad: [], toUnload: [...loaded], loaded, loading };
+            }
+            const firstVisible = visibleIndices[0];
+            const lastVisible = visibleIndices[visibleIndices.length - 1];
+            // Calculate range to keep loaded
+            const keepStart = Math.max(0, firstVisible - keepBehind);
+            const keepEnd = Math.min(allIds.length, lastVisible + preloadAhead);
+            const toKeep = new Set(allIds.slice(keepStart, keepEnd));
+            // Determine what to load and unload
+            const toLoad = [];
+            for (const id of toKeep) {
+                if (!loaded.has(id) && !loading.has(id)) {
+                    toLoad.push(id);
+                }
+            }
+            const toUnload = [];
+            for (const id of loaded) {
+                if (!toKeep.has(id) && !visibleSet.has(id)) {
+                    toUnload.push(id);
+                }
+            }
+            return { toLoad, toUnload, loaded, loading };
+        },
+        /** Mark an item as loading */
+        markLoading(id) {
+            loading.add(id);
+        },
+        /** Mark an item as loaded (removes from loading, adds to loaded) */
+        markLoaded(id) {
+            loading.delete(id);
+            loaded.add(id);
+        },
+        /** Mark an item as unloaded */
+        markUnloaded(id) {
+            loaded.delete(id);
+            loading.delete(id);
+        },
+        /** Get current state */
+        getState() {
+            return {
+                loaded: new Set(loaded),
+                loading: new Set(loading),
+                toUnload: new Set()
+            };
+        },
+        /** Reset all state */
+        reset() {
+            loaded.clear();
+            loading.clear();
+        }
+    };
+}
+/**
+ * Calculate grid layout for virtual scrolling
+ *
+ * Helper for grid-based virtual scrolling (masonry, card grids).
+ *
+ * @example
+ * const grid = calculateGridLayout({
+ *   totalItems: 100,
+ *   containerWidth: 800,
+   itemWidth: 150,
+ *   gap: 16
+ * });
+ * // grid.columns = 5, grid.rows = 20
+ */
+export function calculateGridLayout(config) {
+    const { totalItems, containerWidth, itemWidth, gap } = config;
+    // Calculate columns that fit
+    const columns = Math.max(1, Math.floor((containerWidth + gap) / (itemWidth + gap)));
+    const effectiveWidth = columns * itemWidth + (columns - 1) * gap;
+    const rows = Math.ceil(totalItems / columns);
+    return { columns, rows, effectiveWidth };
+}
+/**
+ * Create a virtual grid calculator
+ *
+ * Specialized virtual list for grid layouts with fixed item sizes.
+ * Returns row-based virtual items that can be flattened to individual items.
+ *
+ * @example
+ * const virtualGrid = createVirtualGrid({
+ *   totalItems: 500,
+ *   columns: 5,
+ *   itemHeight: 120,
+ *   gap: 8,
+ *   overscan: 2,
+ *   containerHeight: 600
+ * });
+ */
+export function createVirtualGrid(config) {
+    const { totalItems, columns, itemHeight, gap, overscan, containerHeight } = config;
+    const rowHeight = itemHeight + gap;
+    const totalRows = Math.ceil(totalItems / columns);
+    const totalHeight = totalRows * rowHeight - gap; // Subtract trailing gap
+    return {
+        getVisibleRows(scrollTop) {
+            const startRow = Math.floor(scrollTop / rowHeight);
+            const visibleRows = Math.ceil(containerHeight / rowHeight);
+            const renderStart = Math.max(0, startRow - overscan);
+            const renderEnd = Math.min(totalRows, startRow + visibleRows + overscan);
+            const rows = [];
+            for (let i = renderStart; i < renderEnd; i++) {
+                rows.push({
+                    index: i,
+                    offset: i * rowHeight,
+                    isVisible: i >= startRow && i < startRow + visibleRows
+                });
+            }
+            return rows;
+        },
+        getItemsInRow(rowIndex) {
+            const startIndex = rowIndex * columns;
+            const items = [];
+            for (let i = 0; i < columns; i++) {
+                const index = startIndex + i;
+                if (index < totalItems) {
+                    items.push(index);
+                }
+            }
+            return items;
+        },
+        totalHeight,
+        totalRows
+    };
+}

package/{src → dist}/showcase/Showcase.svelte

@@ -323,7 +323,7 @@
           <h3>Component Color Coding</h3>
           <div class="demo-row">
             <div style="display: flex; flex-direction: column; gap: 0.5rem;">
-              {#each Object.entries({ 'rust-crate': '#b87333', 'ui-bundle': '#5f9ea0', 'config': '#daa520', 'faculty-state': '#9370db', 'substrate-binary': '#cd5c5c', 'system-snapshot': '#2f4f4f' }) as [type, color]}
+              {#each Object.entries({ 'rust-crate': 'var(--color-accent)', 'ui-bundle': '#5f9ea0', 'config': '#daa520', 'faculty-state': '#9370db', 'substrate-binary': '#cd5c5c', 'system-snapshot': '#2f4f4f' }) as [type, color]}
                 <div style="display: flex; align-items: center; gap: 0.75rem;">
                   <span style="color: {color}; font-size: 16px;">◉</span>
                   <span style="font-size: 0.85rem; color: var(--color-text-secondary); font-family: var(--font-mono);">{type}</span>

package/dist/showcase/Showcase.svelte.d.ts

@@ -0,0 +1,4 @@
+declare const Showcase: import("svelte").Component<Record<string, never>, {}, "">;
+type Showcase = ReturnType<typeof Showcase>;
+export default Showcase;
+//# sourceMappingURL=Showcase.svelte.d.ts.map

package/dist/showcase/Showcase.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Showcase.svelte.d.ts","sourceRoot":"","sources":["../../src/showcase/Showcase.svelte.ts"],"names":[],"mappings":"AAySA,QAAA,MAAM,QAAQ,2DAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}