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

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,110 @@
+import { __spreadArray } from '/Users/ggn/Development/ui-flik/node_modules/tslib/tslib.es6.js';
+
+/**
+ * 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) {
+    if (maxVisible === void 0) { maxVisible = 3; }
+    var count = users.length;
+    if (count === 0) {
+        return "";
+    }
+    if (count === 1) {
+        return "".concat(users[0].name, " is typing...");
+    }
+    if (count === 2) {
+        return "".concat(users[0].name, " and ").concat(users[1].name, " are typing...");
+    }
+    // 3 or more users
+    if (count <= maxVisible) {
+        var names = users
+            .slice(0, count - 1)
+            .map(function (u) { return u.name; })
+            .join(", ");
+        var lastName = users[count - 1].name;
+        return "".concat(names, ", and ").concat(lastName, " are typing...");
+    }
+    // More than maxVisible users
+    var visibleNames = users
+        .slice(0, maxVisible)
+        .map(function (u) { return u.name; })
+        .join(", ");
+    var remaining = count - maxVisible;
+    return "".concat(visibleNames, ", and ").concat(remaining, " ").concat(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 "".concat(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) {
+    var sorted = __spreadArray([], users, true); // Don't mutate original
+    if (typeof sortBy === "function") {
+        return sorted.sort(sortBy);
+    }
+    switch (sortBy) {
+        case "name":
+            return sorted.sort(function (a, b) { return a.name.localeCompare(b.name); });
+        case "joinedAt":
+            return sorted.sort(function (a, b) {
+                var _a, _b, _c, _d;
+                var aTime = (_b = (_a = a.joinedAt) === null || _a === void 0 ? void 0 : _a.getTime()) !== null && _b !== void 0 ? _b : 0;
+                var 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
+            var statusOrder_1 = { online: 0, busy: 1, away: 2, offline: 3 };
+            return sorted.sort(function (a, b) {
+                var _a, _b;
+                var aOrder = statusOrder_1[(_a = a.status) !== null && _a !== void 0 ? _a : "offline"];
+                var bOrder = statusOrder_1[(_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)
+ */
+var calculateRetryDelay = function (attempt, config) {
+    var initialDelay = (config === null || config === void 0 ? void 0 : config.initialDelay) || 1000;
+    var multiplier = (config === null || config === void 0 ? void 0 : config.backoffMultiplier) || 2;
+    var maxDelay = (config === null || config === void 0 ? void 0 : config.maxDelay) || 10000;
+    var 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)
+ */
+var shouldRetry = function (error, attempt, config) {
+    var 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"
+ */
+var parseOpenAI = function (line) {
+    var _a, _b, _c;
+    if (!line.startsWith('data: '))
+        return null;
+    var data = line.slice(6).trim();
+    // Handle stream end signal
+    if (data === '[DONE]')
+        return null;
+    try {
+        var 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"
+ */
+var parseAnthropic = function (line) {
+    var _a, _b;
+    if (!line.startsWith('data: '))
+        return null;
+    var data = line.slice(6).trim();
+    try {
+        var 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"
+ */
+var parseGemini = function (line) {
+    var _a, _b, _c, _d, _e;
+    if (!line.startsWith('data: '))
+        return null;
+    var data = line.slice(6).trim();
+    try {
+        var 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
+ */
+var 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))
+ */
+var parseSSELine = function (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) {
+    var stateDef = config.states[currentState];
+    if (!stateDef || !stateDef.on) {
+        return { value: currentState, actions: [], changed: false };
+    }
+    var transitionDef = stateDef.on[event];
+    if (!transitionDef) {
+        return { value: currentState, actions: [], changed: false };
+    }
+    var targetConfig = typeof transitionDef === "string"
+        ? { target: transitionDef }
+        : transitionDef;
+    // Check guard if present
+    if (targetConfig.guard && !targetConfig.guard(context)) {
+        return { value: currentState, actions: [], changed: false };
+    }
+    var resultActions = [];
+    // Exit current state actions
+    if (stateDef.exit) {
+        resultActions.push.apply(resultActions, stateDef.exit);
+    }
+    // Transition specific actions
+    if (targetConfig.actions) {
+        resultActions.push.apply(resultActions, targetConfig.actions);
+    }
+    // Entry next state actions
+    var nextStateDef = config.states[targetConfig.target];
+    if (nextStateDef && nextStateDef.entry) {
+        resultActions.push.apply(resultActions, nextStateDef.entry);
+    }
+    return {
+        value: targetConfig.target,
+        actions: resultActions,
+        changed: true,
+    };
+}
+
+export { transition };

package/dist/utils/streamingErrors.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Streaming Error Classes
+ * Defines error types for SSE streaming with retryability flags
+ */
+/**
+ * Base streaming error interface
+ */
+export interface StreamingError {
+    type: 'network' | 'timeout' | 'parse' | 'abort' | 'server';
+    message: string;
+    details?: unknown;
+    retryable: boolean;
+}
+/**
+ * Network error - typically connection issues or fetch failures
+ * Retryable: Yes
+ */
+export declare class StreamingNetworkError extends Error implements StreamingError {
+    details?: unknown | undefined;
+    type: "network";
+    retryable: boolean;
+    constructor(message: string, details?: unknown | undefined);
+}
+/**
+ * Timeout error - request exceeded specified timeout duration
+ * Retryable: Yes
+ */
+export declare class StreamingTimeoutError extends Error implements StreamingError {
+    type: "timeout";
+    retryable: boolean;
+    constructor(timeout: number);
+}
+/**
+ * Parse error - invalid JSON or malformed SSE data
+ * Retryable: No (indicates server-side issue or format mismatch)
+ */
+export declare class StreamingParseError extends Error implements StreamingError {
+    chunk?: string | undefined;
+    type: "parse";
+    retryable: boolean;
+    constructor(message: string, chunk?: string | undefined);
+}
+/**
+ * Abort error - user manually cancelled the stream
+ * Retryable: No (user initiated)
+ */
+export declare class StreamingAbortError extends Error implements StreamingError {
+    type: "abort";
+    retryable: boolean;
+    constructor();
+}
+/**
+ * Server error - HTTP error response from server (4xx, 5xx)
+ * Retryable: No for 4xx, could be Yes for 5xx but defaulting to No
+ */
+export declare class StreamingServerError extends Error implements StreamingError {
+    status: number;
+    details?: unknown | undefined;
+    type: "server";
+    retryable: boolean;
+    constructor(status: number, statusText: string, details?: unknown | undefined);
+}
+/**
+ * Normalize any error into a StreamingError
+ * Used to convert unknown errors (from fetch, network, etc.) into typed streaming errors
+ *
+ * @param error - Any error object
+ * @returns Normalized StreamingError
+ */
+export declare const normalizeError: (error: unknown) => StreamingError;