@luzmo/analytics-components-kit 1.0.6 → 1.0.7

package/components/filter-value-picker-numeric-BaQe4r82.js

@@ -0,0 +1,219 @@
+/*! * A kit of modern Luzmo Web Components for analytics in your web application.
+ * 
+ * Copyright © 2026 Luzmo
+ * All rights reserved.
+ * Luzmo web components (“Luzmo Web Components”)
+ * must be used according to the Luzmo Terms of Service.
+ * This license allows users with a current active Luzmo account
+ * to use the Luzmo Web Components. This license terminates
+ * automatically if a user no longer has an active Luzmo account.
+ * Please view the Luzmo Terms of Service at: https://www.luzmo.com/information-pages/terms-of-use.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ * */
+import { t as e } from "./decorate-DyMgX_Uh.js";
+import { t } from "./localized-mixin-D-vXCJuU.js";
+import { t as n } from "./data-broker-Bdv5V8Yp.js";
+import { html as r, unsafeCSS as i } from "lit";
+import { property as a, state as o } from "lit/decorators.js";
+import { localized as s, msg as c } from "@lit/localize";
+import "@luzmo/lucero/select";
+import "@luzmo/lucero/number-field";
+import { ElementSizes as l, LuzmoElement as u, SizedMixin as d } from "@luzmo/lucero/utils";
+//#region src/components/filter-value-picker-numeric/filter-value-picker-numeric.module.scss?inline
+var f = ":host{flex-direction:row;flex-shrink:1;min-width:0;display:flex}luzmo-number-field,luzmo-select{min-width:var(--luzmo-filter-value-picker-numeric-control-min-width,var(--filter-value-picker-numeric-control-min-width));max-width:100%}.missing-value{opacity:.4}:host{--filter-value-picker-numeric-control-min-width:0}", p = 5e3, m = class extends t(d(u, { validSizes: Object.values(l) })) {
+	constructor(...e) {
+		super(...e), this.contentLanguage = "en", this._numericValues = [], this._retrieving = !0, this._search = "", this._error = null, this._allValuesRetrieved = !1, this._runningQueries = [];
+	}
+	static get styles() {
+		return [i(f)];
+	}
+	connectedCallback() {
+		super.connectedCallback();
+		let e = {};
+		this.apiUrl && (e.apiUrl = this.apiUrl), this.cacheTime && (e.staleTime = this.cacheTime, e.gcTime = this.cacheTime * 2), this.authKey && this.authToken && (e.authKey = this.authKey, e.authToken = this.authToken), n.configure(e);
+	}
+	willUpdate(e) {
+		if (super.willUpdate(e), e.has("filter") && this.filter) {
+			let t = e.get("filter")?.expression, n = this.filter?.expression;
+			((e.get("filter")?.parameters?.[0]?.columnId || e.get("filter")?.parameters?.[0]?.formulaId) !== (this.filter?.parameters?.[0]?.columnId || this.filter?.parameters?.[0]?.formulaId) || !["? in ?", "? not in ?"].includes(t)) && ["? in ?", "? not in ?"].includes(n) && (this._numericValues = [], this._allValuesRetrieved = !1, this._retrieving = !0);
+		}
+	}
+	async _fetchNumericValues(e = 0) {
+		if (this._allValuesRetrieved) {
+			this._retrieving = !1;
+			return;
+		}
+		if (!this.filter?.parameters?.[0]) {
+			this._retrieving = !1, this._error = "Missing column parameters";
+			return;
+		}
+		let t = this.filter.parameters[0], r = t.columnId, i = t.formulaId, a = t.datasetId;
+		if (!r && !i) {
+			this._retrieving = !1, this._error = "Missing column id or formula id";
+			return;
+		} else if (!a) {
+			this._retrieving = !1, this._error = "Missing dataset id";
+			return;
+		}
+		this._retrieving = !0, this._error = null;
+		let o = {
+			expression: "? like ?",
+			parameters: [{
+				dataset_id: a,
+				expression: `CAST({${a}:${r ?? i}},hierarchy)`
+			}, this._search]
+		}, s = {
+			dimensions: [{
+				column_id: r,
+				formula_id: i,
+				dataset_id: a
+			}],
+			where: [],
+			order: [{
+				column_id: r,
+				formula_id: i,
+				dataset_id: a,
+				order: "asc"
+			}],
+			limit: {
+				by: p,
+				offset: e
+			}
+		};
+		this._search && !this._allValuesRetrieved && s.where.push(o);
+		let c = new AbortController(), l = new Promise((e, t) => {
+			n.fetchData(s).then(e).catch(t), c.signal.addEventListener("abort", () => {
+				console.warn("Request aborted"), t({ status: "aborted" });
+			});
+		}), u = {
+			promise: l,
+			abortController: c
+		};
+		this._runningQueries.push(u);
+		try {
+			let t = await l, n = t && Array.isArray(t.data) ? t.data.map((e) => e[0]) : [];
+			this._search || (this._allValuesRetrieved = n.length < p), this._numericValues = e > 0 ? [...this._numericValues, ...n] : n;
+		} catch (e) {
+			if (e?.status === "aborted") return;
+			this._error = e instanceof Error ? e.message : "Unknown error", this._numericValues = [];
+		} finally {
+			this._runningQueries = this._runningQueries.filter((e) => e.promise !== l), this._retrieving = !1;
+		}
+	}
+	_sendChangeEvent() {
+		this.dispatchEvent(new CustomEvent("luzmo-filter-value-changed", {
+			bubbles: !0,
+			composed: !0,
+			cancelable: !0,
+			detail: { value: this._value }
+		}));
+	}
+	setValue(e) {
+		let t = ["? in ?", "? not in ?"].includes(this.filter?.expression) ? e?.detail?.value : e?.target?.value;
+		this._value !== t && (this._value = t, this.filter = {
+			...this.filter,
+			parameters: [{ ...this.filter?.parameters?.[0] }, t]
+		}, this._sendChangeEvent());
+	}
+	selectValue(e) {
+		let t = (e.detail?.value ?? "").map((e) => Number.parseFloat(e));
+		this.filter = {
+			...this.filter,
+			parameters: [{ ...this.filter?.parameters?.[0] }, t]
+		}, this._value = t, this._sendChangeEvent();
+	}
+	onScrolled(e) {
+		!this._retrieving && !this._allValuesRetrieved && e?.detail?.last === this._numericValues.length - 1 && this._fetchNumericValues(this._numericValues.length);
+	}
+	renderNumberField() {
+		return r`<luzmo-number-field
+      label="Numeric filter value"
+      grows
+      .size=${this.size}
+      @change=${this.setValue}
+      @input=${this.setValue}
+      .value=${this.filter?.parameters?.[1]}
+    ></luzmo-number-field>`;
+	}
+	setSearchString(e) {
+		this._search = e?.detail?.string ?? "", this._allValuesRetrieved || (this._searchQueryTimeout && (this._runningQueries.forEach((e) => {
+			e?.abortController && e.abortController.abort();
+		}), this._runningQueries = [], clearTimeout(this._searchQueryTimeout)), this._searchQueryTimeout = setTimeout(() => {
+			this._fetchNumericValues();
+		}, 500));
+	}
+	resetSearchString() {
+		this._search = "";
+	}
+	onOpened() {
+		this._fetchNumericValues();
+	}
+	renderValuePicker() {
+		if (this._error) return r`<div class="error" role="alert">${this._error}</div>`;
+		let e = this._numericValues.filter((e) => e.toString().toLowerCase().includes(this._search.toLowerCase())).map((e) => ({
+			value: e,
+			label: e
+		})), t = c("Selected {count} items"), n = c("Search"), i = c("No data"), a = c("No results"), o = c("Select...");
+		return r`<luzmo-select
+      .size=${this.size}
+      .label=${o}
+      .retrieving=${this._retrieving}
+      selects="multiple"
+      variant="checkboxes"
+      emphasized
+      no-wrap
+      ?invalid=${!!this._error}
+      .multipleLabelTemplate=${t}
+      .searchLabel=${n}
+      .noDataLabel=${i}
+      .noResultsLabel=${a}
+      @change=${this.selectValue}
+      @luzmo-search=${this.setSearchString}
+      @luzmo-opened=${this.onOpened}
+      @luzmo-closed=${this.resetSearchString}
+      @luzmo-scrolled=${this.onScrolled}
+      .options=${e}
+      .value=${this.filter?.parameters?.[1]}
+    >
+    </luzmo-select>`;
+	}
+	render() {
+		let e = this.filter?.expression;
+		return ["? in ?", "? not in ?"].includes(e) ? this.renderValuePicker() : this.renderNumberField();
+	}
+};
+//#endregion
+//#region src/components/filter-value-picker-numeric/index.ts
+e([a({
+	type: String,
+	attribute: "api-url",
+	reflect: !0
+})], m.prototype, "apiUrl", void 0), e([a({
+	type: String,
+	attribute: "auth-key",
+	reflect: !0
+})], m.prototype, "authKey", void 0), e([a({
+	type: String,
+	attribute: "auth-token",
+	reflect: !0
+})], m.prototype, "authToken", void 0), e([a({
+	type: Number,
+	attribute: "cache-time",
+	reflect: !0
+})], m.prototype, "cacheTime", void 0), e([a({
+	type: String,
+	attribute: "content-language",
+	reflect: !0
+})], m.prototype, "contentLanguage", void 0), e([a({
+	type: Object,
+	reflect: !1
+})], m.prototype, "filter", void 0), e([o()], m.prototype, "_numericValues", void 0), e([o()], m.prototype, "_retrieving", void 0), e([o()], m.prototype, "_search", void 0), e([o()], m.prototype, "_error", void 0), m = e([s()], m), customElements.get("luzmo-filter-value-picker-numeric") || customElements.define("luzmo-filter-value-picker-numeric", m);
+//#endregion
+export { m as t };

package/components/filters/filters.d.ts

@@ -3,8 +3,8 @@ import '@luzmo/lucero/button';
 import '@luzmo/lucero/icon';
 import { LuzmoElement } from '@luzmo/lucero/utils';
 import { CSSResultArray, PropertyValues, TemplateResult } from 'lit';
-import type { ItemFilterGroup } from '@luzmo/dashboard-contents-types';
 import '../filter-item';
+import type { FilterParameter, FiltersFormat, FiltersInput } from './types';
 declare const LuzmoFilters_base: (new (...args: any[]) => {
     language: string;
 }) & typeof LuzmoElement & {
@@ -13,7 +13,10 @@ declare const LuzmoFilters_base: (new (...args: any[]) => {
 };
 /**
  * @customElement luzmo-filters
- * @fires {CustomEvent<FiltersChangedEventDetail>} luzmo-filters-changed - Announces that the filters have changed
+ * @fires {CustomEvent<FiltersChangedEventDetail>} luzmo-filters-changed - Announces that the filters have changed,
+ * carrying the emitted groups and the format they are in
+ * @fires {CustomEvent<{ parameter: FilterParameter }>} luzmo-parameter-created - Announces that a parameter was created and added to `parameters`.
+ * @fires {CustomEvent<{ parameter: FilterParameter }>} luzmo-parameter-removed - Announces that a parameter was detached from a filter.
  */
 export declare class LuzmoFilters extends LuzmoFilters_base {
     static get styles(): CSSResultArray;
@@ -47,15 +50,38 @@ export declare class LuzmoFilters extends LuzmoFilters_base {
      */
     datasetIds?: string[];
     /**
-     * The filter groups to display
+     * The filter groups to display.
+     *
+     * Accepts both halves of the public `ItemFilterOutput` / `DashboardFilterOutput`
+     * unions: canonical `ItemFilterGroup[]` and clean clause groups with flattened
+     * leaves. Nested `and` / `or` groups are preserved either way.
      */
-    filters: ItemFilterGroup[];
+    filters: FiltersInput;
+    /**
+     * Output format for the `luzmo-filters-changed` event.
+     *
+     * `canonical` emits `ItemFilterGroup[]`; `clean` emits the clean clause groups
+     * that aligned hosts consume. A tree that cannot be represented cleanly falls
+     * back to canonical output, and the event says which format it carries.
+     * @default canonical
+     */
+    format: FiltersFormat;
+    /**
+     * Whether parameter-backed filter values can be created and selected.
+     * @default false
+     */
+    allowParameters: boolean;
+    /**
+     * Consumer-owned parameter definitions available to filter rows.
+     */
+    parameters: FilterParameter[];
     /**
      * Debounce time in milliseconds for the filters-changed event
      * @default 300
      */
     debounce: number;
     private _internalFilterGroup;
+    private _hasSyntheticRoot;
     private _debounceTimeout;
     /**
      * Get a smaller size for the condition badges
@@ -69,9 +95,17 @@ export declare class LuzmoFilters extends LuzmoFilters_base {
     protected willUpdate(changedProperties: PropertyValues): void;
     private _generateEmptyGroup;
     private _generateEmptyFilter;
+    /**
+     * The root groups to export: either the wrapped children or the single group.
+     */
+    private _rootGroupsForExport;
     private _getFiltersForExport;
     private _sendChangeEvent;
     private _isGroup;
+    /**
+     * A parameter created in one row becomes selectable in every row.
+     */
+    private _handleParameterCreated;
     private _toggleCondition;
     private _addFilter;
     private _addSubGroup;

package/components/filters/index.cjs

@@ -17,4 +17,4 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  * */
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("../filters-B6jGM3ej.cjs");Object.defineProperty(exports,"LuzmoFilters",{enumerable:!0,get:function(){return e.t}});
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("../filters-ms2gFstA.cjs");exports.FilterUnrepresentableError=e.a,Object.defineProperty(exports,"LuzmoFilters",{enumerable:!0,get:function(){return e.t}}),exports.MAX_FILTER_NESTING_DEPTH=e.o,exports.detectFiltersFormat=e.s,exports.reverseTransformFilters=e.n,exports.toLogicalCondition=e.r,exports.transformFilters=e.i;

package/components/filters/index.d.ts

@@ -5,4 +5,7 @@ declare global {
     }
 }
 export { LuzmoFilters } from './filters';
-export type { FilterCondition, FilterGroup, FiltersChangedEventDetail } from './types';
+export { detectFiltersFormat, FilterUnrepresentableError, MAX_FILTER_NESTING_DEPTH } from './transformations/filter-format';
+export { reverseTransformFilters, toLogicalCondition, transformFilters } from './transformations/transform-filters';
+export type { DetectedFiltersFormat, TransformFiltersOptions } from './transformations/transform-filters';
+export type { CleanFilter, CleanFilterClauseGroup, CleanFilterGroup, CleanRetrievedFilterGroup, DashboardFilterOutput, FilterClause, FilterCondition, FilterGroup, FilterParameter, FilterParameterEventDetail, FilterParameterType, FiltersChangedEventDetail, FiltersFormat, FiltersInput, FiltersOutput, ItemFilterOutput } from './types';

package/components/filters/index.js

@@ -24,5 +24,5 @@
 		e.setAttribute("data-luzmo-vars", ""), e.textContent = "html{--luzmo-animation-duration: 0.15s;--luzmo-border-color: rgba(var(--luzmo-border-color-rgb), 0.1);--luzmo-border-color-hover: rgba(var(--luzmo-border-color-rgb), 0.15);--luzmo-border-color-down: rgba(var(--luzmo-border-color-rgb), 0.3);--luzmo-border-color-focus: rgba(var(--luzmo-border-color-rgb), 0.15);--luzmo-border-color-rgb: 0, 0, 0;--luzmo-border-color-full: rgb(180, 180, 180);--luzmo-border-color-full-hover: color-mix(in oklch, var(--luzmo-border-color-full), black 25%);--luzmo-border-color-full-down: color-mix(in oklch, var(--luzmo-border-color-full), black 45%);--luzmo-border-color-full-focus: color-mix(in oklch, var(--luzmo-border-color-full), black 25%);--luzmo-border-color-disabled: #dddddd;--luzmo-border-radius: 6px;--luzmo-border-radius-s: 4px;--luzmo-border-radius-l: 8px;--luzmo-border-radius-xl: 12px;--luzmo-border-radius-full: 999rem;--luzmo-background-color: #ffffff;--luzmo-background-color-rgb: 255, 255, 255;--luzmo-background-color-disabled: #eeeeee;--luzmo-background-color-hover: color-mix( in oklch, color-mix(in oklch, var(--luzmo-background-color), var(--luzmo-primary) 5%), black 1.5% );--luzmo-background-color-down: color-mix(in oklch, color-mix(in oklch, var(--luzmo-background-color), var(--luzmo-primary) 7%), black 1%);--luzmo-background-color-focus: color-mix( in oklch, color-mix(in oklch, var(--luzmo-background-color), var(--luzmo-primary) 5%), black 1.5% );--luzmo-background-color-highlight: rgb(240, 240, 240);--luzmo-background-color-highlight-disabled: rgb(245, 245, 245);--luzmo-background-color-highlight-hover: color-mix(in oklch, var(--luzmo-background-color-highlight), black 10%);--luzmo-background-color-highlight-down: color-mix(in oklch, var(--luzmo-background-color-highlight), black 20%);--luzmo-background-color-highlight-focus: color-mix(in oklch, var(--luzmo-background-color-highlight), black 10%);--luzmo-background-color-alt-1: rgb(250, 250, 250);--luzmo-background-color-alt-2: rgb(239, 239, 239);--luzmo-border-width: 1px;--luzmo-shadow-color-rgb: 0, 0, 0;--luzmo-shadow-opacity: 0.1;--luzmo-shadow-color: rgba(var(--luzmo-shadow-color-rgb), var(--luzmo-shadow-opacity));--luzmo-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen-Sans, Ubuntu, Cantarell, 'Helvetica Neue', Helvetica, Arial, sans-serif;--luzmo-font-size-xs: 10px;--luzmo-font-size-s: 12px;--luzmo-font-size-m: 14px;--luzmo-font-size: 14px;--luzmo-font-size-l: 16px;--luzmo-font-size-xl: 18px;--luzmo-font-size-xxl: 20px;--luzmo-font-style: normal;--luzmo-line-height: normal;--luzmo-font-weight: 400;--luzmo-font-weight-semibold: 500;--luzmo-font-weight-bold: 600;--luzmo-font-color: #333;--luzmo-font-color-hard: #000;--luzmo-font-color-disabled: var(--luzmo-color-disabled);--luzmo-font-color-extra-dimmed: #888;--luzmo-font-color-hover: color-mix(in oklch, var(--luzmo-font-color), black 8%);--luzmo-font-color-down: color-mix(in oklch, var(--luzmo-font-color), black 20%);--luzmo-font-color-focus: color-mix(in oklch, var(--luzmo-font-color), black 8%);--luzmo-scrollbar-size: 6px;--luzmo-scrollbar-width: thin;--luzmo-scrollbar-track-background: transparent;--luzmo-scrollbar-track-border-radius: var(--luzmo-border-radius-s);--luzmo-scrollbar-thumb-background: rgba(var(--luzmo-border-color-rgb), 0.3);--luzmo-scrollbar-thumb-border-radius: var(--luzmo-border-radius-s);--luzmo-scrollbar-thumb-hover-background: rgba(var(--luzmo-border-color-rgb), 0.4);--luzmo-primary: #4434ff;--luzmo-primary-hover: color-mix(in oklch, var(--luzmo-primary), black 8%);--luzmo-primary-down: color-mix(in oklch, var(--luzmo-primary), black 20%);--luzmo-primary-focus: color-mix(in oklch, var(--luzmo-primary), black 8%);--luzmo-primary-inverse-color: #ffffff;--luzmo-primary-rgb: 68, 52, 255;--luzmo-secondary: #ff00ff;--luzmo-secondary-hover: color-mix(in oklch, var(--luzmo-secondary), black 8%);--luzmo-secondary-down: color-mix(in oklch, var(--luzmo-secondary), black 20%);--luzmo-secondary-focus: color-mix(in oklch, var(--luzmo-secondary), black 8%);--luzmo-secondary-inverse-color: #ffffff;--luzmo-secondary-rgb: 255, 0, 255;--luzmo-secondary-outline: rgba(255, 0, 255, 0.2);--luzmo-negative-color: #ca221c;--luzmo-negative-color-hover: color-mix(in oklch, var(--luzmo-negative-color), black 8%);--luzmo-negative-color-down: color-mix(in oklch, var(--luzmo-negative-color), black 20%);--luzmo-negative-color-focus: color-mix(in oklch, var(--luzmo-negative-color), black 8%);--luzmo-negative-color-rgb: 202, 34, 28;--luzmo-positive-color: rgb(20, 150, 101);--luzmo-positive-color-hover: color-mix(in oklch, var(--luzmo-positive-color), black 8%);--luzmo-positive-color-down: color-mix(in oklch, var(--luzmo-positive-color), black 20%);--luzmo-positive-color-focus: color-mix(in oklch, var(--luzmo-positive-color), black 8%);--luzmo-positive-color-rgb: 20, 150, 101;--luzmo-selected-color: rgb(110, 110, 110);--luzmo-selected-color-hover: color-mix(in oklch, var(--luzmo-selected-color), black 25%);--luzmo-selected-color-down: color-mix(in oklch, var(--luzmo-selected-color), black 45%);--luzmo-selected-color-focus: color-mix(in oklch, var(--luzmo-selected-color), black 25%);--luzmo-selected-color-hard: #1e1e1e;--luzmo-selected-color-hard-hover: color-mix(in oklch, var(--luzmo-selected-color-hard), black 25%);--luzmo-selected-color-hard-down: color-mix(in oklch, var(--luzmo-selected-color-hard), black 45%);--luzmo-selected-color-hard-focus: color-mix(in oklch, var(--luzmo-selected-color-hard), black 25%);--luzmo-color-informative: #1a77e9;--luzmo-color-informative-rgb: 26, 119, 233;--luzmo-color-disabled: #aaaaaa;--luzmo-spacing-1: 2px;--luzmo-spacing-2: 4px;--luzmo-spacing-3: 8px;--luzmo-spacing-4: 12px;--luzmo-spacing-5: 16px;--luzmo-indicator-gap: 2px;--luzmo-indicator-width: 1px;--luzmo-indicator-color: var(--luzmo-primary);--luzmo-component-height-xxs: 20px;--luzmo-component-height-xs: 24px;--luzmo-component-height-s: 28px;--luzmo-component-height: 32px;--luzmo-component-height-l: 40px;--luzmo-component-height-xl: 48px;--luzmo-component-height-xxl: 64px;--luzmo-icon-size-xxs: 12px;--luzmo-icon-size-xs: 14px;--luzmo-icon-size-s: 16px;--luzmo-icon-size-m: 18px;--luzmo-icon-size-l: 20px;--luzmo-icon-size-xl: 22px;--luzmo-icon-size-xxl: 32px}", document.head.appendChild(e);
 	}
 })();
-import { t as e } from "../filters-Dj6sRMSR.js";
-export { e as LuzmoFilters };
+import { a as e, i as t, n, o as r, r as i, s as a, t as o } from "../filters-B70hF2NT.js";
+export { e as FilterUnrepresentableError, o as LuzmoFilters, r as MAX_FILTER_NESTING_DEPTH, a as detectFiltersFormat, n as reverseTransformFilters, i as toLogicalCondition, t as transformFilters };

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

@@ -0,0 +1,37 @@
+import type { CleanFilter, CleanFilterClauseGroup, FilterClause, FilterCondition, FilterGroup as EditFilterGroup } from '../types';
+type UnknownRecord = Record<string, unknown>;
+/**
+ * A value that names a column rather than holding a literal. Mirrors the shared
+ * `isFilterColumnParam`: a named source stands on its own, while a bare
+ * `expression` needs a dataset to be a reference rather than a value. A reference
+ * missing its dataset still matches, so that clean emit rejects it instead of
+ * passing the raw canonical object through as a value.
+ */
+export declare function isFilterReference(value: unknown): value is UnknownRecord;
+/**
+ * Clean reference -> canonical `parameters[0]`. `columnId` wins over an ad-hoc
+ * expression, and `columnExpression` becomes the canonical reference `expression`.
+ */
+export declare function cleanReferenceToCanonical(reference: UnknownRecord, allowExpressionAlias?: boolean): UnknownRecord;
+/**
+ * Canonical `parameters[0]` -> clean inlined reference. Nested references inside
+ * `discretization.over` and `aggregation` are converted too, `lowestLevel` and
+ * null-valued optional members are dropped, and a reference that cannot be
+ * expressed publicly throws rather than leaking canonical keys into clean output.
+ */
+export declare function canonicalReferenceToClean(reference: UnknownRecord): UnknownRecord;
+/** Clean leaf -> editor condition, restoring the canonical `parameters` tuple. */
+export declare function cleanLeafToCondition(leaf: UnknownRecord, inheritedClause?: FilterClause): FilterCondition;
+/**
+ * Editor condition -> clean leaf. Returns `null` only for a leaf with no
+ * expression, matching the canonical exporter's drop rule. Anything else that
+ * cannot be expressed cleanly throws, the way the shared normalizer does:
+ * dropping a live predicate would silently widen the rows the host applies.
+ */
+export declare function conditionToCleanLeaf(condition: FilterCondition): CleanFilter | null;
+/**
+ * Editor group -> clean clause groups. A group holding both clauses becomes one
+ * `where` group and one `having` group; neither reuses the original group id.
+ */
+export declare function editGroupToCleanGroups(group: EditFilterGroup): CleanFilterClauseGroup[];
+export {};

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';
 }