@pythia-software/query-table-core 0.9.6 → 0.9.7

package/dist/index.d.ts

@@ -130,6 +130,10 @@ interface SelectConfig {
     default?: boolean;
     /** Default column width (px); a per-column override rides in QueryState.select. */
     width?: number;
+    /** Narrowest usable width (px) when fitting columns to the screen, such as
+     * the room a host renderer's buttons need. Measured native controls are
+     * always kept whole; this adds room they cannot measure. */
+    minWidth?: number;
     align?: Align;
 }
 interface AggregateConfig {
@@ -268,19 +272,44 @@ declare function formulaRuntime(ast: FormulaNode, inputs: Record<string, Formula
 type MetricValue = number | string | boolean | null;
 type MetricKey = MetricValue;
 type MetricScope = "allMatching" | "shownRows";
+/** Calendar intervals: each bucket is one interval on the timeline, keyed by
+ * its start as an ISO instant. */
+type MetricCalendarInterval = "hour" | "day" | "week" | "month" | "year";
+/** Cyclic intervals: each bucket is one slot of a repeating cycle, keyed by a
+ * number. `hourOfDay` is the local hour, 0–23; `dayOfWeek` the ISO weekday,
+ * 1 (Monday) to 7 (Sunday). */
+type MetricCycleInterval = "hourOfDay" | "dayOfWeek";
+/** Summarise each cyclic slot over its occurrences: every whole day or hour
+ * the slot covers inside the query's time bounds. */
+interface MetricDateOccurrence {
+    /** One occurrence: "day" (dayOfWeek only) or "hour". */
+    interval: "hour" | "day";
+    /** Count occurrences without rows: 0 for direct COUNT, COUNT_DISTINCT and
+     * SUM metrics, no value for other expressions. false leaves them out. */
+    includeEmpty: boolean;
+}
 /** Calendar grouping, currently executed over complete local populations. */
 interface MetricDateGrouping {
     field: string;
-    interval: "hour" | "day" | "week" | "month" | "year";
+    interval: MetricCalendarInterval | MetricCycleInterval;
     /** IANA timezone identifier; omitted settings retain UTC behavior. */
     timeZone?: string;
+    /** Add a bucket for every interval of the range, or for every slot of a
+     * cyclic interval. */
     includeEmpty: boolean;
+    /** The calendar range empty intervals fill; for a cyclic interval, the range
+     * whose empty occurrences count. */
     range: "query" | "observed" | "custom";
     start?: string;
     end?: string;
     /** "exclude" leaves out intervals the query's bounds cut, and intervals that
-     * have not ended by the evaluation time; omitted includes them. */
+     * have not ended by the evaluation time; omitted includes them. A cyclic
+     * interval's intervals are its hours or days. */
     partialIntervals?: "include" | "exclude";
+    /** Cyclic intervals only: each slot's value is the mean of its
+     * per-occurrence values, and a box distribution summarises them. Only whole
+     * occurrences count. Computed from a calendar metric by planMetricSeries. */
+    occurrence?: MetricDateOccurrence;
 }
 /** A trailing window over a calendar metric's intervals. */
 interface MetricWindow {
@@ -298,6 +327,19 @@ interface MetricWindow {
 /** Divide each bucket by the total of all groups ("total") or of its first
  * grouping key ("group0"), such as one calendar interval. */
 type MetricShare = "total" | "group0";
+/** A per-group minimum measured over something other than rows: the distinct
+ *  non-null values of one field (like COUNT_DISTINCT), or the sum of one
+ *  numeric field (like SUM; nulls add nothing). Exactly one of `distinct` and
+ *  `sum` is set. A group whose measure is an error is kept. */
+type MetricMinCountOf = {
+    min: number;
+    distinct: string;
+    sum?: never;
+} | {
+    min: number;
+    sum: string;
+    distinct?: never;
+};
 interface MetricValueFormat {
     kind: "number" | "percent" | "duration" | "date" | "time" | "datetime";
     decimals?: number;
@@ -396,6 +438,8 @@ interface MetricDiagnostic extends FormulaDiagnostic {
 }
 /** Host must enforce snapshot against the row response; this token alone does not pin data. */
 interface MetricQuery {
+    /** The table's host-owned state when `hostQuery` is configured. */
+    hostState?: HostQueryState;
     snapshot?: string;
     profile?: string;
     expectedRevisions?: Record<string, string>;
@@ -418,6 +462,8 @@ interface MetricCapabilities {
     filters?: boolean;
     /** Executes AggregationClause.minCount and reports hiddenGroups. */
     minCount?: boolean;
+    /** Also executes an object minCount: distinct values or a sum per group. */
+    minCountMeasures?: boolean;
     maxGroups?: number;
     profile?: string;
 }
@@ -501,6 +547,33 @@ declare function readObjectReference<Row>(field: FieldDef<Row>, fields: FieldDef
 /** Only unambiguous, fully mapped constraints become links. Explicit metadata wins. */
 declare function discoverFieldRelationships<Row>(fields: FieldDef<Row>[], keys: ForeignKey[], types: ObjectTypeDefinition[]): FieldDef<Row>[];
 
+/** Calendar intervals a grouping key can bucket a datetime field by. */
+declare const GROUP_KEY_INTERVALS: readonly MetricCalendarInterval[];
+/** A grouping key that buckets a datetime field by calendar interval: one
+ * group per interval, keyed by the interval's start as an ISO instant. The
+ * result column is named after the field. Intervals follow the metric
+ * calendar (`dateGrouping`), including daylight-saving changes; weeks start
+ * on Monday. */
+interface CalendarGroupKey {
+    field: string;
+    interval: MetricCalendarInterval;
+    /** IANA timezone identifier; omitted means UTC. */
+    timeZone?: string;
+}
+/** A field name (group by its exact value) or a calendar key. */
+type GroupKey = string | CalendarGroupKey;
+declare function isCalendarGroupKey(key: GroupKey): key is CalendarGroupKey;
+/** The source field a key reads; also the name of its result column. */
+declare function groupKeyField(key: GroupKey): string;
+/** Result column names, in key order. */
+declare function groupKeyFields(keys: readonly GroupKey[]): string[];
+/** The calendar key on `field`, if that key buckets by interval. */
+declare function calendarGroupKey(keys: readonly GroupKey[], field: string): CalendarGroupKey | undefined;
+/** `=` (or `is_null`) per key, in key order, or null when any key cannot be
+ * matched exactly (textarray, unknown or unfilterable fields, unparseable
+ * datetimes). A calendar key adds `>= start` and `< end` for its interval. */
+declare function groupKeyTerms(keys: readonly GroupKey[], group: Record<string, unknown>, schema: FieldSchema): WhereClause[] | null;
+
 type QueryFacet = "filters" | "columns" | "order" | "grouping" | "metrics" | "limit";
 interface QueryPatch {
     /** Host identity for the patch; not interpreted. */
@@ -629,7 +702,10 @@ declare function isGroupLinkField(field: Pick<FieldDef, "render"> | undefined):
 interface GroupingView {
     version: 2;
     mode: "rows" | "groups";
+    /** Result key columns: the field each key reads, in key order. */
     keys: string[];
+    /** The keys as defined, including calendar intervals; absent means `keys`. */
+    groupKeys?: GroupKey[];
     summaries: SummaryColumn[];
     representative: RepresentativeRow | null;
     input: QueryState;
@@ -639,7 +715,10 @@ interface GroupingView {
  * HAVING in this mode; source.where is the pre-group WHERE. The source snapshot
  * also restores the record layout, paging, metrics and item details on exit. */
 interface GroupingDefinition {
-    keys: string[];
+    /** Field names, or calendar keys (`{ field, interval, timeZone }`) that
+     * group a datetime field by interval. Each field appears once; its result
+     * column is named after the field. */
+    keys: GroupKey[];
     summaries: SummaryColumn[];
     representative: RepresentativeRow | null;
     diagnostics?: string[];
@@ -653,14 +732,14 @@ declare const MAX_SUMMARY_COLUMNS = 64;
 declare const MAX_RESULT_GROUPS = 10000;
 declare function withoutGrouping(query: QueryState): QueryState;
 /** Leave the grouping stage: the source snapshot restores the record WHERE,
- * layout, ordering, paging, metrics and item details. Ungrouped queries are
- * returned unchanged. */
+ * layout, ordering, paging, metrics and item details, and keeps the host
+ * state of the grouped query. Ungrouped queries are returned unchanged. */
 declare function exitGrouping(query: QueryState): QueryState;
 /** The grouping-key transition behind the grouping controls. Empty keys exit
  * the stage; an ungrouped query becomes the source of a new stage that shows
  * only its keys; a grouped query swaps keys, dropping result columns, HAVING
  * terms and sorts on removed keys and clearing group metrics. */
-declare function withGroupingKeys(query: QueryState, keys: string[]): QueryState;
+declare function withGroupingKeys(query: QueryState, keys: GroupKey[]): QueryState;
 declare const OP_LABEL: Record<SummaryOp, string>;
 /** Bind aggregation helpers to this instance's source catalogue. */
 declare function createGroupingModel<InputRow>(inputSchema: FieldSchema<InputRow>): {
@@ -674,10 +753,10 @@ declare function createGroupingModel<InputRow>(inputSchema: FieldSchema<InputRow
     summaryExpression: (column: SummaryColumn) => string;
     summaryProblem: (column: SummaryColumn) => string | null;
     summaryLabel: (column: SummaryColumn) => string;
-    linkProblem: (column: SummaryColumn, keys: string[], summaries: SummaryColumn[]) => string | null;
+    linkProblem: (column: SummaryColumn, keys: GroupKey[], summaries: SummaryColumn[]) => string | null;
     linkDiagnostics: (definition: Pick<GroupingDefinition, "keys" | "summaries">) => string[];
-    resultSchema: (keys: string[], summaries: SummaryColumn[]) => FieldSchema<Row>;
-    groupRows: (rows: InputRow[], schema: FieldSchema<InputRow>, keys: string[], summaries: SummaryColumn[], rule?: RepresentativeRow | null) => Row[];
+    resultSchema: (keys: GroupKey[], summaries: SummaryColumn[]) => FieldSchema<Row>;
+    groupRows: (rows: InputRow[], schema: FieldSchema<InputRow>, keys: GroupKey[], summaries: SummaryColumn[], rule?: RepresentativeRow | null) => Row[];
     filteredInput: (rows: InputRow[], query: QueryState, schema: FieldSchema<InputRow>, options?: QueryEvaluationOptions) => InputRow[];
     reconcileRepresentative: (query: QueryState, summaries: SummaryColumn[], schema: FieldSchema<Row>, remove: boolean) => QueryState;
     validate: (definition: GroupingDefinition) => void;
@@ -723,25 +802,59 @@ interface SetFilterMetadata {
     values: string[];
 }
 /** A disjunction of predicates — the inner OR of conjunctive normal form. Every
- *  member is a plain literal; nesting is intentionally not allowed yet (CNF
- *  only), but the object shape leaves room to grow. */
+ *  member is a plain literal. See `OrOfAndsGroup` for an OR whose members may
+ *  themselves be conjunctions. */
 interface OrGroup {
     any: WhereClause[];
     setFilter?: SetFilterMetadata;
 }
-/** One conjunct of the WHERE clause: either a single predicate or an OR group.
- *  `QueryState.where` is the AND of these terms, so the whole WHERE is
- *  conjunctive normal form — `(a) AND (b OR c) AND (d)`. A bare literal is
- *  equivalent to a one-element OR group; normalization flattens singleton groups
- *  back to a literal so equality/encoding stay canonical. */
-type WhereTerm = WhereClause | OrGroup;
-/** Narrow a term to an OR group. A literal always carries `field`; a group never
- *  does and always carries an `any` array. */
+/** One branch of an `OrOfAndsGroup` that ANDs several literals. Members are
+ *  always plain literals: nesting stops at `any` → `all` → clause. */
+interface WhereConjunction {
+    all: WhereClause[];
+}
+/** One alternative of an `OrOfAndsGroup`: a literal or a conjunction. */
+type WhereBranch = WhereClause | WhereConjunction;
+/** A disjunction of conjunctions — `(a AND b) OR (c AND d)` — written
+ *  `{ any: [{ all: [a, b] }, { all: [c, d] }] }`. A branch may also be a bare
+ *  literal. It selects the union of its branches' rows, such as a legend
+ *  selection of several (provider, model) pairs, without the exponential
+ *  AND-of-ORs rewrite. Normalization keeps the shape canonical: a one-literal
+ *  conjunction becomes that literal, a group whose branches are all literals is
+ *  an `OrGroup`, and a single conjunction becomes top-level literals. Every
+ *  literal counts against `MAX_WHERE_CLAUSES`, which therefore also bounds the
+ *  number of branches. Each literal keeps its own null-exclusive negation; the
+ *  group itself is never negated. */
+interface OrOfAndsGroup {
+    any: WhereBranch[];
+    setFilter?: SetFilterMetadata;
+}
+/** One conjunct of the WHERE clause: a single predicate, an OR group, or an OR
+ *  of conjunctions. `QueryState.where` is the AND of these terms —
+ *  `(a) AND (b OR c) AND ((d AND e) OR f)`. A bare literal is equivalent to a
+ *  one-element OR group; normalization flattens singleton groups back to a
+ *  literal so equality/encoding stay canonical. */
+type WhereTerm = WhereClause | OrGroup | OrOfAndsGroup;
+/** Narrow a branch to a conjunction. */
+declare function isWhereConjunction(branch: WhereBranch): branch is WhereConjunction;
+/** Narrow a term to a plain OR group (every member a literal). A literal
+ *  always carries `field`; a group never does and always carries an `any`
+ *  array. An `OrOfAndsGroup` is not an `OrGroup`. */
 declare function isOrGroup(term: WhereTerm): term is OrGroup;
-/** The predicate literals a term contributes, in order: the term itself for a
- *  literal, or its members for a group. Handy for anything that must visit every
- *  predicate regardless of grouping (field allowlisting, SELECT projection). */
+/** Narrow a term to an OR group with at least one conjunction branch. */
+declare function isOrOfAndsGroup(term: WhereTerm): term is OrOfAndsGroup;
+/** Narrow a term to either kind of group (anything carrying `any`). */
+declare function isWhereGroup(term: WhereTerm): term is OrGroup | OrOfAndsGroup;
+/** The predicate literals a term references, in order: the term itself for a
+ *  literal, a group's members, and the members of each conjunction branch.
+ *  Handy for anything that must visit every predicate regardless of grouping
+ *  (field allowlisting, SELECT projection, budgets); it does not preserve
+ *  meaning — use `branchesOf` to evaluate a term. */
 declare function predicatesOf(term: WhereTerm): WhereClause[];
+/** A term as a disjunction of conjunctions: it matches when every literal of
+ *  some branch matches. A literal is `[[literal]]`, an OR group one
+ *  single-literal branch per member. */
+declare function branchesOf(term: WhereTerm): WhereClause[][];
 /** One ORDER BY term. Array order in `QueryState.orderBy` is the sort priority. */
 interface OrderByClause {
     field: string;
@@ -810,10 +923,12 @@ interface AggregationClause {
      *  mode it refers to grouped-result fields. Shown-row metrics apply it inside
      *  the shown page. */
     where?: WhereTerm[];
-    /** Drop groups with fewer than this many rows (counted after `where`) before
-     *  sorting, `groupLimit` and Other. Requires at least one grouping field;
-     *  integer 1–1,000,000. Removed groups are reported as `hiddenGroups`. */
-    minCount?: number;
+    /** Drop small groups before sorting, `groupLimit` and Other. A number counts
+     *  rows (after `where`); `{ min, distinct: field }` counts a field's distinct
+     *  non-null values and `{ min, sum: field }` sums a numeric field, ignoring
+     *  nulls. Requires at least one grouping field; `min` is an integer
+     *  1–1,000,000. Removed groups are reported as `hiddenGroups`. */
+    minCount?: number | MetricMinCountOf;
     /** A trailing window or running value over the calendar intervals of
      * `dateGrouping`. Computed from ordinary metrics, so every engine supports it. */
     window?: MetricWindow;
@@ -842,7 +957,29 @@ interface ItemDetailsState {
         mode: "modal" | "expand";
     };
 }
+/**
+ * Query state a host owns and registers with `useQueryTable({ hostQuery })`,
+ * such as a keyword clause it runs itself. It travels with the table query
+ * through saves, links, history and resets as one definition. `params` are
+ * named lists of strings, like URL search parameters; the host's own
+ * `normalize` interprets them. Version 0 marks a payload that could not be
+ * read, and is always rejected on restore.
+ */
+interface HostQueryState {
+    version: number;
+    params: Record<string, string[]>;
+}
+declare const MAX_HOST_QUERY_PARAMS = 64;
+declare const MAX_HOST_QUERY_VALUES = 64;
+declare const MAX_HOST_QUERY_VALUE_LENGTH = 4000;
+declare const MAX_HOST_QUERY_STATE_BYTES: number;
+/** Validates host state and returns its canonical form (parameters sorted by
+ * name, values in order). Throws on a malformed or oversized payload. */
+declare function parseHostQueryState(input: unknown): HostQueryState;
 interface QueryState {
+    /** Host-owned state registered through `useQueryTable({ hostQuery })`.
+     * Only the top-level query carries it; a grouping source never does. */
+    hostState?: HostQueryState;
     /** Optional row-producing stage. `grouping.source` is the original record
      * query (its WHERE runs first). This query selects/filters/sorts the groups;
      * its `where` therefore represents HAVING. Only one stage is supported. */
@@ -988,6 +1125,9 @@ interface ServerQuery {
     orderBy: OrderByClause[];
     limit: number;
     offset: number;
+    /** The table's host-owned state when `hostQuery` is configured; hosts run
+     *  their own clauses from it. Query Table does not interpret it. */
+    hostState?: HostQueryState;
 }
 /** Project a QueryState into the server request, dropping client-only filters,
  *  client-only sorts, and remapping sort fields through `sort.field`. */
@@ -997,6 +1137,8 @@ declare function toServerQuery<Row>(q: QueryState, schema: FieldSchema<Row>): Se
  *  metrics describe every matching row, not the visible page. Mirrors the Go
  *  AggSpec list. */
 interface AggregationRequest {
+    /** The table's host-owned state when `hostQuery` is configured. */
+    hostState?: HostQueryState;
     diagnostics?: MetricDiagnostic[];
     where: WhereTerm[];
     aggregations: AggregationClause[];
@@ -1022,6 +1164,9 @@ interface AggregationBucket {
     /** Calendar intervals combined into a windowed point (`AggregationClause.window`);
      *  fewer than its periods where the window starts before the first interval. */
     intervals?: number;
+    /** Occurrences summarised by a cyclic slot (`dateGrouping.occurrence`):
+     *  those with a value, the samples of its mean and box. */
+    occurrences?: number;
     /** The metric: a number for count/sum/avg, or the column's value for min/max
      *  (which may be a string for text/datetime). null when undefined (e.g. avg of
      *  an all-null column). */
@@ -1219,12 +1364,46 @@ declare function reduceMetricValues(node: Extract<FormulaNode, {
 declare function evaluateMetricReductions(plan: MetricPlan, reductions: readonly FormulaResult[]): FormulaResult;
 declare function metricExpression(clause: AggregationClause): string;
 declare function hasRegex(plan: FormulaPlan): boolean;
+/** A box over a cyclic slot's per-occurrence values: its input is the
+ * metric itself, evaluated once per occurrence. */
+declare function occurrenceDistribution(c: AggregationClause): boolean;
 declare function metricPlans(c: AggregationClause, schema: FieldSchema, resolve?: (name: string) => FormulaPlan | undefined): FormulaPlan[];
 declare function validateMetric(c: AggregationClause, schema: FieldSchema, resolve?: (name: string) => FormulaPlan | undefined): FormulaDiagnostic[];
+/** The threshold of `AggregationClause.minCount` in either form. */
+declare function metricMinCount(c: {
+    minCount?: AggregationClause["minCount"] | undefined;
+}): number | undefined;
+/** What an object `minCount` measures: the aggregate whose value per group
+ * must reach `min`. Undefined when `minCount` counts rows. */
+declare function metricMinCountMeasure(c: {
+    minCount?: AggregationClause["minCount"] | undefined;
+}): {
+    op: "count_distinct" | "sum";
+    field: string;
+} | undefined;
+/** A minimum in words: "3 rows", "5 distinct Conversation values" or
+ * "10 total Calls". `label` names a field (default: its name). */
+declare function metricMinCountText(c: {
+    minCount?: AggregationClause["minCount"] | undefined;
+}, label?: (field: string) => string): string | undefined;
+/** The aggregate plan of an object `minCount`, such as SUM([calls]). */
+declare function metricMinCountPlan(c: {
+    minCount?: AggregationClause["minCount"] | undefined;
+}, schema: FieldSchema, resolve?: (name: string) => FormulaPlan | undefined): MetricPlan | undefined;
+/** Whether a group survives `minCount`. Calendar fill-ins (no rows) always do.
+ * Otherwise the row count, or for an object `minCount` the group's measure
+ * (null counts as 0), must reach `min`. A measure that is an error keeps its
+ * group, so the error stays visible. */
+declare function metricMinCountKeeps(min: number, count: number, measure?: {
+    value: unknown;
+    error?: string | undefined;
+}): boolean;
 /** Executor support for population controls, from either capability handshake. */
 interface MetricPopulationSupport {
     filters?: boolean | undefined;
     minCount?: boolean | undefined;
+    /** A `minCount` object: distinct values or a sum of a field. */
+    minCountMeasures?: boolean | undefined;
 }
 /** A clause the executor cannot run exactly gets its own error; it is never
  * sent with `where`/`minCount` silently dropped. */
@@ -1308,6 +1487,11 @@ interface QueryCapabilitiesV3 {
     version: 3;
     groupedRows: boolean;
     calendarGrouping: boolean;
+    /** Executes the cyclic `hourOfDay` and `dayOfWeek` date intervals. */
+    calendarCycles?: boolean;
+    /** Executes calendar grouping keys (`{ field, interval, timeZone }`) in a
+     * grouping stage. Requests using them are refused otherwise. */
+    calendarGroupKeys?: boolean;
     computedSourceFilters: boolean;
     regex: boolean;
     regexSourceFilters?: boolean;
@@ -1316,12 +1500,16 @@ interface QueryCapabilitiesV3 {
     metricFilters?: boolean;
     /** Executes AggregationClause.minCount and reports hiddenGroups. */
     metricMinCount?: boolean;
+    /** Also executes an object minCount: distinct values or a sum per group. */
+    metricMinCountMeasures?: boolean;
     maxRows: number;
     maxGroups: number;
     maxPopulation: number;
     profile: string;
 }
 interface QueryRequestV3 {
+    /** The table's host-owned state when `hostQuery` is configured. */
+    hostState?: HostQueryState;
     version: 3;
     profile: string;
     now: number;
@@ -1380,6 +1568,8 @@ interface DistinctValuesQuery {
     search: string;
     /** Max suggestions to return (default chosen by the adapter, ~50). */
     limit?: number;
+    /** The table's host-owned state when `hostQuery` is configured. */
+    hostState?: HostQueryState;
 }
 interface DistinctValuesResult {
     values: string[];
@@ -1438,6 +1628,10 @@ interface SavedQuery {
 interface StorageAdapter {
     /** Optional authenticated server store. Ordinary URL sync never calls it. */
     snapshots?: QuerySnapshotStore;
+    /** True when last-used and named queries keep `QueryState.hostState`
+     * exactly. A table with `hostQuery` refuses to save through an adapter
+     * without it rather than store a table-only query. */
+    storesHostState?: boolean;
     loadLast(key: string): Promise<QueryState | null>;
     saveLast(key: string, query: QueryState): Promise<void>;
     listSaved(key: string): Promise<SavedQuery[]>;
@@ -1506,13 +1700,27 @@ declare function boxSummary(values: number[], whiskers?: "minmax" | "tukey"): {
 declare function histogramEdges(values: number[], bins: number): number[];
 declare function histogramCounts(values: number[], edges: number[]): number[];
 
-declare const METRIC_DATE_INTERVALS: readonly ["hour", "day", "week", "month", "year"];
+declare const METRIC_DATE_INTERVALS: readonly ["hour", "day", "week", "month", "year", "hourOfDay", "dayOfWeek"];
+declare const METRIC_CYCLE_INTERVALS: readonly ["hourOfDay", "dayOfWeek"];
+/** Whether an interval is cyclic: keyed by slot number, not by date. */
+declare function isMetricCycle(interval: string | undefined): interval is MetricCycleInterval;
+/** Every slot of a cyclic interval, in order: 0–23 or 1–7 (ISO, Monday 1). */
+declare function metricCycleSlots(interval: MetricCycleInterval): number[];
+/** The calendar interval one occurrence of a slot spans: its hour or day.
+ * Calendar intervals are their own unit. */
+declare function metricCalendarUnit(interval: MetricDateGrouping["interval"]): Exclude<MetricDateGrouping["interval"], MetricCycleInterval>;
+/** The slot an instant occupies in `timeZone`: its local wall-clock hour
+ * (0–23), or its local ISO weekday (1 = Monday … 7 = Sunday). */
+declare function metricCycleSlot(time: number, interval: MetricCycleInterval, timeZone?: string): number;
 /** Strict calendar input; timestamps require an explicit offset. */
 declare function metricDateTime(value: MetricValue, timeZone?: string): number;
-declare function metricDateFloor(time: number, interval: MetricDateGrouping["interval"], timeZone?: string): number;
-declare function metricDateNext(time: number, interval: MetricDateGrouping["interval"], timeZone?: string): number;
+declare function metricDateFloor(time: number, cycleOrInterval: MetricDateGrouping["interval"], timeZone?: string): number;
+declare function metricDateNext(time: number, cycleOrInterval: MetricDateGrouping["interval"], timeZone?: string): number;
 /** A date-only Through value includes the whole local day, even for hourly groups. */
 declare function metricCustomEndTime(value: string, timeZone?: string): number;
+/** An IANA timezone identifier this runtime knows, such as America/Denver or
+ * UTC. Fixed offsets ("+02:00") are refused: they do not follow DST. */
+declare function isGroupingTimeZone(value: unknown): value is string;
 declare function validateDateGrouping(config: MetricDateGrouping): void;
 /** Only conjunctive bounds prove a domain; OR alternatives are not bounds. */
 declare function metricDateRange(config: MetricDateGrouping, query: QueryState, observed: readonly number[], now: number, canonical: (field: string) => string): [number, number] | undefined;
@@ -1522,8 +1730,15 @@ declare const MAX_METRIC_WINDOW_PERIODS = 1000;
 declare function hasMetricSeries(c: AggregationClause): boolean;
 /** Throws when a clause's window or share cannot be computed exactly. */
 declare function validateMetricSeries(c: AggregationClause, plan: FormulaPlan): void;
+/** The conjunctive bounds on a date-grouped clause's field, from the query's
+ * and the metric's own filters: [lower, upper), infinite where absent. */
+declare function metricDateBounds(c: AggregationClause, query: QueryState, schema: FieldSchema, now: number): {
+    lower: number;
+    upper: number;
+};
 /** The whole intervals inside the conjunctive bounds on the date field (the
- * query's and the metric's own), ending by `now`: [start, end). */
+ * query's and the metric's own), ending by `now`: [start, end). A cyclic
+ * interval's intervals are its hours or days. */
 declare function wholeIntervalSpan(c: AggregationClause, query: QueryState, schema: FieldSchema, now: number): {
     start?: number;
     end: number;
@@ -1552,9 +1767,13 @@ interface MetricSeriesPlan {
  *   of every group. With a window, both are windowed first.
  * - **Whole intervals.** `partialIntervals: "exclude"` narrows the metric to
  *   the intervals the query bounds and `now` leave whole.
+ * - **Occurrences.** A cyclic slot with `dateGrouping.occurrence` runs the
+ *   metric per whole occurrence (one calendar hour or day), then summarises
+ *   each slot: the mean of its occurrence values, or a box over them.
  *
- * `sort`, `groupLimit` and `minCount` (counting a window's rows) apply to the
- * combined buckets. Windowed and share results have no Other remainder. */
+ * `sort`, `groupLimit` and `minCount` (counting a window's rows, or summing a
+ * field over the window) apply to the combined buckets. Windowed and share
+ * results have no Other remainder. */
 declare function planMetricSeries(query: QueryState, schema: FieldSchema, options?: MetricSeriesOptions): MetricSeriesPlan | undefined;
 
 interface SavedPropertyView {
@@ -1596,6 +1815,12 @@ declare function sourceDependencies<Row>(query: QueryState, schema: FieldSchema<
  * - A date-grouped key becomes `>= start` and `< next`, using the clause's
  *   interval and timezone. A windowed point starts at its window's first
  *   interval, or has no lower bound for a running value.
+ * - An hour-of-day or day-of-week slot selects its occurrences inside the
+ *   date field's bounds (whole ones with `occurrence` or whole intervals):
+ *   `>= first`, `< last end` and, for each gap between occurrences, an OR
+ *   group `< gap start` or `>= gap end`. Without a lower and an upper bound on
+ *   the date field, or when the filter would exceed the query's predicate
+ *   budget (about 48 occurrences), the result is null.
  * - A histogram bin (`bucket.bin`) adds `>= min` and `< max` (`<= max` for
  *   the final bin) on the distribution input, which must be a field reference.
  *   Box cohorts are their group keys.
@@ -1613,7 +1838,8 @@ declare function inspectBucketQuery(query: QueryState, bucket: AggregationBucket
  *
  * Starts from the grouping source, as leaving the grouping stage does, so its
  * WHERE, columns, order and item details are kept. Each key adds `=` (or
- * `is_null` for a null key) and the offset resets. */
+ * `is_null` for a null key), a calendar key `>= start` and `< end` of its
+ * interval, and the offset resets. */
 declare function groupSourceQuery(query: QueryState, group: GroupedRow, schema: FieldSchema): QueryState | null;
 
 /** Host routes for query-kind links, keyed by `LinkSpec.to.target`. Each
@@ -1640,4 +1866,4 @@ declare function groupLinkQuery(query: QueryState, value: GroupLinkValue): Query
  * routes and unresolvable values return `href: null` with a `problem`. */
 declare function resolveGroupLink(query: QueryState, value: GroupLinkValue, targets?: LinkTargets): ResolvedGroupLink;
 
-export { AGG_OPS_BY_TYPE, AGG_OPS_NEEDING_FIELD, type AggOp, type AggregateConfig, type AggregationBucket, type AggregationClause, type AggregationRequest, type AggregationResult, type AggregationResultEntry, type Align, type ApplyPatchOptions, type ApplyResult, type BackendField, COMPUTED_PREFIX, type CellDisplay, type CellRenderer, type ColumnPreview, type ComputedCellError, type ComputedColumn, type ComputedColumnDraft, type ComputedColumnStore, type ComputedExecution, type ComputedFieldCapabilities, type DerivedField, type DistinctValuesQuery, type DistinctValuesResult, EMPTY_QUERY, FORMULA_FUNCTIONS, type FetchRowsResult, type FetchRowsResultV2, type FieldDef, type FieldOrigin, type FieldRelationship, type FieldSchema, type FieldSource, type FieldStats, type FieldType, type FilterConfig, type FilterOp, type FilterValues, type ForeignKey, type FormulaDiagnostic, FormulaError, type FormulaFunction, type FormulaNode, type FormulaPlan, type FormulaResult, type FormulaType, type FormulaValue, GROUP_ID_FIELD, GROUP_LINK_RENDER, type GroupLinkValue, type GroupedRow, type GroupingDefinition, type GroupingModel, type GroupingState, type GroupingView, ITEM_DETAILS_COLUMN, type ItemDetailMode, type ItemDetailsState, type ItemPageOptions, type ItemPropertyMode, type JsonCellDisplay, type LinkDestination, type LinkSpec, type LinkTargets, MAX_AGGREGATIONS, MAX_GROUP_BY_FIELDS, MAX_METRIC_WINDOW_PERIODS, MAX_ORDER_BY_TERMS, MAX_PROPERTIES, MAX_QUERY_LIMIT, MAX_QUERY_OFFSET, MAX_QUERY_STATE_BYTES, MAX_QUERY_TOKEN_LENGTH, MAX_RELATIVE_TIME_MS, MAX_REPRESENTATIVE_SORTS, MAX_RESULT_GROUPS, MAX_SELECT_COLUMNS, MAX_SUMMARY_COLUMNS, MAX_WHERE_CLAUSES, METRIC_DATE_INTERVALS, METRIC_FUNCTIONS, type MetricAxisScale, type MetricBoxSummary, type MetricCapabilities, type MetricDateGrouping, type MetricDiagnostic, type MetricDisplay, type MetricDistribution, type MetricDistributionResult, type MetricEvaluationOptions, type MetricHistogramBin, type MetricKey, type MetricLayout, type MetricPlan, type MetricPopulationSupport, type MetricQuery, type MetricReductionOptions, type MetricScope, type MetricSeriesOptions, type MetricSeriesPlan, type MetricShare, type MetricSort, type MetricValue, type MetricValueFormat, type MetricWindow, NULLARY_OPS, OPS_BY_TYPE, OP_LABEL, type ObjectReference, type ObjectTypeDefinition, type OpChoice, type OpPair, type OrGroup, type OrderByClause, type PreviewGroup, type PropertyFieldConfig, type PropertyFormat, type PropertySelection, type PropertyViewState, type PropertyViewStorage, type QueryCapabilitiesV3, QueryDecodeError, type QueryEvaluationOptions, type QueryFacet, type QueryLink, type QueryLinkOptions, type QueryLinkService, type QueryPatch, type QueryPatchMatch, type QueryRequestV3, type QueryResultV3, type QuerySnapshot, type QuerySnapshotCache, QuerySnapshotHttpError, type QuerySnapshotHttpErrorCode, type QuerySnapshotStore, type QueryState, type RegexInspection, type RelationshipAdapter, type RepresentativeOrder, type RepresentativeRow, type ResolvedGroupLink, type ResolvedObjectReference, type RowComputedValues, type RowId, type SavedPropertyView, type SavedQuery, type SelectColumn, type SelectConfig, type ServerQuery, type ServerQueryV2, type SetFilterMetadata, type SetFilterMode, type SetFilterTarget, type SortConfig, type SourceDependencies, type StorageAdapter, type SummaryColumn, type SummaryOp, type Transport, type WhereClause, type WhereTerm, aggOpAllowedForType, aggOpNeedsField, aggOpsForField, applyAggregations, applyPatch, applyQuery, boxSummary, coerceValue, compareMetricValues, compileFormula, compileMetric, computedFieldName, createGroupingModel, createPropertyView, createQueryLinkService, createSetFilter, decodeQuery, decodeQueryStrict, discoverFieldRelationships, encodeQuery, evaluateMetricReductions, evaluateMetrics, exitGrouping, filterValues, formulaRuntime, groupLinkQuery, groupPreview, groupSourceQuery, hasMetricSeries, hasRegex, histogramCounts, histogramEdges, httpComputedColumnStore, httpQuerySnapshotStore, indexFields, inspectBucketQuery, isComputedCellError, isComputedField, isFilterable, isGroupLinkField, isGroupLinkValue, isGroupable, isMeasurable, isNegativePredicate, isOrGroup, isPushdownFilter, isSelectable, isSortable, itemPageFields, jsonPropertyViewStorage, loadSchema, localPropertyViewStorage, localQuerySnapshotCache, localStorageAdapter, mapSetFilterValues, matchPatch, matchesClause, memoryComputedColumnStore, memoryPropertyViewStorage, memoryQuerySnapshotCache, memoryStorageAdapter, metricAggregatePlans, metricComputationKey, metricCustomEndTime, metricDateFloor, metricDateNext, metricDateRange, metricDateTime, metricDependencies, metricExpression, metricPlans, metricPopulationError, negateClause, normalizePropertyFormat, normalizePropertyView, normalizeQueryState, objectReferenceKey, opAllowedForType, opPairsForField, opsForField, parseRelativeDuration, percentile, planMetricSeries, predicatesOf, prepareGrouping, queriesEqual, readFieldValue, readObjectReference, readSetFilter, reduceMetricValues, removePatch, renderItemPageTemplate, resolveFieldName, resolveGroupLink, selectMetricShownRows, selectedFields, setFilterModes, setFilterTarget, sortMetricBuckets, sourceDependencies, sourceExecutionSchema, stripSetFilter, toAggregationQuery, toMetricQuery, toQueryRequestV3, toServerQuery, toServerQueryV2, validateComputedColumn, validateDateGrouping, validateItemPageTemplate, validateMetric, validateMetricSeries, validateQueryResultV3, validateQuerySnapshot, wholeIntervalSpan, withGroupingKeys, withoutGrouping, withoutLinkSummaries };
+export { AGG_OPS_BY_TYPE, AGG_OPS_NEEDING_FIELD, type AggOp, type AggregateConfig, type AggregationBucket, type AggregationClause, type AggregationRequest, type AggregationResult, type AggregationResultEntry, type Align, type ApplyPatchOptions, type ApplyResult, type BackendField, COMPUTED_PREFIX, type CalendarGroupKey, type CellDisplay, type CellRenderer, type ColumnPreview, type ComputedCellError, type ComputedColumn, type ComputedColumnDraft, type ComputedColumnStore, type ComputedExecution, type ComputedFieldCapabilities, type DerivedField, type DistinctValuesQuery, type DistinctValuesResult, EMPTY_QUERY, FORMULA_FUNCTIONS, type FetchRowsResult, type FetchRowsResultV2, type FieldDef, type FieldOrigin, type FieldRelationship, type FieldSchema, type FieldSource, type FieldStats, type FieldType, type FilterConfig, type FilterOp, type FilterValues, type ForeignKey, type FormulaDiagnostic, FormulaError, type FormulaFunction, type FormulaNode, type FormulaPlan, type FormulaResult, type FormulaType, type FormulaValue, GROUP_ID_FIELD, GROUP_KEY_INTERVALS, GROUP_LINK_RENDER, type GroupKey, type GroupLinkValue, type GroupedRow, type GroupingDefinition, type GroupingModel, type GroupingState, type GroupingView, type HostQueryState, ITEM_DETAILS_COLUMN, type ItemDetailMode, type ItemDetailsState, type ItemPageOptions, type ItemPropertyMode, type JsonCellDisplay, type LinkDestination, type LinkSpec, type LinkTargets, MAX_AGGREGATIONS, MAX_GROUP_BY_FIELDS, MAX_HOST_QUERY_PARAMS, MAX_HOST_QUERY_STATE_BYTES, MAX_HOST_QUERY_VALUES, MAX_HOST_QUERY_VALUE_LENGTH, MAX_METRIC_WINDOW_PERIODS, MAX_ORDER_BY_TERMS, MAX_PROPERTIES, MAX_QUERY_LIMIT, MAX_QUERY_OFFSET, MAX_QUERY_STATE_BYTES, MAX_QUERY_TOKEN_LENGTH, MAX_RELATIVE_TIME_MS, MAX_REPRESENTATIVE_SORTS, MAX_RESULT_GROUPS, MAX_SELECT_COLUMNS, MAX_SUMMARY_COLUMNS, MAX_WHERE_CLAUSES, METRIC_CYCLE_INTERVALS, METRIC_DATE_INTERVALS, METRIC_FUNCTIONS, type MetricAxisScale, type MetricBoxSummary, type MetricCalendarInterval, type MetricCapabilities, type MetricCycleInterval, type MetricDateGrouping, type MetricDateOccurrence, type MetricDiagnostic, type MetricDisplay, type MetricDistribution, type MetricDistributionResult, type MetricEvaluationOptions, type MetricHistogramBin, type MetricKey, type MetricLayout, type MetricMinCountOf, type MetricPlan, type MetricPopulationSupport, type MetricQuery, type MetricReductionOptions, type MetricScope, type MetricSeriesOptions, type MetricSeriesPlan, type MetricShare, type MetricSort, type MetricValue, type MetricValueFormat, type MetricWindow, NULLARY_OPS, OPS_BY_TYPE, OP_LABEL, type ObjectReference, type ObjectTypeDefinition, type OpChoice, type OpPair, type OrGroup, type OrOfAndsGroup, type OrderByClause, type PreviewGroup, type PropertyFieldConfig, type PropertyFormat, type PropertySelection, type PropertyViewState, type PropertyViewStorage, type QueryCapabilitiesV3, QueryDecodeError, type QueryEvaluationOptions, type QueryFacet, type QueryLink, type QueryLinkOptions, type QueryLinkService, type QueryPatch, type QueryPatchMatch, type QueryRequestV3, type QueryResultV3, type QuerySnapshot, type QuerySnapshotCache, QuerySnapshotHttpError, type QuerySnapshotHttpErrorCode, type QuerySnapshotStore, type QueryState, type RegexInspection, type RelationshipAdapter, type RepresentativeOrder, type RepresentativeRow, type ResolvedGroupLink, type ResolvedObjectReference, type RowComputedValues, type RowId, type SavedPropertyView, type SavedQuery, type SelectColumn, type SelectConfig, type ServerQuery, type ServerQueryV2, type SetFilterMetadata, type SetFilterMode, type SetFilterTarget, type SortConfig, type SourceDependencies, type StorageAdapter, type SummaryColumn, type SummaryOp, type Transport, type WhereBranch, type WhereClause, type WhereConjunction, type WhereTerm, aggOpAllowedForType, aggOpNeedsField, aggOpsForField, applyAggregations, applyPatch, applyQuery, boxSummary, branchesOf, calendarGroupKey, coerceValue, compareMetricValues, compileFormula, compileMetric, computedFieldName, createGroupingModel, createPropertyView, createQueryLinkService, createSetFilter, decodeQuery, decodeQueryStrict, discoverFieldRelationships, encodeQuery, evaluateMetricReductions, evaluateMetrics, exitGrouping, filterValues, formulaRuntime, groupKeyField, groupKeyFields, groupKeyTerms, groupLinkQuery, groupPreview, groupSourceQuery, hasMetricSeries, hasRegex, histogramCounts, histogramEdges, httpComputedColumnStore, httpQuerySnapshotStore, indexFields, inspectBucketQuery, isCalendarGroupKey, isComputedCellError, isComputedField, isFilterable, isGroupLinkField, isGroupLinkValue, isGroupable, isGroupingTimeZone, isMeasurable, isMetricCycle, isNegativePredicate, isOrGroup, isOrOfAndsGroup, isPushdownFilter, isSelectable, isSortable, isWhereConjunction, isWhereGroup, itemPageFields, jsonPropertyViewStorage, loadSchema, localPropertyViewStorage, localQuerySnapshotCache, localStorageAdapter, mapSetFilterValues, matchPatch, matchesClause, memoryComputedColumnStore, memoryPropertyViewStorage, memoryQuerySnapshotCache, memoryStorageAdapter, metricAggregatePlans, metricCalendarUnit, metricComputationKey, metricCustomEndTime, metricCycleSlot, metricCycleSlots, metricDateBounds, metricDateFloor, metricDateNext, metricDateRange, metricDateTime, metricDependencies, metricExpression, metricMinCount, metricMinCountKeeps, metricMinCountMeasure, metricMinCountPlan, metricMinCountText, metricPlans, metricPopulationError, negateClause, normalizePropertyFormat, normalizePropertyView, normalizeQueryState, objectReferenceKey, occurrenceDistribution, opAllowedForType, opPairsForField, opsForField, parseHostQueryState, parseRelativeDuration, percentile, planMetricSeries, predicatesOf, prepareGrouping, queriesEqual, readFieldValue, readObjectReference, readSetFilter, reduceMetricValues, removePatch, renderItemPageTemplate, resolveFieldName, resolveGroupLink, selectMetricShownRows, selectedFields, setFilterModes, setFilterTarget, sortMetricBuckets, sourceDependencies, sourceExecutionSchema, stripSetFilter, toAggregationQuery, toMetricQuery, toQueryRequestV3, toServerQuery, toServerQueryV2, validateComputedColumn, validateDateGrouping, validateItemPageTemplate, validateMetric, validateMetricSeries, validateQueryResultV3, validateQuerySnapshot, wholeIntervalSpan, withGroupingKeys, withoutGrouping, withoutLinkSummaries };