foldkit-primitives 0.1.0

package/dist/state/index.d.mts

@@ -0,0 +1,342 @@
+import { Schema } from "effect";
+import * as Mount from "foldkit/mount";
+import { Bundle } from "foldkit-bundle";
+//#region src/state/history.d.ts
+export declare const HistoryModel: <Value>(value: Schema.Codec<Value, unknown>) => Schema.Struct<{
+  readonly past: Schema.$Array<Schema.Codec<Value, unknown, never, never>>;
+  readonly present: Schema.Codec<Value, unknown, never, never>;
+  readonly future: Schema.$Array<Schema.Codec<Value, unknown, never, never>>;
+}>;
+export type HistoryModel<Value> = {
+  readonly past: ReadonlyArray<Value>;
+  readonly present: Value;
+  readonly future: ReadonlyArray<Value>;
+};
+export declare const history: <const Name extends string, Value>(config: {
+  readonly name: Name;
+  readonly value: Schema.Codec<Value, unknown>;
+  readonly capacity?: number | undefined;
+}) => Bundle.Bundle<Name, {
+  readonly initial: Value;
+}, {
+  readonly past: readonly Value[];
+  readonly present: Value;
+  readonly future: readonly Value[];
+}, {
+  readonly _tag: "Push";
+  readonly value: Value;
+} | {
+  readonly _tag: "Undo";
+} | {
+  readonly _tag: "Redo";
+} | {
+  readonly _tag: "Clear";
+}, never, never, never, void, {}, {}> & {
+  Message: import("foldkit/message").MessageUnion<{
+    readonly Push: {
+      readonly value: Schema.Codec<Value, unknown, never, never>;
+    };
+    readonly Undo: {};
+    readonly Redo: {};
+    readonly Clear: {};
+  }>;
+};
+/** Whether Undo would move: the past is non-empty. */
+export declare const canUndo: <Value>(model: HistoryModel<Value>) => boolean;
+/** Whether Redo would move: the future is non-empty. */
+export declare const canRedo: <Value>(model: HistoryModel<Value>) => boolean;
+//#endregion
+//#region src/state/locale.d.ts
+export declare const LocaleModel: Schema.Struct<{
+  readonly locale: Schema.String;
+}>;
+export type LocaleModel = typeof LocaleModel.Type;
+export declare const LocaleMessage: import("foldkit/message").MessageUnion<{
+  readonly SetLocale: {
+    readonly locale: Schema.String;
+  };
+}>;
+export type LocaleMessage = typeof LocaleMessage.Type;
+export declare const Locale: Bundle.Bundle<"Locale", {
+  readonly default: string;
+}, {
+  locale: string;
+}, {
+  readonly _tag: "SetLocale";
+  readonly locale: string;
+}, never, never, never, void, {}, {}>;
+//#endregion
+//#region src/state/pagination.d.ts
+export declare const PaginationModel: Schema.Struct<{
+  readonly page: Schema.Number;
+  readonly perPage: Schema.Number;
+  readonly total: Schema.NullOr<Schema.Number>;
+}>;
+export type PaginationModel = typeof PaginationModel.Type;
+export declare const PaginationMessage: import("foldkit/message").MessageUnion<{
+  readonly GoToPage: {
+    readonly page: Schema.Number;
+  };
+  readonly NextPage: {};
+  readonly PrevPage: {};
+  readonly SetPerPage: {
+    readonly perPage: Schema.Number;
+  };
+  readonly SetTotal: {
+    readonly total: Schema.NullOr<Schema.Number>;
+  };
+}>;
+export type PaginationMessage = typeof PaginationMessage.Type;
+/** The number of pages, or null while the total is unknown. */
+export declare const pageCount: (model: PaginationModel) => number | null;
+/** The offset of the first item on the page, for a slice or a query. */
+export declare const offset: (model: PaginationModel) => number;
+export declare const Pagination: Bundle.Bundle<"Pagination", {
+  readonly perPage: number;
+  readonly total?: number | null | undefined;
+}, {
+  total: number | null;
+  page: number;
+  perPage: number;
+}, {
+  readonly _tag: "GoToPage";
+  readonly page: number;
+} | {
+  readonly _tag: "NextPage";
+} | {
+  readonly _tag: "PrevPage";
+} | {
+  readonly _tag: "SetPerPage";
+  readonly perPage: number;
+} | {
+  readonly _tag: "SetTotal";
+  readonly total: number | null;
+}, never, never, never, void, {}, {}>;
+//#endregion
+//#region src/state/range.d.ts
+/**
+ * A numeric range as an array: `range(1, 4)` is `[1, 2, 3]`, inclusive of
+ * the start and exclusive of the end, like `Array.from` length math. The
+ * pagination companion: `range(1, (pageCount(model) ?? 0) + 1)` is the page
+ * list. A zero or non-finite step would loop forever, so it throws, naming
+ * the caller — like History's capacity check.
+ */
+export declare const range: (start: number, end: number, step?: number) => ReadonlyArray<number>;
+//#endregion
+//#region src/state/selection.d.ts
+export declare const SelectionSetModel: Schema.Struct<{
+  readonly selected: Schema.$Array<Schema.String>;
+}>;
+export type SelectionSetModel = typeof SelectionSetModel.Type;
+export declare const SelectionSetMessage: import("foldkit/message").MessageUnion<{
+  readonly Select: {
+    readonly id: Schema.String;
+  };
+  readonly Deselect: {
+    readonly id: Schema.String;
+  };
+  readonly Toggle: {
+    readonly id: Schema.String;
+  };
+  readonly ReplaceAll: {
+    readonly ids: Schema.$Array<Schema.String>;
+  };
+  readonly Clear: {};
+}>;
+export type SelectionSetMessage = typeof SelectionSetMessage.Type;
+/** Whether the id is currently selected. */
+export declare const isSelected: (model: SelectionSetModel, id: string) => boolean;
+export declare const SelectionSet: Bundle.Bundle<"SelectionSet", void, {
+  readonly selected: readonly string[];
+}, {
+  readonly _tag: "Clear";
+} | {
+  readonly _tag: "Select";
+  readonly id: string;
+} | {
+  readonly _tag: "Deselect";
+  readonly id: string;
+} | {
+  readonly _tag: "Toggle";
+  readonly id: string;
+} | {
+  readonly _tag: "ReplaceAll";
+  readonly ids: readonly string[];
+}, never, never, never, void, {}, {}>;
+//#endregion
+//#region src/state/virtual.d.ts
+export interface VirtualWindow {
+  /** First visible row index, inclusive. */
+  readonly start: number;
+  /** End row index, exclusive. */
+  readonly end: number;
+}
+/** Layout constants: per-row estimate, inter-row gap, and end padding. */
+export interface VirtualLayout {
+  readonly estimatedHeight: number;
+  readonly gap: number;
+  readonly paddingStart: number;
+  readonly paddingEnd: number;
+}
+/** Total scrollable height: padding, measured rows, estimates, and gaps. */
+export declare const totalHeight: (keys: ReadonlyArray<string>, heights: Readonly<Record<string, number>>, layout: VirtualLayout) => number;
+/** Pixel offset of a row's top edge: padding plus the prefix before it. */
+export declare const offsetFor: (index: number, keys: ReadonlyArray<string>, heights: Readonly<Record<string, number>>, layout: VirtualLayout) => number;
+/**
+ * Which rows to render for a scroll position: the rows intersecting
+ * `[scrollTop, scrollTop + viewportHeight)`, widened by `overscan` on both
+ * sides and clamped to `[0, count]`. Gaps and padding are dead space — no
+ * row — so boxes are tested, not cumulative coverage. An overscan of zero
+ * renders exactly the visible rows.
+ */
+export declare const visibleRange: (keys: ReadonlyArray<string>, heights: Readonly<Record<string, number>>, layout: VirtualLayout, scrollTop: number, viewportHeight: number, overscan: number) => VirtualWindow;
+export declare const VirtualModel: Schema.Struct<{
+  readonly scrollTop: Schema.Number;
+  readonly heights: Schema.$Record<Schema.String, Schema.Number>;
+  readonly scrolling: Schema.Boolean;
+  readonly generation: Schema.Number;
+  readonly estimatedHeight: Schema.Number;
+  readonly overscan: Schema.Number;
+  readonly gap: Schema.Number;
+  readonly paddingStart: Schema.Number;
+  readonly paddingEnd: Schema.Number;
+}>;
+export type VirtualModel = typeof VirtualModel.Type;
+export declare const VirtualMessage: import("foldkit/message").MessageUnion<{
+  readonly Scrolled: {
+    readonly top: Schema.Number;
+  };
+  readonly Measured: {
+    readonly key: Schema.String;
+    readonly height: Schema.Number;
+  };
+  /** Drops heights for keys no longer listed: the bundle never sees the key
+      order, so the application tells it what left. */
+  readonly Prune: {
+    readonly keys: Schema.$Array<Schema.String>;
+  };
+  /** Fires when scrolling has been silent for `settleMs`: only the latest
+      generation counts, so a fling's intermediate timers emit nothing. */
+  readonly Settled: {
+    readonly generation: Schema.Number;
+  };
+}>;
+export type VirtualMessage = typeof VirtualMessage.Type;
+/**
+ * The rows to render plus the spacer height, from the Model, the key order,
+ * and the viewport height. Layout and overscan come from the Model, so the
+ * call cannot disagree with the placement. Keys stay the application's:
+ * render each row keyed, and per-row placements keep identity.
+ */
+export declare const windowFor: (model: VirtualModel, keys: ReadonlyArray<string>, viewportHeight: number) => VirtualWindow & {
+  readonly totalHeight: number;
+};
+/**
+ * Whether the viewport rests at (or past) the end, within `threshold`
+ * pixels: the infinite-scroll check. An empty list counts as ended — there
+ * is nothing to scroll, so more should load. Thresholds below zero clamp
+ * to zero.
+ */
+export declare const isAtEnd: (model: VirtualModel, keys: ReadonlyArray<string>, viewportHeight: number, threshold?: number) => boolean;
+export declare const Virtual: Bundle.Bundle<"Virtual", {
+  readonly estimatedHeight: number;
+  readonly overscan: number;
+  readonly gap: number;
+  readonly paddingStart: number;
+  readonly paddingEnd: number;
+  readonly settleMs?: number | undefined;
+  readonly initialScrollTop?: number | undefined;
+  readonly initialHeights?: Readonly<Record<string, number>> | undefined;
+}, {
+  readonly scrollTop: number;
+  readonly heights: {
+    readonly [x: string]: number;
+  };
+  readonly scrolling: boolean;
+  readonly generation: number;
+  readonly estimatedHeight: number;
+  readonly overscan: number;
+  readonly gap: number;
+  readonly paddingStart: number;
+  readonly paddingEnd: number;
+}, {
+  readonly _tag: "Measured";
+  readonly key: string;
+  readonly height: number;
+} | {
+  readonly _tag: "Settled";
+  readonly generation: number;
+} | {
+  readonly _tag: "Scrolled";
+  readonly top: number;
+} | {
+  readonly _tag: "Prune";
+  readonly keys: readonly string[];
+}, never, never, never, void, {}, {}>;
+export declare const ViewportScrolled: Schema.TaggedStruct<"ViewportScrolled", {
+  readonly top: Schema.Number;
+}>;
+export type ViewportScrolled = typeof ViewportScrolled.Type;
+/**
+ * The scroll container's position, reported on its own scrolls starting
+ * with the current one. Attach to the scrolling element — viewport scrolls
+ * arrive through the window-level scroll entry instead.
+ */
+export declare const Viewport: Mount.MountDefinitionNoArgs<"Viewport", {
+  readonly _tag: "ViewportScrolled";
+  readonly top: number;
+}>;
+export declare const RowMeasured: Schema.TaggedStruct<"RowMeasured", {
+  readonly key: Schema.String;
+  readonly height: Schema.Number;
+}>;
+export type RowMeasured = typeof RowMeasured.Type;
+/**
+ * One row's height, reported on every resize starting with the current
+ * one. The key is the application's row identity, echoed back so the
+ * parent files the height without tracking which Mount sent what.
+ */
+export declare const MeasureRow: Mount.MountDefinitionWithArgs<"MeasureRow", {
+  key: Schema.String;
+}, {
+  readonly _tag: "RowMeasured";
+  readonly key: string;
+  readonly height: number;
+}>;
+/**
+ * Which section header sticks for a window: the last section starting at
+ * or before the first rendered row, or null above the first section. Order
+ * independent — the scan takes the maximum, so unsorted input still
+ * answers. CSS `position: sticky` does the sticking; this answers *what*
+ * sticks, for styling and callbacks.
+ */
+export declare const stickyHeader: (sections: ReadonlyArray<{
+  readonly key: string;
+  readonly index: number;
+}>, startIndex: number) => string | null;
+export interface MasonryPlacement {
+  readonly key: string;
+  readonly column: number;
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+/**
+ * Masonry layout as a pure function: fixed column count and width, each
+ * item packed into the currently shortest column. Unmeasured items use the
+ * estimate; poisoned heights fall back the same way. This is layout only,
+ * not windowing — every placed item renders, so it fits hundreds of images,
+ * not hundred-thousands. Needing a windowed grid is a different algorithm.
+ */
+export declare const masonry: (keys: ReadonlyArray<string>, heights: Readonly<Record<string, number>>, options: {
+  readonly columns: number;
+  readonly columnWidth: number;
+  readonly gap: number;
+  readonly estimatedHeight: number;
+}) => {
+  readonly placements: ReadonlyArray<MasonryPlacement>;
+  readonly totalHeight: number;
+};
+//#endregion
+//# sourceMappingURL=index.d.mts.map

package/dist/state/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/state/history.ts","../../src/state/locale.ts","../../src/state/pagination.ts","../../src/state/range.ts","../../src/state/selection.ts","../../src/state/virtual.ts"],"mappings":";;;;qBASa,eAAgB,OAAK,OAAS,OAAO,MAAM,oBAAe,OAAA;;;;;YAM3D,aAAa;WACd,MAAM,cAAc;WACpB,SAAS;WACT,QAAQ,cAAc;;qBAGpB,gBAAiB,qBAAqB,OAAK;WAC7C,MAAM;WACN,OAAO,OAAO,MAAM;WACpB;MACV,OAAA,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;qBA+DY,UAAW,OAAK,OAAS,aAAa;;qBAGtC,UAAW,OAAK,OAAS,aAAa;;;qBCjFtC,aAAW,OAAA;;;YACZ,qBAAqB,YAAY;qBAEhC,yCAAa;;qBAAb,OAAA;;;YACD,uBAAuB,cAAc;qBAEpC,QAAM,OAAA;;;;;;;;;;qBCPN,iBAAe,OAAA;;;;;YAKhB,yBAAyB,gBAAgB;qBAExC,6CAAiB;;;;;;;;;;;;;YAOlB,2BAA2B,kBAAkB;;qBAU5C,YAAS,OAAW;;qBAIpB,SAAM,OAAW;qBAEjB,YAAU,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBChCV,QAAK,eAAiB,aAAa,kBAAa;;;qBCEhD,mBAAiB,OAAA;;;YAClB,2BAA2B,kBAAkB;qBAE5C,+CAAmB;;;;;;;;;;;;;;;YAOpB,6BAA6B,oBAAoB;;qBAMhD,aAAU,OAAW,mBAAiB;qBAGtC,cAAY,OAAA;;;;;;;;;;;;;;;;;;;iBCRR;;WAEN;;WAEA;;;iBAIM;WACN;WACA;WACA;WACA;;;qBAkBE,cAAW,MAChB,uBAAqB,SAClB,SAAS,yBAAuB,QACjC;;qBAWG,YAAS,eACP,MACP,uBAAqB,SAClB,SAAS,yBAAuB,QACjC;;;;;;;;qBAiBG,eAAY,MACjB,uBAAqB,SAClB,SAAS,yBAAuB,QACjC,eAAa,mBACJ,wBACK,qBAErB;qBA4BU,cAAY,OAAA;;;;;;;;;;;YAWb,sBAAsB,aAAa;qBAElC,0CAAc;;;;;;;;;;;;;;;;;;;YAUf,wBAAwB,eAAe;;;;;;;qBAetC,YAAS,OACb,cAAY,MACb,uBAAqB,2BAE1B;WAA2B;;;;;;;;qBAmBjB,UAAO,OACX,cAAY,MACb,uBAAqB,wBACL;qBAaX,SAAO,OAAA;WAKU;WACP;WACL;WACS;WACF;WACD;WACQ;WACF,iBAAA,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAmG1B,kBAAgB,OAAA;;;YACjB,0BAA0B,iBAAiB;;;;;;qBAO1C,UAAQ,MAAA;;;;qBAeR,aAAW,OAAA;;;;YAIZ,qBAAqB,YAAY;;;;;;qBAShC,YAAU,MAAA;;;;;;;;;;;;;;qBAgCV,eAAY,UACb;WAAyB;WAAsB;IAAgB;iBAc1D;WACN;WACA;WACA;WACA;WACA;WACA;;;;;;;;;qBAUE,UAAO,MACZ,uBAAqB,SAClB,SAAS,yBAAuB;WAE9B;WACA;WACA;WACA;;WAEC,YAAY,cAAc;WAA4B"}