@ahoo-wang/wow-view-engine 9.2.0-rc.0

package/dist/filter/describe.d.ts

@@ -0,0 +1,234 @@
+import { AnalysisDateDiffUnit, AnalysisDateUnit, FieldKindId, FieldDefinition, FilterGroupOperator, FilterOperatorName, FilterTree, IssuePath, NumberFormat } from '../model/index.js';
+import { FieldKindRegistry } from './fieldKind.js';
+import { DateTimePreset, DurationComparison, RelativeDateDirection, RelativeDateUnit } from './values.js';
+/**
+ * What a condition compares against, as its kind read it.
+ *
+ * A closed union, and the reason the summary can be translated at all: the
+ * bar used to be handed one English sentence per condition, so the most
+ * visible line of the result area was the one line no catalogue could reach.
+ * Each variant carries the raw value, plus the labels a kind has already
+ * resolved — `/ui` turns it into words with the wording in force.
+ */
+export type FilterSummaryValue = 
+/** The operator is the whole condition: `IS_NULL`, `IS_EMPTY`. */
+{
+    kind: 'none';
+}
+/**
+ * The kind cannot read this value, so only the field's name is true of it.
+ * A stored config outlives the definition that admitted it.
+ */
+ | {
+    kind: 'blank';
+}
+/** One value, as the field holds it; `label` when the kind resolved one. */
+ | {
+    kind: 'text';
+    value: string | number | boolean;
+    label?: string;
+}
+/**
+ * Several values, and the label the definition gave each one — positional,
+ * and `undefined` where it named none.
+ *
+ * A label is what the definition said this value is called, never a
+ * stand-in for the value itself: a label the kind invented by stringifying
+ * the value would win over the field's own formatting, and a currency
+ * entry would show as a bare number beside a column showing ¥.
+ */
+ | {
+    kind: 'list';
+    values: readonly (string | number)[];
+    labels?: readonly (string | undefined)[];
+}
+/**
+ * Two bounds in the field's own units. Both are required: one bound is not
+ * a range, it is the condition that actually compiles — an absolute
+ * `BETWEEN` with no upper edge compiles to `GTE`, and it says `GTE`.
+ */
+ | {
+    kind: 'range';
+    from: string | number;
+    to: string | number;
+}
+/**
+ * A distance from the evaluation moment, and what the condition makes of
+ * it: `window` reaches from now to there, `instant` stands on it.
+ *
+ * The two are different conditions over the same stored value — `BETWEEN`
+ * asks for the span, `GTE` and `LTE` compare against its far edge — and
+ * saying "in the last 7 days" where "7 days ago" was meant is the summary
+ * describing a query that did not run. It is not the operator restated:
+ * `direction` already says which side of now, `operator` already says
+ * which way the comparison runs, and a kind offering `LT` would leave a
+ * `before`/`after` spelling stale on the first use.
+ */
+ | {
+    kind: 'relative';
+    amount: number;
+    unit: RelativeDateUnit;
+    direction: RelativeDateDirection;
+    bound: 'window' | 'instant';
+}
+/**
+ * A time since another moment (N3): the earlier moment by its label, how
+ * the time between compares, the amount and its unit.
+ */
+ | {
+    kind: 'duration';
+    from: string;
+    comparison: DurationComparison;
+    amount: number;
+    unit: AnalysisDateDiffUnit;
+}
+/** A named calendar period, resolved at compile time. */
+ | {
+    kind: 'preset';
+    preset: DateTimePreset;
+}
+/**
+ * A range that is exactly one period on the calendar of its zone — one
+ * day, one month, the seven days from a midnight (`periodOf`) — which is
+ * what a group pressed on a date axis opens its records under. It reads as
+ * the period, 「2026年9月22日」, the way the bucket was printed where it was
+ * pressed, rather than as the two instants bounding it: the last of those
+ * is a millisecond before the next midnight, a detail nobody chose.
+ */
+ | {
+    kind: 'period';
+    unit: AnalysisDateUnit;
+    /** The period's first instant, as the range stores it. */
+    from: string;
+    /** The zone the period is one on the calendar of. */
+    timeZone: string;
+}
+/**
+ * A range that is whole periods of one unit, more than one of them — the
+ * first one's start to the last one's end, on the calendar of its zone —
+ * which is what a brushed stretch of a date axis opens its records under
+ * (D33 Q52). It reads as the first and the last period, 「9月1日 ～ 9月3日」,
+ * as the buckets were printed where they were brushed.
+ */
+ | {
+    kind: 'periods';
+    unit: AnalysisDateUnit;
+    /** The first period's first instant, as the range stores it. */
+    from: string;
+    /** The last period's first instant. */
+    last: string;
+    timeZone: string;
+}
+/**
+ * One segment of a number line, `[from, to)`: the pair `GTE from` and
+ * `LT to` on one field, side by side under "all of" — which is what a band
+ * of a number histogram opens its records under. It reads as the band,
+ * 「单价 在 ¥0～500」, the way the band was printed where it was pressed,
+ * rather than as two comparisons: two chips for one question, where the
+ * menu and the name of the view opened from it said one sentence. Not a
+ * kind's reading — no one leaf is it — so `describeFilter` joins the two
+ * items (`FilterSummaryItem.paths`).
+ */
+ | {
+    kind: 'segment';
+    from: number;
+    to: number;
+};
+/**
+ * What a `FieldKind` says about one applied condition.
+ *
+ * `text` is the English line the kind has always produced, kept because a
+ * host may read `FilterSummaryItem.text` directly; the parts beside it are
+ * what `/ui` formats the badge from.
+ */
+export interface FieldKindDescription {
+    /** The English reading, for a host that consumes `text` as it stands. */
+    text: string;
+    /** How the condition reads; the leaf's own operator unless given. */
+    operator?: FilterOperatorName;
+    /**
+     * What the operator means for this kind, where the generic word would say
+     * something else. `IN` over an array asks whether the array contains any
+     * of the candidates, not whether a value is one of them, and "is any of"
+     * reads as the second — so `array` names the relation and the bar words
+     * that instead.
+     */
+    relation?: FilterSummaryRelation;
+    value: FilterSummaryValue;
+    /** For a predicate-valued kind: the conditions inside it. */
+    items?: readonly FilterSummaryItem[];
+    /** The operator joining `items`. */
+    group?: FilterGroupOperator;
+}
+/**
+ * A relation a kind reads its operator as, where the operator's own word
+ * would mislead. `/ui` words these through the catalogue, as it does
+ * operators.
+ */
+export type FilterSummaryRelation = 'has-any' | 'has-none' | 'has-all' | 'has-no-entries' | 'has-entries';
+/** One applied condition, for the summary bar above a result. */
+export interface FilterSummaryItem {
+    /** Location of the node, so the bar can remove or focus it. */
+    path: IssuePath;
+    /**
+     * Every condition the item reads, when it is more than the one at `path`:
+     * a segment's two comparisons (`FilterSummaryValue` `segment`), in tree
+     * order. Taking the item out of force takes out each of them.
+     */
+    paths?: readonly IssuePath[];
+    /**
+     * The condition in English, as the kind reads it out. It is a fallback
+     * rather than the summary: `/ui` builds the badge from the parts below, so
+     * the bar reads in the language the catalogue is in.
+     */
+    text: string;
+    /** The field or its kind is no longer available, in it or under it. */
+    unresolved: boolean;
+    /** A condition's field; a group has none. */
+    field?: string;
+    /** Field label, or the raw name when the field is gone. */
+    label?: string;
+    /** The field's kind, so the bar shows the value the way the field does. */
+    kind?: FieldKindId;
+    /** The field's renderer key, which overrides its kind: `cell ?? kind`. */
+    cell?: string;
+    /** The field's number format, for the same reason. */
+    numberFormat?: NumberFormat;
+    /**
+     * How the condition reads; absent on a group, and on a segment, which is
+     * two operators said as one reading.
+     */
+    operator?: FilterOperatorName;
+    /** What that operator means for this kind, when its own word would not. */
+    relation?: FilterSummaryRelation;
+    /** What the condition compares against; absent on a group. */
+    value?: FilterSummaryValue;
+    /**
+     * The operator joining `items`: a group's own, or the one inside a
+     * predicate. An item with no `field` is a group.
+     */
+    group?: FilterGroupOperator;
+    /** The conditions read out inside: a group's children, or a predicate's. */
+    items?: readonly FilterSummaryItem[];
+}
+/** How a group's own operator reads between its conditions. */
+export declare function groupJoinWord(op: FilterGroupOperator): string;
+/**
+ * Whether this item is a group rather than one condition.
+ *
+ * A group names no field. A predicate-valued condition carries `items` and a
+ * `group` too — it reads its predicate out — but it is one condition, and the
+ * bar draws it as one.
+ */
+export declare function isGroupItem(item: FilterSummaryItem): boolean;
+/**
+ * The conditions in force, one item per child of the root, so the summary
+ * keeps the tree's logic: a group under the root is one item that reads out
+ * its own conditions joined by its own operator, with a group inside it in
+ * parentheses. Items side by side read as "all of"; a root that is `or` or
+ * `nor` therefore folds into one item that says so. Blank conditions never
+ * reached the query and are left out; a condition whose field or kind is
+ * gone is named rather than hidden.
+ */
+export declare function describeFilter(fields: readonly FieldDefinition[], tree: FilterTree, kinds: FieldKindRegistry): FilterSummaryItem[];
+//# sourceMappingURL=describe.d.ts.map

package/dist/filter/describe.d.ts.map

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

package/dist/filter/fieldGroups.d.ts

@@ -0,0 +1,17 @@
+import { FieldGroupDefinition } from '../model/index.js';
+/** One group of a picker: its label, or none for the fields outside any. */
+export interface FieldGroup<T> {
+    group: FieldGroupDefinition | undefined;
+    items: T[];
+}
+/**
+ * Fields as a picker lists them: the ones no group lists first, in the
+ * field list's order, then each declared group in the definition's order,
+ * each in its own `fields` order. A picker often lists a subset — the fields
+ * not yet a condition, the ones a column can show — so a group none of the
+ * items belong to is not shown. A field two groups list, or one group lists
+ * twice, is kept where it was listed first; admission reports that as a
+ * definition error, so it is never the picker's to guess.
+ */
+export declare function fieldGroups<T>(items: readonly T[], groups: readonly FieldGroupDefinition[], key: (item: T) => string): FieldGroup<T>[];
+//# sourceMappingURL=fieldGroups.d.ts.map

package/dist/filter/fieldGroups.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fieldGroups.d.ts","sourceRoot":"","sources":["../../src/filter/fieldGroups.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE9D,4EAA4E;AAC5E,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,KAAK,EAAE,oBAAoB,GAAG,SAAS,CAAC;IACxC,KAAK,EAAE,CAAC,EAAE,CAAC;CACZ;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,MAAM,EAAE,SAAS,oBAAoB,EAAE,EACvC,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,GACvB,UAAU,CAAC,CAAC,CAAC,EAAE,CA4BjB"}

package/dist/filter/fieldKind.d.ts

@@ -0,0 +1,244 @@
+import { FilterExpression } from '@ahoo-wang/wow-client';
+import { FieldDefinition, FilterValue, FieldKindId, FieldOption, FilterLeaf, FilterOperatorName, FilterTree, Issue, IssuePath, RuntimeLimits } from '../model/index.js';
+import { FieldKindDescription, FilterSummaryRelation } from './describe.js';
+/**
+ * Everything the engine needs to know about one field type.
+ *
+ * A kind owns the shape of its values, so an application can add a type
+ * without the kernel learning anything about it. The React editor registers
+ * separately under the same id: a kind stays free of components, which is why
+ * a saved config never holds a component name.
+ */
+export interface FieldKind {
+    id: FieldKindId;
+    /** Operators this kind supports, in the order an editor should offer them. */
+    operators: FilterOperatorName[];
+    defaultOperator: FilterOperatorName;
+    /**
+     * The relation an operator means on this kind, where it means something
+     * other than its name: on a list field `IN` asks whether the entries
+     * include any of those listed. The condition's editor and the applied bar
+     * both say the relation's word (`label.relation.*`), so one condition has
+     * one name — 「属于」 in the editor beside 「含有其中任一」 on the bar read
+     * as two (second review R1-P1-7).
+     */
+    relations?: Partial<Record<FilterOperatorName, FilterSummaryRelation>>;
+    /**
+     * The Wow operators `operator` is sent as, when that is not just itself —
+     * an array's 「没有条目」 is `IS_EMPTY` or `IS_NULL`, because MongoDB's
+     * `$size: 0` misses a list that is absent or null. The descriptor must
+     * admit every one of them for the operator to be offered
+     * (`capabilities/fields.ts`). Left out, the operator is sent as itself.
+     */
+    compiledOperators?(operator: FilterOperatorName): readonly FilterOperatorName[];
+    /**
+     * The value a leaf starts from, which is normally "nothing yet". A picked
+     * field is a question the user has not finished asking, so the starting
+     * value must not narrow anything: seeding a number with `0` would silently
+     * apply `amount = 0` the moment the row appeared.
+     */
+    emptyValue(operator: FilterOperatorName, field: FieldDefinition): unknown;
+    /**
+     * Whether this value still counts as unsupplied. The registry's default
+     * covers `null`, `''` and `[]`; a kind whose empty shape is its own — a
+     * reference holding no items, a predicate whose every condition is itself
+     * unfilled — says so here. It replaces the default rather than extending
+     * it, so a kind that also starts from `''` or `[]` must recognise those too.
+     */
+    isBlank?(context: FieldKindBlankContext): boolean;
+    /**
+     * The tree this value holds, for a kind whose value is a condition rather
+     * than a scalar.
+     *
+     * Declaring it is what keeps the budget honest. `maxFilterDepth` and
+     * `maxFilterNodes` exist because a tree arrives from a store and must not
+     * exhaust the stack; a tree hidden inside a value would be a second
+     * dimension nobody counted, so a kind that holds one says so and the
+     * budget walks it with everything else.
+     *
+     * The operator is passed because a stored leaf keeps its old value when the
+     * operator changes: a predicate left behind under `IS_EMPTY` is not a tree
+     * this leaf asks anything with, and a kind that answers with it anyway has
+     * the budget charged for a tree nothing ever validates. A kind gates this
+     * on the operator exactly as its `isBlank` and `validate` do.
+     */
+    nested?(value: unknown, field: FieldDefinition, operator: FilterOperatorName): NestedTree | null;
+    /**
+     * Whether a leaf of this kind tests one value of the record.
+     *
+     * Defaults to true. `array` and `elementMatch` compile to conditions over
+     * the entries of a collection, and `search` compiles to a full-text match
+     * across the record, so none of the three has a single value to test. Wow
+     * refuses all three wherever a filter has to be a whole-value predicate —
+     * a metric's own filter — so a kind that compiles to one of those shapes
+     * must say so here, or it passes that check and is refused by the server
+     * instead.
+     */
+    scalar?: boolean;
+    /**
+     * Whether one record's value of this kind is a single string.
+     *
+     * Defaults to false, unlike `scalar`: most kinds hold numbers, moments or
+     * many values, and the one rule that reads this — a `TERMS` sentinel bucket
+     * (`missingKey`), which Wow allows on single-valued string fields only —
+     * must not be offered on a guess. A kind that does hold one string says so
+     * here, and `isSingleStringField` still lets the field's own candidates
+     * veto it: a closed set of numeric codes is a numeric field.
+     */
+    singleString?: boolean;
+    /**
+     * Whether this kind's `name` is a handle for the editor rather than a path
+     * into the document.
+     *
+     * Wow calls the filters that name no field root filters — `SEARCH` and the
+     * metadata ones — and refuses them inside an element predicate, so a kind
+     * that compiles to one must say so or the server rejects a condition the
+     * engine called usable. `FIELDLESS_FIELD_KIND_IDS` names the built-ins;
+     * this flag is how a custom kind joins them, and it is what
+     * `isFieldlessKind` reads whenever the registry has resolved the kind.
+     */
+    fieldless?: true;
+    /** Reports why a value cannot be used; an empty array admits it. */
+    validate(context: FieldKindValidateContext): Issue[];
+    /** Maps one admitted leaf onto the Wow protocol. */
+    compile(context: FieldKindCompileContext): FilterExpression;
+    /** Describes the editor implied by the operator and the value's variant. */
+    editor(operator: FilterOperatorName, field: FieldDefinition, value?: unknown): EditorDescriptor;
+    /**
+     * One applied condition, for the summary bar: its parts, and the English
+     * line they read as.
+     *
+     * The parts are what makes the bar translatable — it is the most visible
+     * text of the result area, and a kind that returned a sentence put it
+     * beyond every catalogue. `text` stays the English reading, because a host
+     * may consume `FilterSummaryItem.text` as it stands.
+     */
+    describe(context: FieldKindDescribeContext): FieldKindDescription;
+}
+/** A tree held inside a leaf's value, and the fields it is written against. */
+export interface NestedTree {
+    tree: FilterTree;
+    fields: readonly FieldDefinition[];
+}
+export interface FieldKindBlankContext {
+    value: unknown;
+    operator: FilterOperatorName;
+    field: FieldDefinition;
+    /**
+     * The registry in play, for a kind whose value is itself a condition: its
+     * blankness is that of the conditions it holds, judged by their own kinds.
+     */
+    kinds: FieldKindRegistry;
+}
+export interface FieldKindValidateContext {
+    value: unknown;
+    operator: FilterOperatorName;
+    field: FieldDefinition;
+    /**
+     * The fields the condition sits among, when the caller has them: what a
+     * value that names another field — the earlier moment of a time since
+     * (N3) — is checked against.
+     */
+    fields?: readonly FieldDefinition[];
+    /**
+     * The registry in play, for a kind whose value is itself a condition. It
+     * is passed rather than imported so a predicate admits custom kinds on the
+     * same terms as the tree around it.
+     */
+    kinds: FieldKindRegistry;
+    /** Location of the leaf, so an issue points at the offending node. */
+    path: IssuePath;
+    /**
+     * The budget the caller admitted the tree under, for a kind whose value is
+     * itself a condition. Without it a nested predicate would be judged against
+     * `DEFAULT_RUNTIME_LIMITS` while the tree around it was judged against the
+     * caller's, so one filter would answer to two budgets. It is optional
+     * because an editor may ask a kind about one leaf outside any walk.
+     */
+    limits?: Pick<RuntimeLimits, 'maxFilterDepth' | 'maxFilterNodes'>;
+}
+export interface FieldKindCompileContext {
+    leaf: FilterLeaf;
+    field: FieldDefinition;
+    /** The registry in play; see `FieldKindValidateContext`. */
+    kinds: FieldKindRegistry;
+    /** Evaluation moment and zone; the kernel never reads the system clock. */
+    now: Date;
+    timeZone: string;
+}
+export interface FieldKindDescribeContext {
+    leaf: FilterLeaf;
+    field: FieldDefinition;
+    /** The fields the condition sits among, for a value naming another one. */
+    fields?: readonly FieldDefinition[];
+    /** The registry in play; see `FieldKindValidateContext`. */
+    kinds: FieldKindRegistry;
+}
+/**
+ * Every input shape the engine can draw, as values and not as a type alone.
+ *
+ * `FilterValueEditor` switches over exactly this union and a kind picks one
+ * of its members — there is no renderer registry, so a kind that asks for
+ * anything else asks for a control nobody wrote. The list lives here, beside
+ * the union it spells out, so admission can hold a kind to the contract
+ * instead of the surface degrading to a text box: `validateFilter` refuses
+ * such a leaf with `filter.kind.unknown-editor`.
+ */
+export declare const EDITOR_INPUTS: readonly ["none", "text", "number", "boolean", "deletion", "select", "remote", "date", "dateRange", "relativeDate", "predicate", "duration"];
+export type EditorInput = (typeof EDITOR_INPUTS)[number];
+/** Whether a kind named an input the engine has a control for. */
+export declare function isKnownEditorInput(input: unknown): input is EditorInput;
+/** Shape of the input an editor should render; never a component name. */
+export interface EditorDescriptor {
+    input: EditorInput;
+    /** The input collects several values, e.g. for `IN`. */
+    multiple?: boolean;
+    /** Two bounds rather than one value, e.g. for `BETWEEN`. */
+    range?: boolean;
+    /** Static candidates, for `select`. */
+    options?: FieldOption[];
+    /** Candidate source key, for `remote`. */
+    remote?: string;
+    /** Whether the value carries a time of day. */
+    withTime?: boolean;
+}
+/** Kinds available to the kernels, keyed by id. */
+export type FieldKindRegistry = ReadonlyMap<FieldKindId, FieldKind>;
+export declare function createFieldKindRegistry(kinds: readonly FieldKind[]): FieldKindRegistry;
+/**
+ * Adds or replaces kinds, so an application extends the built-in set without
+ * mutating it.
+ */
+export declare function withFieldKinds(registry: FieldKindRegistry, kinds: readonly FieldKind[]): FieldKindRegistry;
+/** Operators a field actually offers: its own list narrows its kind's. */
+export declare function operatorsOf(field: FieldDefinition, kind: FieldKind): FilterOperatorName[];
+/**
+ * Reads an admitted leaf value as the shape its kind defined. Only
+ * `validateFilter` decides admissibility; a compile step runs after it.
+ */
+export declare function readValue<T>(value: unknown): T;
+/**
+ * Stores a value a kind produced, the mirror of `readValue`.
+ *
+ * A kind owns the shape of its values and declares it as an interface, which
+ * TypeScript does not consider assignable to a JSON index signature even when
+ * every field is JSON. Admission still runs on the way back in.
+ */
+export declare function writeValue<T>(value: T): FilterValue;
+/**
+ * Whether a leaf is still waiting to be filled in.
+ *
+ * An unfinished condition is an ordinary state of an editor, not a mistake:
+ * the user picked a field and has not yet said what to compare it to. Such a
+ * leaf is neither validated against its kind nor compiled into the query, so
+ * adding a row narrows nothing and blocks nothing until it says something.
+ *
+ * An operator that needs no input is never blank. `IS_NULL` is the whole
+ * condition and the value beside it is never read, so dropping it for looking
+ * empty would delete the condition. The kind already declares which operators
+ * those are by describing their editor as `none`, which is a better answer
+ * than a list here could be, because a custom kind gets it right too.
+ */
+export declare function isBlankLeafValue(value: unknown, operator: FilterOperatorName, field: FieldDefinition, kind: FieldKind, kinds: FieldKindRegistry): boolean;
+export declare function issue(code: string, path: IssuePath, params?: Issue['params'], severity?: Issue['severity']): Issue;
+//# sourceMappingURL=fieldKind.d.ts.map

package/dist/filter/fieldKind.d.ts.map

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

package/dist/filter/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The filter kernel: pure functions over a stored tree, plus the `FieldKind`
+ * registry that makes field types the one axis an application extends.
+ *
+ * Nothing here touches React, the DOM or the network, and relative dates are
+ * resolved against an injected moment rather than the system clock.
+ */
+export * from './compile.js';
+export * from './configBase.js';
+export * from './describe.js';
+export * from './fieldGroups.js';
+export * from './fieldKind.js';
+export * from './issuePath.js';
+export * from './kinds/index.js';
+export * from './marks.js';
+export * from './search.js';
+export * from './time.js';
+export * from './tree.js';
+export * from './validate.js';
+export * from './values.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/filter/index.ts"],"names":[],"mappings":"AAaA;;;;;;GAMG;AACH,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC"}

package/dist/filter/issuePath.d.ts

@@ -0,0 +1,21 @@
+import { Issue, IssuePath } from '../model/index.js';
+import { FilterPath } from './tree.js';
+/**
+ * Whether a finding is about the config's own filter tree rather than a
+ * nested one.
+ *
+ * The root tree's findings sit either at the config root — the tree as a
+ * whole was refused, for its size or its shape — or under `['children', …]`,
+ * which addresses one of its nodes. A metric's, an element's or a dashboard
+ * panel's filter is validated in its own scope and re-pathed under
+ * `['metrics', …]`, `['elements', …]` or `['panels', …]`, so the first
+ * segment is what tells the two apart.
+ */
+export declare function isRootFilterIssue(found: Issue): boolean;
+/**
+ * The node a path addresses, as the tree's own addressing: an issue path
+ * interleaves the `children` key with each index (`['children', 1]`), and a
+ * `FilterPath` is the indexes alone (`[1]`).
+ */
+export declare function filterIndexes(path: IssuePath): FilterPath;
+//# sourceMappingURL=issuePath.d.ts.map

package/dist/filter/issuePath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"issuePath.d.ts","sourceRoot":"","sources":["../../src/filter/issuePath.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,UAAU,CAIzD"}

package/dist/filter/kinds/array.d.ts

@@ -0,0 +1,18 @@
+import { FieldKind } from '../fieldKind.js';
+/** What one entry of an array field may be. */
+export type ArrayFilterValue = (string | number)[];
+/**
+ * A field holding several values at once: tags, categories, labels.
+ *
+ * It is a kind of its own rather than a flag on `string`, because its
+ * operators mean something else. On a scalar field `IN` asks whether the one
+ * value is among those listed; on this one it asks whether the field's entries
+ * include any of them, and that difference is the whole reason the kind
+ * exists. `CONTAINS_ALL` asks for all of them.
+ *
+ * Of emptiness it offers two questions, not five (second review R1-P1-7):
+ * 「没有条目」 and 「有条目」 (`entries.ts`). Absent, null and an empty list
+ * are three storage states and one answer to whoever reads the list.
+ */
+export declare const arrayFieldKind: FieldKind;
+//# sourceMappingURL=array.d.ts.map

package/dist/filter/kinds/array.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"array.d.ts","sourceRoot":"","sources":["../../../src/filter/kinds/array.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAoC5D,+CAA+C;AAC/C,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;AAEnD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,EAAE,SA+E5B,CAAC"}

package/dist/filter/kinds/boolean.d.ts

@@ -0,0 +1,3 @@
+import { FieldKind } from '../fieldKind.js';
+export declare const booleanFieldKind: FieldKind;
+//# sourceMappingURL=boolean.d.ts.map

package/dist/filter/kinds/boolean.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boolean.d.ts","sourceRoot":"","sources":["../../../src/filter/kinds/boolean.ts"],"names":[],"mappings":"AAcA,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAQnE,eAAO,MAAM,gBAAgB,EAAE,SA4C9B,CAAC"}

package/dist/filter/kinds/dateTime.d.ts

@@ -0,0 +1,39 @@
+import { EpochTimeUnit } from '../../model/index.js';
+import { FieldKind } from '../fieldKind.js';
+/** The instant a value of this kind names, and what kind of value said it. */
+export interface DateInstant {
+    /** Milliseconds since the epoch. */
+    ms: number;
+    /**
+     * The value named a time on a clock rather than a moment, so `ms` is it
+     * read at UTC — which is what prints it as written wherever it is shown.
+     */
+    wallClock?: true;
+    /** That wall-clock value carried no time of day, which is a meaning. */
+    dayOnly?: true;
+}
+/**
+ * The instant one of this kind's values names, or `undefined` when it names
+ * none.
+ *
+ * This is the kind's own reading of a value, and the one reading in the
+ * package: a cell shows a date through it (`ui/kit/display.ts`), and the record
+ * kernel orders a column's values by it to find its earliest and its latest
+ * (`record/project.ts`). `Date.parse` alone would not do — Wow keeps a time
+ * as epoch milliseconds, which arrives as a number or as a string of digits,
+ * and a wall-clock day has to be read at UTC so the 18th is not the 17th in
+ * Los Angeles. Anything the two agree on they agree on because they ask
+ * here.
+ */
+export declare function readInstant(value: unknown, 
+/**
+ * The unit a number counts in: the field's own (`epochUnitOf`), since a
+ * Wow time kept in seconds is a thousand times smaller than one in
+ * milliseconds and read as milliseconds lands in January 1970.
+ */
+unit?: EpochTimeUnit): DateInstant | undefined;
+/** A calendar day, without a time of day. */
+export declare const dateFieldKind: FieldKind;
+/** An instant, with a time of day. */
+export declare const dateTimeFieldKind: FieldKind;
+//# sourceMappingURL=dateTime.d.ts.map

package/dist/filter/kinds/dateTime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dateTime.d.ts","sourceRoot":"","sources":["../../../src/filter/kinds/dateTime.ts"],"names":[],"mappings":"AAeA,OAAO,EAOL,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AA4CnE,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,oCAAoC;IACpC,EAAE,EAAE,MAAM,CAAC;IACX;;;OAGG;IACH,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,wEAAwE;IACxE,OAAO,CAAC,EAAE,IAAI,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,OAAO;AACd;;;;GAIG;AACH,IAAI,GAAE,aAA8B,GACnC,WAAW,GAAG,SAAS,CAmBzB;AA4YD,6CAA6C;AAC7C,eAAO,MAAM,aAAa,EAAE,SAAyC,CAAC;AAEtE,sCAAsC;AACtC,eAAO,MAAM,iBAAiB,EAAE,SAA4C,CAAC"}