@conduction/nextcloud-vue 2.62.0 → 2.64.0

package/src/schemas/app-manifest-v2.schema.json

@@ -3,7 +3,7 @@
 	"$id": "https://raw.githubusercontent.com/ConductionNL/nextcloud-vue/main/src/schemas/app-manifest-v2.schema.json",
 	"title": "Conduction App Manifest v2",
 	"description": "v2 schema for the JSON-driven page and navigation manifest consumed by @conduction/nextcloud-vue. Introduces a uniform widgets[] array on every page type with a per-slot grid coordinate system, a typed actions[] discriminator, and the required $schema field for version detection. v1 manifests continue to validate against app-manifest.schema.json (unchanged).",
-	"version": "2.43.0",
+	"version": "2.46.0",
 	"type": "object",
 	"required": ["$schema", "version"],
 	"allOf": [
@@ -97,6 +97,8 @@
 							"suggestFrom": { "type": "string", "description": "choice: the configKey of an earlier choice this step pre-fills a suggestion from. When that value is set and the user has not yet picked here, the option matching suggestMap[parentValue] is auto-selected (still user-overridable)." },
 							"suggestMap": { "type": "object", "description": "choice: map of suggestFrom value → suggested option value. Used to auto-suggest a default (e.g. RGS template suggested from organisation type).", "additionalProperties": { "type": "string" } },
 							"multiple": { "type": "boolean", "default": false, "description": "choice: allow multi-select." },
+							"loadAction": { "type": "string", "minLength": 1, "description": "choice with display cards: an actionId each option card loads itself with. Every card except the one whose value is `none` gets its own Load button, which POSTs { dataset: <value> } to /api/setup/action/{loadAction}, spins while it runs and shows the result on that card. A successful load also selects the card. With loadAction the separate run-action step that loaded the picked dataset is no longer needed; manifests that keep it still work." },
+							"requires": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true, "description": "App ids this step needs. When any of them is not installed and enabled, the wizard skips the step and the summary shows it as skipped, naming the missing apps. Do not combine with required: true; setup status would keep reporting the skipped step as unmet." },
 							"action": { "type": "string", "description": "run-action: actionId POSTed to /api/setup/action/{action}." },
 							"onDemand": { "type": "boolean", "default": false, "description": "run-action: the step runs only when the user clicks Run, never automatically, and is never outstanding work (it does not open the wizard or decide where a resumed wizard starts). The summary ticks it only when its action succeeded in the current session and shows it as not run otherwise, whatever the server reports. For destructive steps an app reports as done on purpose so they never auto-run, such as removing example data." },
 							"healthCheck": { "type": "boolean", "default": false, "description": "summary: render a health recap." },
@@ -236,6 +238,40 @@
 					"type": "string",
 					"description": "Override label for the settings foldout's gear button. Defaults to 'Settings'."
 				},
+				"card": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["title"],
+					"description": "A card above the footer entries, rendered by CnAppNav (zuiddrecht-pixel-gaps): a title, a line of text and one link. Title, text and link label are i18n keys. Omitted, nothing renders there.",
+					"properties": {
+						"title": { "type": "string", "minLength": 1 },
+						"text": { "type": "string" },
+						"link": {
+							"type": "object",
+							"additionalProperties": false,
+							"required": ["label"],
+							"description": "The card's link: a `route` (named page, optional `params`) is a router link, an `href` a plain anchor, an `action` id a button that emits `card-action`.",
+							"properties": {
+								"label": { "type": "string", "minLength": 1 },
+								"route": { "type": "string" },
+								"params": { "type": "object", "additionalProperties": true },
+								"href": { "type": "string" },
+								"action": { "type": "string" }
+							}
+						}
+					}
+				},
+				"help": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["label"],
+					"description": "A help entry with a help icon in the navigation footer, above the settings foldout (zuiddrecht-pixel-gaps): `route` (named page) or `href` (opens in a new tab).",
+					"properties": {
+						"label": { "type": "string", "minLength": 1 },
+						"route": { "type": "string" },
+						"href": { "type": "string" }
+					}
+				},
 				"primaryAction": {
 					"$ref": "#/$defs/primaryAction",
 					"description": "App-wide default primary action rendered as an NcAppNavigationNew button above the main menu list. A page-scoped pages[].primaryAction for the current route wins over this default."
@@ -249,6 +285,10 @@
 							"type": "string",
 							"description": "URL of the logo image. Decorative when `name` is set."
 						},
+						"emblem": {
+							"type": ["string", "boolean"],
+							"description": "An emblem drawn in place of the logo (zuiddrecht-pixel-gaps): the municipality's mark beside the app name, distinct from the wordmark in the top bar. A URL, or `true` to draw the theme's emblem from the `--nldesign-emblem-url` custom property. Decorative when `name` is set."
+						},
 						"name": {
 							"type": "string",
 							"description": "i18n key / text for the app or organisation name."
@@ -1156,6 +1196,23 @@
 				},
 				"payload": {
 					"description": "Free-form payload echoed back to the host inside the @primary-action-click event."
+				},
+				"action": {
+					"$ref": "#/$defs/action",
+					"description": "A page action to run on click (zuiddrecht-pixel-gaps): CnAppNav then renders the button through CnActionButtons, so `type: \"open-form\"` (with `register` + `schema`) opens the create dialog without a create page, `navigate` pushes a route, `api-call` calls an endpoint. Drawn as one solid full-width primary button. `route` / `href` on the primary action itself are ignored while `action` is set."
+				},
+				"solid": {
+					"type": "boolean",
+					"default": false,
+					"description": "Draw the primary action as a solid, full-width primary button whatever its form (zuiddrecht-pixel-gaps). Default: a link action is already a primary button; a plain one is NcAppNavigationNew."
+				},
+				"permission": {
+					"type": "string",
+					"description": "Permission the reader must hold for the action to render, checked like `menuItem.permission` (zuiddrecht-pixel-gaps)."
+				},
+				"visibleIf": {
+					"$ref": "#/$defs/visibleIfCondition",
+					"description": "Display condition evaluated at render time, like `menuItem.visibleIf` (zuiddrecht-pixel-gaps). A gated-out page-scoped action falls back to `nav.primaryAction`."
 				}
 			}
 		},
@@ -1173,6 +1230,11 @@
 					"type": "string",
 					"description": "i18n translation key resolved by the consuming app's t() function at render time."
 				},
+				"translateLabel": {
+					"type": "boolean",
+					"default": true,
+					"description": "Whether CnAppNav runs `label` through the translate function. Set false for a user-authored title (e.g. a catalog name) that must render as written even when it equals a translation key such as 'Search'. Rendered as text either way, never as HTML."
+				},
 				"icon": {
 					"type": "string",
 					"description": "CSS class for the icon (e.g. 'icon-checkmark') or MDI component name."
@@ -1186,6 +1248,11 @@
 					"additionalProperties": { "type": ["string", "number", "boolean"] },
 					"description": "Optional vue-router query parameters merged into the target route link (e.g. a filter like { caseType: '<uuid>' }). Deep-links a nav entry to a pre-filtered index page."
 				},
+				"params": {
+					"type": "object",
+					"additionalProperties": { "type": ["string", "number"], "minLength": 1 },
+					"description": "Optional vue-router route params for a parameterised route (e.g. { catalogSlug: 'news' } for a page at '/catalogs/:catalogSlug'). String values must be non-empty. CnAppNav links to { name: route, params, query }. The entry is active only while every declared param equals the current route's param (compared as strings), so sibling entries on one route that differ in params are never marked together. On pages whose path sits below its page path with these params filled in, it is active too: by the same params check when those routes carry the same param names, otherwise as the one entry marked below its route."
+				},
 				"order": {
 					"type": "integer",
 					"description": "Display order in the menu. Items without an order render last."
@@ -1209,9 +1276,20 @@
 				"count": {
 					"oneOf": [
 						{ "type": "integer", "minimum": 0 },
-						{ "type": "string", "enum": ["auto"] }
+						{ "type": "string", "enum": ["auto"] },
+						{
+							"type": "object",
+							"additionalProperties": false,
+							"required": ["register", "schema"],
+							"description": "A FILTERED count (zuiddrecht-pixel-gaps): the total of this register and schema with `filter` applied (filter-value tokens such as `@me` and `@today` resolve at fetch time), fetched by CnAppRoot under the entry's own key so an index page's whole-schema total is untouched. Renders \"My work 6\" beside \"All cases 48\".",
+							"properties": {
+								"register": { "type": "string", "minLength": 1 },
+								"schema": { "type": "string", "minLength": 1 },
+								"filter": { "type": "object", "additionalProperties": true }
+							}
+						}
 					],
-					"description": "Counter badge in the entry's #counter slot. Positive integer renders as-is; 'auto' resolves from cnMenuCounts (populated by CnAppRoot from useObjectStore totals) for the entry's resolved index-type page (register + schema)."
+					"description": "Counter badge in the entry's #counter slot. Positive integer renders as-is; 'auto' resolves from cnMenuCounts (populated by CnAppRoot from useObjectStore totals) for the entry's resolved index-type page (register + schema); an object `{ register, schema, filter? }` is the total of that filtered list."
 				},
 				"pinned": {
 					"type": "boolean",
@@ -1259,6 +1337,11 @@
 			"properties": {
 				"id": { "type": "string" },
 				"label": { "type": "string" },
+				"translateLabel": {
+					"type": "boolean",
+					"default": true,
+					"description": "Same as menuItem.translateLabel: false renders `label` as written instead of translating it."
+				},
 				"icon": { "type": "string" },
 				"route": { "type": "string" },
 				"query": {
@@ -1266,6 +1349,11 @@
 					"additionalProperties": { "type": ["string", "number", "boolean"] },
 					"description": "Optional vue-router query parameters merged into the target route link (e.g. a filter like { caseType: '<uuid>' }). Deep-links a nav entry to a pre-filtered index page."
 				},
+				"params": {
+					"type": "object",
+					"additionalProperties": { "type": ["string", "number"], "minLength": 1 },
+					"description": "Optional vue-router route params for a parameterised route; string values must be non-empty. Same contract as menuItem.params: part of the link, and the entry is active only while every declared param equals the current route's param."
+				},
 				"order": { "type": "integer" },
 				"permission": { "type": "string" },
 				"section": {
@@ -1463,6 +1551,19 @@
 					"minimum": 1,
 					"description": "Row span (>= 1)."
 				},
+				"headerLink": {
+					"type": "object",
+					"additionalProperties": false,
+					"required": ["label"],
+					"description": "One text link in the widget header's actions group, before the overflow menu (zuiddrecht-pixel-gaps): \"All deadlines\", \"To the board\". A `route` (named page, optional `params` / `query`) is a router link, an `href` a plain anchor. The label is an i18n key. Rendered by CnWidgetWrapper; CnDashboardPage reads it off the layout entry or the widget definition.",
+					"properties": {
+						"label": { "type": "string", "minLength": 1 },
+						"route": { "type": "string" },
+						"params": { "type": "object", "additionalProperties": true },
+						"query": { "type": "object", "additionalProperties": true },
+						"href": { "type": "string" }
+					}
+				},
 				"sizeToContent": {
 					"type": ["boolean", "integer"],
 					"minimum": 1,
@@ -3497,6 +3598,37 @@
 							"type": "string",
 							"description": "type='index': accessible name and tooltip for the split pane's close button. Defaults to \"Close\". Maps to CnIndexPage `splitCloseLabel`."
 						},
+						"showHeader": {
+							"type": "boolean",
+							"default": true,
+							"description": "type='dashboard': `false` drops the header row (title, description, header actions, edit toggle) for a page that opens with its own heading, such as a greeting widget; the title stays as a visually hidden heading (zuiddrecht-pixel-gaps). Maps to CnDashboardPage `showHeader`."
+						},
+						"showTitle": {
+							"type": "boolean",
+							"default": false,
+							"description": "type='index': show the page header (icon, title, description) inline. Default false: the title renders visually hidden and the sidebar names the page. Maps to CnIndexPage `showTitle`."
+						},
+						"countSubtitle": {
+							"type": "string",
+							"description": "type='index': an i18n key for the description line with `{total}` replaced by the collection's total, e.g. \"{total} open cases\" (zuiddrecht-pixel-gaps). Shown in place of `description` once a total is known. Maps to CnIndexPage `countSubtitle`."
+						},
+						"showTypeEyebrow": {
+							"type": "boolean",
+							"default": true,
+							"description": "type='detail': `false` drops the type eyebrow (the type label above the record name) once the record resolves, for a header that says the type in a pill instead (zuiddrecht-pixel-gaps). Maps to CnDetailPage `showTypeEyebrow`."
+						},
+						"breadcrumb": {
+							"type": "object",
+							"additionalProperties": false,
+							"required": ["label"],
+							"description": "type='detail': a breadcrumb line above the header (zuiddrecht-pixel-gaps): this crumb names the list the record belongs to (`route` + optional `params`, or `href`), the record's display name follows as the current crumb. Maps to CnDetailPage `breadcrumb`.",
+							"properties": {
+								"label": { "type": "string", "minLength": 1 },
+								"route": { "type": "string" },
+								"params": { "type": "object", "additionalProperties": true },
+								"href": { "type": "string" }
+							}
+						},
 						"mapConfig": {
 							"type": "object",
 							"additionalProperties": true,

package/src/store/useObjectStore.js

@@ -5,6 +5,7 @@ import { genericError, networkError, parseResponseError } from '../utils/errors.
 import { normalizeFacets } from '../utils/facets.js'
 import { buildHeaders, buildQueryString, capitalize, prefixUrl } from '../utils/headers.js'
 import { extractId } from '../utils/id.js'
+import { dispatchObjectCreated } from '../utils/walkthroughSignals.js'
 import { mergePluginActions, mergePluginGetters, mergePluginState } from './pluginMerge.js'
 import { liveUpdatesPlugin } from './plugins/liveUpdates.js'
 
@@ -830,6 +831,13 @@ const baseActions = {
 				[type]: { ...(this.objects[type] || {}), [savedId]: data },
 			}
 
+			// Every create through the store lets an `advanceOn:
+			// object-created` walkthrough step advance, whichever form made it.
+			if (!isUpdate) {
+				const config = this.objectTypeRegistry[type] || {}
+				dispatchObjectCreated({ register: config.registerSlug || config.register, schema: config.schemaSlug || config.schema, object: data })
+			}
+
 			return data
 		} catch (error) {
 			this.errors = {

package/src/utils/columnFilters.js

@@ -0,0 +1,324 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ * SPDX-License-Identifier: EUPL-1.2
+ */
+
+/**
+ * Per-column sorting and filtering for table headers.
+ *
+ * Pure helpers: which column can sort, which can filter and how, and the
+ * translation between a header filter's state and the OpenRegister query
+ * parameters the facet sidebar already sends. A header filter writes into the
+ * SAME active-filter map (`{ paramKey: values[] }`) the sidebar uses, so the
+ * fetch, the route query and saved views need nothing new.
+ *
+ * Parameter shapes, as OpenRegister reads them:
+ * - equality and "any of": `key=value`, `key[]=a&key[]=b`
+ * - ranges: `key[gte]=from`, `key[lte]=to`
+ *
+ * @module utils/columnFilters
+ * @spec openspec/changes/table-header-sort-and-filter/specs/cn-data-table/spec.md
+ */
+
+import { schemaRefSlug } from './schemaRefSlug.js'
+
+/** Column keys that mark a value computed on the client, never stored. */
+const COMPUTED_MARKERS = ['aggregate', 'compute', 'computed', 'virtual']
+
+/**
+ * Normalise a `$ref` to the referenced schema slug, or null.
+ *
+ * @param {unknown} ref A `$ref` value.
+ * @return {string|number|null} The slug.
+ */
+function refSlug(ref) {
+	if (typeof ref === 'number' && !Number.isNaN(ref)) {
+		return ref
+	}
+	if (typeof ref !== 'string' || ref === '') {
+		return null
+	}
+	const tail = ref.includes('/') ? ref.substring(ref.lastIndexOf('/') + 1) : ref
+	const slug = tail === '' ? '' : schemaRefSlug(tail)
+	return slug !== '' ? slug : null
+}
+
+/**
+ * The schema property behind a column, or null when the column has none.
+ *
+ * @param {object} column The column definition.
+ * @param {object|null} schema The table's schema.
+ * @return {object|null} The property.
+ */
+export function columnProperty(column, schema) {
+	if (!column || !schema || !schema.properties || typeof column.key !== 'string') {
+		return null
+	}
+	const prop = schema.properties[column.key]
+	return (prop && typeof prop === 'object') ? prop : null
+}
+
+/**
+ * Whether a column computes its value on the client, so the server cannot
+ * sort or filter on it.
+ *
+ * @param {object} column The column definition.
+ * @return {boolean} True for a computed column.
+ */
+function isComputedColumn(column) {
+	return COMPUTED_MARKERS.some((marker) => column[marker] !== undefined && column[marker] !== null && column[marker] !== false)
+}
+
+/**
+ * Whether a column header sorts.
+ *
+ * `sortable: false` always wins, and so does an explicit `sortable: true`.
+ * Otherwise, with a schema, a column sorts when a stored schema property backs
+ * it: OpenRegister orders on schema properties, so a widget or computed column
+ * with no property behind it stays unsortable. Without a schema nothing says
+ * the server can sort, so only an explicit flag makes the column sortable,
+ * which is how such tables behaved before.
+ *
+ * @param {object} column The column definition.
+ * @param {object|null} schema The table's schema.
+ * @return {boolean} True when the header sorts.
+ * @spec openspec/changes/table-header-sort-and-filter/specs/cn-data-table/spec.md#requirement-every-backed-column-sorts-by-default
+ */
+export function isColumnSortable(column, schema) {
+	if (!column || typeof column !== 'object') {
+		return false
+	}
+	if (column.sortable === false) {
+		return false
+	}
+	if (column.sortable === true) {
+		return true
+	}
+	if (!schema || isComputedColumn(column)) {
+		return false
+	}
+	const prop = columnProperty(column, schema)
+	return !!prop && prop.type !== 'object'
+}
+
+/**
+ * Display options for an enum filter: schema `enum` (or `items.enum`) with
+ * `x-enum-labels`, else a column `enum` hint, else a badge column's colour
+ * map keys.
+ *
+ * @param {object} column The column definition.
+ * @param {object|null} prop The schema property.
+ * @return {Array<{value: string, label: string}>} The options, or [].
+ */
+function enumOptions(column, prop) {
+	const p = prop || {}
+	const labels = p.enumLabels || p['x-enum-labels'] || (p.items && (p.items.enumLabels || p.items['x-enum-labels'])) || {}
+	let values = null
+	if (Array.isArray(p.enum) && p.enum.length > 0) {
+		values = p.enum
+	} else if (p.items && Array.isArray(p.items.enum) && p.items.enum.length > 0) {
+		values = p.items.enum
+	} else if (Array.isArray(column.enum) && column.enum.length > 0) {
+		values = column.enum
+	} else if (column.widget === 'badge' && column.widgetProps && column.widgetProps.colorMap) {
+		values = Object.keys(column.widgetProps.colorMap)
+	}
+	if (!values) {
+		return []
+	}
+	return values
+		.filter((v) => v !== null && v !== undefined && v !== '')
+		.map((v) => ({ value: String(v), label: String(labels[v] !== undefined ? labels[v] : v) }))
+}
+
+/**
+ * The reference a column points at, for a searchable object filter: a schema
+ * `$ref` (or `items.$ref`), else an `fkResolve` cell widget's config.
+ *
+ * @param {object} column The column definition.
+ * @param {object|null} prop The schema property.
+ * @return {{schema: (string|number), register: string, labelField: string}|null} The reference.
+ */
+function referenceTarget(column, prop) {
+	const widgetProps = (column.widget === 'fkResolve' && column.widgetProps) || null
+	const p = prop || {}
+	const schemaRef = refSlug(p.$ref) ?? (p.items ? refSlug(p.items.$ref) : null)
+	const schema = schemaRef ?? (widgetProps && widgetProps.schema ? widgetProps.schema : null)
+	if (schema === null || schema === undefined || schema === '') {
+		return null
+	}
+	const register = (widgetProps && widgetProps.register)
+		|| p['x-external-register']
+		|| (p.items && p.items['x-external-register'])
+		|| ''
+	const labelField = (widgetProps && widgetProps.labelField) || ''
+	return { schema, register, labelField }
+}
+
+/**
+ * How a column filters, or null when it does not.
+ *
+ * Kinds: `enum` (checkbox list), `boolean` (yes, no, any), `reference`
+ * (searchable list of the referenced objects), `number` and `date` (from and
+ * to), and `string` (equals). `filterable: false` on the column turns it
+ * off. A column with no schema property behind it only filters when it
+ * carries an enum hint (`enum`, or a badge widget's colour map), because the
+ * server cannot filter on a value it does not store.
+ *
+ * @param {object} column The column definition.
+ * @param {object|null} schema The table's schema.
+ * @return {{key: string, kind: string, label: string, options: Array<{value: string, label: string}>, reference: object|null, dateTime: boolean}|null} The filter definition.
+ * @spec openspec/changes/table-header-sort-and-filter/specs/cn-data-table/spec.md#requirement-every-backed-column-filters-from-its-header
+ */
+export function columnFilterDef(column, schema) {
+	if (!column || typeof column !== 'object' || typeof column.key !== 'string' || column.key === '') {
+		return null
+	}
+	if (column.filterable === false || isComputedColumn(column)) {
+		return null
+	}
+	const prop = columnProperty(column, schema)
+	const base = { key: column.key, label: column.label || (prop && prop.title) || column.key, options: [], reference: null, dateTime: false }
+
+	const options = enumOptions(column, prop)
+	if (options.length > 0) {
+		return { ...base, kind: 'enum', options }
+	}
+	if (!prop) {
+		return null
+	}
+	const reference = referenceTarget(column, prop)
+	if (reference) {
+		return { ...base, kind: 'reference', reference }
+	}
+	const type = Array.isArray(prop.type) ? prop.type.find((t) => t !== 'null') : prop.type
+	const format = prop.format || ''
+	if (type === 'boolean') {
+		return { ...base, kind: 'boolean' }
+	}
+	if (type === 'number' || type === 'integer') {
+		return { ...base, kind: 'number' }
+	}
+	if (type === 'string' && (format === 'date' || format === 'date-time')) {
+		return { ...base, kind: 'date', dateTime: format === 'date-time' }
+	}
+	if (type === 'string') {
+		return { ...base, kind: 'string' }
+	}
+	return null
+}
+
+/**
+ * Read one active-filter entry as a list of strings.
+ *
+ * @param {unknown} raw An active-filter value: an array, a scalar, or absent.
+ * @return {Array<string>} The values.
+ */
+function asList(raw) {
+	if (raw === undefined || raw === null || raw === '') {
+		return []
+	}
+	return (Array.isArray(raw) ? raw : [raw]).filter((v) => v !== undefined && v !== null && v !== '').map((v) => String(v))
+}
+
+/**
+ * The parameter keys one column filter owns.
+ *
+ * @param {object} def A filter definition from `columnFilterDef`.
+ * @return {Array<string>} The keys.
+ */
+export function columnFilterParamKeys(def) {
+	if (!def) {
+		return []
+	}
+	if (def.kind === 'number' || def.kind === 'date') {
+		return [`${def.key}[gte]`, `${def.key}[lte]`]
+	}
+	return [def.key]
+}
+
+/**
+ * A column filter's current state, read from the active-filter map.
+ *
+ * @param {object} def A filter definition.
+ * @param {object} activeFilters The active-filter map (`{ paramKey: values }`).
+ * @return {object} `{ values }` for enum and reference, `{ value }` for boolean and string, `{ from, to }` for number and date.
+ */
+export function columnFilterState(def, activeFilters) {
+	const filters = (activeFilters && typeof activeFilters === 'object') ? activeFilters : {}
+	if (!def) {
+		return {}
+	}
+	if (def.kind === 'enum' || def.kind === 'reference') {
+		return { values: asList(filters[def.key]) }
+	}
+	if (def.kind === 'number' || def.kind === 'date') {
+		const from = asList(filters[`${def.key}[gte]`])[0] || ''
+		const to = asList(filters[`${def.key}[lte]`])[0] || ''
+		// A date-time column is queried up to the end of the day; the input
+		// shows the date the person picked.
+		return {
+			from: def.kind === 'date' ? from.slice(0, 10) : from,
+			to: def.kind === 'date' ? to.slice(0, 10) : to,
+		}
+	}
+	return { value: asList(filters[def.key])[0] || '' }
+}
+
+/**
+ * Whether a column filter is active.
+ *
+ * @param {object} def A filter definition.
+ * @param {object} activeFilters The active-filter map.
+ * @return {boolean} True when any of its parameters is set.
+ */
+export function isColumnFilterActive(def, activeFilters) {
+	const filters = (activeFilters && typeof activeFilters === 'object') ? activeFilters : {}
+	return columnFilterParamKeys(def).some((key) => asList(filters[key]).length > 0)
+}
+
+/**
+ * The active-filter entries a column filter state produces. Every key the
+ * column owns is present; an empty list clears that key, so changing a range
+ * from "from and to" to "from" drops the old upper bound.
+ *
+ * @param {object} def A filter definition.
+ * @param {object} state The column filter state (see `columnFilterState`).
+ * @return {object} `{ paramKey: values[] }`.
+ * @spec openspec/changes/table-header-sort-and-filter/specs/cn-data-table/spec.md#requirement-a-header-filter-speaks-the-sidebars-query-language
+ */
+export function columnFilterParams(def, state) {
+	const s = state || {}
+	if (!def) {
+		return {}
+	}
+	if (def.kind === 'enum' || def.kind === 'reference') {
+		return { [def.key]: asList(s.values) }
+	}
+	if (def.kind === 'number' || def.kind === 'date') {
+		const from = s.from === undefined || s.from === null ? '' : String(s.from).trim()
+		let to = s.to === undefined || s.to === null ? '' : String(s.to).trim()
+		if (def.kind === 'date' && def.dateTime && to !== '' && to.length === 10) {
+			to = `${to}T23:59:59`
+		}
+		return {
+			[`${def.key}[gte]`]: from === '' ? [] : [from],
+			[`${def.key}[lte]`]: to === '' ? [] : [to],
+		}
+	}
+	if (def.kind === 'boolean') {
+		return { [def.key]: (s.value === 'true' || s.value === 'false') ? [s.value] : [] }
+	}
+	const value = s.value === undefined || s.value === null ? '' : String(s.value).trim()
+	return { [def.key]: value === '' ? [] : [value] }
+}
+
+/**
+ * Clear-all entries for one column: every key it owns, emptied.
+ *
+ * @param {object} def A filter definition.
+ * @return {object} `{ paramKey: [] }`.
+ */
+export function clearedColumnFilterParams(def) {
+	return Object.fromEntries(columnFilterParamKeys(def).map((key) => [key, []]))
+}