aeon-ui-engine 1.8.0 → 1.10.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/store.d.ts

@@ -0,0 +1,286 @@
+import * as xstate from 'xstate';
+import { fromCallback } from 'xstate';
+import { CacheState, CacheView } from './cache.js';
+
+/**
+ * One store per app: every entity lives once, by id, in its slice. Charts and
+ * components read through selectors and project state onto `data-aeon-*`
+ * attributes; the only way to change anything is an event sent to the store.
+ */
+interface SliceOptions<E, Q> {
+    idOf: (entity: E) => string;
+    /** Loads the entities a query names. Slices without `load` are filled by events only. */
+    load?: (query: Q, context: {
+        signal: AbortSignal;
+    }) => Promise<readonly E[]>;
+    /** Milliseconds a query result stays fresh. Default 30 seconds. */
+    ttl?: number | ((query: Q) => number);
+    tags?: (query: Q) => readonly string[];
+    /** Turns a query into the key its result is stored under. Defaults to `String` for strings, else JSON. */
+    queryKey?: (query: Q) => string;
+    /** An incoming entity equal to the held one keeps the held object, so selectors stay quiet. Default: shallow equality. */
+    equals?: (a: E, b: E) => boolean;
+    /** Saved by the store's persistence adapter. Default true. */
+    persist?: boolean;
+}
+interface SliceDefinition<E, Q> extends SliceOptions<E, Q> {
+    readonly __types?: {
+        entity: E;
+        query: Q;
+    };
+}
+declare function defineSlice<E, Q = string>(options: SliceOptions<E, Q>): SliceDefinition<E, Q>;
+type AnySlices = Record<string, SliceDefinition<any, any>>;
+type EntityOf<D> = D extends {
+    readonly __types?: {
+        entity: infer E;
+    };
+} ? E : never;
+type QueryOf<D> = D extends {
+    readonly __types?: {
+        query: infer Q;
+    };
+} ? Q : never;
+/** One query's result: its load state and the ids it returned, in order. */
+interface QueryView {
+    readonly state: CacheState;
+    readonly ids: readonly string[];
+    readonly error: string | null;
+    readonly loadedAt: number | null;
+}
+interface SliceState<E> {
+    readonly byId: Readonly<Record<string, E>>;
+    /** Every held id, in arrival order. */
+    readonly ids: readonly string[];
+    readonly queries: Readonly<Record<string, QueryView>>;
+    /** Entity id → the optimistic write it waits on. */
+    readonly pending: Readonly<Record<string, string>>;
+    /** Entity id → why its last write was rolled back. Cleared by the next write to it. */
+    readonly failed: Readonly<Record<string, string>>;
+}
+type StoreStatus = 'hydrating' | 'ready';
+interface PendingWrite {
+    slice: string;
+    /** Values before the write, restored on rollback. */
+    before: Record<string, unknown>;
+    /** Values the write put in place; rollback only restores entities still holding them. */
+    after: Record<string, unknown>;
+}
+interface StoreState<S extends AnySlices> {
+    readonly status: StoreStatus;
+    readonly slices: {
+        readonly [N in keyof S]: SliceState<EntityOf<S[N]>>;
+    };
+    readonly writes: Readonly<Record<string, PendingWrite>>;
+}
+type SliceEvent<N extends string, E, Q> = {
+    type: 'ENTITY.UPSERT';
+    slice: N;
+    entities: readonly E[];
+} | {
+    type: 'ENTITY.PATCH';
+    slice: N;
+    id: string;
+    patch: Partial<E>;
+} | {
+    type: 'ENTITY.REMOVE';
+    slice: N;
+    ids: readonly string[];
+} | {
+    type: 'QUERY.FETCH';
+    slice: N;
+    query: Q;
+} | {
+    type: 'QUERY.REFRESH';
+    slice: N;
+    query: Q;
+} | {
+    type: 'QUERY.INVALIDATE';
+    slice: N;
+    query?: Q;
+    tag?: string;
+}
+/** Applies at once and marks the entities pending until WRITE.CONFIRM or WRITE.ROLLBACK. */
+ | {
+    type: 'WRITE.BEGIN';
+    slice: N;
+    write: string;
+    upsert?: readonly E[];
+    remove?: readonly string[];
+};
+/** Everything a store accepts. Writes, loads and invalidations all go through here. */
+type StoreEvent<S extends AnySlices> = {
+    [N in keyof S & string]: SliceEvent<N, EntityOf<S[N]>, QueryOf<S[N]>>;
+}[keyof S & string] | {
+    type: 'WRITE.CONFIRM';
+    write: string;
+} | {
+    type: 'WRITE.ROLLBACK';
+    write: string;
+    error?: string;
+}
+/** Marks every query stale; watched ones reload (reconnect, window focus). */
+ | {
+    type: 'STORE.INVALIDATE';
+}
+/** Drops all data, running loads and saved data (lock, account or network switch). */
+ | {
+    type: 'STORE.CLEAR';
+};
+interface StoreAdapter {
+    load(key: string): string | null | undefined | Promise<string | null | undefined>;
+    save(key: string, value: string): void | Promise<void>;
+    remove(key: string): void | Promise<void>;
+}
+interface StorePersistOptions {
+    adapter: StoreAdapter;
+    /** Bump when the saved shape changes; older data goes through `migrate` or is dropped. */
+    version: number;
+    migrate?: (saved: PersistedSlices, fromVersion: number) => PersistedSlices | null | undefined;
+    /** Milliseconds of quiet before a save. Default 250. */
+    delayMs?: number;
+}
+type PersistedSlices = Record<string, {
+    byId: Record<string, unknown>;
+    ids: string[];
+}>;
+interface StoreOptions<S extends AnySlices> {
+    /** Names the store and its saved data. Names of secrets, keys or spend decisions are refused. */
+    id: string;
+    slices: S;
+    persist?: StorePersistOptions;
+    /** Starts a server or disk feed that sends store events; returns its stop function. */
+    sync?: (send: (event: StoreEvent<S>) => void) => (() => void) | void;
+    now?: () => number;
+}
+/** A query's view with its entities resolved. Stable until the view or one of its entities changes. */
+interface QueryResult<E> extends QueryView {
+    readonly entities: readonly E[];
+}
+interface Selection<T> {
+    get(): T;
+    /** Calls back only when the selected value changes under `equals`. */
+    subscribe(listener: (value: T) => void): () => void;
+}
+/** What the invoked store actor sends its parent chart whenever its selection changes. */
+interface StoreUpdate<T> {
+    type: 'STORE.UPDATE';
+    store: string;
+    value: T;
+}
+interface AeonStore<S extends AnySlices> {
+    readonly id: string;
+    getSnapshot(): StoreState<S>;
+    /** For `useSyncExternalStore`: calls back after every change. */
+    subscribe(listener: () => void): () => void;
+    send(event: StoreEvent<S>): void;
+    select<T>(selector: (state: StoreState<S>) => T, equals?: (a: T, b: T) => boolean): Selection<T>;
+    entity<N extends keyof S & string>(slice: N, id: string): EntityOf<S[N]> | undefined;
+    query<N extends keyof S & string>(slice: N, query: QueryOf<S[N]>): QueryResult<EntityOf<S[N]>>;
+    /** Resolves once saved data has loaded (at once without persistence). */
+    readonly ready: Promise<void>;
+    /** Saves now instead of after the quiet delay (app quit). */
+    flush(): Promise<void>;
+    stop(): void;
+    /**
+     * Invoke from a chart: `invoke: { id: 'store', src: store.actor, input: { select } }`.
+     * It sends `STORE.UPDATE` whenever the selection changes and forwards store
+     * events the chart sends it (`sendTo('store', …)`).
+     */
+    readonly actor: ReturnType<typeof fromCallback<StoreEvent<S>, {
+        select: (state: StoreState<S>) => unknown;
+        equals?: (a: unknown, b: unknown) => boolean;
+    }>>;
+}
+declare function shallowEqual(a: unknown, b: unknown): boolean;
+/** Field and slice names are checked word by word, so `seedPhrase` and `privateKey` are caught. */
+declare function isStorableName(name: string): boolean;
+/** The first field name, at any depth, that names a secret, key or spend decision. */
+declare function unstorableField(value: unknown, depth?: number): string | null;
+/** `data-aeon-*` projection of a query: its load state and how many entities it holds. */
+declare function queryAttrs(result: QueryView): Record<string, string>;
+/** `data-aeon-*` projection of one entity: pending while a write waits on the server, failed after a rollback. */
+declare function entityAttrs<E>(slice: SliceState<E>, sliceName: string, id: string): Record<string, string>;
+declare function memoryAdapter(initial?: Record<string, string>): StoreAdapter & {
+    readonly data: Map<string, string>;
+};
+declare function webStorageAdapter(storage?: Storage): StoreAdapter;
+type AnyEntity = unknown;
+type AnySliceState = SliceState<AnyEntity>;
+interface Data {
+    status: StoreStatus;
+    slices: Record<string, AnySliceState>;
+    writes: Record<string, PendingWrite>;
+}
+/**
+ * The store's chart: `hydrating` until saved data has loaded, then `ready`.
+ * Every event folds into one immutable snapshot (`context.data`) that keeps
+ * its identity, and that of every untouched slice and entity, when an event
+ * changes nothing.
+ */
+declare function createStoreMachine(defs: AnySlices): xstate.StateMachine<{
+    data: Data;
+}, {
+    type: "ENTITY.REMOVE";
+    slice: string;
+    ids: readonly string[];
+} | {
+    type: "WRITE.CONFIRM";
+    write: string;
+} | {
+    type: "WRITE.ROLLBACK";
+    write: string;
+    error?: string;
+} | {
+    type: "STORE.INVALIDATE";
+} | {
+    type: "STORE.CLEAR";
+} | {
+    type: "ENTITY.UPSERT";
+    slice: string;
+    entities: readonly any[];
+} | {
+    type: "ENTITY.PATCH";
+    slice: string;
+    id: string;
+    patch: Partial<any>;
+} | {
+    type: "QUERY.FETCH";
+    slice: string;
+    query: any;
+} | {
+    type: "QUERY.REFRESH";
+    slice: string;
+    query: any;
+} | {
+    type: "QUERY.INVALIDATE";
+    slice: string;
+    query?: any;
+    tag?: string;
+} | {
+    type: "WRITE.BEGIN";
+    slice: string;
+    write: string;
+    upsert?: readonly any[] | undefined;
+    remove?: readonly string[];
+} | {
+    type: "QUERY.UPDATE";
+    slice: string;
+    key: string;
+    view: CacheView<readonly AnyEntity[]>;
+} | {
+    type: "STORE.HYDRATED";
+    slices: PersistedSlices | null;
+}, {}, never, never, never, never, "ready" | "hydrating" | "boot", string, {
+    hydrate: boolean;
+}, xstate.NonReducibleUnknown, xstate.EventObject, xstate.MetaObject, {
+    id: "aeonStore";
+    states: {
+        readonly boot: {};
+        readonly hydrating: {};
+        readonly ready: {};
+    };
+}>;
+declare function createAeonStore<S extends AnySlices>(options: StoreOptions<S>): AeonStore<S>;
+
+export { type AeonStore, type AnySlices, type EntityOf, type PersistedSlices, type QueryOf, type QueryResult, type QueryView, type Selection, type SliceDefinition, type SliceOptions, type SliceState, type StoreAdapter, type StoreEvent, type StoreOptions, type StorePersistOptions, type StoreState, type StoreStatus, type StoreUpdate, createAeonStore, createStoreMachine, defineSlice, entityAttrs, isStorableName, memoryAdapter, queryAttrs, shallowEqual, unstorableField, webStorageAdapter };

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

@@ -0,0 +1,25 @@
+import {
+  createAeonStore,
+  createStoreMachine,
+  defineSlice,
+  entityAttrs,
+  isStorableName,
+  memoryAdapter,
+  queryAttrs,
+  shallowEqual,
+  unstorableField,
+  webStorageAdapter
+} from "../chunk-H5XJGZHT.js";
+import "../chunk-5BNAV4S2.js";
+export {
+  createAeonStore,
+  createStoreMachine,
+  defineSlice,
+  entityAttrs,
+  isStorableName,
+  memoryAdapter,
+  queryAttrs,
+  shallowEqual,
+  unstorableField,
+  webStorageAdapter
+};

package/packages/primitives/src/index.ts

@@ -15,3 +15,6 @@ 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'
+export * from './machines/store.js'