@elaraai/e3-ui 1.0.97 → 1.0.98

package/dist/src/schedule/pages.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Where a paged resource kind's windows come from (#1199, #1344, #1424): the
+ * kind's own paged read, its resources in their key order; or, its builder's
+ * slice naming a source after its slot, that source's narrowed rows
+ * themselves, the narrowing's resources in the source's index's order — never
+ * a window of every resource filtered by the keys the source shows. The Plan's
+ * paged rows (`plan/event-rows.ts`) and the Calendar's (`calendar/paged.ts`)
+ * page through them alike.
+ *
+ * @packageDocumentation
+ */
+import { ArrayType, StringType, type BlockBuilder, type DictType, type EastType, type ExprType, type FunctionType, type IntegerType, type NullType, type OptionType, type StructType } from "@elaraai/east";
+import type { SeekQueryType, SeekRangeType } from "@elaraai/east-ui";
+import type { ScheduleResourceKind } from "./resources.js";
+/** A block's scope — the `$` of an East function body, its result type erased. */
+export type ScheduleBlock = BlockBuilder<EastType>;
+/** A paged source's handle, as a builder's paged rows read it: its identity, size, key search, snapshot and — a rail's narrowed source's — narrowing. */
+export type SchedulePagedHandle = ExprType<StructType<{
+    id: StringType;
+    total: FunctionType<[], OptionType<IntegerType>>;
+    seek: OptionType<FunctionType<[typeof SeekQueryType], OptionType<typeof SeekRangeType>>>;
+    revision: FunctionType<[], OptionType<StringType>>;
+    refresh: FunctionType<[OptionType<StringType>], NullType>;
+    query: FunctionType<[], StringType>;
+}>>;
+/** A whole window's read of a paged kind's resources: `(offset, limit)` → the window, `none` while a piece is in flight. */
+export type ScheduleWindowRead = ExprType<FunctionType<[IntegerType, IntegerType], OptionType<EastType>>>;
+/**
+ * Where a paged resource kind's windows come from, and how one read is drawn:
+ * the kind's own paged read, in its resources' key order; or its source of the
+ * slice, the narrowing's rows in the source's index's order.
+ */
+export interface ScheduleKindWindows {
+    /** The window `[offset, offset + limit)`, whole. */
+    readonly read: ScheduleWindowRead;
+    /** A window read → its resources, by key. */
+    readonly rows: (page: ExprType<EastType>) => ExprType<DictType<EastType, EastType>>;
+    /** A window read → the texts of its resources' keys, in the order its rows draw. */
+    readonly keys: ($: ScheduleBlock, page: ExprType<EastType>) => ExprType<ArrayType<StringType>>;
+    /** Whether a window's rows are drawn in its keys' order rather than the resources' key order: an index's order. */
+    readonly indexed: boolean;
+    /** The handle: its identity, size, key search, snapshot and narrowing. */
+    readonly handle: SchedulePagedHandle;
+    /** Whether the handle names its snapshot, `revision` and `refresh`. */
+    readonly pinned: boolean;
+    /** Whether the handle names the narrowing it serves, `query`: a source of the slice. */
+    readonly query: boolean;
+}
+/**
+ * A paged kind's own windows (#1199): its paged read, in its resources' key
+ * order.
+ *
+ * @param kind - The paged resource kind
+ * @param where - The kind, as a refusal names it (`Plan: resources.presses`)
+ * @returns Its windows
+ * @throws {Error} When its paged read is not a paged source of its resources
+ */
+export declare function scheduleOwnWindows(kind: ScheduleResourceKind<EastType, EastType>, where: string): ScheduleKindWindows;
+/**
+ * A paged kind's windows narrowed by its source of the slice (#1344): the
+ * narrowing's rows themselves, paged in the source's index's order — never a
+ * window of every resource filtered by the keys the source shows.
+ *
+ * @param kind - The paged resource kind
+ * @param slot - Its slot, which names its source
+ * @param narrowed - The source's narrowed data, as the builder's payload bound it: a rail's live source of index entries
+ * @param builder - The builder, as its refusals name it (`Plan`, `Calendar`)
+ * @returns Its windows
+ * @throws {Error} When the source's rows are not the kind's, or its entries carry no rows
+ */
+export declare function scheduleNarrowedWindows(kind: ScheduleResourceKind<EastType, EastType>, slot: string, narrowed: ExprType<StructType>, builder: string): ScheduleKindWindows;
+//# sourceMappingURL=pages.d.ts.map

package/dist/src/schedule/pages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pages.d.ts","sourceRoot":"","sources":["../../../src/schedule/pages.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;GAUG;AAEH,OAAO,EACH,SAAS,EAAQ,UAAU,EAC3B,KAAK,YAAY,EAAE,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EACvJ,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGrE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE3D,kFAAkF;AAClF,MAAM,MAAM,aAAa,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;AAEnD,yJAAyJ;AACzJ,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,UAAU,CAAC;IAClD,EAAE,EAAE,UAAU,CAAC;IACf,KAAK,EAAE,YAAY,CAAC,EAAE,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC;IACjD,IAAI,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC,OAAO,aAAa,CAAC,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC;IACzF,QAAQ,EAAE,YAAY,CAAC,EAAE,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC;IACnD,OAAO,EAAE,YAAY,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;IAC1D,KAAK,EAAE,YAAY,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;CACvC,CAAC,CAAC,CAAC;AAEJ,4HAA4H;AAC5H,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC,WAAW,EAAE,WAAW,CAAC,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AAE1G;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAChC,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC,KAAK,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;IACpF,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC,KAAK,QAAQ,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;IAC/F,mHAAmH;IACnH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,wFAAwF;IACxF,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,mBAAmB,CAuBrH;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACnC,IAAI,EAAE,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,MAAM,GAC9G,mBAAmB,CAoBrB"}

package/dist/src/schedule/pages.js

@@ -0,0 +1,86 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Where a paged resource kind's windows come from (#1199, #1344, #1424): the
+ * kind's own paged read, its resources in their key order; or, its builder's
+ * slice naming a source after its slot, that source's narrowed rows
+ * themselves, the narrowing's resources in the source's index's order — never
+ * a window of every resource filtered by the keys the source shows. The Plan's
+ * paged rows (`plan/event-rows.ts`) and the Calendar's (`calendar/paged.ts`)
+ * page through them alike.
+ *
+ * @packageDocumentation
+ */
+import { ArrayType, East, StringType, isTypeEqual, printType, } from "@elaraai/east";
+import { buildPagedWindow, resolveRowSource } from "@elaraai/east-ui/internal";
+import { orderedRowSource } from "../utils/ordered-source.js";
+/**
+ * A paged kind's own windows (#1199): its paged read, in its resources' key
+ * order.
+ *
+ * @param kind - The paged resource kind
+ * @param where - The kind, as a refusal names it (`Plan: resources.presses`)
+ * @returns Its windows
+ * @throws {Error} When its paged read is not a paged source of its resources
+ */
+export function scheduleOwnWindows(kind, where) {
+    // The resources a window at a time — each window whole, a piece the source cut short read on to its end.
+    const resolved = resolveRowSource(kind.window, where);
+    if (resolved.kind === "inline") {
+        throw new Error(`${where}: a paged kind's resources are a paged read — Data.bindPaged(record) over the resources' record`);
+    }
+    // A key's text, as the rows name it: a paged kind's keys are Strings, as `Schedule.resources` holds them.
+    const keyText = isTypeEqual(kind.keyType, StringType)
+        ? (key) => key
+        : (key) => East.print(key);
+    return {
+        read: buildPagedWindow(resolved),
+        rows: (page) => page,
+        keys: ($, page) => {
+            const out = $.let([], ArrayType(StringType));
+            $.for(page, ($2, _row, key) => { $2(out.pushLast(keyText(key))); });
+            return out;
+        },
+        indexed: false,
+        handle: resolved.source,
+        pinned: resolved.pinned,
+        query: false,
+    };
+}
+/**
+ * A paged kind's windows narrowed by its source of the slice (#1344): the
+ * narrowing's rows themselves, paged in the source's index's order — never a
+ * window of every resource filtered by the keys the source shows.
+ *
+ * @param kind - The paged resource kind
+ * @param slot - Its slot, which names its source
+ * @param narrowed - The source's narrowed data, as the builder's payload bound it: a rail's live source of index entries
+ * @param builder - The builder, as its refusals name it (`Plan`, `Calendar`)
+ * @returns Its windows
+ * @throws {Error} When the source's rows are not the kind's, or its entries carry no rows
+ */
+export function scheduleNarrowedWindows(kind, slot, narrowed, builder) {
+    const where = `${builder}: the slice's source "${slot}"`;
+    const resolved = resolveRowSource(narrowed, where);
+    // The slice binds only a record's indexed reads, so a source is an index's window (`recordSources`).
+    if (resolved.kind !== "ordered")
+        throw new Error(`${where} narrows resources.${slot}, and it is no index's window of a record`);
+    const ordered = orderedRowSource(resolved, builder);
+    const row = ordered.resolved.elementType;
+    if (!isTypeEqual(resolved.keyType, kind.keyType) || !isTypeEqual(row, kind.rowType)) {
+        throw new Error(`${where} narrows resources.${slot}, and its rows are ${printType(row)} — the kind's are ${printType(kind.rowType)}: ` +
+            "bind the source over the kind's own record, Data.bindPaged(record, { indexes })");
+    }
+    return {
+        read: ordered.window,
+        rows: (page) => ordered.rows(page),
+        keys: (_$, page) => ordered.keys(page),
+        indexed: true,
+        handle: resolved.source,
+        pinned: resolved.pinned,
+        query: resolved.query,
+    };
+}
+//# sourceMappingURL=pages.js.map

package/dist/src/schedule/pages.js.map

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

package/dist/src/schedule/record-window.d.ts

@@ -2,8 +2,28 @@
  * Copyright (c) 2025 Elara AI Pty Ltd
  * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
  */
-/** Schedule's typed adapter to record Slice's indexed queries. */
+/**
+ * Schedule's typed adapter to record Slice's indexed queries: a kind's window
+ * and its backlog read through its source of its builder's slice, and the
+ * window's events counted before one is read.
+ *
+ * A window read under a cap counts first: its count is the request its read
+ * asks first, the same searches, so counting asks e3 nothing of its own; past
+ * the cap the read answers `none` and reads no page — the builder draws the
+ * kind's summary, or hatches its rows and says how many events there are
+ * ({@link SCHEDULE_EVENT_CAP}).
+ *
+ * @packageDocumentation
+ */
 import { ArrayType, DateTimeType, DictType, FunctionType, IntegerType, OptionType, StringType, StructType, type EastType, type ExprType, type SubtypeExprOrValue } from "@elaraai/east";
+/**
+ * The most events a builder reads and draws of one kind over what it reads at
+ * once (#1039): its cells, or its window. Past it, the kind's events are never
+ * read or drawn: its resources' rows shade from its source's summary where the
+ * source lists one, and are hatched otherwise, the builder saying how many
+ * events there are.
+ */
+export declare const SCHEDULE_EVENT_CAP = 10000;
 /** Minimal typed query reader; additional index-entry fields remain opaque. */
 export declare function ScheduleRecordSliceType<K extends EastType, R extends EastType>(key: K, row: R): StructType<{
     readonly data: StructType<{
@@ -17,6 +37,12 @@ export declare function ScheduleRecordSliceType<K extends EastType, R extends Ea
             readonly to: StringType;
         }>;
         readonly prefix: StringType;
+        readonly window: StructType<{
+            readonly minX: import("@elaraai/east").FloatType;
+            readonly minY: import("@elaraai/east").FloatType;
+            readonly maxX: import("@elaraai/east").FloatType;
+            readonly maxY: import("@elaraai/east").FloatType;
+        }>;
     }>>, IntegerType, IntegerType], OptionType<ArrayType<StructType<{
         readonly key: K;
         readonly row: OptionType<R>;
@@ -57,6 +83,39 @@ export declare function ScheduleRecordSliceType<K extends EastType, R extends Ea
                 readonly to: StringType;
                 readonly optional: import("@elaraai/east").BooleanType;
             }>>;
+            readonly area: OptionType<StructType<{
+                readonly x: StringType;
+                readonly y: StringType;
+                readonly width: OptionType<StringType>;
+                readonly height: OptionType<StringType>;
+                readonly centre: import("@elaraai/east").BooleanType;
+                readonly cell: import("@elaraai/east").FloatType;
+                readonly optional: import("@elaraai/east").BooleanType;
+            }>>;
+            readonly series: OptionType<StructType<{
+                readonly key: StringType;
+                readonly from: StringType;
+                readonly to: StringType;
+                readonly tile: import("@elaraai/east").VariantType<{
+                    readonly day: import("@elaraai/east").NullType;
+                    readonly week: import("@elaraai/east").NullType;
+                    readonly month: import("@elaraai/east").NullType;
+                    readonly quarter: import("@elaraai/east").NullType;
+                    readonly year: import("@elaraai/east").NullType;
+                }>;
+            }>>;
+            readonly summary: OptionType<StructType<{
+                readonly key: StringType;
+                readonly from: StringType;
+                readonly to: StringType;
+                readonly tile: import("@elaraai/east").VariantType<{
+                    readonly day: import("@elaraai/east").NullType;
+                    readonly week: import("@elaraai/east").NullType;
+                    readonly month: import("@elaraai/east").NullType;
+                    readonly quarter: import("@elaraai/east").NullType;
+                    readonly year: import("@elaraai/east").NullType;
+                }>;
+            }>>;
         }>>;
         readonly range: OptionType<StringType>;
         readonly search: ArrayType<StringType>;
@@ -70,6 +129,12 @@ export declare function ScheduleRecordSliceType<K extends EastType, R extends Ea
                     readonly to: StringType;
                 }>;
                 readonly prefix: StringType;
+                readonly window: StructType<{
+                    readonly minX: import("@elaraai/east").FloatType;
+                    readonly minY: import("@elaraai/east").FloatType;
+                    readonly maxX: import("@elaraai/east").FloatType;
+                    readonly maxY: import("@elaraai/east").FloatType;
+                }>;
             }>>;
         }>>;
     }>;
@@ -81,6 +146,12 @@ export declare function ScheduleRecordSliceType<K extends EastType, R extends Ea
                 readonly to: StringType;
             }>;
             readonly prefix: StringType;
+            readonly window: StructType<{
+                readonly minX: import("@elaraai/east").FloatType;
+                readonly minY: import("@elaraai/east").FloatType;
+                readonly maxX: import("@elaraai/east").FloatType;
+                readonly maxY: import("@elaraai/east").FloatType;
+            }>;
         }>>;
         readonly preset: OptionType<StringType>;
         readonly resolution: OptionType<import("@elaraai/east").VariantType<{
@@ -101,6 +172,12 @@ export declare function ScheduleRecordSliceType<K extends EastType, R extends Ea
                 readonly to: StringType;
             }>;
             readonly prefix: StringType;
+            readonly window: StructType<{
+                readonly minX: import("@elaraai/east").FloatType;
+                readonly minY: import("@elaraai/east").FloatType;
+                readonly maxX: import("@elaraai/east").FloatType;
+                readonly maxY: import("@elaraai/east").FloatType;
+            }>;
         }>>;
         readonly preset: OptionType<StringType>;
         readonly resolution: OptionType<import("@elaraai/east").VariantType<{
@@ -126,6 +203,12 @@ export declare function ScheduleRecordSliceType<K extends EastType, R extends Ea
             readonly to: StringType;
         }>;
         readonly prefix: StringType;
+        readonly window: StructType<{
+            readonly minX: import("@elaraai/east").FloatType;
+            readonly minY: import("@elaraai/east").FloatType;
+            readonly maxX: import("@elaraai/east").FloatType;
+            readonly maxY: import("@elaraai/east").FloatType;
+        }>;
     }>>], OptionType<IntegerType>>;
     readonly total: FunctionType<[], OptionType<IntegerType>>;
     readonly domain: FunctionType<[StringType], OptionType<StructType<{
@@ -167,6 +250,12 @@ export declare function ScheduleRecordSliceType<K extends EastType, R extends Ea
             readonly to: StringType;
         }>;
         readonly prefix: StringType;
+        readonly window: StructType<{
+            readonly minX: import("@elaraai/east").FloatType;
+            readonly minY: import("@elaraai/east").FloatType;
+            readonly maxX: import("@elaraai/east").FloatType;
+            readonly maxY: import("@elaraai/east").FloatType;
+        }>;
     }>>, StringType], OptionType<import("@elaraai/east").BooleanType>>;
     readonly containsRow: FunctionType<[DictType<StringType, import("@elaraai/east").VariantType<{
         readonly values: ArrayType<StringType>;
@@ -175,6 +264,12 @@ export declare function ScheduleRecordSliceType<K extends EastType, R extends Ea
             readonly to: StringType;
         }>;
         readonly prefix: StringType;
+        readonly window: StructType<{
+            readonly minX: import("@elaraai/east").FloatType;
+            readonly minY: import("@elaraai/east").FloatType;
+            readonly maxX: import("@elaraai/east").FloatType;
+            readonly maxY: import("@elaraai/east").FloatType;
+        }>;
     }>>, StringType, import("@elaraai/east").BlobType], OptionType<import("@elaraai/east").BooleanType>>;
 }>;
 /** A record Slice over the event record's original key and row types. */
@@ -190,10 +285,9 @@ export type ScheduleKindPart = ExprType<StructType>;
 /**
  * Read a visible interval or backlog through the same declared Slice paths.
  * This reads only the chosen result, in bounded pages. Index bounds own all
- * membership and distinct counts; no row predicate implements narrowing.
- * The narrowing is the source's choices but its start field's and, on the
- * start field, the window's half-open range — or, for a backlog, the start
- * Unset; exact start values a choice holds stand for a window.
+ * membership and distinct counts; no row predicate implements narrowing. A
+ * window read under a cap counts its events first — the count its read asks
+ * first, so no request of its own — and past the cap reads no page.
  * @param part - The kind's source of its builder's slice, bound in the builder's payload.
  * @param slot - The kind's slot, which names its source.
  * @param key - Original record key type.
@@ -203,9 +297,28 @@ export type ScheduleKindPart = ExprType<StructType>;
  * @param optional - Whether the time fields admit backlog rows.
  * @param backlog - Read Unset starts instead of a scheduled interval.
  * @param label - Kind name used by authoring errors.
+ * @param cap - The most events a window is read with ({@link SCHEDULE_EVENT_CAP}): counted first, and past it the read
+ *   answers `none`, reading no page; no cap, every window is read. A backlog is read whole, whatever the cap.
  * @returns A window reader compatible with the existing Schedule seams; refused as it reads when the source's range is
  *   not the start field, or it declares no interval index from the start to the end.
  * @throws {Error} When the source is not a record Slice over this event record with joined rows.
  */
-export declare function scheduleRecordWindow(part: ScheduleKindPart, slot: string, key: EastType, row: EastType, start: string, end: string, optional: boolean, backlog: boolean, label: string): ExprType<FunctionType<[DateTimeType, DateTimeType], OptionType<DictType<EastType, EastType>>>>;
+export declare function scheduleRecordWindow(part: ScheduleKindPart, slot: string, key: EastType, row: EastType, start: string, end: string, optional: boolean, backlog: boolean, label: string, cap?: number): ExprType<FunctionType<[DateTimeType, DateTimeType], OptionType<DictType<EastType, EastType>>>>;
+/**
+ * Count a window's events through a kind's source before one is read: the
+ * count {@link scheduleRecordWindow} asks first over the same window — the same
+ * searches, so a count and its window's read ask e3 once.
+ * @param part - The kind's source of its builder's slice, bound in the builder's payload.
+ * @param slot - The kind's slot, which names its source.
+ * @param key - Original record key type.
+ * @param row - Record row type.
+ * @param start - Interval start field.
+ * @param end - Interval end field (the same field for an instant).
+ * @param optional - Whether the time fields admit backlog rows: a row with no start is in no window, and not counted.
+ * @param label - Kind name used by authoring errors.
+ * @returns `(from, to)` → how many of the source's events overlap `[from, to)`, under its narrowing; `none` while the
+ *   count is in flight. Refused as it counts, as the window's read is.
+ * @throws {Error} When the source is not a record Slice over this event record with joined rows.
+ */
+export declare function scheduleRecordCount(part: ScheduleKindPart, slot: string, key: EastType, row: EastType, start: string, end: string, optional: boolean, label: string): ExprType<FunctionType<[DateTimeType, DateTimeType], OptionType<IntegerType>>>;
 //# sourceMappingURL=record-window.d.ts.map

package/dist/src/schedule/record-window.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"record-window.d.ts","sourceRoot":"","sources":["../../../src/schedule/record-window.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,kEAAkE;AAClE,OAAO,EACH,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAc,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAC/D,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,KAAK,kBAAkB,EACrG,MAAM,eAAe,CAAC;AAKvB,+EAA+E;AAC/E,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAM7F;AACD,yEAAyE;AACzE,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,IAAI,kBAAkB,CAAC,UAAU,CAAC,OAAO,uBAAuB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAE/I;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAC/H,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC,YAAY,EAAE,YAAY,CAAC,EAAE,UAAU,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CA8EtJ"}
+{"version":3,"file":"record-window.d.ts","sourceRoot":"","sources":["../../../src/schedule/record-window.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;GAYG;AACH,OAAO,EACH,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAc,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAC5C,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,KAAK,kBAAkB,EACxH,MAAM,eAAe,CAAC;AAKvB;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAEzC,+EAA+E;AAC/E,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAM7F;AACD,yEAAyE;AACzE,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,QAAQ,IAAI,kBAAkB,CAAC,UAAU,CAAC,OAAO,uBAAuB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAE/I;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC;AAsFpD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAC/H,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC,YAAY,EAAE,YAAY,CAAC,EAAE,UAAU,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAqCpK;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAC9H,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC,YAAY,EAAE,YAAY,CAAC,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,CAQnH"}

package/dist/src/schedule/record-window.js

@@ -2,9 +2,29 @@
  * Copyright (c) 2025 Elara AI Pty Ltd
  * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
  */
-/** Schedule's typed adapter to record Slice's indexed queries. */
+/**
+ * Schedule's typed adapter to record Slice's indexed queries: a kind's window
+ * and its backlog read through its source of its builder's slice, and the
+ * window's events counted before one is read.
+ *
+ * A window read under a cap counts first: its count is the request its read
+ * asks first, the same searches, so counting asks e3 nothing of its own; past
+ * the cap the read answers `none` and reads no page — the builder draws the
+ * kind's summary, or hatches its rows and says how many events there are
+ * ({@link SCHEDULE_EVENT_CAP}).
+ *
+ * @packageDocumentation
+ */
 import { ArrayType, DateTimeType, DictType, East, Expr, FunctionType, IntegerType, OptionType, StringType, StructType, isSubtype, isTypeEqual, none, some, variant, } from "@elaraai/east";
 import { RecordSliceBindType, RecordSliceChoiceType, RecordSliceConfigType, RecordSliceStateType, RecordSliceWhereType, recordSliceReadPlatform, } from "@elaraai/east-ui/internal";
+/**
+ * The most events a builder reads and draws of one kind over what it reads at
+ * once (#1039): its cells, or its window. Past it, the kind's events are never
+ * read or drawn: its resources' rows shade from its source's summary where the
+ * source lists one, and are hatched otherwise, the builder saying how many
+ * events there are.
+ */
+export const SCHEDULE_EVENT_CAP = 10_000;
 /** Minimal typed query reader; additional index-entry fields remain opaque. */
 export function ScheduleRecordSliceType(key, row) {
     return StructType({ ...RecordSliceBindType.fields,
@@ -13,26 +33,13 @@ export function ScheduleRecordSliceType(key, row) {
     });
 }
 /**
- * Read a visible interval or backlog through the same declared Slice paths.
- * This reads only the chosen result, in bounded pages. Index bounds own all
- * membership and distinct counts; no row predicate implements narrowing.
- * The narrowing is the source's choices but its start field's and, on the
- * start field, the window's half-open range — or, for a backlog, the start
- * Unset; exact start values a choice holds stand for a window.
- * @param part - The kind's source of its builder's slice, bound in the builder's payload.
- * @param slot - The kind's slot, which names its source.
- * @param key - Original record key type.
- * @param row - Record row type.
- * @param start - Interval start field.
- * @param end - Interval end field (the same field for an instant).
- * @param optional - Whether the time fields admit backlog rows.
- * @param backlog - Read Unset starts instead of a scheduled interval.
- * @param label - Kind name used by authoring errors.
- * @returns A window reader compatible with the existing Schedule seams; refused as it reads when the source's range is
- *   not the start field, or it declares no interval index from the start to the end.
- * @throws {Error} When the source is not a record Slice over this event record with joined rows.
+ * Checks a kind's source at build: a record Slice over the kind's own record,
+ * its entries carrying their rows.
+ *
+ * @returns The source's entries' type: the window's own wire type, its index key and covering value preserved
+ * @throws {Error} When the source is not a record Slice over this event record with joined rows
  */
-export function scheduleRecordWindow(part, slot, key, row, start, end, optional, backlog, label) {
+function checkedSource(part, slot, key, row, label) {
     const Type = ScheduleRecordSliceType(key, row);
     const type = Expr.type(part);
     const fields = type.type === "Struct" ? type.fields : {};
@@ -52,57 +59,129 @@ export function scheduleRecordWindow(part, slot, key, row, start, end, optional,
         throw new Error(`${label}: the builder's source "${slot}" narrows another record — name it after this kind's slot over the kind's own record, ` +
             "Data.bindPaged(record, { indexes }), its rows joined");
     }
+    return collection;
+}
+/**
+ * The narrowing a window `[from, to)` is read under, built in a read's block —
+ * its window's read and its count build it alike, so they ask the same
+ * searches: the source's choices but its start field's and, on the start
+ * field, the window's half-open range — or, for a backlog, the start Unset;
+ * exact start values a choice holds stand for a window. Refused as it is read
+ * when the source's range is not the start field, or it declares no interval
+ * index from the start to the end.
+ */
+function windowWhere($, source, from, to, start, end, optional, backlog, label) {
+    const config = $.const(source.config);
+    const read = $.const(source.read);
+    $.if(config.range.match({ none: () => true, some: (_$2, field) => field.notEqual(start) }), $2 => {
+        $2.error(`${label}: set the record Slice range to '${start}' so navigation and filters share one window`);
+    });
+    const supported = $.let(false);
+    $.for(config.indexes, ($2, index) => {
+        $2.match(index.interval, { some: ($3, interval) => {
+                $3.if(interval.from.equal(start).and(() => interval.to.equal(end)), $4 => { $4.assign(supported, true); });
+            } });
+    });
+    $.if(supported.not(), $2 => { $2.error(`${label}: declare an interval index for ${start} and ${end} to preserve overlapping events`); });
+    const where = $.let(new Map(), RecordSliceWhereType);
+    const state = $.const(read());
+    $.for(state.where, ($2, choice, field) => {
+        $2.if(field.notEqual(start), $3 => { $3(where.insert(field, choice)); });
+    });
+    const time = $.let(backlog ? variant("values", [East.print(East.value(none, OptionType(DateTimeType)))])
+        : variant("range", { from: East.print(optional ? East.value(some(from), OptionType(DateTimeType)) : from),
+            to: East.print(optional ? East.value(some(to), OptionType(DateTimeType)) : to) }), RecordSliceChoiceType);
+    if (!backlog) {
+        $.match(state.where.tryGet(start), { some: ($2, choice) => {
+                $2.match(choice, { values: ($3, values) => { $3.assign(time, variant("values", values)); } });
+            } });
+    }
+    $(where.insert(start, time));
+    return where;
+}
+/**
+ * Read a visible interval or backlog through the same declared Slice paths.
+ * This reads only the chosen result, in bounded pages. Index bounds own all
+ * membership and distinct counts; no row predicate implements narrowing. A
+ * window read under a cap counts its events first — the count its read asks
+ * first, so no request of its own — and past the cap reads no page.
+ * @param part - The kind's source of its builder's slice, bound in the builder's payload.
+ * @param slot - The kind's slot, which names its source.
+ * @param key - Original record key type.
+ * @param row - Record row type.
+ * @param start - Interval start field.
+ * @param end - Interval end field (the same field for an instant).
+ * @param optional - Whether the time fields admit backlog rows.
+ * @param backlog - Read Unset starts instead of a scheduled interval.
+ * @param label - Kind name used by authoring errors.
+ * @param cap - The most events a window is read with ({@link SCHEDULE_EVENT_CAP}): counted first, and past it the read
+ *   answers `none`, reading no page; no cap, every window is read. A backlog is read whole, whatever the cap.
+ * @returns A window reader compatible with the existing Schedule seams; refused as it reads when the source's range is
+ *   not the start field, or it declares no interval index from the start to the end.
+ * @throws {Error} When the source is not a record Slice over this event record with joined rows.
+ */
+export function scheduleRecordWindow(part, slot, key, row, start, end, optional, backlog, label, cap) {
+    const entriesType = checkedSource(part, slot, key, row, label);
     const Held = DictType(key, row);
-    // Preserve the actual window's wire type (including its index key and
-    // covering value); only the two validated entry fields are inspected.
-    const Entries = collection;
     return East.function([DateTimeType, DateTimeType], OptionType(Held), ($, from, to) => {
         // The source as the builder bound it, its members read here: the reader captures the source alone.
         const source = $.const(part);
-        const config = $.const(source.config);
-        const read = $.const(source.read);
         const countWhere = $.const(source.countWhere);
         const pageWhere = $.const(source.pageWhere);
         const id = $.const(source.data.id);
         const revision = $.const(source.data.revision);
-        $.if(config.range.match({ none: () => true, some: (_$2, field) => field.notEqual(start) }), $2 => {
-            $2.error(`${label}: set the record Slice range to '${start}' so navigation and filters share one window`);
-        });
-        const supported = $.let(false);
-        $.for(config.indexes, ($2, index) => {
-            $2.match(index.interval, { some: ($3, interval) => {
-                    $3.if(interval.from.equal(start).and(() => interval.to.equal(end)), $4 => { $4.assign(supported, true); });
-                } });
-        });
-        $.if(supported.not(), $2 => { $2.error(`${label}: declare an interval index for ${start} and ${end} to preserve overlapping events`); });
-        const where = $.let(new Map(), RecordSliceWhereType);
-        const state = $.const(read());
-        $.for(state.where, ($2, choice, field) => {
-            $2.if(field.notEqual(start), $3 => { $3(where.insert(field, choice)); });
-        });
-        const time = $.let(backlog ? variant("values", [East.print(East.value(none, OptionType(DateTimeType)))])
-            : variant("range", { from: East.print(optional ? East.value(some(from), OptionType(DateTimeType)) : from),
-                to: East.print(optional ? East.value(some(to), OptionType(DateTimeType)) : to) }), RecordSliceChoiceType);
-        if (!backlog) {
-            $.match(state.where.tryGet(start), { some: ($2, choice) => {
-                    $2.match(choice, { values: ($3, values) => { $3.assign(time, variant("values", values)); } });
-                } });
-        }
-        $(where.insert(start, time));
+        const where = windowWhere($, source, from, to, start, end, optional, backlog, label);
         const result = $.let(none, OptionType(Held));
-        $.match(recordSliceReadPlatform([Entries], id, revision, countWhere, pageWhere, where), {
-            some: ($2, entries) => {
-                const held = $2.let(new Map(), Held);
-                $2.for(entries, ($3, entry) => {
-                    $3.match(entry.row, {
-                        none: $4 => { $4.error(`${label}: the builder's source "${slot}" reads no rows — bind it with Data.bindPaged with join: true`); },
-                        some: ($4, value) => { $4(held.insert(entry.key, value)); },
+        // The window's entries, read a page at a time once their count is known: the rows by their keys.
+        const read = ($b) => {
+            $b.match(recordSliceReadPlatform([entriesType], id, revision, countWhere, pageWhere, where), {
+                some: ($2, entries) => {
+                    const held = $2.let(new Map(), Held);
+                    $2.for(entries, ($3, entry) => {
+                        $3.match(entry.row, {
+                            none: $4 => { $4.error(`${label}: the builder's source "${slot}" reads no rows — bind it with Data.bindPaged with join: true`); },
+                            some: ($4, value) => { $4(held.insert(entry.key, value)); },
+                        });
                     });
-                });
-                $2.assign(result, some(held));
-            },
-        });
+                    $2.assign(result, some(held));
+                },
+            });
+        };
+        if (cap === undefined || backlog) {
+            read($);
+        }
+        else {
+            // Counted first, as the read counts first: past the cap, no page is read and the window answers none.
+            $.match(countWhere(where), {
+                some: ($2, count) => { $2.if(count.lessEqual(BigInt(cap)), ($3) => { read($3); }); },
+            });
+        }
         return result;
     });
 }
+/**
+ * Count a window's events through a kind's source before one is read: the
+ * count {@link scheduleRecordWindow} asks first over the same window — the same
+ * searches, so a count and its window's read ask e3 once.
+ * @param part - The kind's source of its builder's slice, bound in the builder's payload.
+ * @param slot - The kind's slot, which names its source.
+ * @param key - Original record key type.
+ * @param row - Record row type.
+ * @param start - Interval start field.
+ * @param end - Interval end field (the same field for an instant).
+ * @param optional - Whether the time fields admit backlog rows: a row with no start is in no window, and not counted.
+ * @param label - Kind name used by authoring errors.
+ * @returns `(from, to)` → how many of the source's events overlap `[from, to)`, under its narrowing; `none` while the
+ *   count is in flight. Refused as it counts, as the window's read is.
+ * @throws {Error} When the source is not a record Slice over this event record with joined rows.
+ */
+export function scheduleRecordCount(part, slot, key, row, start, end, optional, label) {
+    checkedSource(part, slot, key, row, label);
+    return East.function([DateTimeType, DateTimeType], OptionType(IntegerType), ($, from, to) => {
+        const source = $.const(part);
+        const countWhere = $.const(source.countWhere);
+        const where = windowWhere($, source, from, to, start, end, optional, false, label);
+        return countWhere(where);
+    });
+}
 //# sourceMappingURL=record-window.js.map