foldkit 0.74.1 → 0.75.0

package/dist/ui/index.d.ts

@@ -21,4 +21,5 @@ export * as Textarea from './textarea/public.js';
 export * as Tabs from './tabs/public.js';
 export * as Toast from './toast/public.js';
 export * as Tooltip from './tooltip/public.js';
+export * as VirtualList from './virtualList/public.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/ui/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,uBAAuB,CAAA;AAClD,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAA;AAC5C,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAA;AAChD,OAAO,KAAK,UAAU,MAAM,wBAAwB,CAAA;AACpD,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAA;AAChD,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAA;AAChD,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAA;AAC5C,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAA;AACtD,OAAO,KAAK,UAAU,MAAM,wBAAwB,CAAA;AACpD,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAA;AAChD,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAA;AAChD,OAAO,KAAK,KAAK,MAAM,mBAAmB,CAAA;AAC1C,OAAO,KAAK,OAAO,MAAM,qBAAqB,CAAA;AAC9C,OAAO,KAAK,IAAI,MAAM,kBAAkB,CAAA;AACxC,OAAO,KAAK,OAAO,MAAM,qBAAqB,CAAA;AAC9C,OAAO,KAAK,UAAU,MAAM,wBAAwB,CAAA;AACpD,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAA;AAC5C,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAA;AAC5C,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAA;AAC5C,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAA;AAChD,OAAO,KAAK,IAAI,MAAM,kBAAkB,CAAA;AACxC,OAAO,KAAK,KAAK,MAAM,mBAAmB,CAAA;AAC1C,OAAO,KAAK,OAAO,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,SAAS,MAAM,uBAAuB,CAAA;AAClD,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAA;AAC5C,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAA;AAChD,OAAO,KAAK,UAAU,MAAM,wBAAwB,CAAA;AACpD,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAA;AAChD,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAA;AAChD,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAA;AAC5C,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAA;AACtD,OAAO,KAAK,UAAU,MAAM,wBAAwB,CAAA;AACpD,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAA;AAChD,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAA;AAChD,OAAO,KAAK,KAAK,MAAM,mBAAmB,CAAA;AAC1C,OAAO,KAAK,OAAO,MAAM,qBAAqB,CAAA;AAC9C,OAAO,KAAK,IAAI,MAAM,kBAAkB,CAAA;AACxC,OAAO,KAAK,OAAO,MAAM,qBAAqB,CAAA;AAC9C,OAAO,KAAK,UAAU,MAAM,wBAAwB,CAAA;AACpD,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAA;AAC5C,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAA;AAC5C,OAAO,KAAK,MAAM,MAAM,oBAAoB,CAAA;AAC5C,OAAO,KAAK,QAAQ,MAAM,sBAAsB,CAAA;AAChD,OAAO,KAAK,IAAI,MAAM,kBAAkB,CAAA;AACxC,OAAO,KAAK,KAAK,MAAM,mBAAmB,CAAA;AAC1C,OAAO,KAAK,OAAO,MAAM,qBAAqB,CAAA;AAC9C,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAA"}

package/dist/ui/index.js

@@ -21,3 +21,4 @@ export * as Textarea from './textarea/public.js';
 export * as Tabs from './tabs/public.js';
 export * as Toast from './toast/public.js';
 export * as Tooltip from './tooltip/public.js';
+export * as VirtualList from './virtualList/public.js';

package/dist/ui/virtualList/index.d.ts

@@ -0,0 +1,179 @@
+import { Option, Schema as S } from 'effect';
+import * as Command from '../../command/index.js';
+import { type Attribute, type Html, type TagName } from '../../html/index.js';
+/** Schema for the virtual list's state. Tracks scroll position, container
+ *  measurement, and any in-flight programmatic scroll. */
+export declare const Model: S.Struct<{
+    id: typeof S.String;
+    rowHeightPx: typeof S.Number;
+    scrollTop: typeof S.Number;
+    measurement: S.Union<[import("../../schema/index.js").CallableTaggedStruct<"Unmeasured", {}>, import("../../schema/index.js").CallableTaggedStruct<"Measured", {
+        containerHeight: typeof S.Number;
+    }>]>;
+    pendingScroll: S.Union<[import("../../schema/index.js").CallableTaggedStruct<"Idle", {}>, import("../../schema/index.js").CallableTaggedStruct<"ScrollingToIndex", {
+        index: typeof S.Number;
+        version: typeof S.Number;
+    }>]>;
+    pendingScrollVersion: typeof S.Number;
+}>;
+export type Model = typeof Model.Type;
+/** Sent when the user scrolls the container. Carries the new scroll position
+ *  read from the scroll event. */
+export declare const ScrolledContainer: import("../../schema/index.js").CallableTaggedStruct<"ScrolledContainer", {
+    scrollTop: typeof S.Number;
+}>;
+/** Sent when the container resizes. Carries the new container height read
+ *  from the `ResizeObserver` entry. */
+export declare const MeasuredContainer: import("../../schema/index.js").CallableTaggedStruct<"MeasuredContainer", {
+    containerHeight: typeof S.Number;
+}>;
+/** Sent when a `scrollToIndex` Command completes. Carries the version it was
+ *  issued with so the update can ignore stale completions. */
+export declare const CompletedApplyScroll: import("../../schema/index.js").CallableTaggedStruct<"CompletedApplyScroll", {
+    version: typeof S.Number;
+}>;
+/** Union of all messages the virtual list component can produce. */
+export declare const Message: S.Union<[
+    typeof ScrolledContainer,
+    typeof MeasuredContainer,
+    typeof CompletedApplyScroll
+]>;
+export type ScrolledContainer = typeof ScrolledContainer.Type;
+export type MeasuredContainer = typeof MeasuredContainer.Type;
+export type Message = typeof Message.Type;
+/** Configuration for creating a virtual list model with `init`. */
+export type InitConfig = Readonly<{
+    id: string;
+    rowHeightPx: number;
+    initialScrollTop?: number;
+}>;
+/** Creates an initial virtual list model from a config. The container starts
+ *  in `Unmeasured` state. The first `ResizeObserver` entry transitions it to
+ *  `Measured`. */
+export declare const init: (config: InitConfig) => Model;
+export declare const ApplyScroll: Command.CommandDefinition<"ApplyScroll", {
+    readonly _tag: "CompletedApplyScroll";
+    readonly version: number;
+}>;
+/** Processes a virtual list message and returns the next model and commands. */
+export declare const update: (model: Model, message: Message) => readonly [Model, ReadonlyArray<Command.Command<Message>>];
+/** Programmatically scrolls the container so the row at `index` is visible.
+ *  Returns the next model and a Command that mutates `element.scrollTop`. The
+ *  natural scroll event then flows back through `ScrolledContainer` and the
+ *  component re-renders the new visible slice.
+ *
+ *  Uses version-based cancellation: each call increments
+ *  `pendingScrollVersion` so a stale `CompletedApplyScroll` (e.g. from a
+ *  previous in-flight scroll) is ignored when its version no longer matches.
+ *
+ *  Should be called after the container has rendered. If the container is not
+ *  yet in the DOM the Command silently no-ops (the model still transitions
+ *  through `ScrollingToIndex` → `Idle` via the version-matched completion). */
+export declare const scrollToIndex: (model: Model, index: number) => readonly [Model, ReadonlyArray<Command.Command<Message>>];
+/** Slice of the data array that the view should render, plus the spacer
+ *  heights that keep the scrollbar physically correct. The first row in the
+ *  slice corresponds to data index `startIndex`. */
+export type VisibleWindow = Readonly<{
+    startIndex: number;
+    endIndex: number;
+    topSpacerHeight: number;
+    bottomSpacerHeight: number;
+}>;
+/** Computes the visible slice of a data array given the current scroll
+ *  position, container height, row height, and an overscan buffer.
+ *
+ *  Returns `Option.none()` when the container has not yet been measured;
+ *  callers should render a placeholder (or `Html.empty`) and wait for the
+ *  first `MeasuredContainer` message. */
+export declare const visibleWindow: (model: Model, itemCount: number, overscan: number) => Option.Option<VisibleWindow>;
+/** Schema describing the subscription dependencies for container scroll and
+ *  resize tracking. */
+export declare const SubscriptionDeps: S.Struct<{
+    containerEvents: S.Struct<{
+        id: typeof S.String;
+    }>;
+}>;
+/** Subscriptions that track the container's scroll position and size.
+ *
+ *  - **scroll**: listens for `scroll` events on the container element and
+ *    emits `ScrolledContainer` with the new `scrollTop`.
+ *  - **resize**: observes the container with `ResizeObserver` and emits
+ *    `MeasuredContainer` with the new height.
+ *
+ *  A `MutationObserver` watches the document for the container element
+ *  appearing and disappearing, so the listeners attach the moment the
+ *  element is inserted into the DOM and clean up when it is removed. This
+ *  makes the subscription robust across SPA route changes: navigating to a
+ *  page that mounts the list, away, and back all reattach correctly without
+ *  the consumer having to teach the framework about navigation. */
+export declare const subscriptions: import("../../runtime/subscription.js").Subscriptions<{
+    readonly id: string;
+    readonly rowHeightPx: number;
+    readonly scrollTop: number;
+    readonly measurement: {
+        readonly _tag: "Unmeasured";
+    } | {
+        readonly _tag: "Measured";
+        readonly containerHeight: number;
+    };
+    readonly pendingScroll: {
+        readonly _tag: "Idle";
+    } | {
+        readonly _tag: "ScrollingToIndex";
+        readonly index: number;
+        readonly version: number;
+    };
+    readonly pendingScrollVersion: number;
+}, {
+    readonly _tag: "ScrolledContainer";
+    readonly scrollTop: number;
+} | {
+    readonly _tag: "MeasuredContainer";
+    readonly containerHeight: number;
+} | {
+    readonly _tag: "CompletedApplyScroll";
+    readonly version: number;
+}, S.Struct<{
+    containerEvents: S.Struct<{
+        id: typeof S.String;
+    }>;
+}>, never>;
+/** Configuration for rendering a virtual list with `view`.
+ *
+ *  VirtualList does not take a `toParentMessage` callback. All input
+ *  (scroll events and resize observations) flows through the
+ *  `containerEvents` Subscription, not through view-bound handlers.
+ *  Consumers wrap the subscription's stream into their parent Message in
+ *  their own `subscriptions` definition. */
+export type ViewConfig<Message, Item> = Readonly<{
+    model: Model;
+    items: ReadonlyArray<Item>;
+    itemToKey: (item: Item, index: number) => string;
+    itemToView: (item: Item, index: number) => Html;
+    /** Number of rows rendered above and below the visible viewport. Higher
+     *  values smooth out fast scroll at the cost of mounting more DOM. Default
+     *  is 5; react-window uses 1 and react-virtualized uses 3. Pick a value
+     *  that suits the row's mount cost. */
+    overscan?: number;
+    rowElement?: TagName;
+    className?: string;
+    attributes?: ReadonlyArray<Attribute<Message>>;
+}>;
+/** Renders a virtualized list. Only items inside the viewport (plus an
+ *  overscan buffer) are mounted; spacer divs above and below the slice keep
+ *  the scrollbar's apparent total height correct.
+ *
+ *  Items must be keyed via `itemToKey` so the VDOM matches `row 150` to
+ *  `row 150` after the slice shifts during scroll, rather than matching by
+ *  position and producing stale DOM.
+ *
+ *  Each row wrapper is rendered with `display: grid` so the consumer's
+ *  `itemToView` content fills the configured `rowHeightPx` and the full row
+ *  width. Use flex/grid with `align-items: center` inside `itemToView` to
+ *  vertically center content within the row. */
+export declare const view: <Message, Item>(config: ViewConfig<Message, Item>) => Html;
+/** Creates a memoized virtual list view. Static config is captured in a
+ *  closure; only `model` and `items` are compared per render via
+ *  `createLazy`. */
+export declare const lazy: <Message, Item>(staticConfig: Omit<ViewConfig<Message, Item>, "model" | "items">) => ((model: Model, items: ReadonlyArray<Item>) => Html);
+//# sourceMappingURL=index.d.ts.map

package/dist/ui/virtualList/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ui/virtualList/index.ts"],"names":[],"mappings":"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"}

package/dist/ui/virtualList/index.js

@@ -0,0 +1,318 @@
+import { Array, Effect, Match as M, Number, Option, Schema as S, Stream, } from 'effect';
+import * as Command from '../../command/index.js';
+import { createLazy, html, } from '../../html/index.js';
+import { m } from '../../message/index.js';
+import { makeSubscriptions } from '../../runtime/subscription.js';
+import { ts } from '../../schema/index.js';
+import { evo } from '../../struct/index.js';
+// MODEL
+const Unmeasured = ts('Unmeasured');
+const Measured = ts('Measured', { containerHeight: S.Number });
+/** Measurement state of the virtual list's scrollable container.
+ *
+ * Before the container's `ResizeObserver` fires for the first time we don't
+ * know its height and cannot compute a visible slice. The view must handle
+ * `Unmeasured` explicitly, typically by rendering a placeholder until the
+ * first measurement arrives.
+ */
+const Measurement = S.Union(Unmeasured, Measured);
+const Idle = ts('Idle');
+const ScrollingToIndex = ts('ScrollingToIndex', {
+    index: S.Number,
+    version: S.Number,
+});
+/** State of a programmatic scroll initiated by `scrollToIndex`. */
+const PendingScroll = S.Union(Idle, ScrollingToIndex);
+/** Schema for the virtual list's state. Tracks scroll position, container
+ *  measurement, and any in-flight programmatic scroll. */
+export const Model = S.Struct({
+    id: S.String,
+    rowHeightPx: S.Number,
+    scrollTop: S.Number,
+    measurement: Measurement,
+    pendingScroll: PendingScroll,
+    pendingScrollVersion: S.Number,
+});
+// MESSAGE
+/** Sent when the user scrolls the container. Carries the new scroll position
+ *  read from the scroll event. */
+export const ScrolledContainer = m('ScrolledContainer', {
+    scrollTop: S.Number,
+});
+/** Sent when the container resizes. Carries the new container height read
+ *  from the `ResizeObserver` entry. */
+export const MeasuredContainer = m('MeasuredContainer', {
+    containerHeight: S.Number,
+});
+/** Sent when a `scrollToIndex` Command completes. Carries the version it was
+ *  issued with so the update can ignore stale completions. */
+export const CompletedApplyScroll = m('CompletedApplyScroll', {
+    version: S.Number,
+});
+/** Union of all messages the virtual list component can produce. */
+export const Message = S.Union(ScrolledContainer, MeasuredContainer, CompletedApplyScroll);
+/** Creates an initial virtual list model from a config. The container starts
+ *  in `Unmeasured` state. The first `ResizeObserver` entry transitions it to
+ *  `Measured`. */
+export const init = (config) => ({
+    id: config.id,
+    rowHeightPx: config.rowHeightPx,
+    scrollTop: config.initialScrollTop ?? 0,
+    measurement: Unmeasured(),
+    pendingScroll: Idle(),
+    pendingScrollVersion: 0,
+});
+// UPDATE
+export const ApplyScroll = Command.define('ApplyScroll', CompletedApplyScroll);
+const applyScroll = (id, scrollTop, version) => ApplyScroll(Effect.sync(() => {
+    const element = document.getElementById(id);
+    if (element !== null) {
+        element.scrollTop = scrollTop;
+    }
+    return CompletedApplyScroll({ version });
+}));
+/** Processes a virtual list message and returns the next model and commands. */
+export const update = (model, message) => M.value(message).pipe(M.withReturnType(), M.tagsExhaustive({
+    ScrolledContainer: ({ scrollTop }) => [
+        evo(model, { scrollTop: () => scrollTop }),
+        [],
+    ],
+    MeasuredContainer: ({ containerHeight }) => {
+        const wasUnmeasured = model.measurement._tag === 'Unmeasured';
+        const needsInitialApply = wasUnmeasured && model.scrollTop !== 0;
+        if (needsInitialApply) {
+            const nextVersion = Number.increment(model.pendingScrollVersion);
+            return [
+                evo(model, {
+                    measurement: () => Measured({ containerHeight }),
+                    pendingScrollVersion: () => nextVersion,
+                    pendingScroll: () => ScrollingToIndex({
+                        index: Math.floor(model.scrollTop / model.rowHeightPx),
+                        version: nextVersion,
+                    }),
+                }),
+                [applyScroll(model.id, model.scrollTop, nextVersion)],
+            ];
+        }
+        else {
+            return [
+                evo(model, { measurement: () => Measured({ containerHeight }) }),
+                [],
+            ];
+        }
+    },
+    CompletedApplyScroll: ({ version }) => {
+        if (version !== model.pendingScrollVersion) {
+            return [model, []];
+        }
+        else {
+            return [evo(model, { pendingScroll: () => Idle() }), []];
+        }
+    },
+}));
+/** Programmatically scrolls the container so the row at `index` is visible.
+ *  Returns the next model and a Command that mutates `element.scrollTop`. The
+ *  natural scroll event then flows back through `ScrolledContainer` and the
+ *  component re-renders the new visible slice.
+ *
+ *  Uses version-based cancellation: each call increments
+ *  `pendingScrollVersion` so a stale `CompletedApplyScroll` (e.g. from a
+ *  previous in-flight scroll) is ignored when its version no longer matches.
+ *
+ *  Should be called after the container has rendered. If the container is not
+ *  yet in the DOM the Command silently no-ops (the model still transitions
+ *  through `ScrollingToIndex` → `Idle` via the version-matched completion). */
+export const scrollToIndex = (model, index) => {
+    const nextVersion = Number.increment(model.pendingScrollVersion);
+    const targetScrollTop = index * model.rowHeightPx;
+    return [
+        evo(model, {
+            pendingScrollVersion: () => nextVersion,
+            pendingScroll: () => ScrollingToIndex({ index, version: nextVersion }),
+        }),
+        [applyScroll(model.id, targetScrollTop, nextVersion)],
+    ];
+};
+const clampIndex = (index, itemCount) => Math.max(0, Math.min(index, itemCount));
+/** Computes the visible slice of a data array given the current scroll
+ *  position, container height, row height, and an overscan buffer.
+ *
+ *  Returns `Option.none()` when the container has not yet been measured;
+ *  callers should render a placeholder (or `Html.empty`) and wait for the
+ *  first `MeasuredContainer` message. */
+export const visibleWindow = (model, itemCount, overscan) => M.value(model.measurement).pipe(M.withReturnType(), M.tagsExhaustive({
+    Unmeasured: () => Option.none(),
+    Measured: ({ containerHeight }) => {
+        const firstVisibleIndex = Math.floor(model.scrollTop / model.rowHeightPx);
+        const lastVisibleIndex = Math.ceil((model.scrollTop + containerHeight) / model.rowHeightPx);
+        const startIndex = clampIndex(firstVisibleIndex - overscan, itemCount);
+        const endIndex = clampIndex(lastVisibleIndex + overscan, itemCount);
+        const topSpacerHeight = startIndex * model.rowHeightPx;
+        const bottomSpacerHeight = (itemCount - endIndex) * model.rowHeightPx;
+        return Option.some({
+            startIndex,
+            endIndex,
+            topSpacerHeight,
+            bottomSpacerHeight,
+        });
+    },
+}));
+// SUBSCRIPTION
+const containerElement = (id) => Option.fromNullable(document.getElementById(id));
+/** Schema describing the subscription dependencies for container scroll and
+ *  resize tracking. */
+export const SubscriptionDeps = S.Struct({
+    containerEvents: S.Struct({
+        id: S.String,
+    }),
+});
+/** Subscriptions that track the container's scroll position and size.
+ *
+ *  - **scroll**: listens for `scroll` events on the container element and
+ *    emits `ScrolledContainer` with the new `scrollTop`.
+ *  - **resize**: observes the container with `ResizeObserver` and emits
+ *    `MeasuredContainer` with the new height.
+ *
+ *  A `MutationObserver` watches the document for the container element
+ *  appearing and disappearing, so the listeners attach the moment the
+ *  element is inserted into the DOM and clean up when it is removed. This
+ *  makes the subscription robust across SPA route changes: navigating to a
+ *  page that mounts the list, away, and back all reattach correctly without
+ *  the consumer having to teach the framework about navigation. */
+export const subscriptions = makeSubscriptions(SubscriptionDeps)({
+    containerEvents: {
+        modelToDependencies: model => ({ id: model.id }),
+        dependenciesToStream: ({ id }) => Stream.async(emit => {
+            let scrollListener = null;
+            let resizeObserver = null;
+            let observedElement = null;
+            let pendingFrame = null;
+            const detach = () => {
+                if (resizeObserver !== null) {
+                    resizeObserver.disconnect();
+                    resizeObserver = null;
+                }
+                if (observedElement !== null && scrollListener !== null) {
+                    observedElement.removeEventListener('scroll', scrollListener);
+                }
+                observedElement = null;
+                scrollListener = null;
+            };
+            const attach = (element) => {
+                const listener = () => emit.single(ScrolledContainer({ scrollTop: element.scrollTop }));
+                element.addEventListener('scroll', listener, { passive: true });
+                scrollListener = listener;
+                observedElement = element;
+                resizeObserver = new ResizeObserver(entries => {
+                    const lastEntry = Array.last(entries);
+                    if (Option.isSome(lastEntry)) {
+                        emit.single(MeasuredContainer({
+                            containerHeight: lastEntry.value.contentRect.height,
+                        }));
+                    }
+                });
+                resizeObserver.observe(element);
+            };
+            const reconcile = () => {
+                const maybeElement = containerElement(id);
+                if (Option.isNone(maybeElement)) {
+                    if (observedElement !== null) {
+                        detach();
+                    }
+                    return;
+                }
+                if (observedElement === maybeElement.value) {
+                    return;
+                }
+                detach();
+                attach(maybeElement.value);
+            };
+            reconcile();
+            // NOTE: observes the entire document subtree because the container
+            // can be inserted/removed by any parent the consumer chooses (route
+            // changes, conditional renders, modal mounts), and the framework has
+            // no way to know that hierarchy in advance. Reconcile is gated by rAF
+            // and short-circuits when the cached observedElement is still in the
+            // DOM, so per-mutation cost stays low even with subtree: true.
+            const mutationObserver = new MutationObserver(() => {
+                if (pendingFrame !== null) {
+                    return;
+                }
+                pendingFrame = requestAnimationFrame(() => {
+                    pendingFrame = null;
+                    reconcile();
+                });
+            });
+            mutationObserver.observe(document.body, {
+                childList: true,
+                subtree: true,
+            });
+            return Effect.sync(() => {
+                mutationObserver.disconnect();
+                if (pendingFrame !== null) {
+                    cancelAnimationFrame(pendingFrame);
+                }
+                detach();
+            });
+        }),
+    },
+});
+// VIEW
+const DEFAULT_OVERSCAN = 5;
+/** Renders a virtualized list. Only items inside the viewport (plus an
+ *  overscan buffer) are mounted; spacer divs above and below the slice keep
+ *  the scrollbar's apparent total height correct.
+ *
+ *  Items must be keyed via `itemToKey` so the VDOM matches `row 150` to
+ *  `row 150` after the slice shifts during scroll, rather than matching by
+ *  position and producing stale DOM.
+ *
+ *  Each row wrapper is rendered with `display: grid` so the consumer's
+ *  `itemToView` content fills the configured `rowHeightPx` and the full row
+ *  width. Use flex/grid with `align-items: center` inside `itemToView` to
+ *  vertically center content within the row. */
+export const view = (config) => {
+    const { Class, DataAttribute, Id, Role, Style, keyed } = html();
+    const { model, items, itemToKey, itemToView, overscan = DEFAULT_OVERSCAN, rowElement = 'li', className, attributes = [], } = config;
+    const containerAttributes = [
+        Id(model.id),
+        Role('list'),
+        DataAttribute('virtual-list-id', model.id),
+        Style({
+            overflow: 'auto',
+            'list-style': 'none',
+            margin: '0',
+            padding: '0',
+        }),
+        ...(className !== undefined ? [Class(className)] : []),
+        ...attributes,
+    ];
+    const renderContainer = (children) => keyed('ul')(model.id, containerAttributes, children);
+    return Option.match(visibleWindow(model, items.length, overscan), {
+        onNone: () => renderContainer([]),
+        onSome: ({ startIndex, endIndex, topSpacerHeight, bottomSpacerHeight }) => {
+            const visibleItems = items.slice(startIndex, endIndex);
+            const topSpacer = keyed('li')(`${model.id}-top-spacer`, [Role('presentation'), Style({ height: `${topSpacerHeight}px` })], []);
+            const bottomSpacer = keyed('li')(`${model.id}-bottom-spacer`, [Role('presentation'), Style({ height: `${bottomSpacerHeight}px` })], []);
+            const renderedRows = Array.map(visibleItems, (item, sliceIndex) => {
+                const dataIndex = startIndex + sliceIndex;
+                return keyed(rowElement)(itemToKey(item, dataIndex), [
+                    DataAttribute('virtual-list-item-index', String(dataIndex)),
+                    Style({ height: `${model.rowHeightPx}px`, display: 'grid' }),
+                ], [itemToView(item, dataIndex)]);
+            });
+            return renderContainer([topSpacer, ...renderedRows, bottomSpacer]);
+        },
+    });
+};
+/** Creates a memoized virtual list view. Static config is captured in a
+ *  closure; only `model` and `items` are compared per render via
+ *  `createLazy`. */
+export const lazy = (staticConfig) => {
+    const lazyView = createLazy();
+    return (model, items) => lazyView((currentModel, currentItems) => view({
+        ...staticConfig,
+        model: currentModel,
+        items: currentItems,
+    }), [model, items]);
+};

package/dist/ui/virtualList/public.d.ts

@@ -0,0 +1,3 @@
+export { init, update, scrollToIndex, view, lazy, subscriptions, visibleWindow, Model, Message, ScrolledContainer, MeasuredContainer, CompletedApplyScroll, SubscriptionDeps, } from './index.js';
+export type { InitConfig, ViewConfig, VisibleWindow } from './index.js';
+//# sourceMappingURL=public.d.ts.map

package/dist/ui/virtualList/public.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../../src/ui/virtualList/public.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,IAAI,EACJ,MAAM,EACN,aAAa,EACb,IAAI,EACJ,IAAI,EACJ,aAAa,EACb,aAAa,EACb,KAAK,EACL,OAAO,EACP,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,YAAY,CAAA;AAEnB,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA"}

package/dist/ui/virtualList/public.js

@@ -0,0 +1 @@
+export { init, update, scrollToIndex, view, lazy, subscriptions, visibleWindow, Model, Message, ScrolledContainer, MeasuredContainer, CompletedApplyScroll, SubscriptionDeps, } from './index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foldkit",
-  "version": "0.74.1",
+  "version": "0.75.0",
   "description": "A frontend framework for TypeScript, built on Effect, using The Elm Architecture",
   "type": "module",
   "main": "./dist/index.js",
@@ -159,6 +159,10 @@
       "types": "./dist/ui/tooltip/public.d.ts",
       "import": "./dist/ui/tooltip/public.js"
     },
+    "./ui/virtualList": {
+      "types": "./dist/ui/virtualList/public.d.ts",
+      "import": "./dist/ui/virtualList/public.js"
+    },
     "./url": {
       "types": "./dist/url/public.d.ts",
       "import": "./dist/url/public.js"