flikkui 0.1.0-beta.9 → 0.2.0-beta.1

package/dist/utils/optimisticErrors.js

@@ -0,0 +1,96 @@
+/**
+ * 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)
+ */
+class MutationError extends Error {
+    constructor(message, retryable = true, originalData, rollbackData, details) {
+        super(message);
+        this.retryable = retryable;
+        this.originalData = originalData;
+        this.rollbackData = rollbackData;
+        this.details = details;
+        this.type = "mutation";
+        this.name = "MutationError";
+    }
+}
+/**
+ * Rollback error - occurs when attempting to rollback optimistic state fails
+ * Retryable: No (indicates a serious state corruption issue)
+ */
+class RollbackError extends Error {
+    constructor(message, originalData, rollbackData, details) {
+        super(message);
+        this.originalData = originalData;
+        this.rollbackData = rollbackData;
+        this.details = details;
+        this.type = "rollback";
+        this.retryable = false;
+        this.name = "RollbackError";
+    }
+}
+/**
+ * Queue error - occurs when action queue operations fail
+ * Retryable: Yes (queue operations can be retried)
+ */
+class QueueError extends Error {
+    constructor(message, actionId, details) {
+        super(message);
+        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;
+    }
+}
+/**
+ * Network error for optimistic operations - typically connection issues
+ * Retryable: Yes
+ */
+class OptimisticNetworkError extends Error {
+    constructor(message, originalData, rollbackData, details) {
+        super(message);
+        this.originalData = originalData;
+        this.rollbackData = rollbackData;
+        this.details = details;
+        this.type = "network";
+        this.retryable = true;
+        this.name = "OptimisticNetworkError";
+    }
+}
+/**
+ * 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
+ */
+const normalizeOptimisticError = (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 };

package/dist/utils/presenceUtils.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Presence Utilities
+ *
+ * Helper functions for formatting presence and typing indicators.
+ */
+import { PresenceUser, TypingUser } from "../components/ai/PresenceProvider/PresenceProvider.types";
+/**
+ * Format typing users into human-readable text
+ *
+ * @param users - Array of users currently typing
+ * @param maxVisible - Maximum users to show by name (default: 3)
+ * @returns Formatted text like "Alice is typing..." or "3 people are typing..."
+ *
+ * @example
+ * formatTypingText([{ id: '1', name: 'Alice' }]) // "Alice is typing..."
+ * formatTypingText([{ id: '1', name: 'Alice' }, { id: '2', name: 'Bob' }]) // "Alice and Bob are typing..."
+ * formatTypingText([...4 users...]) // "Alice, Bob, Charlie, and 1 other are typing..."
+ */
+export declare function formatTypingText(users: TypingUser[], maxVisible?: number): string;
+/**
+ * Format presence count into human-readable text
+ *
+ * @param count - Number of users online
+ * @returns Formatted text like "5 users online" or "1 user online"
+ *
+ * @example
+ * formatPresenceCount(1) // "1 user online"
+ * formatPresenceCount(5) // "5 users online"
+ */
+export declare function formatPresenceCount(count: number): string;
+/**
+ * Validate presence user data
+ * Type guard to ensure object conforms to PresenceUser interface
+ *
+ * @param user - Unknown object to validate
+ * @returns True if valid PresenceUser
+ *
+ * @example
+ * const data = await fetchUserData();
+ * if (validatePresenceUser(data)) {
+ *   // TypeScript knows data is PresenceUser
+ *   console.log(data.name);
+ * }
+ */
+export declare function validatePresenceUser(user: unknown): user is PresenceUser;
+/**
+ * Validate typing user data
+ * Type guard to ensure object conforms to TypingUser interface
+ *
+ * @param user - Unknown object to validate
+ * @returns True if valid TypingUser
+ */
+export declare function validateTypingUser(user: unknown): user is TypingUser;
+/**
+ * Sort presence users by various criteria
+ *
+ * @param users - Array of users to sort
+ * @param sortBy - Sort criteria or custom comparator
+ * @returns Sorted array (does not mutate original)
+ *
+ * @example
+ * sortUsers(users, 'name') // Sort alphabetically by name
+ * sortUsers(users, 'joinedAt') // Sort by join time (newest first)
+ * sortUsers(users, (a, b) => a.metadata.score - b.metadata.score) // Custom sort
+ */
+export declare function sortUsers(users: PresenceUser[], sortBy: "name" | "joinedAt" | "status" | ((a: PresenceUser, b: PresenceUser) => number)): PresenceUser[];

package/dist/utils/presenceUtils.js

@@ -0,0 +1,107 @@
+/**
+ * Presence Utilities
+ *
+ * Helper functions for formatting presence and typing indicators.
+ */
+/**
+ * Format typing users into human-readable text
+ *
+ * @param users - Array of users currently typing
+ * @param maxVisible - Maximum users to show by name (default: 3)
+ * @returns Formatted text like "Alice is typing..." or "3 people are typing..."
+ *
+ * @example
+ * formatTypingText([{ id: '1', name: 'Alice' }]) // "Alice is typing..."
+ * formatTypingText([{ id: '1', name: 'Alice' }, { id: '2', name: 'Bob' }]) // "Alice and Bob are typing..."
+ * formatTypingText([...4 users...]) // "Alice, Bob, Charlie, and 1 other are typing..."
+ */
+function formatTypingText(users, maxVisible = 3) {
+    const count = users.length;
+    if (count === 0) {
+        return "";
+    }
+    if (count === 1) {
+        return `${users[0].name} is typing...`;
+    }
+    if (count === 2) {
+        return `${users[0].name} and ${users[1].name} are typing...`;
+    }
+    // 3 or more users
+    if (count <= maxVisible) {
+        const names = users
+            .slice(0, count - 1)
+            .map((u) => u.name)
+            .join(", ");
+        const lastName = users[count - 1].name;
+        return `${names}, and ${lastName} are typing...`;
+    }
+    // More than maxVisible users
+    const visibleNames = users
+        .slice(0, maxVisible)
+        .map((u) => u.name)
+        .join(", ");
+    const remaining = count - maxVisible;
+    return `${visibleNames}, and ${remaining} ${remaining === 1 ? "other" : "others"} are typing...`;
+}
+/**
+ * Format presence count into human-readable text
+ *
+ * @param count - Number of users online
+ * @returns Formatted text like "5 users online" or "1 user online"
+ *
+ * @example
+ * formatPresenceCount(1) // "1 user online"
+ * formatPresenceCount(5) // "5 users online"
+ */
+function formatPresenceCount(count) {
+    if (count === 0) {
+        return "No users online";
+    }
+    if (count === 1) {
+        return "1 user online";
+    }
+    return `${count} users online`;
+}
+/**
+ * Sort presence users by various criteria
+ *
+ * @param users - Array of users to sort
+ * @param sortBy - Sort criteria or custom comparator
+ * @returns Sorted array (does not mutate original)
+ *
+ * @example
+ * sortUsers(users, 'name') // Sort alphabetically by name
+ * sortUsers(users, 'joinedAt') // Sort by join time (newest first)
+ * sortUsers(users, (a, b) => a.metadata.score - b.metadata.score) // Custom sort
+ */
+function sortUsers(users, sortBy) {
+    const sorted = [...users]; // Don't mutate original
+    if (typeof sortBy === "function") {
+        return sorted.sort(sortBy);
+    }
+    switch (sortBy) {
+        case "name":
+            return sorted.sort((a, b) => a.name.localeCompare(b.name));
+        case "joinedAt":
+            return sorted.sort((a, b) => {
+                var _a, _b, _c, _d;
+                const aTime = (_b = (_a = a.joinedAt) === null || _a === void 0 ? void 0 : _a.getTime()) !== null && _b !== void 0 ? _b : 0;
+                const bTime = (_d = (_c = b.joinedAt) === null || _c === void 0 ? void 0 : _c.getTime()) !== null && _d !== void 0 ? _d : 0;
+                return bTime - aTime; // Newest first
+            });
+        case "status": {
+            // Order: online > busy > away > offline
+            const statusOrder = { online: 0, busy: 1, away: 2, offline: 3 };
+            return sorted.sort((a, b) => {
+                var _a, _b;
+                const aOrder = statusOrder[(_a = a.status) !== null && _a !== void 0 ? _a : "offline"];
+                const bOrder = statusOrder[(_b = b.status) !== null && _b !== void 0 ? _b : "offline"];
+                return aOrder - bOrder;
+            });
+        }
+        default:
+            return sorted;
+    }
+}
+
+export { formatPresenceCount, formatTypingText, sortUsers };

package/dist/utils/retryUtils.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Retry Logic Utilities
+ * Handles exponential backoff and retry decision logic for streaming errors
+ */
+import type { StreamingError } from './streamingErrors';
+/**
+ * Retry configuration options
+ */
+export interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    maxAttempts?: number;
+    /** Initial delay in milliseconds (default: 1000) */
+    initialDelay?: number;
+    /** Delay multiplier for exponential backoff (default: 2) */
+    backoffMultiplier?: number;
+    /** Maximum delay cap in milliseconds (default: 10000) */
+    maxDelay?: number;
+    /** Custom retry logic function */
+    shouldRetry?: (error: StreamingError, attempt: number) => boolean;
+}
+/**
+ * Calculate retry delay using exponential backoff
+ *
+ * @param attempt - Current retry attempt number (0-indexed)
+ * @param config - Retry configuration options
+ * @returns Delay in milliseconds before next retry
+ *
+ * @example
+ * calculateRetryDelay(0) // Returns: 1000ms
+ * calculateRetryDelay(1) // Returns: 2000ms
+ * calculateRetryDelay(2) // Returns: 4000ms
+ * calculateRetryDelay(3) // Returns: 8000ms
+ * calculateRetryDelay(4) // Returns: 10000ms (capped at maxDelay)
+ */
+export declare const calculateRetryDelay: (attempt: number, config?: RetryConfig) => number;
+/**
+ * Determine if a streaming error should be retried
+ *
+ * @param error - The streaming error that occurred
+ * @param attempt - Current retry attempt number (0-indexed)
+ * @param config - Retry configuration options
+ * @returns True if should retry, false otherwise
+ *
+ * @example
+ * shouldRetry(networkError, 0) // Returns: true
+ * shouldRetry(networkError, 3) // Returns: false (max attempts reached)
+ * shouldRetry(parseError, 0) // Returns: false (not retryable)
+ */
+export declare const shouldRetry: (error: StreamingError, attempt: number, config?: RetryConfig) => boolean;

package/dist/utils/retryUtils.js

@@ -0,0 +1,53 @@
+/**
+ * Retry Logic Utilities
+ * Handles exponential backoff and retry decision logic for streaming errors
+ */
+/**
+ * Calculate retry delay using exponential backoff
+ *
+ * @param attempt - Current retry attempt number (0-indexed)
+ * @param config - Retry configuration options
+ * @returns Delay in milliseconds before next retry
+ *
+ * @example
+ * calculateRetryDelay(0) // Returns: 1000ms
+ * calculateRetryDelay(1) // Returns: 2000ms
+ * calculateRetryDelay(2) // Returns: 4000ms
+ * calculateRetryDelay(3) // Returns: 8000ms
+ * calculateRetryDelay(4) // Returns: 10000ms (capped at maxDelay)
+ */
+const calculateRetryDelay = (attempt, config) => {
+    const initialDelay = (config === null || config === void 0 ? void 0 : config.initialDelay) || 1000;
+    const multiplier = (config === null || config === void 0 ? void 0 : config.backoffMultiplier) || 2;
+    const maxDelay = (config === null || config === void 0 ? void 0 : config.maxDelay) || 10000;
+    const delay = initialDelay * Math.pow(multiplier, attempt);
+    return Math.min(delay, maxDelay);
+};
+/**
+ * Determine if a streaming error should be retried
+ *
+ * @param error - The streaming error that occurred
+ * @param attempt - Current retry attempt number (0-indexed)
+ * @param config - Retry configuration options
+ * @returns True if should retry, false otherwise
+ *
+ * @example
+ * shouldRetry(networkError, 0) // Returns: true
+ * shouldRetry(networkError, 3) // Returns: false (max attempts reached)
+ * shouldRetry(parseError, 0) // Returns: false (not retryable)
+ */
+const shouldRetry = (error, attempt, config) => {
+    const maxAttempts = (config === null || config === void 0 ? void 0 : config.maxAttempts) || 3;
+    // Use custom retry logic if provided
+    if (config === null || config === void 0 ? void 0 : config.shouldRetry) {
+        return config.shouldRetry(error, attempt);
+    }
+    // Don't retry if max attempts reached
+    if (attempt >= maxAttempts) {
+        return false;
+    }
+    // Only retry if error is marked as retryable
+    return error.retryable;
+};
+
+export { calculateRetryDelay, shouldRetry };

package/dist/utils/sseFormatParsers.d.ts

@@ -0,0 +1,64 @@
+/**
+ * SSE Format Parsers for different AI providers
+ * Handles parsing Server-Sent Events from OpenAI, Anthropic (Claude), and Google Gemini APIs
+ */
+export type SSEFormat = 'openai' | 'anthropic' | 'google-gemini';
+export type SSEParser = (line: string) => string | null;
+/**
+ * OpenAI streaming format parser
+ * Format: data: {"choices":[{"delta":{"content":"token"}}]}
+ * End signal: data: [DONE]
+ *
+ * @param line - Raw SSE line from stream
+ * @returns Extracted token or null
+ *
+ * @example
+ * parseOpenAI('data: {"choices":[{"delta":{"content":"Hello"}}]}')
+ * // Returns: "Hello"
+ */
+export declare const parseOpenAI: SSEParser;
+/**
+ * Anthropic (Claude) streaming format parser
+ * Format:
+ *   event: content_block_delta
+ *   data: {"delta":{"type":"text_delta","text":"token"}}
+ *
+ * @param line - Raw SSE line from stream
+ * @returns Extracted token or null
+ *
+ * @example
+ * parseAnthropic('data: {"delta":{"type":"text_delta","text":"Hello"}}')
+ * // Returns: "Hello"
+ */
+export declare const parseAnthropic: SSEParser;
+/**
+ * Google Gemini streaming format parser
+ * Format: data: {"candidates":[{"content":{"parts":[{"text":"token"}]}}]}
+ *
+ * @param line - Raw SSE line from stream
+ * @returns Extracted token or null
+ *
+ * @example
+ * parseGemini('data: {"candidates":[{"content":{"parts":[{"text":"Hello"}]}}]}')
+ * // Returns: "Hello"
+ */
+export declare const parseGemini: SSEParser;
+/**
+ * Parser registry mapping format names to parser functions
+ */
+export declare const SSE_PARSERS: Record<SSEFormat, SSEParser>;
+/**
+ * Parse an SSE line using the specified format parser
+ *
+ * @param line - Raw SSE line from stream
+ * @param format - AI provider format or custom parser function
+ * @returns Extracted token or null
+ *
+ * @example
+ * // Using predefined format
+ * parseSSELine('data: {...}', 'openai')
+ *
+ * // Using custom parser
+ * parseSSELine('data: {...}', (line) => customParser(line))
+ */
+export declare const parseSSELine: (line: string, format: SSEFormat | SSEParser) => string | null;

package/dist/utils/sseFormatParsers.js

@@ -0,0 +1,124 @@
+/**
+ * SSE Format Parsers for different AI providers
+ * Handles parsing Server-Sent Events from OpenAI, Anthropic (Claude), and Google Gemini APIs
+ */
+/**
+ * OpenAI streaming format parser
+ * Format: data: {"choices":[{"delta":{"content":"token"}}]}
+ * End signal: data: [DONE]
+ *
+ * @param line - Raw SSE line from stream
+ * @returns Extracted token or null
+ *
+ * @example
+ * parseOpenAI('data: {"choices":[{"delta":{"content":"Hello"}}]}')
+ * // Returns: "Hello"
+ */
+const parseOpenAI = (line) => {
+    var _a, _b, _c;
+    if (!line.startsWith('data: '))
+        return null;
+    const data = line.slice(6).trim();
+    // Handle stream end signal
+    if (data === '[DONE]')
+        return null;
+    try {
+        const parsed = JSON.parse(data);
+        return ((_c = (_b = (_a = parsed.choices) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.delta) === null || _c === void 0 ? void 0 : _c.content) || null;
+    }
+    catch (_d) {
+        // Invalid JSON - skip this line
+        return null;
+    }
+};
+/**
+ * Anthropic (Claude) streaming format parser
+ * Format:
+ *   event: content_block_delta
+ *   data: {"delta":{"type":"text_delta","text":"token"}}
+ *
+ * @param line - Raw SSE line from stream
+ * @returns Extracted token or null
+ *
+ * @example
+ * parseAnthropic('data: {"delta":{"type":"text_delta","text":"Hello"}}')
+ * // Returns: "Hello"
+ */
+const parseAnthropic = (line) => {
+    var _a, _b;
+    if (!line.startsWith('data: '))
+        return null;
+    const data = line.slice(6).trim();
+    try {
+        const parsed = JSON.parse(data);
+        // Anthropic sends different event types - we only care about text deltas
+        if (parsed.type === 'content_block_delta') {
+            return ((_a = parsed.delta) === null || _a === void 0 ? void 0 : _a.text) || null;
+        }
+        // Also handle direct delta format
+        if (((_b = parsed.delta) === null || _b === void 0 ? void 0 : _b.type) === 'text_delta') {
+            return parsed.delta.text || null;
+        }
+        return null;
+    }
+    catch (_c) {
+        // Invalid JSON - skip this line
+        return null;
+    }
+};
+/**
+ * Google Gemini streaming format parser
+ * Format: data: {"candidates":[{"content":{"parts":[{"text":"token"}]}}]}
+ *
+ * @param line - Raw SSE line from stream
+ * @returns Extracted token or null
+ *
+ * @example
+ * parseGemini('data: {"candidates":[{"content":{"parts":[{"text":"Hello"}]}}]}')
+ * // Returns: "Hello"
+ */
+const parseGemini = (line) => {
+    var _a, _b, _c, _d, _e;
+    if (!line.startsWith('data: '))
+        return null;
+    const data = line.slice(6).trim();
+    try {
+        const parsed = JSON.parse(data);
+        return ((_e = (_d = (_c = (_b = (_a = parsed.candidates) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.content) === null || _c === void 0 ? void 0 : _c.parts) === null || _d === void 0 ? void 0 : _d[0]) === null || _e === void 0 ? void 0 : _e.text) || null;
+    }
+    catch (_f) {
+        // Invalid JSON - skip this line
+        return null;
+    }
+};
+/**
+ * Parser registry mapping format names to parser functions
+ */
+const SSE_PARSERS = {
+    'openai': parseOpenAI,
+    'anthropic': parseAnthropic,
+    'google-gemini': parseGemini,
+};
+/**
+ * Parse an SSE line using the specified format parser
+ *
+ * @param line - Raw SSE line from stream
+ * @param format - AI provider format or custom parser function
+ * @returns Extracted token or null
+ *
+ * @example
+ * // Using predefined format
+ * parseSSELine('data: {...}', 'openai')
+ *
+ * // Using custom parser
+ * parseSSELine('data: {...}', (line) => customParser(line))
+ */
+const parseSSELine = (line, format) => {
+    var _a;
+    if (typeof format === 'function') {
+        return format(line);
+    }
+    return ((_a = SSE_PARSERS[format]) === null || _a === void 0 ? void 0 : _a.call(SSE_PARSERS, line)) || null;
+};
+
+export { SSE_PARSERS, parseAnthropic, parseGemini, parseOpenAI, parseSSELine };

package/dist/utils/stateMachine.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Form State Machine Logic
+ * Lightweight engine for declarative form transitions and branching.
+ */
+export type StateIdentifier = string;
+export interface StateMachineConfig<TContext = any> {
+    /** The initial state name */
+    initial: StateIdentifier;
+    /** State definitions */
+    states: Record<StateIdentifier, StateDefinition<TContext>>;
+}
+export interface StateDefinition<TContext = any> {
+    /** Map of events to transitions */
+    on?: Record<string, Transition<TContext>>;
+    /** Actions executed when entering this state */
+    entry?: Array<(context: TContext) => void>;
+    /** Actions executed when exiting this state */
+    exit?: Array<(context: TContext) => void>;
+}
+export type Transition<TContext = any> = StateIdentifier | TransitionConfig<TContext>;
+export interface TransitionConfig<TContext = any> {
+    /** Target state */
+    target: StateIdentifier;
+    /** Optional conditional guard */
+    guard?: (context: TContext) => boolean;
+    /** Actions to execute during transition */
+    actions?: Array<(context: TContext) => void>;
+}
+/**
+ * Result of a state transition
+ */
+export interface TransitionResult<TContext> {
+    /** The new state name */
+    value: StateIdentifier;
+    /** Actions to be performed by the runner */
+    actions: Array<(context: TContext) => void>;
+    /** Whether the transition actually occurred */
+    changed: boolean;
+}
+/**
+ * Pure transition function for the state machine
+ */
+export declare function transition<TContext>(config: StateMachineConfig<TContext>, currentState: StateIdentifier, event: string, context: TContext): TransitionResult<TContext>;

package/dist/utils/stateMachine.js

@@ -0,0 +1,45 @@
+/**
+ * Form State Machine Logic
+ * Lightweight engine for declarative form transitions and branching.
+ */
+/**
+ * Pure transition function for the state machine
+ */
+function transition(config, currentState, event, context) {
+    const stateDef = config.states[currentState];
+    if (!stateDef || !stateDef.on) {
+        return { value: currentState, actions: [], changed: false };
+    }
+    const transitionDef = stateDef.on[event];
+    if (!transitionDef) {
+        return { value: currentState, actions: [], changed: false };
+    }
+    const targetConfig = typeof transitionDef === "string"
+        ? { target: transitionDef }
+        : transitionDef;
+    // Check guard if present
+    if (targetConfig.guard && !targetConfig.guard(context)) {
+        return { value: currentState, actions: [], changed: false };
+    }
+    const resultActions = [];
+    // Exit current state actions
+    if (stateDef.exit) {
+        resultActions.push(...stateDef.exit);
+    }
+    // Transition specific actions
+    if (targetConfig.actions) {
+        resultActions.push(...targetConfig.actions);
+    }
+    // Entry next state actions
+    const nextStateDef = config.states[targetConfig.target];
+    if (nextStateDef && nextStateDef.entry) {
+        resultActions.push(...nextStateDef.entry);
+    }
+    return {
+        value: targetConfig.target,
+        actions: resultActions,
+        changed: true,
+    };
+}
+
+export { transition };