@apple-pie/slice 0.1.9 → 0.1.11

package/dist/types/utils/functions/debounce.d.ts

@@ -0,0 +1,9 @@
+export interface DebouncedFunction<T extends (...args: any[]) => any> {
+    (...args: Parameters<T>): void;
+    cancel: () => void;
+    flush: () => void;
+}
+/**
+ * Delay a function call until activity stops, with cancel and flush helpers.
+ */
+export declare function debounce<T extends (...args: any[]) => any>(func: T, delay: number): DebouncedFunction<T>;

package/dist/types/utils/functions/files.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Split a file name into its display name and extension.
+ */
+export declare function nameAndExtension(fileName: string): {
+    name: string;
+    ext: string;
+};
+/**
+ * Map a file extension to the corresponding file icon name.
+ */
+export declare function fileIconName(extension: string): "other" | "text" | "sheet" | "image" | "video" | "audio" | "code" | "md" | "preso" | "pdf" | "clipboard";
+/**
+ * Create a clipboard-text file with a guaranteed `.clipboard` extension.
+ */
+export declare function clipboardTextToFile(content: string, fileName?: string): File;

package/dist/types/utils/functions/misc.d.ts

@@ -0,0 +1,61 @@
+import type React from 'react';
+/**
+ * Convert a numeric or string size into a CSS-ready size value.
+ */
+export declare function setSizeStyle(size: string | number | undefined): string;
+/**
+ * Remove scripts, invisible characters, and optional HTML tags from a string.
+ */
+export declare function cleanString(input: string, removeInvisible?: boolean, removeHtml?: boolean): string;
+/**
+ * Check whether the active document theme is currently dark.
+ */
+export declare function isDarkMode(): boolean;
+/**
+ * Log mount, unmount, and prop-change reasons for debug render tracking.
+ */
+export declare function debug(previous: any, updated: any, name?: string): {
+    props: any;
+    mount: boolean;
+    unmount: boolean;
+} | undefined;
+/**
+ * Build a readable list of prop changes between two prop snapshots.
+ */
+export declare function createPropChangeArray(props: any, updated: any): string[];
+/**
+ * Capture props and lifecycle flags for the render debug helpers.
+ */
+export declare function setProps(props: any, mount?: boolean, unmount?: boolean): {
+    props: any;
+    mount: boolean;
+    unmount: boolean;
+} | undefined;
+/**
+ * Convert a hex color into an RGB string literal.
+ */
+export declare const hexToRgb: (hex: string | undefined) => string | undefined;
+/**
+ * Trigger a click-like callback when one of the configured keys is pressed.
+ */
+export declare function accessibleKeyDown(e: React.KeyboardEvent<any>, clickFunction: () => void, keys?: string[]): void;
+/**
+ * Read the horizontal pointer position from a mouse or touch event.
+ */
+export declare function pointerPosition(e: MouseEvent | TouchEvent): number;
+/**
+ * Remove empty class names and join the remainder into one class string.
+ */
+export declare function filterClasses(classNames: string[]): string;
+/**
+ * Normalize a style value or fallback into a CSS-ready string.
+ */
+export declare function setStyle(value: string | number | undefined, defaultVal?: number | string | undefined): string;
+/**
+ * Copy text to the clipboard using a temporary hidden textarea.
+ */
+export declare const copyToClipboard: (rawContent: string) => Promise<boolean>;
+/**
+ * Convert numeric or string percentage input into a normalized number.
+ */
+export declare function normalizedPercent(value: number | string): number;

package/dist/types/utils/index.d.ts

@@ -0,0 +1,5 @@
+export { copyToClipboard, hexToRgb } from './functions/misc';
+export { debounce } from './functions/debounce';
+export * from './functions/colors';
+export { IndexedDB, SSEConnection, WSConnection } from './objects';
+export type { IndexedDBOptions, SSECustomEvent, SSEConnectionCloseOption, SSEConnectionOptions, SSEEventMap, SSEUnifiedBuiltInMessage, SSEUnifiedCustomMessage, SSEUnifiedMessage, UnifiedMessageEvent, WSConnectionOptions, } from './objects';

package/dist/types/utils/objects/IndexedDB/IndexedDB.d.ts

@@ -0,0 +1,62 @@
+export interface IndexedDBOptions {
+    databaseName?: string;
+    version?: number;
+    key?: string;
+    autoIncrement?: boolean;
+}
+export declare class IndexedDB<T> {
+    private readonly databaseName;
+    private readonly storeName;
+    private readonly version;
+    private readonly key?;
+    private readonly autoIncrement;
+    private db;
+    constructor(storeName: string, options?: IndexedDBOptions);
+    /**
+     * Initialize the IndexedDB connection.
+     */
+    initialize(create?: boolean): Promise<void>;
+    /**
+     * Get a single DB value by key.
+     */
+    get(key: IDBValidKey): Promise<T | null>;
+    /**
+     * Get all the values in the store.
+     */
+    getAll(): Promise<T[]>;
+    /**
+     * Get all keys in the store.
+     */
+    getAllKeys(): Promise<IDBValidKey[]>;
+    set(key: IDBValidKey, value: T): Promise<IDBValidKey>;
+    /**
+     * Adds a new value to the store with or without a key.
+     * If a key already exists it will error.
+     */
+    add(value: T, key?: IDBValidKey): Promise<IDBValidKey>;
+    /**
+     * Updates a value by key. This uses IndexedDB put semantics.
+     */
+    update(key: IDBValidKey, value: T): Promise<IDBValidKey>;
+    /**
+     * Removes a value from the store by key.
+     */
+    remove(key: IDBValidKey): Promise<void>;
+    /**
+     * Clear all the store values
+     */
+    clear(): Promise<void>;
+    /**
+     * Cleanly close the IndexedDB connection.
+     */
+    close(): Promise<void>;
+    /**
+     * Deletes an indexedDB database.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Private executor of request of the indexedDB
+     * Returns the result of the indexedDB request including the error if there is one
+     */
+    private runRequest;
+}

package/dist/types/utils/objects/SSEConnection/SSEConnection.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Maps each custom SSE event name to the payload type that event emits.
+ */
+export type SSEEventMap = Record<string, unknown>;
+/**
+ * Parsed SSE payloads can still be raw strings when the event data is not JSON.
+ */
+type SSEParsedData<T> = T | string;
+/**
+ * Restricts custom event names to string keys so they can be used with
+ * `addEventListener`.
+ */
+type SSEEventName<TCustomEvents extends SSEEventMap> = Extract<keyof TCustomEvents, string>;
+/**
+ * Built-in EventSource events represented in unified callback mode.
+ */
+export type SSEUnifiedBuiltInMessage<TMessage> = {
+    type: 'message';
+    data: SSEParsedData<TMessage>;
+    event: MessageEvent;
+} | {
+    type: 'error';
+    event: Event;
+} | {
+    type: 'open';
+    event: Event;
+} | {
+    type: 'close';
+    event: Event;
+};
+export interface SSEConnectionCloseOption<TCustomEvents extends SSEEventMap = Record<string, never>> {
+    event?: SSEEventName<TCustomEvents>;
+    message?: string;
+}
+/**
+ * A custom event in unified callback mode. The `type` determines the shape of
+ * `data`.
+ */
+export type SSEUnifiedCustomMessage<TCustomEvents extends SSEEventMap, TName extends SSEEventName<TCustomEvents> = SSEEventName<TCustomEvents>> = {
+    type: TName;
+    data: SSEParsedData<TCustomEvents[TName]>;
+    event: MessageEvent;
+};
+/**
+ * All messages that can flow through the single unified callback.
+ */
+export type SSEUnifiedMessage<TMessage, TCustomEvents extends SSEEventMap> = SSEUnifiedBuiltInMessage<TMessage> | SSEUnifiedCustomMessage<TCustomEvents>;
+/**
+ * Callback signature for standard mode, where only the default `message`
+ * event is routed to `onMessageCallback`.
+ */
+type SSEStandardMessageCallback<TMessage> = (data: SSEParsedData<TMessage>) => void;
+/**
+ * Callback signature for unified mode, where built-in and custom events are
+ * all routed through a discriminated object.
+ */
+type SSEUnifiedMessageCallback<TMessage, TCustomEvents extends SSEEventMap> = (message: SSEUnifiedMessage<TMessage, TCustomEvents>) => void;
+/**
+ * Declares one custom SSE event. `name` selects a key from the event map, and
+ * `handler` is typed to that event's payload when provided.
+ */
+export interface SSECustomEvent<TCustomEvents extends SSEEventMap, TName extends SSEEventName<TCustomEvents> = SSEEventName<TCustomEvents>> {
+    name: TName;
+    handler?: (data: TCustomEvents[TName]) => void;
+}
+/**
+ * Options shared by both standard and unified message modes.
+ */
+interface SSEConnectionOptionsBase<TCustomEvents extends SSEEventMap = Record<string, never>> {
+    url?: string;
+    options?: EventSourceInit;
+    connectionClose?: SSEConnectionCloseOption<TCustomEvents>;
+    onErrorCallback?: (event: Event) => void;
+    onOpenCallback?: (event: Event) => void;
+    onCloseCallback?: (event: Event) => void;
+    customEvents?: SSECustomEvent<TCustomEvents> | SSECustomEvent<TCustomEvents>[];
+}
+/**
+ * Options for unified mode. When enabled, every built-in and custom event is
+ * emitted through `onMessageCallback`.
+ */
+interface SSEConnectionUnifiedOptions<TMessage = unknown, TCustomEvents extends SSEEventMap = Record<string, never>> extends SSEConnectionOptionsBase<TCustomEvents> {
+    unifiedOnMessage: true;
+    onMessageCallback?: SSEUnifiedMessageCallback<TMessage, TCustomEvents>;
+}
+/**
+ * Options for standard mode. Only the default `message` event payload is sent
+ * to `onMessageCallback`.
+ */
+interface SSEConnectionStandardOptions<TMessage = unknown, TCustomEvents extends SSEEventMap = Record<string, never>> extends SSEConnectionOptionsBase<TCustomEvents> {
+    unifiedOnMessage?: false;
+    onMessageCallback?: SSEStandardMessageCallback<TMessage>;
+}
+/**
+ * Public connection options. The `unifiedOnMessage` flag selects which
+ * callback signature is valid.
+ */
+export type SSEConnectionOptions<TMessage = unknown, TCustomEvents extends SSEEventMap = Record<string, never>> = SSEConnectionStandardOptions<TMessage, TCustomEvents> | SSEConnectionUnifiedOptions<TMessage, TCustomEvents>;
+/**
+ * Manage an EventSource connection with optional unified callbacks and typed custom events.
+ */
+export declare class SSEConnection<TMessage = unknown, TCustomEvents extends SSEEventMap = Record<string, never>> {
+    private readonly url;
+    private readonly options;
+    private sseConnection;
+    private readonly onMessageCallback?;
+    private readonly onErrorCallback?;
+    private readonly onOpenCallback?;
+    private readonly onCloseCallback?;
+    private readonly connectionClose?;
+    private readonly customEvents;
+    private readonly customEventHandlers;
+    private readonly unifiedOnMessage;
+    /**
+     * Whether the underlying EventSource is currently open.
+     */
+    get connected(): boolean;
+    /**
+     * Direct access to the underlying EventSource instance.
+     */
+    get connection(): EventSource | null;
+    /**
+     * Create the EventSource connection and attach its initial listeners.
+     */
+    constructor(options?: SSEConnectionOptions<TMessage, TCustomEvents>);
+    /**
+     * Safely parse SSE event data. Falls back to the raw string when the payload is not JSON.
+     */
+    private parseEventData;
+    /**
+     * Attach the default EventSource listeners for message, error, and open events.
+     */
+    private attachDefaultEventListeners;
+    /**
+     * Emit parsed message data when standard callback mode is enabled.
+     */
+    private emitParsedMessage;
+    /**
+     * Emit a unified message object when unified callback mode is enabled.
+     */
+    private emitUnifiedMessage;
+    /**
+     * Emit the close callback and unified close event.
+     */
+    private emitCloseEvent;
+    /**
+     * Close the connection in response to an SSE-level close condition.
+     */
+    private closeFromConnectionEvent;
+    /**
+     * Check whether an incoming message should close the connection.
+     */
+    private shouldCloseFromMessage;
+    /**
+     * Emit one custom event through unified callback mode.
+     */
+    private emitUnifiedCustomMessage;
+    /**
+     * Attach one typed custom event listener to the SSE connection.
+     */
+    private attachCustomEventListener;
+    /**
+     * Attach all configured custom event listeners to the SSE connection.
+     */
+    private attachCustomEventListeners;
+    /**
+     * Detach every default and custom listener from the current EventSource.
+     */
+    private detachAllEventListeners;
+    /**
+     * Parse and emit the default `message` event payload.
+     */
+    onMessage: (event: MessageEvent) => void;
+    /**
+     * Forward EventSource errors through the configured callbacks.
+     */
+    onError: (event: Event) => void;
+    /**
+     * Forward EventSource open events through the configured callbacks.
+     */
+    onOpen: (event: Event) => void;
+    /**
+     * Close the SSE connection and release resources.
+     */
+    close: () => void;
+}
+export {};

package/dist/types/utils/objects/WSConnection/WSConnection.d.ts

@@ -0,0 +1,159 @@
+type WSRawData = string | Blob | ArrayBuffer;
+type WSParsedData<TMessage> = TMessage | WSRawData;
+export type UnifiedMessageEvent<TMessage> = {
+    type: 'message';
+    data: WSParsedData<TMessage>;
+    event: MessageEvent;
+} | {
+    type: 'open';
+    event: Event;
+} | {
+    type: 'close';
+    event: CloseEvent;
+} | {
+    type: 'error';
+    event: ErrorEvent;
+};
+type WSStandardMessageCallback<TMessage> = (data: WSParsedData<TMessage>) => void;
+type WSUnifiedMessageCallback<TMessage> = (message: UnifiedMessageEvent<TMessage>) => void;
+interface WSConnectionOptionsBase {
+    url: string;
+    autoReconnect?: boolean;
+    reconnectInterval?: number;
+    reconnectAttempts?: number;
+    reconnectFalloff?: boolean;
+    keepAlive?: boolean;
+    keepAliveInterval?: number;
+    token?: string | (() => Promise<string>);
+    onOpenCallback?: (event: Event) => void;
+    onCloseCallback?: (event: CloseEvent) => void;
+    onErrorCallback?: (error: ErrorEvent) => void;
+}
+interface WSConnectionUnifiedOptions<TMessage = unknown> extends WSConnectionOptionsBase {
+    unifiedMessages: true;
+    onMessageCallback?: WSUnifiedMessageCallback<TMessage>;
+}
+interface WSConnectionStandardOptions<TMessage = unknown> extends WSConnectionOptionsBase {
+    unifiedMessages?: false;
+    onMessageCallback?: WSStandardMessageCallback<TMessage>;
+}
+export type WSConnectionOptions<TMessage = unknown> = WSConnectionStandardOptions<TMessage> | WSConnectionUnifiedOptions<TMessage>;
+/**
+ * Manage a WebSocket connection with optional unified events, retries, and keep-alive pings.
+ */
+export declare class WSConnection<TMessage = unknown> {
+    private readonly url;
+    private readonly autoReconnect;
+    private readonly reconnectInterval;
+    private readonly reconnectAttempts;
+    private readonly reconnectFalloff;
+    private readonly keepAlive;
+    private readonly keepAliveInterval;
+    private readonly unifiedMessages;
+    private readonly token;
+    private readonly onMessageCallback?;
+    private readonly onOpenCallback?;
+    private readonly onCloseCallback?;
+    private readonly onErrorCallback?;
+    private socket;
+    private keepAliveTimer;
+    private reconnectIntervalTimer;
+    private reconnectAttemptsCount;
+    private manuallyClosed;
+    /**
+     * Report whether the underlying socket is currently open.
+     */
+    get connected(): boolean;
+    /**
+     * Expose the underlying WebSocket instance.
+     */
+    get connection(): WebSocket | null;
+    /**
+     * Initialize the socket connection and configure its runtime options.
+     */
+    constructor(options: WSConnectionOptions<TMessage>);
+    /**
+     * Send a string or JSON-serializable payload through the socket.
+     */
+    send(message: unknown): void;
+    /**
+     * Close the socket intentionally and stop any reconnect attempts.
+     */
+    close(closeEvent: {
+        code: number;
+        reason: string;
+    }): void;
+    /**
+     * Emit parsed message data when standard callback mode is enabled.
+     */
+    private emitParsedMessage;
+    /**
+     * Emit a unified event object when unified callback mode is enabled.
+     */
+    private emitUnifiedMessage;
+    /**
+     * Forward an error event through both direct and unified callbacks.
+     */
+    private emitErrorEvent;
+    /**
+     * Parse incoming message data, falling back to raw socket payloads when needed.
+     */
+    private parseEventData;
+    /**
+     * Initialize connection state after the socket opens.
+     */
+    private readonly onOpen;
+    /**
+     * Parse and emit each incoming socket message.
+     */
+    private readonly onMessage;
+    /**
+     * Clean up the socket and trigger reconnect logic after unexpected closes.
+     */
+    private readonly onClose;
+    /**
+     * Normalize socket errors before forwarding them to consumers.
+     */
+    private readonly onError;
+    /**
+     * Attach the connection lifecycle listeners to the current socket.
+     */
+    private attachEventListeners;
+    /**
+     * Start periodic ping messages to keep the socket active.
+     */
+    private setKeepAlive;
+    /**
+     * Stop the active keep-alive timer if one is running.
+     */
+    private clearKeepAliveTimer;
+    /**
+     * Stop the active reconnect timer if one is running.
+     */
+    private clearReconnectTimer;
+    /**
+     * Detach all lifecycle listeners from the current socket.
+     */
+    private detachEventListeners;
+    /**
+     * Open a new socket connection when one is not already active.
+     */
+    private connect;
+    /**
+     * Schedule the next reconnect attempt when reconnects are allowed.
+     */
+    private reconnect;
+    /**
+     * Calculate the reconnect delay, optionally using exponential backoff.
+     */
+    private getReconnectDelay;
+    /**
+     * Decide whether a close event should trigger a reconnect attempt.
+     */
+    private shouldReconnect;
+    /**
+     * Close the current socket instance and release its timers and listeners.
+     */
+    private closeSocket;
+}
+export {};

package/dist/types/utils/objects/index.d.ts

@@ -0,0 +1,6 @@
+export { IndexedDB } from './IndexedDB/IndexedDB';
+export type { IndexedDBOptions } from './IndexedDB/IndexedDB';
+export { SSEConnection } from './SSEConnection/SSEConnection';
+export { WSConnection } from './WSConnection/WSConnection';
+export type { SSECustomEvent, SSEConnectionCloseOption, SSEConnectionOptions, SSEEventMap, SSEUnifiedBuiltInMessage, SSEUnifiedCustomMessage, SSEUnifiedMessage, } from './SSEConnection/SSEConnection';
+export type { UnifiedMessageEvent, WSConnectionOptions, } from './WSConnection/WSConnection';

package/dist/types/workers/uploads/uploads-worker.d.ts

@@ -0,0 +1,129 @@
+export declare enum FileUploadStatus {
+    queued = "pending",
+    uploading = "uploading",
+    completed = "completed",
+    failed = "failed"
+}
+export declare enum UploadError {
+    SizeExceedsLimit = "size exceed limit",
+    TypeNotAllowed = "file type not allowed",
+    UploadFailed = "upload failed",
+    UploadURLNotFound = "invalid upload url",
+    AccessForbidden = "upload access forbidden",
+    NotAuthorized = "upload not authorized on server",
+    TooLarge = "payload too large for server",
+    MediaNotSupported = "server does not supported file type",
+    InternalError = "Internal server error",
+    Other = "Other server error"
+}
+export type Upload = {
+    id: string;
+    file: File;
+    uploadURL?: string;
+    status: FileUploadStatus;
+    error?: UploadError;
+    progress?: number;
+};
+export type UploadInput = {
+    file: File;
+    uploadURL?: string;
+};
+export type ConfigurationOptions = {
+    uploadURL: string;
+    maxQueueSize?: number;
+    maxFileSize?: number;
+    accepted?: string[];
+    maxConcurrentUploads?: number;
+};
+export type UploadStatusMessage = {
+    type: 'status';
+    uploads: Upload[];
+    workerStatus: WorkerStatus;
+};
+export type UploadWorkerErrorMessage = {
+    type: 'error';
+    message: string;
+};
+export type UploadWorkerMessage = {
+    type: 'initialize';
+    options: ConfigurationOptions;
+} | {
+    type: 'add-files';
+    files: UploadInput[];
+} | {
+    type: 'clear-uploads';
+};
+export type UploadWorkerResponse = UploadStatusMessage | UploadWorkerErrorMessage;
+export interface UploadWorkerBridge {
+    updateStatus(status: Upload[]): void;
+}
+export declare enum WorkerStatus {
+    Idle = "idle",
+    Busy = "busy"
+}
+export declare class UploadWorkerClient implements UploadWorkerBridge {
+    private readonly target;
+    private readonly getWorkerStatus;
+    constructor(target: {
+        postMessage: (message: UploadWorkerResponse) => void;
+    }, getWorkerStatus: () => WorkerStatus);
+    updateStatus(status: Upload[]): void;
+}
+type UploadWorkerTarget = {
+    onmessage: ((event: MessageEvent<UploadWorkerMessage>) => void) | null;
+    postMessage: (message: UploadWorkerResponse) => void;
+};
+export declare class UploadsWorker {
+    private readonly uploadURL;
+    private readonly maxQueueSize;
+    private readonly maxFileSize;
+    private readonly accepted;
+    private readonly maxConcurrentUploads;
+    private readonly worker;
+    private readonly queue;
+    private readonly active;
+    private readonly completed;
+    private readonly failed;
+    private workerStatus;
+    constructor(options: ConfigurationOptions, worker?: UploadWorkerBridge);
+    /**
+     * Add new files to the upload queue
+     */
+    addFiles(file: UploadInput | File | Array<UploadInput | File>): void;
+    /**
+     * Stop activity and flush all maps / data
+     */
+    clearUploads(): void;
+    /**
+     * Start the processing files in the upload queue
+     */
+    process(): void;
+    get status(): WorkerStatus;
+    private startUpload;
+    /**
+     * perform the actual upload
+     */
+    private uploadFile;
+    /**
+     * Update the active upload with new data
+     */
+    private updateUploadStatus;
+    /**
+     * Create array with the current state of all uploads
+     */
+    private currentStatus;
+    /**
+     * Push status updates to the web worker
+     */
+    private notifyStatus;
+}
+export declare class UploadsWorkerRuntime {
+    private readonly target;
+    private uploads;
+    constructor(target: UploadWorkerTarget);
+    private handleMessage;
+    private getWorkerStatus;
+    private postError;
+}
+export declare function registerUploadsWorker(target?: UploadWorkerTarget): UploadsWorkerRuntime;
+export {};

package/dist/types/workers/uploads/uploads.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@apple-pie/slice",
-	"version": "0.1.9",
+	"version": "0.1.11",
 	"main": "dist/cjs/index.js",
 	"module": "dist/esm/index.mjs",
 	"exports": {