@conduction/nextcloud-vue 2.82.0 → 2.84.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.92.0",
+	"version": "2.96.0",
 	"type": "object",
 	"required": ["$schema", "version"],
 	"allOf": [
@@ -150,6 +150,7 @@
 							"title": { "type": "string", "description": "i18n key / text for the tour name (restart menu)." },
 							"trigger": { "type": "string", "enum": ["first-visit", "version-bump", "empty-index", "manual"], "default": "manual", "description": "When the tour auto-starts." },
 							"minAppVersion": { "type": "string", "description": "Semver; the tour is inert below this app version." },
+							"startOn": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "uniqueItems": true, "description": "Route names the tour may auto-start on. A user who first lands anywhere else, such as on a case opened from a link, does not get the tour there: it waits until they reach one of these routes. Without it a tour whose first step is centered starts wherever the user lands. Has no effect on a tour started by hand." },
 							"steps": {
 								"type": "array",
 								"description": "Ordered steps.",
@@ -808,6 +809,11 @@
 			"pattern": "^@row\\.[A-Za-z][A-Za-z0-9_.@]*$",
 			"description": "Row context: a field of the row a row action runs on (@row.<field>, dot path allowed), read by the field-list widget's rowActions request url and payload (payload values resolve at any depth). Mirrors SENTINEL_TOKEN_PATTERNS.row."
 		},
+		"sentinelContextToken": {
+			"type": "string",
+			"pattern": "^@context\\.[A-Za-z][A-Za-z0-9_.]*$",
+			"description": "Detail context: a record a detail page reads beside the loaded one (`config.visibilityContext`), read by a grid widget's or a tab's `visibleWhen` field as @context.<name>.<field> (dot path allowed). Mirrors SENTINEL_TOKEN_PATTERNS.context."
+		},
 		"sentinelSubjectToken": {
 			"type": "string",
 			"pattern": "^@subject\\.[A-Za-z][A-Za-z0-9_.]*$",
@@ -826,6 +832,7 @@
 				{ "$ref": "#/$defs/sentinelAnswerToken" },
 				{ "$ref": "#/$defs/sentinelRowToken" },
 				{ "$ref": "#/$defs/sentinelSubjectToken" },
+				{ "$ref": "#/$defs/sentinelContextToken" },
 				{ "$ref": "#/$defs/sentinelDeprecatedToken" }
 			]
 		},
@@ -4297,7 +4304,7 @@
 						},
 						"headerButtons": {
 							"type": "array",
-							"description": "type='index': buttons beside the page title, as the board's \"Export\" and \"New case\" (zuiddrecht-pixel-gaps-3). `action` is `add` (the Add flow; the label defaults to the Add label), `export` (the export leaf in `format`, else the export dialog; under the board look it reads \"Download\" by default), `actions-menu` (the page's header actions as one labelled menu button, absent when the page has none), `import`, `refresh`, or the id of a `headerActions` entry. Under the board look the buttons render in a fixed order whatever the manifest declares: export, actions-menu, other secondary buttons, the buildiq square, then the primary button. Shown only with `showTitle`; when they show, the actions bar drops its Views and Actions menus, and the Add button and Export menu when a button takes their action. Maps to CnIndexPage `headerButtons`.",
+							"description": "type='index': buttons beside the page title, as the board's \"Export\" and \"New case\" (zuiddrecht-pixel-gaps-3). `action` is `add` (the Add flow; the label defaults to the Add label), `export` (the export leaf in `format`, else the export dialog; under the board look it reads \"Download\" by default), `actions-menu` (the page's header actions as one labelled menu button, absent when the page has none), `import`, `refresh`, or the id of a `headerActions` entry. Under the board look the buttons render in a fixed order whatever the manifest declares: export, actions-menu, other secondary buttons, the buildiq square, then the primary button. Shown only with `showTitle`; when they show, the actions bar drops its Views and Actions menus, and the Add button and Export menu when a button takes their action. Maps to CnIndexPage `headerButtons`. type='reports' (screens-reports-header-buttons, 2.96.0): the same buttons beside the reports page title, as board DcRapportages draws \"Downloaden\". There `label` is required and `action` is the id of a `headerActions` entry (same shape as on an index page), which says what the click does; every click also emits `header-action`. Under the board look the buildiq square sits between the secondary buttons and the primary one. Maps to CnReportsPage `headerButtons`.",
 							"items": {
 								"type": "object",
 								"additionalProperties": false,
@@ -4309,7 +4316,7 @@
 									"variant": { "type": "string", "enum": ["primary", "secondary"], "default": "secondary" },
 									"icon": { "type": "string", "minLength": 1, "description": "MDI icon name." },
 									"format": { "type": "string", "enum": ["csv", "excel"], "default": "csv", "description": "For `export`." },
-									"items": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 }, "description": "For `actions-menu`: the menu's entries, in order. Each is `header-actions` (every header action), the id of one `headerActions` entry, or a built-in of the actions bar's own menu, which the bar drops while header buttons show: `import`, `export`, `refresh`, `copy-selected`, `delete-selected` (disabled until a row is selected) or `documentation` (a link to the page's documentationUrl, left out without one). An unknown name is left out. Absent: the header actions only (screens-index-header-actions-menu, 2.90.0)." }
+									"items": { "type": "array", "minItems": 1, "items": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "object", "additionalProperties": false, "required": ["heading"], "properties": { "heading": { "type": "string", "minLength": 1, "description": "i18n key of a group heading." } } } ] }, "description": "For `actions-menu`: the menu's entries, in order. Each is `header-actions` (every header action), the id of one `headerActions` entry, or a built-in of the actions bar's own menu, which the bar drops while header buttons show: `import`, `export`, `refresh`, `copy-selected`, `delete-selected` (disabled until a row is selected) or `documentation` (a link to the page's documentationUrl, left out without one). An unknown name is left out. Absent: the header actions only (screens-index-header-actions-menu, 2.90.0). Entries can be grouped: `{ \"heading\": \"<i18n key>\" }` draws a group heading and `\"separator\"` a rule, each only when an entry follows it, so a group whose entries are all left out leaves no empty heading (screens-index-header-menu-headings, 2.93.0)." }
 								}
 							}
 						},
@@ -4349,6 +4356,20 @@
 							"minLength": 1,
 							"description": "type='detail': the id of a widget in `widgets` to render inside the header on its own row under the title, without a card of its own, e.g. the stages bars (zuiddrecht-pixel-gaps-2). The widget leaves the body grid. Maps to CnDetailPage `headerWidget`."
 						},
+						"visibilityContext": {
+							"type": "object",
+							"description": "type='detail': records the page reads beside the loaded one, so a widget's or a tab's `visibleWhen` can ask about them (detail-widgets-visible-when). `{ <name>: { field, register, schema } }`: `field` is the property of the loaded record holding the other record's id, and a condition reads that record as `@context.<name>.<path>`, e.g. `{ \"field\": \"@context.caseType.category\", \"op\": \"in\", \"value\": [\"Sociaal domein\"] }`. A record that cannot be read is absent, so its condition fails safe. Maps to CnDetailPage `visibilityContext`.",
+							"additionalProperties": {
+								"type": "object",
+								"required": ["field", "register", "schema"],
+								"additionalProperties": false,
+								"properties": {
+									"field": { "type": "string", "minLength": 1, "description": "Dot-path on the loaded record to the id of the record to read." },
+									"register": { "type": "string", "minLength": 1, "description": "Register slug or id of the record to read." },
+									"schema": { "type": "string", "minLength": 1, "description": "Schema slug or id of the record to read." }
+								}
+							}
+						},
 						"mapConfig": {
 							"type": "object",
 							"additionalProperties": true,

package/src/utils/buildManifest.js

@@ -195,6 +195,7 @@ export function applyMenuRelocations(menu, relocations) {
 	if (!relocations || typeof relocations !== 'object') {
 		return menu
 	}
+	const heldEntries = captionsHoldingEntries(menu)
 	for (let pass = 0; pass < 5; pass++) {
 		const moves = []
 		for (let i = menu.length - 1; i >= 0; i--) {
@@ -240,9 +241,42 @@ export function applyMenuRelocations(menu, relocations) {
 			}
 		})
 	}
-	// Drop empty group shells left behind by relocations.
-	return menu.filter((m) => m.route || m.href || m.action
+	// Drop empty group shells left behind by relocations. A caption (a
+	// section heading) has no route and no children and is kept, unless the
+	// relocations emptied it: every entry under it moved away.
+	const kept = menu.filter((m) => m.type === 'caption' || m.route || m.href || m.action
 		|| (Array.isArray(m.children) && m.children.length > 0))
+	const holdingNow = captionsHoldingEntries(kept)
+	return kept.filter((m) => m.type !== 'caption' || !heldEntries.has(m) || holdingNow.has(m))
+}
+
+/**
+ * The captions (`type: "caption"`) that have at least one entry under them:
+ * a non-caption entry of the same section before the next caption.
+ *
+ * @param {Array<object>} menu The top-level menu.
+ * @return {Set<object>} The captions holding an entry.
+ */
+function captionsHoldingEntries(menu) {
+	const holding = new Set()
+	menu.forEach((entry, index) => {
+		if (entry.type !== 'caption') {
+			return
+		}
+		const section = entry.section ?? 'main'
+		for (let i = index + 1; i < menu.length; i++) {
+			const next = menu[i]
+			if ((next.section ?? 'main') !== section) {
+				continue
+			}
+			if (next.type === 'caption') {
+				break
+			}
+			holding.add(entry)
+			break
+		}
+	})
+	return holding
 }
 
 /**

package/src/utils/detailWidgetVisibility.js

@@ -0,0 +1,145 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ * SPDX-License-Identifier: EUPL-1.2
+ *
+ * detailWidgetVisibility: whether a widget on a detail page shows for the
+ * loaded record, through the shared `visibleWhen` grammar.
+ *
+ * A detail page can name records it reads beside the loaded one
+ * (`visibilityContext`, e.g. a case's case type). A condition reads such a
+ * record as `@context.<name>.<path>`, so a widget can be shown for some case types
+ * only while the configuration stays in the app manifest.
+ *
+ * @module utils/detailWidgetVisibility
+ */
+
+import { cnFetchJson } from './cnFetch.js'
+import { evaluateVisibleWhenLocal, isLocallyDecidableVisibleWhen, isWorkspaceCondition } from './visibleWhen.js'
+
+/**
+ * Read a reference value as an id: a plain string or number, or an object
+ * carrying `id`, `uuid` or `@self.id` (an extended reference).
+ *
+ * @param {unknown} value The value of the reference field.
+ * @return {string} The id, or '' when there is none.
+ */
+function referenceId(value) {
+	if (typeof value === 'string' || typeof value === 'number') {
+		return String(value)
+	}
+	if (value && typeof value === 'object') {
+		const id = value.id ?? value.uuid ?? (value['@self'] && value['@self'].id)
+		return id === undefined || id === null ? '' : String(id)
+	}
+	return ''
+}
+
+/**
+ * The records a `visibilityContext` names for one loaded record.
+ *
+ * @param {object} context `{ <name>: { field, register, schema } }`.
+ * @param {object|null} record The loaded record.
+ * @return {Array<{key: string, register: string, schema: string, id: string}>} One entry per usable name; `id` is '' when the record holds no reference.
+ * @spec openspec/changes/detail-widgets-visible-when/specs/detail-widgets-visible-when/spec.md#requirement-a-detail-page-can-load-records-a-condition-names
+ */
+export function visibilityContextRefs(context, record) {
+	if (!context || typeof context !== 'object' || !record || typeof record !== 'object') {
+		return []
+	}
+	return Object.entries(context)
+		.filter(([name, ref]) => name !== '' && ref && typeof ref === 'object'
+			&& typeof ref.field === 'string' && ref.field !== ''
+			&& typeof ref.register === 'string' && ref.register !== ''
+			&& typeof ref.schema === 'string' && ref.schema !== '')
+		.map(([name, ref]) => ({
+			key: name,
+			register: ref.register,
+			schema: ref.schema,
+			id: referenceId(ref.field.split('.').reduce((obj, part) => (obj === null || obj === undefined ? obj : obj[part]), record)),
+		}))
+}
+
+/**
+ * Read the records `refs` names. A reference without an id, and a read that
+ * fails, resolve `null`: the record is absent, and a condition on it fails
+ * safe rather than throwing out of the page.
+ *
+ * @param {Array<{key: string, register: string, schema: string, id: string}>} refs From {@link visibilityContextRefs}.
+ * @param {Map<string, object|null>} [cache] Rows already read, by `register/schema/id`.
+ * @return {Promise<object>} `{ <name>: row | null }`.
+ * @spec openspec/changes/detail-widgets-visible-when/specs/detail-widgets-visible-when/spec.md#requirement-a-detail-page-can-load-records-a-condition-names
+ */
+export async function fetchVisibilityRows(refs, cache) {
+	const rows = {}
+	await Promise.all((refs || []).map(async (ref) => {
+		if (!ref.id) {
+			rows[ref.key] = null
+			return
+		}
+		const cacheKey = `${ref.register}/${ref.schema}/${ref.id}`
+		if (cache && cache.has(cacheKey)) {
+			rows[ref.key] = cache.get(cacheKey)
+			return
+		}
+		let row
+		try {
+			const body = await cnFetchJson(`/apps/openregister/api/objects/${encodeURIComponent(ref.register)}/${encodeURIComponent(ref.schema)}/${encodeURIComponent(ref.id)}`)
+			row = body && typeof body === 'object' ? body : null
+		} catch {
+			row = null
+		}
+		if (cache) {
+			cache.set(cacheKey, row)
+		}
+		rows[ref.key] = row
+	}))
+	return rows
+}
+
+/**
+ * The data a widget condition reads: the record, with the named records
+ * beside it under `@context.<name>`. Null while the record has not loaded.
+ *
+ * @param {object|null} record The loaded record.
+ * @param {object} [rows] `{ <name>: row | null }`.
+ * @return {object|null} The condition data.
+ * @spec openspec/changes/detail-widgets-visible-when/specs/detail-widgets-visible-when/spec.md#requirement-a-detail-grid-widget-shows-only-while-its-visiblewhen-holds-for-the-record
+ */
+export function widgetConditionData(record, rows) {
+	if (!record || typeof record !== 'object') {
+		return null
+	}
+	return { ...record, '@context': { ...(rows || {}) } }
+}
+
+/**
+ * Whether a widget's own `visibleWhen` lets it show on a detail page.
+ *
+ * No condition: shown, as before. A workspace condition: shown, a detail page
+ * has no workspace. While the data is not there (`data` null, or `pending`):
+ * hidden, so the widget never shows and then vanishes. A local condition is
+ * decided here; an endpoint or source condition takes its answer from
+ * `answers` (by widget id) and is hidden until it has one.
+ *
+ * @param {object|null} widget The widget definition.
+ * @param {object|null} data From {@link widgetConditionData}.
+ * @param {{pending?: boolean, answers?: object}} [state] Whether named records are still on their way, and the remote answers.
+ * @return {boolean} Whether the widget shows.
+ * @spec openspec/changes/detail-widgets-visible-when/specs/detail-widgets-visible-when/spec.md#requirement-a-detail-grid-widget-shows-only-while-its-visiblewhen-holds-for-the-record
+ */
+export function detailWidgetVisible(widget, data, state = {}) {
+	const cond = widget && typeof widget === 'object' ? widget.visibleWhen : null
+	if (cond === null || cond === undefined) {
+		return true
+	}
+	if (typeof cond === 'object' && !Array.isArray(cond) && isWorkspaceCondition(cond)) {
+		return true
+	}
+	if (!data || state.pending === true) {
+		return false
+	}
+	if (isLocallyDecidableVisibleWhen(cond)) {
+		return evaluateVisibleWhenLocal(cond, data)
+	}
+	return Boolean(state.answers && state.answers[widget.id] === true)
+}

package/src/utils/fetchAggregate.js

@@ -37,11 +37,34 @@ export function flattenAggFilter(target, filter, ctx) {
 				target[`filter[${k}][${op}]`] = ov
 			}
 		} else if (v !== '' && v !== null && v !== undefined) {
-			target[`filter[${k}]`] = v
+			target[aggFilterParam(k)] = v
 		}
 	}
 }
 
+/**
+ * Matches a filter key that spells its operator, `field[op]`.
+ *
+ * @type {RegExp}
+ */
+const OPERATOR_KEY = /^(.+)\[([A-Za-z_]+)\]$/
+
+/**
+ * The query parameter of one plain filter key. A key that spells its operator
+ * (`scheduledDate[gte]`, the flat form a list page and a lens use) goes out as
+ * `filter[scheduledDate][gte]`, the form the aggregation endpoint reads, and
+ * not as `filter[scheduledDate[gte]]`, a field it does not have, which counted
+ * 0. Any other key goes out as `filter[key]`.
+ *
+ * @spec openspec/changes/screens-stats-block-operator-keys/specs/stats-block/spec.md#requirement-a-stats-block-filter-can-spell-its-operator-in-the-key
+ * @param {string} key The filter key.
+ * @return {string} The query parameter name.
+ */
+export function aggFilterParam(key) {
+	const match = OPERATOR_KEY.exec(key)
+	return match ? `filter[${match[1]}][${match[2]}]` : `filter[${key}]`
+}
+
 /**
  * Fetch one aggregated scalar from OpenRegister.
  *

package/src/utils/formatMetric.js

@@ -226,6 +226,35 @@ export function metricLocale() {
 	}
 }
 
+/**
+ * A format spec with its literal `prefix` / `suffix` run through the host
+ * translate function. A `@`-token, an empty string, or a missing translate
+ * leaves the affix as written.
+ *
+ * @param {object} format The `content.format` spec.
+ * @param {((text: string) => string)|null} translate The host translate function.
+ * @return {object} A copy of the spec (the same object when nothing changes).
+ * @spec openspec/changes/screens-metric-affix-translate/specs/dashboard-page/spec.md#requirement-a-metric-prefix-and-suffix-are-translated
+ */
+export function translateMetricAffixes(format, translate) {
+	const fmt = format || {}
+	if (typeof translate !== 'function') {
+		return fmt
+	}
+	let out = fmt
+	for (const key of ['prefix', 'suffix']) {
+		const text = fmt[key]
+		if (typeof text === 'string' && text.trim() !== '' && text.charAt(0) !== '@') {
+			const translated = translate(text)
+			if (typeof translated === 'string' && translated !== text) {
+				out = out === fmt ? { ...fmt } : out
+				out[key] = translated
+			}
+		}
+	}
+	return out
+}
+
 /**
  * Format a numeric value per a manifest `content.format` spec.
  *
@@ -250,11 +279,18 @@ export function metricLocale() {
  * @param {unknown}      value     The raw value to format.
  * @param {object} format    The `content.format` spec (`{ style, currency, currencyField, decimals, prefix, suffix }`).
  * @param {object} configCtx The page-level app-config map for `@config.<key>` resolution.
+ * A literal `prefix` / `suffix` (one that is not a `@config.` or `@object.`
+ * token) is run through `translate` when one is given, as every other
+ * manifest-authored string is, so an app's catalogue entry for " days"
+ * (" dagen") applies. A token is resolved, never translated.
+ *
  * @param {object|null} [object] The detail page's object, for `currencyField` and `@object.<field>`.
+ * @param {((text: string) => string)|null} [translate] The host app's translate function (`cnTranslate`).
  * @return {string} The formatted display string.
  * @spec openspec/changes/stat-currency-from-object/specs/dashboard-page/spec.md#requirement-a-money-value-is-shown-in-the-currency-the-entry-names
+ * @spec openspec/changes/screens-metric-affix-translate/specs/dashboard-page/spec.md#requirement-a-metric-prefix-and-suffix-are-translated
  */
-export function formatMetricValue(value, format, configCtx, object = null) {
+export function formatMetricValue(value, format, configCtx, object = null, translate = null) {
 	if (value === null || value === undefined) {
 		return '—'
 	}
@@ -263,7 +299,7 @@ export function formatMetricValue(value, format, configCtx, object = null) {
 		return String(value)
 	}
 
-	const fmt = resolveConfigFormat(format, configCtx, object)
+	const fmt = resolveConfigFormat(translateMetricAffixes(format, translate), configCtx, object)
 	const locale = metricLocale()
 	// `duration-hours` and `decimal` default to ONE fraction digit; the
 	// other styles keep the pre-existing default of 0.

package/src/utils/resolveManifestTokens.js

@@ -56,6 +56,7 @@ export const SENTINEL_RESOLVERS = Object.freeze({
 	answer: 'resolveAssignValue (utils/formAssign.js)',
 	row: 'CnFieldListWidget (rowActions request)',
 	subject: 'CnBannerWidget (action route)',
+	context: 'detailWidgetVisible (utils/detailWidgetVisibility.js)',
 })
 
 /**

package/src/utils/sentinelTokens.js

@@ -89,6 +89,9 @@ export const SENTINEL_TOKEN_PATTERNS = Object.freeze({
 	// A field of the record a start-here attention card names (`@subject.<field>`, dot path),
 	// read by the banner widget's action routes.
 	subject: '^@subject\\.[A-Za-z][A-Za-z0-9_.]*$',
+	// A record a detail page reads beside the loaded one (`visibilityContext`), read by a
+	// grid widget's or a tab's `visibleWhen` as `@context.<name>.<field>` (dot path).
+	context: '^@context\\.[A-Za-z][A-Za-z0-9_.]*$',
 	// Deprecated-but-not-yet-removed tokens. Kept in the schema union so
 	// deployed manifests still validate during the migration window; the gate
 	// downgrades them to a WARN (see SENTINEL_DEPRECATIONS).
@@ -112,6 +115,7 @@ export const SENTINEL_CONTEXTS = Object.freeze([
 	'answer',
 	'row',
 	'subject',
+	'context',
 ])
 
 /**
@@ -172,6 +176,11 @@ export const SENTINEL_VOCABULARY = Object.freeze({
 		description: 'A field of the record an attention card names (the first row of its ordered `visibleWhen` source query), read when the card builds an action\'s route. Dot paths are allowed (`@subject.owner.id`).',
 		members: ['@subject.<field>'],
 	},
+	context: {
+		resolver: 'CnDetailPage visibilityContext (detailWidgetVisibility), read by a grid widget\'s or a tab\'s visibleWhen',
+		description: 'A record the detail page reads beside the loaded one, named in `config.visibilityContext` (a case\'s case type). A `visibleWhen` field reads it as `@context.<name>.<field>`, dot paths allowed (`@context.caseType.category`).',
+		members: ['@context.<name>.<field>'],
+	},
 })
 
 /**

package/src/utils/switchValues.js

@@ -0,0 +1,59 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Conduction B.V.
+ * SPDX-License-Identifier: EUPL-1.2
+ *
+ * A switch's value map: what a switch reads as "on" and what it writes for on
+ * and off. Without a map a switch is a boolean, as before. With `values:
+ * { on, off }` it reads a field stored as `"1"`/`"0"` or `"true"`/`"false"`
+ * (an app config flag) and writes those values back.
+ *
+ * @module utils/switchValues
+ * @spec openspec/changes/screens-switch-value-map/specs/switch-rows/spec.md#requirement-a-switch-can-read-and-write-a-value-map
+ */
+
+/**
+ * The value map of a switch, or null when it has none (a boolean switch).
+ *
+ * @param {unknown} values The declared `values`.
+ * @return {{on: unknown, off: unknown}|null} The map.
+ */
+export function switchValueMap(values) {
+	if (!values || typeof values !== 'object' || Array.isArray(values) || values.on === undefined) {
+		return null
+	}
+	return { on: values.on, off: values.off === undefined ? null : values.off }
+}
+
+/**
+ * Whether a stored value reads as "on". Without a map only `true` does; with
+ * one, the `on` value does, compared as text so `1` and `"1"` are the same.
+ *
+ * @param {unknown} stored The stored value.
+ * @param {unknown} values The declared `values`.
+ * @return {boolean} True when the switch shows on.
+ */
+export function switchIsOn(stored, values) {
+	const map = switchValueMap(values)
+	if (!map) {
+		return stored === true
+	}
+	if (stored === undefined || stored === null) {
+		return false
+	}
+	return stored === map.on || String(stored) === String(map.on)
+}
+
+/**
+ * The value a switch writes for a state.
+ *
+ * @param {boolean} on The switch state.
+ * @param {unknown} values The declared `values`.
+ * @return {unknown} `true`/`false` without a map, else the map's `on` / `off`.
+ */
+export function switchStoredValue(on, values) {
+	const map = switchValueMap(values)
+	if (!map) {
+		return on === true
+	}
+	return on ? map.on : map.off
+}