aeon-ui-engine 1.5.1 → 1.9.0

package/packages/primitives/dist/machines/cache.d.ts

@@ -0,0 +1,223 @@
+import * as xstate from 'xstate';
+import { ActorRefFrom, fromCallback } from 'xstate';
+
+/** Stable lifecycle states of one cache entry (see STATES.md). */
+declare const CACHE_STATES: readonly ["idle", "loading", "ready", "stale", "refreshing", "failed"];
+type CacheState = (typeof CACHE_STATES)[number];
+declare function isCacheableId(id: string): boolean;
+interface CacheEntryContext<T, K> {
+    key: K;
+    ttl: number;
+    data: T | undefined;
+    error: string | null;
+    /** When `data` was loaded; null while there is none. */
+    loadedAt: number | null;
+    /** An invalidation landed mid-load: the result may predate the write, so load once more. */
+    dirty: boolean;
+    now: () => number;
+}
+type CacheEntryEvent = {
+    type: 'FETCH';
+} | {
+    type: 'REFRESH';
+} | {
+    type: 'INVALIDATE';
+    refetch?: boolean;
+} | {
+    type: 'CLEAR';
+};
+interface CacheEntryInput<K> {
+    key: K;
+    ttl: number;
+    now?: () => number;
+}
+/**
+ * One keyed entry: idle until fetched, loading the first time, ready while
+ * younger than its time-to-live, then stale. FETCH on a stale or expired entry
+ * revalidates in `refreshing` while the old data stays readable; FETCH while a
+ * load runs is dropped, so one load serves every caller. INVALIDATE marks the
+ * entry stale (and reloads when `refetch`); CLEAR drops the data and cancels a
+ * running load so its result never lands.
+ */
+declare function createCacheEntryMachine<T, K = string>(): xstate.StateMachine<CacheEntryContext<T, K>, {
+    type: "FETCH";
+} | {
+    type: "REFRESH";
+} | {
+    type: "INVALIDATE";
+    refetch?: boolean;
+} | {
+    type: "CLEAR";
+}, {
+    [x: string]: xstate.ActorRefFromLogic<xstate.PromiseActorLogic<T, {
+        key: K;
+    }, xstate.EventObject>> | undefined;
+}, {
+    src: "load";
+    logic: xstate.PromiseActorLogic<T, {
+        key: K;
+    }, xstate.EventObject>;
+    id: string | undefined;
+}, {
+    type: "clear";
+    params: xstate.NonReducibleUnknown;
+} | {
+    type: "markDirty";
+    params: xstate.NonReducibleUnknown;
+}, {
+    type: "dirty";
+    params: unknown;
+} | {
+    type: "expired";
+    params: unknown;
+} | {
+    type: "refetch";
+    params: unknown;
+}, "ttl", "idle" | "loading" | "stale" | "ready" | "failed" | "refreshing", string, CacheEntryInput<K>, xstate.NonReducibleUnknown, xstate.EventObject, xstate.MetaObject, {
+    id: "cacheEntry";
+    states: {
+        readonly idle: {};
+        readonly loading: {};
+        readonly ready: {};
+        readonly stale: {};
+        readonly refreshing: {};
+        readonly failed: {};
+    };
+}>;
+declare const cacheEntryMachine: xstate.StateMachine<CacheEntryContext<unknown, string>, {
+    type: "FETCH";
+} | {
+    type: "REFRESH";
+} | {
+    type: "INVALIDATE";
+    refetch?: boolean;
+} | {
+    type: "CLEAR";
+}, {
+    [x: string]: xstate.ActorRefFromLogic<xstate.PromiseActorLogic<unknown, {
+        key: string;
+    }, xstate.EventObject>> | undefined;
+}, {
+    src: "load";
+    logic: xstate.PromiseActorLogic<unknown, {
+        key: string;
+    }, xstate.EventObject>;
+    id: string | undefined;
+}, {
+    type: "clear";
+    params: xstate.NonReducibleUnknown;
+} | {
+    type: "markDirty";
+    params: xstate.NonReducibleUnknown;
+}, {
+    type: "dirty";
+    params: unknown;
+} | {
+    type: "expired";
+    params: unknown;
+} | {
+    type: "refetch";
+    params: unknown;
+}, "ttl", "idle" | "loading" | "stale" | "ready" | "failed" | "refreshing", string, CacheEntryInput<string>, xstate.NonReducibleUnknown, xstate.EventObject, xstate.MetaObject, {
+    id: "cacheEntry";
+    states: {
+        readonly idle: {};
+        readonly loading: {};
+        readonly ready: {};
+        readonly stale: {};
+        readonly refreshing: {};
+        readonly failed: {};
+    };
+}>;
+type CacheEntryActor<T, K = string> = ActorRefFrom<ReturnType<typeof createCacheEntryMachine<T, K>>>;
+/**
+ * What a reader sees of one entry. The same object comes back until the entry
+ * changes, and `data` keeps its identity across ready, stale and refreshing,
+ * so selectors over a view never cause a re-render on their own.
+ */
+interface CacheView<T> {
+    readonly state: CacheState;
+    readonly data: T | undefined;
+    readonly error: string | null;
+    readonly loadedAt: number | null;
+}
+/** Commands a chart sends the cache, directly or through the invoked cache actor. */
+type CacheCommand<K> = {
+    type: 'CACHE.FETCH';
+    key?: K;
+} | {
+    type: 'CACHE.REFRESH';
+    key?: K;
+} | {
+    type: 'CACHE.INVALIDATE';
+    key?: K;
+    tag?: string;
+} | {
+    type: 'CACHE.KEY';
+    key: K;
+} | {
+    type: 'CACHE.CLEAR';
+};
+/** What the invoked cache actor sends its parent chart whenever its entry changes. */
+interface CacheUpdate<T, K> {
+    type: 'CACHE.UPDATE';
+    cache: string;
+    key: K;
+    view: CacheView<T>;
+}
+interface ChartCacheOptions<T, K> {
+    /** Names the cache in logs and errors. Names of secrets, keys or spend decisions are refused. */
+    id: string;
+    load: (key: K, context: {
+        signal: AbortSignal;
+    }) => Promise<T>;
+    /** Milliseconds an entry stays fresh, for every key or per key. */
+    ttl: number | ((key: K) => number);
+    tags?: (key: K) => readonly string[];
+    /** Turns a key into the string entries are stored under. Defaults to `String` for strings, else JSON. */
+    keyOf?: (key: K) => string;
+    /** Most entries kept; the least recently used unwatched, settled ones go first. Default 100. */
+    maxEntries?: number;
+    now?: () => number;
+}
+interface ChartCache<T, K = string> {
+    readonly id: string;
+    /** Entries currently held. */
+    readonly size: number;
+    /** The entry's current view, without loading it. Stable until the entry changes. */
+    peek(key: K): CacheView<T>;
+    /** Loads the entry if it is missing, failed, stale or expired; a running load is reused. */
+    fetch(key: K): void;
+    /** Reloads now, keeping the old data readable meanwhile. */
+    refresh(key: K): void;
+    /** Resolves with the entry's data, serving stale data at once while it revalidates. */
+    read(key: K): Promise<T>;
+    /** Marks entries stale; watched ones reload at once. */
+    invalidate(target: {
+        key: K;
+    } | {
+        tag: string;
+    }): void;
+    /** Drops every entry's data and cancels running loads (lock, account or network switch). */
+    clear(): void;
+    subscribe(key: K, listener: (view: CacheView<T>) => void): () => void;
+    send(command: CacheCommand<K>): void;
+    /**
+     * Invoke from a chart: `invoke: { id: 'cache', src: cache.actor, input: { key } }`.
+     * It fetches the key, sends `CACHE.UPDATE` on every change, and takes
+     * `CACHE.*` commands from the parent (`sendTo('cache', …)`); commands without
+     * a key apply to its own, and `CACHE.KEY` moves it to another key.
+     */
+    readonly actor: ReturnType<typeof fromCallback<CacheCommand<K>, {
+        key: K;
+        fetch?: boolean;
+    }>>;
+}
+/**
+ * A keyed cache shared by every chart that reads it, so a remounted chart is
+ * served from memory instead of loading again. Each entry is its own
+ * `cacheEntryMachine`; create one cache per kind of data at module scope.
+ */
+declare function createChartCache<T, K = string>(options: ChartCacheOptions<T, K>): ChartCache<T, K>;
+
+export { CACHE_STATES, type CacheCommand, type CacheEntryActor, type CacheEntryContext, type CacheEntryEvent, type CacheEntryInput, type CacheState, type CacheUpdate, type CacheView, type ChartCache, type ChartCacheOptions, cacheEntryMachine, createCacheEntryMachine, createChartCache, isCacheableId };

package/packages/primitives/dist/machines/cache.js

@@ -0,0 +1,14 @@
+import {
+  CACHE_STATES,
+  cacheEntryMachine,
+  createCacheEntryMachine,
+  createChartCache,
+  isCacheableId
+} from "../chunk-5BNAV4S2.js";
+export {
+  CACHE_STATES,
+  cacheEntryMachine,
+  createCacheEntryMachine,
+  createChartCache,
+  isCacheableId
+};

package/packages/primitives/dist/machines/clipboard.d.ts

@@ -0,0 +1,46 @@
+import * as xstate from 'xstate';
+
+/**
+ * Copy-to-clipboard feedback.
+ *
+ * Events: COPY { value } writes `value` to the system clipboard.
+ * States: idle → copying → copied | failed, back to idle after `timeout` ms. COPY again restarts.
+ * Entering copied / failed plays the `copy` / `error` sound (silent unless the app enabled sounds).
+ */
+interface ClipboardContext {
+    /** How long `copied` / `failed` show before returning to idle, in ms. */
+    timeout: number;
+}
+type ClipboardEvent = {
+    type: 'COPY';
+    value: string;
+};
+declare const CLIPBOARD_STATES: readonly ["idle", "copying", "copied", "failed"];
+type ClipboardStatus = (typeof CLIPBOARD_STATES)[number];
+declare const clipboardMachine: xstate.StateMachine<ClipboardContext, ClipboardEvent, {
+    [x: string]: xstate.ActorRefFromLogic<xstate.PromiseActorLogic<void, {
+        value: string;
+    }, xstate.EventObject>> | undefined;
+}, {
+    src: "write";
+    logic: xstate.PromiseActorLogic<void, {
+        value: string;
+    }, xstate.EventObject>;
+    id: string | undefined;
+}, {
+    type: "soundCopied";
+    params: unknown;
+} | {
+    type: "soundFailed";
+    params: unknown;
+}, never, "timeout", "idle" | "copying" | "copied" | "failed", string, Partial<ClipboardContext>, xstate.NonReducibleUnknown, xstate.EventObject, xstate.MetaObject, {
+    id: "clipboard";
+    states: {
+        readonly idle: {};
+        readonly copying: {};
+        readonly copied: {};
+        readonly failed: {};
+    };
+}>;
+
+export { CLIPBOARD_STATES, type ClipboardContext, type ClipboardEvent, type ClipboardStatus, clipboardMachine };

package/packages/primitives/dist/machines/clipboard.js

@@ -0,0 +1,8 @@
+import {
+  CLIPBOARD_STATES,
+  clipboardMachine
+} from "../chunk-HYHCIMHC.js";
+export {
+  CLIPBOARD_STATES,
+  clipboardMachine
+};

package/packages/primitives/dist/machines/tabs.d.ts

@@ -18,10 +18,10 @@ declare const tabsMachine: xstate.StateMachine<TabsContext, {
     type: "SET_VALUE";
     value: string;
 }, {}, never, {
-    type: "select";
+    type: "setValue";
     params: xstate.NonReducibleUnknown;
 } | {
-    type: "setValue";
+    type: "select";
     params: xstate.NonReducibleUnknown;
 }, {
     type: "notDisabled";

package/packages/primitives/src/index.ts

@@ -15,3 +15,5 @@ export * from './machines/app-shell.js'
 export * from './machines/app-nav.js'
 export * from './machines/sticky-bar.js'
 export * from './machines/content-region.js'
+export * from './machines/clipboard.js'
+export * from './machines/cache.js'