@luzmo/analytics-components-kit 1.0.5 → 1.0.7

package/custom-elements.json

@@ -4900,6 +4900,17 @@
               "attribute": "icons",
               "reflects": true
             },
+            {
+              "kind": "field",
+              "name": "levels",
+              "type": {
+                "text": "'on' | 'off'"
+              },
+              "default": "'on'",
+              "description": "Whether datetime and hierarchy columns expand into selectable sublevels. Turn this off in\ncontexts that address the column as a whole, so the column stays selectable by its own id.",
+              "attribute": "levels",
+              "reflects": true
+            },
             {
               "kind": "field",
               "name": "allowEmpty",
@@ -5108,6 +5119,15 @@
               "description": "Where to show icons",
               "fieldName": "icons"
             },
+            {
+              "name": "levels",
+              "type": {
+                "text": "'on' | 'off'"
+              },
+              "default": "'on'",
+              "description": "Whether datetime and hierarchy columns expand into selectable sublevels. Turn this off in\ncontexts that address the column as a whole, so the column stays selectable by its own id.",
+              "fieldName": "levels"
+            },
             {
               "name": "allow-empty",
               "type": {
@@ -7995,6 +8015,20 @@
           "kind": "class",
           "description": "",
           "name": "LuzmoFilterItem",
+          "cssProperties": [
+            {
+              "description": "Gap between the field, expression and value controls of a filter row.",
+              "name": "--luzmo-filter-item-gap"
+            },
+            {
+              "description": "Smallest width the data field select may shrink to in a narrow filter row.",
+              "name": "--luzmo-filter-item-field-min-width"
+            },
+            {
+              "description": "Smallest width of the value and parameter button cell in a narrow filter row.",
+              "name": "--luzmo-filter-item-value-min-width"
+            }
+          ],
           "members": [
             {
               "kind": "field",
@@ -8079,6 +8113,26 @@
               "description": "The filter to display",
               "attribute": "filter"
             },
+            {
+              "kind": "field",
+              "name": "allowParameters",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether parameter-backed filter values can be created and selected.",
+              "attribute": "allow-parameters",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "parameters",
+              "type": {
+                "text": "FilterParameter[]"
+              },
+              "default": "[]",
+              "description": "Consumer-owned parameter definitions available for selection."
+            },
             {
               "kind": "field",
               "name": "language",
@@ -8187,6 +8241,15 @@
               "description": "The filter to display",
               "fieldName": "filter"
             },
+            {
+              "name": "allow-parameters",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether parameter-backed filter values can be created and selected.",
+              "fieldName": "allowParameters"
+            },
             {
               "name": "size",
               "type": {
@@ -8259,190 +8322,463 @@
     },
     {
       "kind": "javascript-module",
-      "path": "src/components/filter-parameter-picker/filter-parameter-picker.ts",
+      "path": "src/components/filter-parameter-picker/filter-parameter-picker.helpers.ts",
       "declarations": [
         {
-          "kind": "class",
-          "description": "",
-          "name": "LuzmoFilterParameterPicker",
-          "members": [
+          "kind": "function",
+          "name": "getSelectableParameterTypes",
+          "return": {
+            "type": {
+              "text": "FilterParameterType[]"
+            }
+          },
+          "parameters": [
             {
-              "kind": "field",
-              "name": "language",
+              "name": "columnType",
               "type": {
-                "text": "string"
-              },
-              "default": "'en'",
-              "description": "The language of the settings interface",
-              "attribute": "language",
-              "reflects": true
+                "text": "ColumnType | undefined"
+              }
             },
             {
-              "kind": "field",
-              "name": "contentLanguage",
+              "name": "expression",
               "type": {
-                "text": "string"
-              },
-              "default": "'en'",
-              "description": "The language to use for locale-aware formatting and labels",
-              "attribute": "content-language",
-              "reflects": true
-            },
+                "text": "ItemQueryFilterExpression | undefined"
+              }
+            }
+          ]
+        },
+        {
+          "kind": "function",
+          "name": "getParameterTypeLabel",
+          "return": {
+            "type": {
+              "text": "string"
+            }
+          },
+          "parameters": [
             {
-              "kind": "field",
-              "name": "_expressionSelected",
+              "name": "type",
               "type": {
-                "text": "any"
+                "text": "FilterParameterType"
               }
             }
-          ],
-          "attributes": [
+          ]
+        },
+        {
+          "kind": "function",
+          "name": "isFilterParameterDefinition",
+          "return": {
+            "type": {
+              "text": "value is ItemFilterParameterDefinition"
+            }
+          },
+          "parameters": [
             {
-              "name": "language",
+              "name": "value",
+              "type": {
+                "text": "unknown"
+              }
+            }
+          ]
+        },
+        {
+          "kind": "function",
+          "name": "normalizeParameterName",
+          "return": {
+            "type": {
+              "text": "string"
+            }
+          },
+          "parameters": [
+            {
+              "name": "name",
               "type": {
                 "text": "string"
-              },
-              "default": "'en'",
-              "description": "The language of the settings interface",
-              "fieldName": "language"
-            },
+              }
+            }
+          ]
+        },
+        {
+          "kind": "function",
+          "name": "createFilterParameter",
+          "return": {
+            "type": {
+              "text": "ItemFilterParameterDefinition"
+            }
+          },
+          "parameters": [
             {
-              "name": "content-language",
+              "name": "name",
               "type": {
                 "text": "string"
-              },
-              "default": "'en'",
-              "description": "The language to use for locale-aware formatting and labels",
-              "fieldName": "contentLanguage"
+              }
             },
             {
-              "name": "size",
+              "name": "type",
               "type": {
-                "text": "'s' | 'm' | 'l' | 'xl'"
-              },
-              "default": "m",
-              "description": "The size of the element",
-              "fieldName": "size"
+                "text": "FilterParameterType"
+              }
             },
             {
-              "name": "disabled",
+              "name": "currentValue",
+              "optional": true,
               "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "description": "Disable this control. It will not receive focus or events",
-              "fieldName": "disabled"
-            },
+                "text": "unknown"
+              }
+            }
+          ]
+        },
+        {
+          "kind": "function",
+          "name": "getDefaultLiteralValue",
+          "return": {
+            "type": {
+              "text": "ItemFilterParameterValue | undefined"
+            }
+          },
+          "parameters": [
             {
-              "name": "autofocus",
+              "name": "columnType",
               "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "description": "When this control is rendered, focus it automatically",
-              "fieldName": "autofocus"
+                "text": "ColumnType | undefined"
+              }
             },
             {
-              "name": "tabIndex",
+              "name": "expression",
               "type": {
-                "text": "number"
-              },
-              "description": "The tab index to apply to this control. See general documentation about the tabindex HTML property",
-              "fieldName": "tabIndex"
+                "text": "ItemQueryFilterExpression | undefined"
+              }
             }
-          ],
-          "tagName": "luzmo-filter-parameter-picker",
-          "customElement": true
+          ]
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "LuzmoFilterParameterPicker",
+          "name": "getSelectableParameterTypes",
           "declaration": {
-            "name": "LuzmoFilterParameterPicker",
-            "module": "src/components/filter-parameter-picker/filter-parameter-picker.ts"
+            "name": "getSelectableParameterTypes",
+            "module": "src/components/filter-parameter-picker/filter-parameter-picker.helpers.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "getParameterTypeLabel",
+          "declaration": {
+            "name": "getParameterTypeLabel",
+            "module": "src/components/filter-parameter-picker/filter-parameter-picker.helpers.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "isFilterParameterDefinition",
+          "declaration": {
+            "name": "isFilterParameterDefinition",
+            "module": "src/components/filter-parameter-picker/filter-parameter-picker.helpers.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "normalizeParameterName",
+          "declaration": {
+            "name": "normalizeParameterName",
+            "module": "src/components/filter-parameter-picker/filter-parameter-picker.helpers.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "createFilterParameter",
+          "declaration": {
+            "name": "createFilterParameter",
+            "module": "src/components/filter-parameter-picker/filter-parameter-picker.helpers.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "getDefaultLiteralValue",
+          "declaration": {
+            "name": "getDefaultLiteralValue",
+            "module": "src/components/filter-parameter-picker/filter-parameter-picker.helpers.ts"
           }
         }
       ]
     },
     {
       "kind": "javascript-module",
-      "path": "src/components/filter-value-picker/filter-value-picker.ts",
+      "path": "src/components/filter-parameter-picker/filter-parameter-picker.ts",
       "declarations": [
         {
           "kind": "class",
           "description": "",
-          "name": "LuzmoFilterValuePicker",
+          "name": "LuzmoFilterParameterPicker",
           "members": [
             {
               "kind": "field",
-              "name": "apiUrl",
+              "name": "parameters",
               "type": {
-                "text": "string | undefined"
+                "text": "ItemFilterParameterDefinition[]"
               },
-              "description": "The API URL of the databroker",
-              "default": "https://api.luzmo.com",
-              "attribute": "api-url",
-              "reflects": true
+              "default": "[]",
+              "description": "Parameter definitions available for selection."
             },
             {
               "kind": "field",
-              "name": "authKey",
+              "name": "allowedTypes",
               "type": {
-                "text": "string | undefined"
+                "text": "FilterParameterType[]"
               },
-              "description": "The auth key of the databroker",
-              "attribute": "auth-key",
-              "reflects": true
+              "default": "[]",
+              "description": "Parameter types compatible with the active field and expression."
             },
             {
               "kind": "field",
-              "name": "authToken",
+              "name": "selectedParameter",
               "type": {
-                "text": "string | undefined"
+                "text": "ItemFilterParameterDefinition | undefined"
               },
-              "description": "The auth token of the databroker",
-              "attribute": "auth-token",
-              "reflects": true
+              "description": "The parameter currently attached to the filter."
             },
             {
               "kind": "field",
-              "name": "cacheTime",
+              "name": "currentValue",
               "type": {
-                "text": "number | undefined"
+                "text": "unknown | undefined"
               },
-              "description": "The cache time of the databroker",
-              "default": "30000",
-              "attribute": "cache-time",
-              "reflects": true
+              "description": "The current literal filter value used as the default for a new parameter."
             },
             {
               "kind": "field",
-              "name": "contentLanguage",
+              "name": "disabled",
               "type": {
-                "text": "string"
+                "text": "boolean"
               },
-              "default": "'en'",
-              "description": "The language to use for locale-aware formatting and labels",
-              "attribute": "content-language",
+              "default": "false",
+              "description": "Whether parameter selection is disabled.",
+              "attribute": "disabled",
               "reflects": true
             },
             {
               "kind": "field",
-              "name": "timeZone",
+              "name": "language",
               "type": {
-                "text": "string | undefined"
+                "text": "string"
               },
-              "description": "The time zone to use for the date picker",
-              "attribute": "time-zone",
-              "reflects": true
-            },
-            {
-              "kind": "field",
-              "name": "valueType",
-              "type": {
-                "text": "'hierarchy' | 'numeric' | 'datetime' | undefined"
+              "default": "'en'",
+              "description": "The language for UI labels.\nSupported values: 'en', 'nl', 'fr', 'de', 'es'",
+              "attribute": "language",
+              "reflects": true,
+              "inheritedFrom": {
+                "name": "LocalizedMixin",
+                "module": "src/utils/base/localized-mixin.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "_syncLocale",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "inheritedFrom": {
+                "name": "LocalizedMixin",
+                "module": "src/utils/base/localized-mixin.ts"
+              }
+            }
+          ],
+          "events": [
+            {
+              "name": "luzmo-parameter-selected",
+              "type": {
+                "text": "CustomEvent<FilterParameterPickerEventDetail>"
+              },
+              "description": "Fired when a parameter is selected."
+            },
+            {
+              "name": "luzmo-parameter-created",
+              "type": {
+                "text": "CustomEvent<FilterParameterPickerEventDetail>"
+              },
+              "description": "Fired when a parameter is created."
+            },
+            {
+              "name": "luzmo-parameter-removed",
+              "type": {
+                "text": "CustomEvent<FilterParameterPickerEventDetail>"
+              },
+              "description": "Fired when a parameter is detached from the filter."
+            }
+          ],
+          "attributes": [
+            {
+              "name": "disabled",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether parameter selection is disabled.",
+              "fieldName": "disabled"
+            },
+            {
+              "name": "size",
+              "type": {
+                "text": "'s' | 'm' | 'l' | 'xl'"
+              },
+              "default": "m",
+              "description": "The size of the element",
+              "fieldName": "size"
+            },
+            {
+              "name": "disabled",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Disable this control. It will not receive focus or events",
+              "fieldName": "disabled"
+            },
+            {
+              "name": "autofocus",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "When this control is rendered, focus it automatically",
+              "fieldName": "autofocus"
+            },
+            {
+              "name": "tabIndex",
+              "type": {
+                "text": "number"
+              },
+              "description": "The tab index to apply to this control. See general documentation about the tabindex HTML property",
+              "fieldName": "tabIndex"
+            },
+            {
+              "name": "language",
+              "type": {
+                "text": "string"
+              },
+              "default": "'en'",
+              "description": "The language for UI labels.\nSupported values: 'en', 'nl', 'fr', 'de', 'es'",
+              "fieldName": "language",
+              "inheritedFrom": {
+                "name": "LocalizedMixin",
+                "module": "src/utils/base/localized-mixin.ts"
+              }
+            }
+          ],
+          "mixins": [
+            {
+              "name": "LocalizedMixin",
+              "module": "/src/utils/base/localized-mixin"
+            }
+          ],
+          "tagName": "luzmo-filter-parameter-picker",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "LuzmoFilterParameterPicker",
+          "declaration": {
+            "name": "LuzmoFilterParameterPicker",
+            "module": "src/components/filter-parameter-picker/filter-parameter-picker.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/components/filter-parameter-picker/types.ts",
+      "declarations": [],
+      "exports": []
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/components/filter-value-picker/filter-value-picker.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "",
+          "name": "LuzmoFilterValuePicker",
+          "cssProperties": [
+            {
+              "description": "Smallest width a value control may shrink to in a narrow filter row.",
+              "name": "--luzmo-filter-value-picker-control-min-width"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "apiUrl",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "The API URL of the databroker",
+              "default": "https://api.luzmo.com",
+              "attribute": "api-url",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "authKey",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "The auth key of the databroker",
+              "attribute": "auth-key",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "authToken",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "The auth token of the databroker",
+              "attribute": "auth-token",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "cacheTime",
+              "type": {
+                "text": "number | undefined"
+              },
+              "description": "The cache time of the databroker",
+              "default": "30000",
+              "attribute": "cache-time",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "contentLanguage",
+              "type": {
+                "text": "string"
+              },
+              "default": "'en'",
+              "description": "The language to use for locale-aware formatting and labels",
+              "attribute": "content-language",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "timeZone",
+              "type": {
+                "text": "string | undefined"
+              },
+              "description": "The time zone to use for the date picker",
+              "attribute": "time-zone",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "valueType",
+              "type": {
+                "text": "'hierarchy' | 'numeric' | 'datetime' | undefined"
               },
               "description": "The type value picker to render",
               "attribute": "value-type",
@@ -8642,6 +8978,16 @@
           "kind": "class",
           "description": "",
           "name": "LuzmoFilterValuePickerDatetime",
+          "cssProperties": [
+            {
+              "description": "Gap between the controls of a relative range value.",
+              "name": "--luzmo-filter-value-picker-datetime-gap"
+            },
+            {
+              "description": "Wrap floor for each control of a relative range before they move onto separate lines.",
+              "name": "--luzmo-filter-value-picker-datetime-control-min-width"
+            }
+          ],
           "members": [
             {
               "kind": "field",
@@ -8852,6 +9198,16 @@
           "kind": "class",
           "description": "",
           "name": "LuzmoFilterValuePickerHierarchy",
+          "cssProperties": [
+            {
+              "description": "Color of the label shown when the stored value is no longer available.",
+              "name": "--luzmo-filter-value-picker-hierarchy-missing-value-color"
+            },
+            {
+              "description": "Smallest width a value control may shrink to in a narrow filter row.",
+              "name": "--luzmo-filter-value-picker-hierarchy-control-min-width"
+            }
+          ],
           "members": [
             {
               "kind": "field",
@@ -9094,6 +9450,12 @@
           "kind": "class",
           "description": "",
           "name": "LuzmoFilterValuePickerNumeric",
+          "cssProperties": [
+            {
+              "description": "Smallest width a value control may shrink to in a narrow filter row.",
+              "name": "--luzmo-filter-value-picker-numeric-control-min-width"
+            }
+          ],
           "members": [
             {
               "kind": "field",
@@ -9413,12 +9775,43 @@
               "kind": "field",
               "name": "filters",
               "type": {
-                "text": "ItemFilterGroup[]"
+                "text": "FiltersInput"
               },
               "default": "[]",
-              "description": "The filter groups to display",
+              "description": "The filter groups to display.\n\nAccepts both halves of the public `ItemFilterOutput` / `DashboardFilterOutput`\nunions: canonical `ItemFilterGroup[]` and clean clause groups with flattened\nleaves. Nested `and` / `or` groups are preserved either way.",
               "attribute": "filters"
             },
+            {
+              "kind": "field",
+              "name": "format",
+              "type": {
+                "text": "FiltersFormat"
+              },
+              "default": "'canonical'",
+              "description": "Output format for the `luzmo-filters-changed` event.\n\n`canonical` emits `ItemFilterGroup[]`; `clean` emits the clean clause groups\nthat aligned hosts consume. A tree that cannot be represented cleanly falls\nback to canonical output, and the event says which format it carries.",
+              "attribute": "format",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "allowParameters",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether parameter-backed filter values can be created and selected.",
+              "attribute": "allow-parameters",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "parameters",
+              "type": {
+                "text": "FilterParameter[]"
+              },
+              "default": "[]",
+              "description": "Consumer-owned parameter definitions available to filter rows."
+            },
             {
               "kind": "field",
               "name": "debounce",
@@ -9466,7 +9859,21 @@
               "type": {
                 "text": "CustomEvent<FiltersChangedEventDetail>"
               },
-              "description": "Announces that the filters have changed"
+              "description": "Announces that the filters have changed, carrying the emitted groups and the format they are in"
+            },
+            {
+              "type": {
+                "text": "CustomEvent<{ parameter: FilterParameter }>"
+              },
+              "description": "Announces that a parameter was created and added to `parameters`.",
+              "name": "luzmo-parameter-created"
+            },
+            {
+              "type": {
+                "text": "CustomEvent<{ parameter: FilterParameter }>"
+              },
+              "description": "Announces that a parameter was detached from a filter.",
+              "name": "luzmo-parameter-removed"
             }
           ],
           "attributes": [
@@ -9531,12 +9938,30 @@
             {
               "name": "filters",
               "type": {
-                "text": "ItemFilterGroup[]"
+                "text": "FiltersInput"
               },
               "default": "[]",
-              "description": "The filter groups to display",
+              "description": "The filter groups to display.\n\nAccepts both halves of the public `ItemFilterOutput` / `DashboardFilterOutput`\nunions: canonical `ItemFilterGroup[]` and clean clause groups with flattened\nleaves. Nested `and` / `or` groups are preserved either way.",
               "fieldName": "filters"
             },
+            {
+              "name": "format",
+              "type": {
+                "text": "FiltersFormat"
+              },
+              "default": "'canonical'",
+              "description": "Output format for the `luzmo-filters-changed` event.\n\n`canonical` emits `ItemFilterGroup[]`; `clean` emits the clean clause groups\nthat aligned hosts consume. A tree that cannot be represented cleanly falls\nback to canonical output, and the event says which format it carries.",
+              "fieldName": "format"
+            },
+            {
+              "name": "allow-parameters",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether parameter-backed filter values can be created and selected.",
+              "fieldName": "allowParameters"
+            },
             {
               "name": "debounce",
               "type": {
@@ -9620,9 +10045,617 @@
       "kind": "javascript-module",
       "path": "src/components/filters/types.ts",
       "declarations": [],
-      "exports": []
-    },
-    {
+      "exports": [
+        {
+          "kind": "js",
+          "name": "CleanFilter",
+          "declaration": {
+            "name": "CleanFilter",
+            "module": "src/components/filters/types.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "CleanFilterClauseGroup",
+          "declaration": {
+            "name": "CleanFilterClauseGroup",
+            "module": "src/components/filters/types.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "CleanFilterGroup",
+          "declaration": {
+            "name": "CleanFilterGroup",
+            "module": "src/components/filters/types.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "CleanRetrievedFilterGroup",
+          "declaration": {
+            "name": "CleanRetrievedFilterGroup",
+            "module": "src/components/filters/types.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "DashboardFilterOutput",
+          "declaration": {
+            "name": "DashboardFilterOutput",
+            "module": "src/components/filters/types.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ItemFilterOutput",
+          "declaration": {
+            "name": "ItemFilterOutput",
+            "module": "src/components/filters/types.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/components/filters/transformations/clean-filters.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "isFilterReference",
+          "return": {
+            "type": {
+              "text": "value is UnknownRecord"
+            }
+          },
+          "parameters": [
+            {
+              "name": "value",
+              "type": {
+                "text": "unknown"
+              }
+            }
+          ],
+          "description": "A value that names a column rather than holding a literal. Mirrors the shared\n`isFilterColumnParam`: a named source stands on its own, while a bare\n`expression` needs a dataset to be a reference rather than a value. A reference\nmissing its dataset still matches, so that clean emit rejects it instead of\npassing the raw canonical object through as a value."
+        },
+        {
+          "kind": "variable",
+          "name": "expression"
+        },
+        {
+          "kind": "function",
+          "name": "cleanReferenceToCanonical",
+          "return": {
+            "type": {
+              "text": "UnknownRecord"
+            }
+          },
+          "parameters": [
+            {
+              "name": "reference",
+              "type": {
+                "text": "UnknownRecord"
+              }
+            },
+            {
+              "name": "allowExpressionAlias",
+              "default": "true"
+            }
+          ],
+          "description": "Clean reference -> canonical `parameters[0]`. `columnId` wins over an ad-hoc\nexpression, and `columnExpression` becomes the canonical reference `expression`."
+        },
+        {
+          "kind": "function",
+          "name": "canonicalReferenceToClean",
+          "return": {
+            "type": {
+              "text": "UnknownRecord"
+            }
+          },
+          "parameters": [
+            {
+              "name": "reference",
+              "type": {
+                "text": "UnknownRecord"
+              }
+            }
+          ],
+          "description": "Canonical `parameters[0]` -> clean inlined reference. Nested references inside\n`discretization.over` and `aggregation` are converted too, `lowestLevel` and\nnull-valued optional members are dropped, and a reference that cannot be\nexpressed publicly throws rather than leaking canonical keys into clean output."
+        },
+        {
+          "kind": "function",
+          "name": "cleanLeafToCondition",
+          "return": {
+            "type": {
+              "text": "FilterCondition"
+            }
+          },
+          "parameters": [
+            {
+              "name": "leaf",
+              "type": {
+                "text": "UnknownRecord"
+              }
+            },
+            {
+              "name": "inheritedClause",
+              "optional": true,
+              "type": {
+                "text": "FilterClause"
+              }
+            }
+          ],
+          "description": "Clean leaf -> editor condition, restoring the canonical `parameters` tuple."
+        },
+        {
+          "kind": "variable",
+          "name": "parameters",
+          "type": {
+            "text": "unknown[]"
+          },
+          "default": "[cleanReferenceToCanonical(leaf, false)]"
+        },
+        {
+          "kind": "function",
+          "name": "conditionToCleanLeaf",
+          "return": {
+            "type": {
+              "text": "CleanFilter | null"
+            }
+          },
+          "parameters": [
+            {
+              "name": "condition",
+              "type": {
+                "text": "FilterCondition"
+              }
+            }
+          ],
+          "description": "Editor condition -> clean leaf. Returns `null` only for a leaf with no\nexpression, matching the canonical exporter's drop rule. Anything else that\ncannot be expressed cleanly throws, the way the shared normalizer does:\ndropping a live predicate would silently widen the rows the host applies."
+        },
+        {
+          "kind": "variable",
+          "name": "filters",
+          "type": {
+            "text": "unknown[]"
+          },
+          "default": "[]"
+        },
+        {
+          "kind": "function",
+          "name": "editGroupToCleanGroups",
+          "return": {
+            "type": {
+              "text": "CleanFilterClauseGroup[]"
+            }
+          },
+          "parameters": [
+            {
+              "name": "group",
+              "type": {
+                "text": "EditFilterGroup"
+              }
+            }
+          ],
+          "description": "Editor group -> clean clause groups. A group holding both clauses becomes one\n`where` group and one `having` group; neither reuses the original group id."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "isFilterReference",
+          "declaration": {
+            "name": "isFilterReference",
+            "module": "src/components/filters/transformations/clean-filters.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "cleanReferenceToCanonical",
+          "declaration": {
+            "name": "cleanReferenceToCanonical",
+            "module": "src/components/filters/transformations/clean-filters.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "canonicalReferenceToClean",
+          "declaration": {
+            "name": "canonicalReferenceToClean",
+            "module": "src/components/filters/transformations/clean-filters.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "cleanLeafToCondition",
+          "declaration": {
+            "name": "cleanLeafToCondition",
+            "module": "src/components/filters/transformations/clean-filters.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "conditionToCleanLeaf",
+          "declaration": {
+            "name": "conditionToCleanLeaf",
+            "module": "src/components/filters/transformations/clean-filters.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "editGroupToCleanGroups",
+          "declaration": {
+            "name": "editGroupToCleanGroups",
+            "module": "src/components/filters/transformations/clean-filters.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/components/filters/transformations/filter-format.ts",
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "MAX_FILTER_NESTING_DEPTH",
+          "type": {
+            "text": "number"
+          },
+          "default": "20",
+          "description": "Shared nesting limit, matching the platform-wide filter depth guard."
+        },
+        {
+          "kind": "class",
+          "description": "Raised when a filter tree cannot be represented in the requested encoding.",
+          "name": "FilterUnrepresentableError",
+          "members": [
+            {
+              "kind": "field",
+              "name": "name",
+              "type": {
+                "text": "string"
+              },
+              "default": "'FilterUnrepresentableError'"
+            }
+          ],
+          "superclass": {
+            "name": "Error",
+            "module": "src/components/filters/transformations/filter-format.ts"
+          }
+        },
+        {
+          "kind": "function",
+          "name": "isRecord",
+          "return": {
+            "type": {
+              "text": "value is Record<string, unknown>"
+            }
+          },
+          "parameters": [
+            {
+              "name": "value",
+              "type": {
+                "text": "unknown"
+              }
+            }
+          ]
+        },
+        {
+          "kind": "function",
+          "name": "isFilterGroupLike",
+          "return": {
+            "type": {
+              "text": "value is Record<string, unknown>"
+            }
+          },
+          "parameters": [
+            {
+              "name": "value",
+              "type": {
+                "text": "unknown"
+              }
+            }
+          ],
+          "description": "A group in either encoding, including a leftover uppercase condition. A group\nmay omit `condition` entirely, which `toLogicalCondition` resolves to `and`;\na condition that is present but not `and` / `or` is not a group."
+        },
+        {
+          "kind": "function",
+          "name": "isFilterLeafLike",
+          "return": {
+            "type": {
+              "text": "value is Record<string, unknown>"
+            }
+          },
+          "parameters": [
+            {
+              "name": "value",
+              "type": {
+                "text": "unknown"
+              }
+            }
+          ],
+          "description": "A leaf in either encoding. Groups are excluded by their `condition`."
+        },
+        {
+          "kind": "function",
+          "name": "hasCleanEncodingMarker",
+          "return": {
+            "type": {
+              "text": "boolean"
+            }
+          },
+          "parameters": [
+            {
+              "name": "leaf",
+              "type": {
+                "text": "Record<string, unknown>"
+              }
+            }
+          ]
+        },
+        {
+          "kind": "function",
+          "name": "hasExactlyOneReferenceSource",
+          "return": {
+            "type": {
+              "text": "boolean"
+            }
+          },
+          "parameters": [
+            {
+              "name": "reference",
+              "type": {
+                "text": "Record<string, unknown>"
+              }
+            },
+            {
+              "name": "allowExpressionAlias",
+              "default": "false"
+            }
+          ],
+          "description": "Clean references name exactly one source. `columnExpression` is an alias that\nloses to `columnId` rather than competing with it, so the two together are one\nsource; `columnId` with `formulaId` is genuinely ambiguous and is rejected.\n\n`allowExpressionAlias` covers a standalone reference object, where a bare\n`expression` is the ad-hoc column. On a flattened leaf `expression` is the\nfilter operator instead, so callers there must leave it off."
+        },
+        {
+          "kind": "function",
+          "name": "isCleanFilterLeaf",
+          "return": {
+            "type": {
+              "text": "value is Record<string, unknown>"
+            }
+          },
+          "parameters": [
+            {
+              "name": "value",
+              "type": {
+                "text": "unknown"
+              }
+            }
+          ],
+          "description": "A flattened leaf: a dataset, exactly one reference source, and no `parameters`."
+        },
+        {
+          "kind": "function",
+          "name": "isCanonicalFilterLeaf",
+          "return": {
+            "type": {
+              "text": "value is Record<string, unknown>"
+            }
+          },
+          "parameters": [
+            {
+              "name": "value",
+              "type": {
+                "text": "unknown"
+              }
+            }
+          ],
+          "description": "A canonical leaf: an ordered `parameters` tuple and no clean inline key."
+        },
+        {
+          "kind": "function",
+          "name": "assertLeafEncodingNotMixed",
+          "return": {
+            "type": {
+              "text": "void"
+            }
+          },
+          "parameters": [
+            {
+              "name": "leaf",
+              "type": {
+                "text": "Record<string, unknown>"
+              }
+            }
+          ],
+          "description": "A leaf carrying both encodings is ambiguous about which operand is the\npredicate, so it is rejected rather than guessed."
+        },
+        {
+          "kind": "function",
+          "name": "assertCleanLeafIsComplete",
+          "return": {
+            "type": {
+              "text": "void"
+            }
+          },
+          "parameters": [
+            {
+              "name": "leaf",
+              "type": {
+                "text": "Record<string, unknown>"
+              }
+            }
+          ],
+          "description": "A leaf that is clean-encoded but not a valid clean leaf. Called only once\n`isCleanFilterLeaf` has rejected it, so that an incomplete reference is\nreported rather than silently reinterpreted as an empty canonical leaf."
+        },
+        {
+          "kind": "function",
+          "name": "isFilterClause",
+          "return": {
+            "type": {
+              "text": "value is 'where' | 'having'"
+            }
+          },
+          "parameters": [
+            {
+              "name": "value",
+              "type": {
+                "text": "unknown"
+              }
+            }
+          ]
+        },
+        {
+          "kind": "function",
+          "name": "assertFilterNestingDepth",
+          "return": {
+            "type": {
+              "text": "void"
+            }
+          },
+          "parameters": [
+            {
+              "name": "depth",
+              "type": {
+                "text": "number"
+              }
+            }
+          ]
+        },
+        {
+          "kind": "function",
+          "name": "detectFiltersFormat",
+          "return": {
+            "type": {
+              "text": "DetectedFiltersFormat"
+            }
+          },
+          "parameters": [
+            {
+              "name": "input",
+              "type": {
+                "text": "unknown"
+              }
+            }
+          ],
+          "description": "Classifies a filter payload for diagnostics. Never throws."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "MAX_FILTER_NESTING_DEPTH",
+          "declaration": {
+            "name": "MAX_FILTER_NESTING_DEPTH",
+            "module": "src/components/filters/transformations/filter-format.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "FilterUnrepresentableError",
+          "declaration": {
+            "name": "FilterUnrepresentableError",
+            "module": "src/components/filters/transformations/filter-format.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "isRecord",
+          "declaration": {
+            "name": "isRecord",
+            "module": "src/components/filters/transformations/filter-format.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "isFilterGroupLike",
+          "declaration": {
+            "name": "isFilterGroupLike",
+            "module": "src/components/filters/transformations/filter-format.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "isFilterLeafLike",
+          "declaration": {
+            "name": "isFilterLeafLike",
+            "module": "src/components/filters/transformations/filter-format.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "hasCleanEncodingMarker",
+          "declaration": {
+            "name": "hasCleanEncodingMarker",
+            "module": "src/components/filters/transformations/filter-format.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "hasExactlyOneReferenceSource",
+          "declaration": {
+            "name": "hasExactlyOneReferenceSource",
+            "module": "src/components/filters/transformations/filter-format.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "isCleanFilterLeaf",
+          "declaration": {
+            "name": "isCleanFilterLeaf",
+            "module": "src/components/filters/transformations/filter-format.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "isCanonicalFilterLeaf",
+          "declaration": {
+            "name": "isCanonicalFilterLeaf",
+            "module": "src/components/filters/transformations/filter-format.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "assertLeafEncodingNotMixed",
+          "declaration": {
+            "name": "assertLeafEncodingNotMixed",
+            "module": "src/components/filters/transformations/filter-format.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "assertCleanLeafIsComplete",
+          "declaration": {
+            "name": "assertCleanLeafIsComplete",
+            "module": "src/components/filters/transformations/filter-format.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "isFilterClause",
+          "declaration": {
+            "name": "isFilterClause",
+            "module": "src/components/filters/transformations/filter-format.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "assertFilterNestingDepth",
+          "declaration": {
+            "name": "assertFilterNestingDepth",
+            "module": "src/components/filters/transformations/filter-format.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "detectFiltersFormat",
+          "declaration": {
+            "name": "detectFiltersFormat",
+            "module": "src/components/filters/transformations/filter-format.ts"
+          }
+        }
+      ]
+    },
+    {
       "kind": "javascript-module",
       "path": "src/components/filters/transformations/transform-filters.ts",
       "declarations": [
@@ -9644,6 +10677,14 @@
           ],
           "description": "Normalize a group condition to the lowercase `'and' | 'or'` contract.\nAccepts legacy uppercase `'AND' | 'OR'` values."
         },
+        {
+          "kind": "variable",
+          "name": "subGroups",
+          "type": {
+            "text": "ItemFilterGroup[]"
+          },
+          "default": "[]"
+        },
         {
           "kind": "function",
           "name": "transformFilters",
@@ -9659,9 +10700,115 @@
                 "text": "EditFilterGroup | null | undefined"
               },
               "description": "Filter group in the internal/legacy filters format"
+            },
+            {
+              "description": "`format: 'clean'` opts into clean clause-group output",
+              "name": "options"
             }
           ],
-          "description": "Transform EditFilterGroup from filters component into the format\nexpected by luzmo-embed-viz-item (ItemFilterGroup[])."
+          "description": "Transform EditFilterGroup from filters component into the format\nexpected by luzmo-embed-viz-item (ItemFilterGroup[]), or into the clean\nclause groups published as `ItemFilterOutput` / `DashboardFilterOutput`."
+        },
+        {
+          "kind": "function",
+          "name": "transformFilters",
+          "return": {
+            "type": {
+              "text": "CleanFilterClauseGroup[]"
+            }
+          },
+          "parameters": [
+            {
+              "name": "filters",
+              "type": {
+                "text": "EditFilterGroup | null | undefined"
+              }
+            },
+            {
+              "name": "options",
+              "type": {
+                "text": "{ format: 'clean' }"
+              }
+            }
+          ]
+        },
+        {
+          "kind": "function",
+          "name": "transformFilters",
+          "return": {
+            "type": {
+              "text": "ItemFilterGroup[]"
+            }
+          },
+          "parameters": [
+            {
+              "name": "filters",
+              "type": {
+                "text": "EditFilterGroup | null | undefined"
+              }
+            },
+            {
+              "name": "options",
+              "type": {
+                "text": "{ format?: 'canonical' }"
+              }
+            }
+          ]
+        },
+        {
+          "kind": "function",
+          "name": "transformFilters",
+          "return": {
+            "type": {
+              "text": "FiltersOutput"
+            }
+          },
+          "parameters": [
+            {
+              "name": "filters",
+              "type": {
+                "text": "EditFilterGroup | null | undefined"
+              }
+            },
+            {
+              "name": "options",
+              "optional": true,
+              "type": {
+                "text": "TransformFiltersOptions"
+              }
+            }
+          ]
+        },
+        {
+          "kind": "function",
+          "name": "transformFilters",
+          "return": {
+            "type": {
+              "text": "FiltersOutput"
+            }
+          },
+          "parameters": [
+            {
+              "name": "filters",
+              "type": {
+                "text": "EditFilterGroup | null | undefined"
+              }
+            },
+            {
+              "name": "options",
+              "optional": true,
+              "type": {
+                "text": "TransformFiltersOptions"
+              }
+            }
+          ]
+        },
+        {
+          "kind": "variable",
+          "name": "filters",
+          "type": {
+            "text": "(FilterCondition | EditFilterGroup)[]"
+          },
+          "default": "[]"
         },
         {
           "kind": "function",
@@ -9675,21 +10822,45 @@
             {
               "name": "filters",
               "type": {
-                "text": "ItemFilterGroup[] | null | undefined"
+                "text": "FiltersInput | null | undefined"
               },
               "description": "Filter groups from viz-item filters property or getFilters()"
             }
           ],
-          "description": "Transform filter groups from luzmo-embed-viz-item format into the format\nused internally by luzmo-filters."
+          "description": "Transform filter groups from luzmo-embed-viz-item format into the format\nused internally by luzmo-filters.\n\nAccepts both halves of the public `ItemFilterOutput` / `DashboardFilterOutput`\nunions: canonical `ItemFilterGroup[]` and clean clause groups with flattened\nleaves. Nested `and` / `or` groups are preserved, never flattened."
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "VizItemFilterGroup",
+          "name": "detectFiltersFormat",
+          "declaration": {
+            "name": "detectFiltersFormat",
+            "module": "./filter-format"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "FilterUnrepresentableError",
+          "declaration": {
+            "name": "FilterUnrepresentableError",
+            "module": "./filter-format"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "MAX_FILTER_NESTING_DEPTH",
+          "declaration": {
+            "name": "MAX_FILTER_NESTING_DEPTH",
+            "module": "./filter-format"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "DetectedFiltersFormat",
           "declaration": {
-            "name": "ItemFilterGroup",
-            "package": "@luzmo/dashboard-contents-types"
+            "name": "DetectedFiltersFormat",
+            "module": "./filter-format"
           }
         },
         {
@@ -9708,6 +10879,38 @@
             "module": "src/components/filters/transformations/transform-filters.ts"
           }
         },
+        {
+          "kind": "js",
+          "name": "transformFilters",
+          "declaration": {
+            "name": "transformFilters",
+            "module": "src/components/filters/transformations/transform-filters.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "transformFilters",
+          "declaration": {
+            "name": "transformFilters",
+            "module": "src/components/filters/transformations/transform-filters.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "transformFilters",
+          "declaration": {
+            "name": "transformFilters",
+            "module": "src/components/filters/transformations/transform-filters.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "transformFilters",
+          "declaration": {
+            "name": "transformFilters",
+            "module": "src/components/filters/transformations/transform-filters.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "reverseTransformFilters",