@ixfx/components 0.15.4 → 0.16.0

package/dist/types-LU1u0CB8.d.ts

@@ -0,0 +1,87 @@
+//#region src/common/view-state/types.d.ts
+/**
+ * Shared view-state contract for list-like components.
+ *
+ * View state is everything about *how* a component is showing its data —
+ * selection, expansion, scroll, column sizes — kept separate from the data
+ * itself. It is plain JSON (arrays and records, never Sets or Maps) so a host
+ * can `JSON.stringify` it straight into whatever storage it likes. Components
+ * never persist it themselves; see `bindViewState()`.
+ *
+ * Every field is keyed by the stable item / column / group key, never by
+ * index, so state can be re-applied to data that has been rebuilt, re-sorted
+ * or streamed in over time. Keys the current data doesn't contain are kept
+ * as pending and applied once a matching item appears.
+ */
+/** Current schema version. Bump on breaking shape changes. */
+declare const VIEW_STATE_VERSION = 1;
+/** Name of the debounced change event every view-stateful component fires. */
+declare const VIEW_STATE_CHANGE = "view-state-change";
+/**
+ * Where the viewport is scrolled to. `anchor` is the preferred form: the key
+ * of the first visible item plus how far (px) the viewport top sits below
+ * that item's start. It survives items being inserted above. `top` / `left`
+ * are raw pixel offsets, used when there is no keyed item to anchor to.
+ */
+type ScrollState = {
+  readonly top: number;
+  readonly left?: number;
+  readonly anchor?: {
+    readonly key: string;
+    readonly offset: number;
+  };
+};
+/** Fields shared by all view states. Components extend this with their own. */
+type ViewStateBase = {
+  readonly v: typeof VIEW_STATE_VERSION;
+  /** Component kind, e.g. `tree-list`. Mismatched states are ignored. */
+  readonly kind: string;
+  /** Selected item keys. In `checked` interaction modes this is the checked set. */
+  readonly selected?: readonly string[];
+  /** Keyboard cursor (tickled / focused item) key. */
+  readonly focus?: string;
+  readonly scroll?: ScrollState;
+  /**
+   * Explicit open/closed choices for expandable things (tree branches, groups),
+   * keyed by item or group key. A missing key means "use the default".
+   */
+  readonly expanded?: Readonly<Record<string, boolean>>;
+};
+/**
+ * What triggered a `view-state-change`:
+ * - `user` — a direct interaction (click, key, drag, scroll)
+ * - `data` — the data changed and the component adjusted (e.g. pruned focus)
+ * - `restore` — pending state was applied to newly-arrived items, or `setViewState()` ran
+ */
+type ViewStateChangeReason = `user` | `data` | `restore`;
+type ViewStateChangeDetail<S extends ViewStateBase = ViewStateBase> = {
+  readonly state: S;
+  readonly reason: ViewStateChangeReason;
+};
+type ViewStateChangeEvent<S extends ViewStateBase = ViewStateBase> = CustomEvent<ViewStateChangeDetail<S>>;
+type GetViewStateOptions<S extends ViewStateBase> = {
+  /** Only include these fields (plus `v` and `kind`). Default: all. */
+  readonly include?: ReadonlyArray<Exclude<keyof S, `v` | `kind`>>;
+  /**
+   * Include pending state for keys not (yet) present in the data. Default
+   * `true` — leaving it out means a save made mid-rebuild overwrites the
+   * stored state with a partial one.
+   */
+  readonly includePending?: boolean;
+};
+/** Implemented by every component that supports view-state snapshot / restore. */
+type ViewStateful<S extends ViewStateBase = ViewStateBase> = {
+  /** Snapshot the current view state as plain JSON. */
+  getViewState: (options?: GetViewStateOptions<S>) => S;
+  /**
+   * Apply a (possibly partial) view state. Only fields present are applied;
+   * absent fields are left as they are. Keys not in the current data are kept
+   * pending and applied when matching items appear. A state whose `kind` or
+   * `v` doesn't match is ignored with a console warning.
+   */
+  setViewState: (state: Partial<S>) => void;
+  /** Drop all pending (not-yet-matched) state. */
+  clearPendingViewState: () => void;
+};
+//#endregion
+export { ViewStateBase as a, ViewStateChangeReason as c, VIEW_STATE_VERSION as i, ViewStateful as l, ScrollState as n, ViewStateChangeDetail as o, VIEW_STATE_CHANGE as r, ViewStateChangeEvent as s, GetViewStateOptions as t };