flikkui 0.1.0-beta.11 → 0.1.0-beta.12

package/dist/utils/actionQueue.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Action Queue for Offline Support
+ * Manages queued mutations when the user is offline
+ */
+/**
+ * Queued action interface
+ */
+export interface QueuedAction<T = unknown> {
+    /** Unique identifier for the action */
+    id: string;
+    /** Function to execute when online */
+    action: () => Promise<T>;
+    /** Timestamp when action was queued */
+    timestamp: number;
+    /** Number of retry attempts */
+    retryCount: number;
+    /** Maximum retry attempts */
+    maxRetries: number;
+    /** Optional metadata for display */
+    metadata?: {
+        label?: string;
+        description?: string;
+    };
+}
+/**
+ * Configuration options for ActionQueue
+ */
+export interface ActionQueueOptions {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Key for localStorage persistence (default: 'flikkui-action-queue') */
+    storageKey?: string;
+    /** Whether to persist queue to localStorage (default: true) */
+    persist?: boolean;
+    /** Called when an action is processed successfully */
+    onActionSuccess?: <T>(action: QueuedAction<T>, result: T) => void;
+    /** Called when an action fails after all retries */
+    onActionFailed?: <T>(action: QueuedAction<T>, error: Error) => void;
+    /** Called when queue changes */
+    onQueueChange?: (queue: QueuedAction[]) => void;
+}
+/**
+ * Options for adding an action to the queue
+ */
+export interface AddActionOptions {
+    /** Maximum retry attempts for this specific action */
+    maxRetries?: number;
+    /** Label for the action (shown in OfflineIndicator) */
+    label?: string;
+    /** Description for the action */
+    description?: string;
+}
+/**
+ * ActionQueue class for managing offline mutations
+ */
+export declare class ActionQueue {
+    private queue;
+    private isProcessing;
+    private options;
+    constructor(options?: ActionQueueOptions);
+    /**
+     * Generate a unique ID for an action
+     */
+    private generateId;
+    /**
+     * Save queue to localStorage
+     */
+    private saveToStorage;
+    /**
+     * Load queue from localStorage
+     * Note: Actions (functions) cannot be persisted, only metadata
+     */
+    private loadFromStorage;
+    /**
+     * Notify listeners of queue changes
+     */
+    private notifyChange;
+    /**
+     * Add an action to the queue
+     * @returns The action ID
+     */
+    add<T>(action: () => Promise<T>, options?: AddActionOptions): string;
+    /**
+     * Remove an action from the queue
+     */
+    remove(id: string): boolean;
+    /**
+     * Get all queued actions
+     */
+    getAll(): QueuedAction[];
+    /**
+     * Get the number of queued actions
+     */
+    get size(): number;
+    /**
+     * Check if queue is currently processing
+     */
+    get processing(): boolean;
+    /**
+     * Clear all queued actions
+     */
+    clear(): void;
+    /**
+     * Process all queued actions
+     * Call this when the user comes back online
+     */
+    process(): Promise<void>;
+}
+/**
+ * Create an ActionQueue instance
+ */
+export declare const createActionQueue: (options?: ActionQueueOptions) => ActionQueue;
+export declare const getDefaultQueue: () => ActionQueue;

package/dist/utils/actionQueue.js

@@ -0,0 +1,233 @@
+import { __spreadArray, __awaiter, __generator } from '/Users/ggn/Development/ui-flik/node_modules/tslib/tslib.es6.js';
+import { QueueError } from './optimisticErrors.js';
+
+/**
+ * Action Queue for Offline Support
+ * Manages queued mutations when the user is offline
+ */
+/**
+ * ActionQueue class for managing offline mutations
+ */
+var ActionQueue = /** @class */ (function () {
+    function ActionQueue(options) {
+        if (options === void 0) { options = {}; }
+        var _a, _b, _c;
+        this.queue = [];
+        this.isProcessing = false;
+        this.options = {
+            maxRetries: (_a = options.maxRetries) !== null && _a !== void 0 ? _a : 3,
+            storageKey: (_b = options.storageKey) !== null && _b !== void 0 ? _b : "flikkui-action-queue",
+            persist: (_c = options.persist) !== null && _c !== void 0 ? _c : true,
+            onActionSuccess: options.onActionSuccess,
+            onActionFailed: options.onActionFailed,
+            onQueueChange: options.onQueueChange,
+        };
+        // Load persisted queue on initialization
+        if (this.options.persist) {
+            this.loadFromStorage();
+        }
+    }
+    /**
+     * Generate a unique ID for an action
+     */
+    ActionQueue.prototype.generateId = function () {
+        return "action-".concat(Date.now(), "-").concat(Math.random().toString(36).slice(2, 9));
+    };
+    /**
+     * Save queue to localStorage
+     */
+    ActionQueue.prototype.saveToStorage = function () {
+        if (!this.options.persist || typeof window === "undefined")
+            return;
+        try {
+            // We can't serialize functions, so we only persist metadata
+            var persistableQueue = this.queue.map(function (_a) {
+                var id = _a.id, timestamp = _a.timestamp, retryCount = _a.retryCount, maxRetries = _a.maxRetries, metadata = _a.metadata;
+                return ({
+                    id: id,
+                    timestamp: timestamp,
+                    retryCount: retryCount,
+                    maxRetries: maxRetries,
+                    metadata: metadata,
+                });
+            });
+            localStorage.setItem(this.options.storageKey, JSON.stringify(persistableQueue));
+        }
+        catch (_a) {
+            // localStorage might be unavailable or full
+            if (process.env.NODE_ENV !== "production") {
+                console.warn("[ActionQueue] Failed to persist queue to localStorage");
+            }
+        }
+    };
+    /**
+     * Load queue from localStorage
+     * Note: Actions (functions) cannot be persisted, only metadata
+     */
+    ActionQueue.prototype.loadFromStorage = function () {
+        if (typeof window === "undefined")
+            return;
+        try {
+            var stored = localStorage.getItem(this.options.storageKey);
+            if (stored) {
+                // Only load metadata - actions will need to be re-registered
+                var parsed = JSON.parse(stored);
+                if (process.env.NODE_ENV !== "production" && parsed.length > 0) {
+                    console.warn("[ActionQueue] Found ".concat(parsed.length, " stale queued actions. Actions cannot be restored after page reload."));
+                }
+                // Clear stale entries
+                localStorage.removeItem(this.options.storageKey);
+            }
+        }
+        catch (_a) {
+            // localStorage might be unavailable
+        }
+    };
+    /**
+     * Notify listeners of queue changes
+     */
+    ActionQueue.prototype.notifyChange = function () {
+        var _a, _b;
+        this.saveToStorage();
+        (_b = (_a = this.options).onQueueChange) === null || _b === void 0 ? void 0 : _b.call(_a, this.queue);
+    };
+    /**
+     * Add an action to the queue
+     * @returns The action ID
+     */
+    ActionQueue.prototype.add = function (action, options) {
+        var _a;
+        var id = this.generateId();
+        var queuedAction = {
+            id: id,
+            action: action,
+            timestamp: Date.now(),
+            retryCount: 0,
+            maxRetries: (_a = options === null || options === void 0 ? void 0 : options.maxRetries) !== null && _a !== void 0 ? _a : this.options.maxRetries,
+            metadata: {
+                label: options === null || options === void 0 ? void 0 : options.label,
+                description: options === null || options === void 0 ? void 0 : options.description,
+            },
+        };
+        this.queue.push(queuedAction);
+        this.notifyChange();
+        return id;
+    };
+    /**
+     * Remove an action from the queue
+     */
+    ActionQueue.prototype.remove = function (id) {
+        var initialLength = this.queue.length;
+        this.queue = this.queue.filter(function (action) { return action.id !== id; });
+        if (this.queue.length !== initialLength) {
+            this.notifyChange();
+            return true;
+        }
+        return false;
+    };
+    /**
+     * Get all queued actions
+     */
+    ActionQueue.prototype.getAll = function () {
+        return __spreadArray([], this.queue, true);
+    };
+    Object.defineProperty(ActionQueue.prototype, "size", {
+        /**
+         * Get the number of queued actions
+         */
+        get: function () {
+            return this.queue.length;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(ActionQueue.prototype, "processing", {
+        /**
+         * Check if queue is currently processing
+         */
+        get: function () {
+            return this.isProcessing;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    /**
+     * Clear all queued actions
+     */
+    ActionQueue.prototype.clear = function () {
+        this.queue = [];
+        this.notifyChange();
+    };
+    /**
+     * Process all queued actions
+     * Call this when the user comes back online
+     */
+    ActionQueue.prototype.process = function () {
+        return __awaiter(this, void 0, void 0, function () {
+            var action, result, error_1;
+            var _a, _b, _c, _d;
+            return __generator(this, function (_e) {
+                switch (_e.label) {
+                    case 0:
+                        if (this.isProcessing || this.queue.length === 0)
+                            return [2 /*return*/];
+                        this.isProcessing = true;
+                        _e.label = 1;
+                    case 1:
+                        if (!(this.queue.length > 0)) return [3 /*break*/, 6];
+                        action = this.queue[0];
+                        _e.label = 2;
+                    case 2:
+                        _e.trys.push([2, 4, , 5]);
+                        return [4 /*yield*/, action.action()];
+                    case 3:
+                        result = _e.sent();
+                        (_b = (_a = this.options).onActionSuccess) === null || _b === void 0 ? void 0 : _b.call(_a, action, result);
+                        this.queue.shift(); // Remove successful action
+                        this.notifyChange();
+                        return [3 /*break*/, 5];
+                    case 4:
+                        error_1 = _e.sent();
+                        action.retryCount++;
+                        if (action.retryCount >= action.maxRetries) {
+                            // Max retries reached, remove and report failure
+                            (_d = (_c = this.options).onActionFailed) === null || _d === void 0 ? void 0 : _d.call(_c, action, error_1 instanceof Error
+                                ? error_1
+                                : new QueueError("Action failed after max retries", action.id, error_1));
+                            this.queue.shift();
+                            this.notifyChange();
+                        }
+                        else {
+                            // Will retry on next process() call
+                            this.notifyChange();
+                            return [3 /*break*/, 6]; // Stop processing, wait for next attempt
+                        }
+                        return [3 /*break*/, 5];
+                    case 5: return [3 /*break*/, 1];
+                    case 6:
+                        this.isProcessing = false;
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    return ActionQueue;
+}());
+/**
+ * Create an ActionQueue instance
+ */
+var createActionQueue = function (options) {
+    return new ActionQueue(options);
+};
+/**
+ * Default singleton queue for simple use cases
+ */
+var defaultQueue = null;
+var getDefaultQueue = function () {
+    if (!defaultQueue) {
+        defaultQueue = createActionQueue();
+    }
+    return defaultQueue;
+};
+
+export { ActionQueue, createActionQueue, getDefaultQueue };

package/dist/utils/cn.js

@@ -1,5 +1,5 @@
-import { clsx } from '../node_modules/clsx/dist/clsx.js';
-import { twMerge } from '../node_modules/tailwind-merge/dist/bundle-mjs.js';
+import { clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
 
 function cn() {
     var inputs = [];

package/dist/utils/dateUtils.js

@@ -1,4 +1,4 @@
-import { __assign } from '../node_modules/tslib/tslib.es6.js';
+import { __assign } from '/Users/ggn/Development/ui-flik/node_modules/tslib/tslib.es6.js';
 
 /**
  * Date and time utility functions for consistent formatting across the component library

package/dist/utils/formValidation.d.ts

@@ -0,0 +1,20 @@
+import { StateIdentifier, StateMachineConfig } from "./stateMachine";
+/**
+ * Result of a step validation
+ * Can be a boolean, a string (single error), or an array of strings (multiple errors)
+ */
+export type ValidationResult = boolean | string | string[];
+/**
+ * Enhanced configuration that includes validation predicates for each step
+ */
+export interface ValidatedStateMachineConfig<TData> extends StateMachineConfig<TData> {
+    /** Map of states to validation functions */
+    validation?: Record<StateIdentifier, (data: TData) => ValidationResult | Promise<ValidationResult>>;
+}
+/**
+ * Helper to validate the data for a specific state
+ */
+export declare function validateStep<TData>(config: ValidatedStateMachineConfig<TData>, state: StateIdentifier, data: TData): Promise<{
+    success: boolean;
+    errors?: string[];
+}>;

package/dist/utils/formValidation.js

@@ -0,0 +1,33 @@
+import { __awaiter, __generator } from '/Users/ggn/Development/ui-flik/node_modules/tslib/tslib.es6.js';
+
+/**
+ * Helper to validate the data for a specific state
+ */
+function validateStep(config, state, data) {
+    return __awaiter(this, void 0, void 0, function () {
+        var validator, result;
+        var _a;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    validator = (_a = config.validation) === null || _a === void 0 ? void 0 : _a[state];
+                    if (!validator)
+                        return [2 /*return*/, { success: true }];
+                    return [4 /*yield*/, validator(data)];
+                case 1:
+                    result = _b.sent();
+                    if (result === true)
+                        return [2 /*return*/, { success: true }];
+                    if (result === false)
+                        return [2 /*return*/, { success: false, errors: ["Invalid step data"] }];
+                    if (typeof result === "string")
+                        return [2 /*return*/, { success: false, errors: [result] }];
+                    if (Array.isArray(result))
+                        return [2 /*return*/, { success: false, errors: result }];
+                    return [2 /*return*/, { success: true }];
+            }
+        });
+    });
+}
+
+export { validateStep };

package/dist/utils/index.d.ts

@@ -1,6 +1,14 @@
-export { cn } from './cn';
-export { debounce } from './debounce';
-export { formatTimestamp, formatDate, formatTime, formatDateCustom, formatRelativeTime, isToday, isYesterday, isThisWeek, getLastNDays, getThisWeek, getLastWeek, getThisMonth, getLastMonth, getThisYear, getLastYear, type DateInput, type TimestampOptions, type DateRange, } from './dateUtils';
-export { useClickOutside } from './useClickOutside';
-export { findNextMatchingOption, isValidTypeaheadChar, TYPEAHEAD_TIMEOUT_MS, type TypeaheadOption, type FindNextMatchingOptionParams, } from './typeaheadUtils';
-export { timeToMinutes, minutesToTime, getEventDuration, getTotalTimeSlots, getTimeSlotIndex, getTimeSlotForIndex, calculateEventPosition, calculateEventHeight, eventsOverlap, findOverlappingEvents, groupOverlappingEvents, resolveOverlappingEvents, generateTimeGrid, filterEventsByDate, sortEventsByStartTime, separateAllDayEvents, isValidTimeFormat, isValidDateFormat, validateEvent, DEFAULT_GRID_CONFIGS, type CalendarEvent, type GridConfig, type EventPosition, type EventLayout, type TimeSlot, } from './calendarUtils';
+export { cn } from "./cn";
+export { debounce } from "./debounce";
+export { formatTimestamp, formatDate, formatTime, formatDateCustom, formatRelativeTime, isToday, isYesterday, isThisWeek, getLastNDays, getThisWeek, getLastWeek, getThisMonth, getLastMonth, getThisYear, getLastYear, type DateInput, type TimestampOptions, type DateRange, } from "./dateUtils";
+export { useClickOutside } from "./useClickOutside";
+export { findNextMatchingOption, isValidTypeaheadChar, TYPEAHEAD_TIMEOUT_MS, type TypeaheadOption, type FindNextMatchingOptionParams, } from "./typeaheadUtils";
+export { timeToMinutes, minutesToTime, getEventDuration, getTotalTimeSlots, getTimeSlotIndex, getTimeSlotForIndex, calculateEventPosition, calculateEventHeight, eventsOverlap, findOverlappingEvents, groupOverlappingEvents, resolveOverlappingEvents, generateTimeGrid, filterEventsByDate, sortEventsByStartTime, separateAllDayEvents, isValidTimeFormat, isValidDateFormat, validateEvent, DEFAULT_GRID_CONFIGS, type CalendarEvent, type GridConfig, type EventPosition, type EventLayout, type TimeSlot, } from "./calendarUtils";
+export { parseOpenAI, parseAnthropic, parseGemini, parseSSELine, SSE_PARSERS, type SSEFormat, type SSEParser, } from "./sseFormatParsers";
+export { StreamingNetworkError, StreamingTimeoutError, StreamingParseError, StreamingAbortError, StreamingServerError, normalizeError, type StreamingError, } from "./streamingErrors";
+export { calculateRetryDelay, shouldRetry, type RetryConfig, } from "./retryUtils";
+export { MutationError, RollbackError, QueueError, OptimisticNetworkError, normalizeOptimisticError, isOptimisticError, type OptimisticError, } from "./optimisticErrors";
+export { ActionQueue, createActionQueue, getDefaultQueue, type QueuedAction, type ActionQueueOptions, type AddActionOptions, } from "./actionQueue";
+export * from "./stateMachine";
+export * from "./formValidation";
+export { formatTypingText, formatPresenceCount, validatePresenceUser, validateTypingUser, sortUsers, } from "./presenceUtils";

package/dist/utils/optimisticErrors.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Optimistic Mutation Error Classes
+ * Defines error types for optimistic UI updates with rollback support
+ */
+/**
+ * Base optimistic error interface
+ */
+export interface OptimisticError {
+    type: "mutation" | "rollback" | "queue" | "network";
+    message: string;
+    originalData?: unknown;
+    rollbackData?: unknown;
+    retryable: boolean;
+}
+/**
+ * Mutation error - occurs when the server rejects the mutation
+ * Retryable: Depends on error type (network yes, validation no)
+ */
+export declare class MutationError extends Error implements OptimisticError {
+    retryable: boolean;
+    originalData?: unknown | undefined;
+    rollbackData?: unknown | undefined;
+    details?: unknown | undefined;
+    type: "mutation";
+    constructor(message: string, retryable?: boolean, originalData?: unknown | undefined, rollbackData?: unknown | undefined, details?: unknown | undefined);
+}
+/**
+ * Rollback error - occurs when attempting to rollback optimistic state fails
+ * Retryable: No (indicates a serious state corruption issue)
+ */
+export declare class RollbackError extends Error implements OptimisticError {
+    originalData?: unknown | undefined;
+    rollbackData?: unknown | undefined;
+    details?: unknown | undefined;
+    type: "rollback";
+    retryable: boolean;
+    constructor(message: string, originalData?: unknown | undefined, rollbackData?: unknown | undefined, details?: unknown | undefined);
+}
+/**
+ * Queue error - occurs when action queue operations fail
+ * Retryable: Yes (queue operations can be retried)
+ */
+export declare class QueueError extends Error implements OptimisticError {
+    actionId?: string | undefined;
+    details?: unknown | undefined;
+    type: "queue";
+    retryable: boolean;
+    constructor(message: string, actionId?: string | undefined, details?: unknown | undefined);
+    originalData: undefined;
+    rollbackData: undefined;
+}
+/**
+ * Network error for optimistic operations - typically connection issues
+ * Retryable: Yes
+ */
+export declare class OptimisticNetworkError extends Error implements OptimisticError {
+    originalData?: unknown | undefined;
+    rollbackData?: unknown | undefined;
+    details?: unknown | undefined;
+    type: "network";
+    retryable: boolean;
+    constructor(message: string, originalData?: unknown | undefined, rollbackData?: unknown | undefined, details?: unknown | undefined);
+}
+/**
+ * Normalize any error into an OptimisticError
+ * Used to convert unknown errors into typed optimistic errors
+ *
+ * @param error - Any error object
+ * @param context - Optional context for rollback (originalData, rollbackData)
+ * @returns Normalized OptimisticError
+ */
+export declare const normalizeOptimisticError: (error: unknown, context?: {
+    originalData?: unknown;
+    rollbackData?: unknown;
+}) => OptimisticError;
+/**
+ * Check if an error is an OptimisticError
+ */
+export declare const isOptimisticError: (error: unknown) => error is OptimisticError;

package/dist/utils/optimisticErrors.js

@@ -0,0 +1,111 @@
+import { __extends } from '/Users/ggn/Development/ui-flik/node_modules/tslib/tslib.es6.js';
+
+/**
+ * Optimistic Mutation Error Classes
+ * Defines error types for optimistic UI updates with rollback support
+ */
+/**
+ * Mutation error - occurs when the server rejects the mutation
+ * Retryable: Depends on error type (network yes, validation no)
+ */
+var MutationError = /** @class */ (function (_super) {
+    __extends(MutationError, _super);
+    function MutationError(message, retryable, originalData, rollbackData, details) {
+        if (retryable === void 0) { retryable = true; }
+        var _this = _super.call(this, message) || this;
+        _this.retryable = retryable;
+        _this.originalData = originalData;
+        _this.rollbackData = rollbackData;
+        _this.details = details;
+        _this.type = "mutation";
+        _this.name = "MutationError";
+        return _this;
+    }
+    return MutationError;
+}(Error));
+/**
+ * Rollback error - occurs when attempting to rollback optimistic state fails
+ * Retryable: No (indicates a serious state corruption issue)
+ */
+var RollbackError = /** @class */ (function (_super) {
+    __extends(RollbackError, _super);
+    function RollbackError(message, originalData, rollbackData, details) {
+        var _this = _super.call(this, message) || this;
+        _this.originalData = originalData;
+        _this.rollbackData = rollbackData;
+        _this.details = details;
+        _this.type = "rollback";
+        _this.retryable = false;
+        _this.name = "RollbackError";
+        return _this;
+    }
+    return RollbackError;
+}(Error));
+/**
+ * Queue error - occurs when action queue operations fail
+ * Retryable: Yes (queue operations can be retried)
+ */
+var QueueError = /** @class */ (function (_super) {
+    __extends(QueueError, _super);
+    function QueueError(message, actionId, details) {
+        var _this = _super.call(this, message) || this;
+        _this.actionId = actionId;
+        _this.details = details;
+        _this.type = "queue";
+        _this.retryable = true;
+        _this.name = "QueueError";
+        // Queue errors don't have original/rollback data
+        _this.originalData = undefined;
+        _this.rollbackData = undefined;
+        return _this;
+    }
+    return QueueError;
+}(Error));
+/**
+ * Network error for optimistic operations - typically connection issues
+ * Retryable: Yes
+ */
+var OptimisticNetworkError = /** @class */ (function (_super) {
+    __extends(OptimisticNetworkError, _super);
+    function OptimisticNetworkError(message, originalData, rollbackData, details) {
+        var _this = _super.call(this, message) || this;
+        _this.originalData = originalData;
+        _this.rollbackData = rollbackData;
+        _this.details = details;
+        _this.type = "network";
+        _this.retryable = true;
+        _this.name = "OptimisticNetworkError";
+        return _this;
+    }
+    return OptimisticNetworkError;
+}(Error));
+/**
+ * Normalize any error into an OptimisticError
+ * Used to convert unknown errors into typed optimistic errors
+ *
+ * @param error - Any error object
+ * @param context - Optional context for rollback (originalData, rollbackData)
+ * @returns Normalized OptimisticError
+ */
+var normalizeOptimisticError = function (error, context) {
+    // Already an optimistic error - return as-is
+    if (error instanceof MutationError ||
+        error instanceof RollbackError ||
+        error instanceof QueueError ||
+        error instanceof OptimisticNetworkError) {
+        return error;
+    }
+    // Handle fetch/network errors
+    if (error instanceof TypeError && error.message.includes("fetch")) {
+        return new OptimisticNetworkError(error.message, context === null || context === void 0 ? void 0 : context.originalData, context === null || context === void 0 ? void 0 : context.rollbackData, error);
+    }
+    // Handle AbortController abortion
+    if (error instanceof DOMException && error.name === "AbortError") {
+        return new MutationError("Request was aborted", false, // Not retryable - user initiated
+        context === null || context === void 0 ? void 0 : context.originalData, context === null || context === void 0 ? void 0 : context.rollbackData, error);
+    }
+    // Unknown error - treat as mutation error (retryable)
+    return new MutationError(error instanceof Error ? error.message : "Unknown mutation error", true, context === null || context === void 0 ? void 0 : context.originalData, context === null || context === void 0 ? void 0 : context.rollbackData, error);
+};
+
+export { MutationError, OptimisticNetworkError, QueueError, RollbackError, normalizeOptimisticError };