@luzmo/analytics-components-kit 1.0.5 → 1.0.7

package/components/filters/transformations/filter-format.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Runtime recognition of the two filter encodings ACK accepts.
+ *
+ * Groups look the same in both: a lowercase `and` / `or` condition plus a
+ * `filters` array. Only the leaves differ, so detection is per leaf rather than
+ * per array, and a payload that mixes the two converts leaf by leaf.
+ */
+/** Shared nesting limit, matching the platform-wide filter depth guard. */
+export declare const MAX_FILTER_NESTING_DEPTH = 20;
+/** Raised when a filter tree cannot be represented in the requested encoding. */
+export declare class FilterUnrepresentableError extends Error {
+    constructor(message: string);
+}
+/** Format label for a filter payload. Diagnostics only; conversion never depends on it. */
+export type DetectedFiltersFormat = 'empty' | 'canonical' | 'clean' | 'mixed' | 'unknown';
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * A group in either encoding, including a leftover uppercase condition. A group
+ * may omit `condition` entirely, which `toLogicalCondition` resolves to `and`;
+ * a condition that is present but not `and` / `or` is not a group.
+ */
+export declare function isFilterGroupLike(value: unknown): value is Record<string, unknown>;
+/** A leaf in either encoding. Groups are excluded by their `condition`. */
+export declare function isFilterLeafLike(value: unknown): value is Record<string, unknown>;
+export declare function hasCleanEncodingMarker(leaf: Record<string, unknown>): boolean;
+/**
+ * Clean references name exactly one source. `columnExpression` is an alias that
+ * loses to `columnId` rather than competing with it, so the two together are one
+ * source; `columnId` with `formulaId` is genuinely ambiguous and is rejected.
+ *
+ * `allowExpressionAlias` covers a standalone reference object, where a bare
+ * `expression` is the ad-hoc column. On a flattened leaf `expression` is the
+ * filter operator instead, so callers there must leave it off.
+ */
+export declare function hasExactlyOneReferenceSource(reference: Record<string, unknown>, allowExpressionAlias?: boolean): boolean;
+/** A flattened leaf: a dataset, exactly one reference source, and no `parameters`. */
+export declare function isCleanFilterLeaf(value: unknown): value is Record<string, unknown>;
+/** A canonical leaf: an ordered `parameters` tuple and no clean inline key. */
+export declare function isCanonicalFilterLeaf(value: unknown): value is Record<string, unknown>;
+/**
+ * A leaf carrying both encodings is ambiguous about which operand is the
+ * predicate, so it is rejected rather than guessed.
+ */
+export declare function assertLeafEncodingNotMixed(leaf: Record<string, unknown>): void;
+/**
+ * A leaf that is clean-encoded but not a valid clean leaf. Called only once
+ * `isCleanFilterLeaf` has rejected it, so that an incomplete reference is
+ * reported rather than silently reinterpreted as an empty canonical leaf.
+ */
+export declare function assertCleanLeafIsComplete(leaf: Record<string, unknown>): void;
+export declare function isFilterClause(value: unknown): value is 'where' | 'having';
+export declare function assertFilterNestingDepth(depth: number): void;
+/** Classifies a filter payload for diagnostics. Never throws. */
+export declare function detectFiltersFormat(input: unknown): DetectedFiltersFormat;

package/components/filters/transformations/transform-filters.d.ts

@@ -1,13 +1,11 @@
 import type { ItemFilterGroup } from '@luzmo/dashboard-contents-types';
-import type { FilterGroup as EditFilterGroup } from '../types';
-/**
- * Filter group format expected by luzmo-embed-viz-item.
- *
- * This differs from EditFilterGroup in that:
- * - nested groups are separated into subGroups array
- * - filters array contains only leaf filter items (no nested groups)
- */
-export type { ItemFilterGroup as VizItemFilterGroup } from '@luzmo/dashboard-contents-types';
+import type { CleanFilterClauseGroup, FilterGroup as EditFilterGroup, FiltersFormat, FiltersInput, FiltersOutput } from '../types';
+export { detectFiltersFormat, FilterUnrepresentableError, MAX_FILTER_NESTING_DEPTH } from './filter-format';
+export type { DetectedFiltersFormat } from './filter-format';
+export interface TransformFiltersOptions {
+    /** `canonical` (default) emits `ItemFilterGroup[]`; `clean` emits `CleanFilterClauseGroup[]`. */
+    format?: FiltersFormat;
+}
 /**
  * Normalize a group condition to the lowercase `'and' | 'or'` contract.
  * Accepts legacy uppercase `'AND' | 'OR'` values.
@@ -15,23 +13,40 @@ export type { ItemFilterGroup as VizItemFilterGroup } from '@luzmo/dashboard-con
 export declare function toLogicalCondition(condition: string | undefined): ItemFilterGroup['condition'];
 /**
  * Transform EditFilterGroup from filters component into the format
- * expected by luzmo-embed-viz-item (ItemFilterGroup[]).
+ * expected by luzmo-embed-viz-item (ItemFilterGroup[]), or into the clean
+ * clause groups published as `ItemFilterOutput` / `DashboardFilterOutput`.
  *
  * @param filters - Filter group in the internal/legacy filters format
- * @returns Array of VizItemFilterGroup for use with viz-item filters property
+ * @param options - `format: 'clean'` opts into clean clause-group output
+ * @returns Filter groups in the requested public format
  *
  * @example
  * ```typescript
  * const vizItemFilters = transformFilters(legacyFiltersGroup);
  * vizItem.filters = vizItemFilters;
+ *
+ * const cleanFilters = transformFilters(legacyFiltersGroup, { format: 'clean' });
  * ```
  */
 export declare function transformFilters(filters: EditFilterGroup | null | undefined): ItemFilterGroup[];
+export declare function transformFilters(filters: EditFilterGroup | null | undefined, options: {
+    format: 'clean';
+}): CleanFilterClauseGroup[];
+export declare function transformFilters(filters: EditFilterGroup | null | undefined, options: {
+    format?: 'canonical';
+}): ItemFilterGroup[];
+export declare function transformFilters(filters: EditFilterGroup | null | undefined, options?: TransformFiltersOptions): FiltersOutput;
 /**
  * Transform filter groups from luzmo-embed-viz-item format into the format
  * used internally by luzmo-filters.
  *
+ * Accepts both halves of the public `ItemFilterOutput` / `DashboardFilterOutput`
+ * unions: canonical `ItemFilterGroup[]` and clean clause groups with flattened
+ * leaves. Nested `and` / `or` groups are preserved, never flattened.
+ *
  * @param filters - Filter groups from viz-item filters property or getFilters()
  * @returns FilterGroup array in the internal filters format
+ * @throws FilterUnrepresentableError when a leaf mixes both encodings, matches
+ * neither a complete clean nor a complete canonical encoding, or nesting is too deep
  */
-export declare function reverseTransformFilters(filters: ItemFilterGroup[] | null | undefined): EditFilterGroup[];
+export declare function reverseTransformFilters(filters: FiltersInput | null | undefined): EditFilterGroup[];

package/components/filters/types.d.ts

@@ -1,18 +1,63 @@
-import type { ItemFilterGroup } from '@luzmo/dashboard-contents-types';
-export interface FiltersChangedEventDetail {
-    filters: ItemFilterGroup[];
+import type { ItemFilterGroup, ItemFilterParameterDefinition, ItemFilterProperties } from '@luzmo/dashboard-contents-types';
+import type { CleanFilter, CleanFilterClauseGroup, CleanFilterGroup, CleanRetrievedFilterGroup, DashboardFilterOutput, ItemFilterOutput } from '@luzmo/embed';
+export type FilterParameterType = 'numeric' | 'datetime' | 'hierarchy' | 'array[numeric]' | 'array[datetime]' | 'array[hierarchy]';
+export type FilterParameter = Omit<ItemFilterParameterDefinition, 'type'> & {
+    type: FilterParameterType;
+};
+export interface FilterParameterEventDetail {
+    parameter: FilterParameter;
 }
+export type { CleanFilter, CleanFilterClauseGroup, CleanFilterGroup, CleanRetrievedFilterGroup, DashboardFilterOutput, ItemFilterOutput };
+/** Clause owned by a top-level clean filter group. Nested groups inherit it. */
+export type FilterClause = 'where' | 'having';
+/** Output format for `luzmo-filters-changed` and `transformFilters`. */
+export type FiltersFormat = 'canonical' | 'clean';
+/**
+ * Every filter array `luzmo-filters` and `reverseTransformFilters` accept: both
+ * halves of the public `ItemFilterOutput` / `DashboardFilterOutput` unions.
+ */
+export type FiltersInput = ItemFilterOutput | DashboardFilterOutput;
+/** Every filter array `luzmo-filters` and `transformFilters` can produce. */
+export type FiltersOutput = ItemFilterGroup[] | CleanFilterClauseGroup[];
+/**
+ * Detail of `luzmo-filters-changed`, discriminated by `format` so a consumer
+ * that never opts into clean output keeps the narrow `ItemFilterGroup[]` type.
+ */
+export type FiltersChangedEventDetail = {
+    format: 'canonical';
+    filters: ItemFilterGroup[];
+} | {
+    format: 'clean';
+    filters: CleanFilterClauseGroup[];
+};
 export interface FilterCondition {
     expression?: string;
     parameters?: unknown[];
+    /**
+     * Canonical leaf metadata, preserved across ingest, edit, and export so that
+     * `properties.type` (clause), `properties.ignore` (`ignoredItemIds`), and
+     * `properties.id` survive a round trip. Never part of clean output.
+     */
+    properties?: ItemFilterProperties;
 }
 /**
  * Nested filter group used by the `luzmo-filters` editor.
  *
  * `condition` uses the same lowercase `'and' | 'or'` values as `ItemFilterGroup`.
  * Nested groups live in `filters`; the public `ItemFilterGroup` shape uses `subGroups`.
+ *
+ * Every member below `filters` is optional metadata carried through from the
+ * ingested group. Only `id` and `clause` reach clean output; the rest stay internal.
  */
 export interface FilterGroup {
     condition: ItemFilterGroup['condition'];
     filters: (FilterCondition | FilterGroup)[];
+    id?: string;
+    clause?: FilterClause;
+    origin?: ItemFilterGroup['origin'];
+    datasetId?: string;
+    vizId?: string;
+    itemId?: string;
+    isDrilldown?: boolean;
+    type?: 'injected';
 }