@conduction/nextcloud-vue 1.0.0-beta.20 → 1.0.0-beta.22

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@conduction/nextcloud-vue",
-	"version": "1.0.0-beta.20",
+	"version": "1.0.0-beta.22",
 	"description": "Shared Vue component library for Conduction Nextcloud apps — complements @nextcloud/vue with higher-level components, OpenRegister integration, and NL Design System support",
 	"license": "EUPL-1.2",
 	"author": "Conduction B.V. <info@conduction.nl>",

package/src/components/CnSettingsPage/CnSettingsPage.vue

@@ -1,8 +1,12 @@
 <!--
   CnSettingsPage — Admin / config surface.
 
-  Renders manifest-driven config sections. Each section in
-  `config.sections[]` is a CnSettingsCard wrapping a CnSettingsSection.
+  Renders manifest-driven config sections. The page MAY declare
+  EITHER a flat `sections[]` array (back-compat) OR a `tabs[]` array
+  (each tab owns its own `sections[]`) — XOR, never both. See
+  manifest-settings-orchestration spec.
+
+  Each section is a CnSettingsCard wrapping a CnSettingsSection.
   A section MUST declare exactly one of three body kinds:
 
     1. `fields[]`   — flat form fields (back-compat, default)
@@ -12,6 +16,8 @@
   Built-in widget types (resolved BEFORE the customComponents registry):
     - `version-info`     → CnVersionInfoCard
     - `register-mapping` → CnRegisterMapping
+    - `component`        → discriminator; `widget.componentName`
+                           resolves against customComponents
 
   Saves via `axios.put(saveEndpoint, formData)` with the consumer's
   settings controller URL. Widget events bubble up through
@@ -44,10 +50,33 @@
 			<slot name="actions" />
 		</div>
 
-		<!-- Sections -->
+		<!-- Tab strip — only rendered when `tabs[]` is set
+			 (manifest-settings-orchestration REQ-MSO-5). Built with
+			 native <button role="tab"> + ARIA wiring; uses Nextcloud
+			 CSS variables only (no hex literals). -->
+		<div
+			v-if="hasTabs"
+			class="cn-settings-page__tabs"
+			role="tablist">
+			<button
+				v-for="(tab, tabIndex) in tabs"
+				:key="`tab-${tab.id}`"
+				role="tab"
+				type="button"
+				class="cn-settings-page__tab"
+				:class="{ 'cn-settings-page__tab--active': activeTabId === tab.id }"
+				:aria-selected="activeTabId === tab.id ? 'true' : 'false'"
+				:aria-controls="`cn-settings-tab-panel-${tab.id}`"
+				@click="onTabClick(tab, tabIndex)">
+				{{ resolveLabel(tab.label) }}
+			</button>
+		</div>
+
+		<!-- Sections — rendered for the active tab when `tabs[]` is
+			 set, otherwise the flat `sections[]` (back-compat). -->
 		<CnSettingsCard
-			v-for="(section, sectionIndex) in sections"
-			:key="`section-${sectionIndex}`"
+			v-for="(section, sectionIndex) in activeSections"
+			:key="`section-${activeTabId || 'flat'}-${sectionIndex}`"
 			:title="resolveLabel(section.title)"
 			:icon="section.icon || ''"
 			:collapsible="section.collapsible || false">
@@ -198,6 +227,15 @@ import CnVersionInfoCard from '../CnVersionInfoCard/CnVersionInfoCard.vue'
 import CnRegisterMapping from '../CnRegisterMapping/CnRegisterMapping.vue'
 import CnSettingsWidgetMount from './CnSettingsWidgetMount.js'
 
+/**
+ * Sentinel value used in the built-in widget registry to mark the
+ * `'component'` discriminator (manifest-settings-orchestration
+ * REQ-MSO-6). The discriminator does NOT resolve to a fixed
+ * component — instead, the resolver detects this sentinel and looks
+ * up `widget.componentName` in the customComponents registry.
+ */
+const COMPONENT_DISCRIMINATOR = Symbol('cn-settings-component-widget')
+
 /**
  * Built-in widget registry. Used by `CnSettingsPage` to resolve
  * `widgets[].type` to a component BEFORE consulting the
@@ -206,13 +244,19 @@ import CnSettingsWidgetMount from './CnSettingsWidgetMount.js'
  * The order matters — built-ins win on collision so consumers can't
  * accidentally shadow `version-info` with their own component. If a
  * consumer needs to truly replace one of these, they can render their
- * own component via `section.component` instead of `widgets[]`.
+ * own component via `section.component` or
+ * `{ type: "component", componentName: <name> }` instead of `widgets[]`.
  *
- * Spec: REQ-MSRS-2 (manifest-settings-rich-sections).
+ * Spec:
+ *  - REQ-MSRS-2 (manifest-settings-rich-sections) — fixed-component
+ *    built-ins (`version-info`, `register-mapping`).
+ *  - REQ-MSO-6 (manifest-settings-orchestration) — `'component'`
+ *    discriminator (sentinel value, resolved via componentName).
  */
 const BUILTIN_SETTINGS_WIDGETS = Object.freeze({
 	'version-info': CnVersionInfoCard,
 	'register-mapping': CnRegisterMapping,
+	component: COMPONENT_DISCRIMINATOR,
 })
 
 /**
@@ -320,19 +364,50 @@ export default {
 			default: '',
 		},
 		/**
-		 * Section definitions. Each section MUST declare EXACTLY ONE of:
+		 * Section definitions (flat shape — back-compat). Each section
+		 * MUST declare EXACTLY ONE of:
 		 *  - `fields: Array<Field>` (back-compat flat-field body)
 		 *  - `component: <registry-name>` + optional `props`
-		 *  - `widgets: Array<{ type, props? }>`
+		 *  - `widgets: Array<{ type, props?, componentName? }>`
 		 *
 		 * Common keys: `{ title, description?, icon?, collapsible?, docUrl? }`.
 		 *
+		 * Mutually exclusive with `tabs[]` (XOR — see
+		 * manifest-settings-orchestration REQ-MSO-1).
+		 *
 		 * @type {Array<object>}
 		 */
 		sections: {
 			type: Array,
 			default: () => [],
 		},
+		/**
+		 * Tab definitions (orchestration shape — manifest-settings-
+		 * orchestration REQ-MSO-2). When set, CnSettingsPage renders
+		 * a tab strip above the section area; the active tab's
+		 * `sections[]` flow into the same renderer used by the flat
+		 * shape. Mutually exclusive with `sections[]`.
+		 *
+		 * Each tab MUST be `{ id: string, label: string,
+		 * icon?: string, sections: array<Section> }`.
+		 *
+		 * @type {Array<object>}
+		 */
+		tabs: {
+			type: Array,
+			default: () => [],
+		},
+		/**
+		 * Optional ID of the tab to activate on mount. When empty AND
+		 * `tabs[]` is non-empty, the first tab is active by default.
+		 * Unknown IDs fall back to the first tab.
+		 *
+		 * @type {string}
+		 */
+		initialTab: {
+			type: String,
+			default: '',
+		},
 		/**
 		 * Initial values keyed by `field.key`. Defaults to an empty
 		 * object; in practice the consumer passes the current
@@ -394,14 +469,30 @@ export default {
 		},
 	},
 
-	emits: ['save', 'error', 'input', 'widget-event'],
+	emits: ['save', 'error', 'input', 'widget-event', 'tab-change'],
 
 	data() {
+		// Resolve the initial active-tab id synchronously so the very
+		// first render has the correct tab active (otherwise tests
+		// that mount + assert without an `await tick` see the empty
+		// default). Mirrors the logic in `resolveInitialTabId` (the
+		// watcher path); keep them aligned.
+		let activeTabId = ''
+		const tabs = Array.isArray(this.tabs) ? this.tabs : []
+		if (tabs.length > 0) {
+			if (typeof this.initialTab === 'string' && this.initialTab.length > 0
+				&& tabs.some(t => t && t.id === this.initialTab)) {
+				activeTabId = this.initialTab
+			} else if (tabs[0] && typeof tabs[0].id === 'string') {
+				activeTabId = tabs[0].id
+			}
+		}
 		return {
 			formData: this.cloneInitial(),
 			originalData: this.cloneInitial(),
 			saving: false,
 			lastError: null,
+			activeTabId,
 		}
 	},
 
@@ -420,6 +511,35 @@ export default {
 		effectiveCustomComponents() {
 			return this.customComponents ?? this.cnCustomComponents ?? {}
 		},
+		/**
+		 * Whether the page is in tabs orchestration mode. True when
+		 * `tabs[]` is non-empty — drives the tab-strip render gate
+		 * (manifest-settings-orchestration REQ-MSO-5).
+		 *
+		 * @return {boolean}
+		 */
+		hasTabs() {
+			return Array.isArray(this.tabs) && this.tabs.length > 0
+		},
+		/**
+		 * The sections to render right now. In flat mode, this is the
+		 * `sections` prop directly. In tabs mode, this is the
+		 * `sections[]` array of the currently active tab. Centralising
+		 * this in one computed keeps the template's `v-for` simple
+		 * and decouples it from the body kind dispatcher (which
+		 * applies per-section, not per-mode).
+		 *
+		 * @return {Array<object>}
+		 */
+		activeSections() {
+			if (!this.hasTabs) return this.sections || []
+			const active = this.tabs.find(t => t && t.id === this.activeTabId)
+			if (active && Array.isArray(active.sections)) return active.sections
+			// Defensive fallback — should not happen because
+			// `resolveInitialTabId` always lands on a known tab.
+			const first = this.tabs[0]
+			return first && Array.isArray(first.sections) ? first.sections : []
+		},
 	},
 
 	watch: {
@@ -430,6 +550,22 @@ export default {
 				this.originalData = this.cloneInitial()
 			},
 		},
+		// When `tabs[]` changes (e.g. consumer swaps manifests at
+		// runtime), re-resolve the active tab so the page doesn't get
+		// stuck on a removed id.
+		tabs: {
+			handler() {
+				this.activeTabId = this.resolveInitialTabId()
+			},
+		},
+		// When `initialTab` changes (consumer-controlled tab
+		// activation), follow it.
+		initialTab(next) {
+			if (typeof next === 'string' && next.length > 0) {
+				const exists = this.tabs.some(t => t && t.id === next)
+				if (exists) this.activeTabId = next
+			}
+		},
 	},
 
 	methods: {
@@ -475,11 +611,20 @@ export default {
 		},
 		cloneInitial() {
 			const merged = { ...(this.initialValues || {}) }
-			// Pre-populate any field with a `default` if no value is set yet.
-			// Only flat-field sections contribute defaults; component and
-			// widgets sections own their own state.
-			for (const section of this.sections || []) {
-				if (!Array.isArray(section.fields)) continue
+			// Collect every section across both modes (flat
+			// `sections[]` AND `tabs[].sections[]`) so default values
+			// are applied regardless of orchestration shape.
+			// Only flat-field sections contribute defaults; component
+			// and widgets sections own their own state.
+			const allSections = []
+			for (const section of this.sections || []) allSections.push(section)
+			for (const tab of this.tabs || []) {
+				if (tab && Array.isArray(tab.sections)) {
+					for (const section of tab.sections) allSections.push(section)
+				}
+			}
+			for (const section of allSections) {
+				if (!section || !Array.isArray(section.fields)) continue
 				for (const field of section.fields) {
 					if (field.default !== undefined && merged[field.key] === undefined) {
 						merged[field.key] = field.default
@@ -545,23 +690,55 @@ export default {
 		},
 
 		/**
-		 * Resolve a `widgets[].type` string to a Vue component. Lookup
-		 * order:
+		 * Resolve a single `widgets[]` entry to a concrete Vue
+		 * component. Lookup order:
 		 *
 		 *   1. Built-in widget map (`version-info`, `register-mapping`).
-		 *   2. `effectiveCustomComponents` registry.
+		 *   2. `'component'` discriminator (REQ-MSO-6) — resolves
+		 *      `widget.componentName` against `effectiveCustomComponents`.
+		 *   3. Legacy fallback — looks up `widget.type` against
+		 *      `effectiveCustomComponents`. Kept for back-compat with
+		 *      manifest-settings-rich-sections consumers; flagged as
+		 *      deprecated in JSDoc — manifest authors should migrate to
+		 *      the explicit `{ type: "component", componentName }` shape.
 		 *
-		 * Returns `null` (and warns) when neither resolves. Built-ins
-		 * win on collision so consumers can't accidentally shadow them
-		 * (REQ-MSRS-2).
+		 * Returns `null` (and warns) when nothing resolves. Built-ins
+		 * win on collision so consumers can't accidentally shadow them.
 		 *
-		 * @param {string} type The widget type string.
+		 * @param {object} widget A `widgets[]` entry, e.g. `{ type, props?, componentName? }`.
 		 * @return {object|null} Vue component or null.
 		 */
-		resolveWidgetComponent(type) {
+		resolveWidgetComponent(widget) {
+			const type = widget && typeof widget.type === 'string' ? widget.type : ''
+			if (!type) return null
 			if (Object.prototype.hasOwnProperty.call(BUILTIN_SETTINGS_WIDGETS, type)) {
-				return BUILTIN_SETTINGS_WIDGETS[type]
+				const builtin = BUILTIN_SETTINGS_WIDGETS[type]
+				if (builtin === COMPONENT_DISCRIMINATOR) {
+					// REQ-MSO-6: discriminator — look up `componentName`.
+					const name = widget.componentName
+					if (typeof name !== 'string' || name.length === 0) {
+						// eslint-disable-next-line no-console
+						console.warn(
+							'[CnSettingsPage] Widget {type:"component"} requires a non-empty `componentName`. Widget will be skipped.',
+						)
+						return null
+					}
+					const resolved = this.effectiveCustomComponents[name]
+					if (!resolved) {
+						// eslint-disable-next-line no-console
+						console.warn(
+							`[CnSettingsPage] Widget component "${name}" not found in customComponents registry. Widget will be skipped.`,
+						)
+						return null
+					}
+					return resolved
+				}
+				return builtin
 			}
+			// Legacy fallback (manifest-settings-rich-sections REQ-MSRS-2).
+			// Deprecated — manifest authors should migrate to
+			// `{ type: "component", componentName: <X> }`. Kept here so
+			// existing consumers continue working unchanged.
 			const resolved = this.effectiveCustomComponents[type]
 			if (!resolved) {
 				// eslint-disable-next-line no-console
@@ -580,6 +757,11 @@ export default {
 		 * has already logged a warn. The filter happens here so the
 		 * template can use a clean `v-for` without nested `v-if`.
 		 *
+		 * The `widgetType` carried on the bubbled `@widget-event`
+		 * payload is the widget's `componentName` (when the
+		 * discriminator is `'component'`) or `widget.type` otherwise —
+		 * giving consumers a stable identifier for the dispatch.
+		 *
 		 * @param {object} section A section entry with `widgets[]`.
 		 * @param {number} sectionIndex Index in `sections[]`.
 		 * @return {Array<{key: string, component: object, props: object, widgetType: string, widgetIndex: number}>}
@@ -589,19 +771,57 @@ export default {
 			const widgets = Array.isArray(section.widgets) ? section.widgets : []
 			for (let widgetIndex = 0; widgetIndex < widgets.length; widgetIndex++) {
 				const widget = widgets[widgetIndex] || {}
-				const component = this.resolveWidgetComponent(widget.type)
+				const component = this.resolveWidgetComponent(widget)
 				if (!component) continue
+				const widgetType = widget.type === 'component' && typeof widget.componentName === 'string'
+					? widget.componentName
+					: widget.type
 				entries.push({
 					key: `widget-${sectionIndex}-${widgetIndex}`,
 					component,
 					props: widget.props || {},
-					widgetType: widget.type,
+					widgetType,
 					widgetIndex,
 				})
 			}
 			return entries
 		},
 
+		/**
+		 * Resolve the active-tab id on mount / when `tabs[]` changes.
+		 * Lookup order: explicit `initialTab` prop → first tab in
+		 * `tabs[]` → empty string. Unknown `initialTab` values fall
+		 * back to the first tab so the page never gets stuck.
+		 * (manifest-settings-orchestration REQ-MSO-5.)
+		 *
+		 * @return {string} The resolved tab id (empty in flat mode).
+		 */
+		resolveInitialTabId() {
+			if (!this.hasTabs) return ''
+			if (typeof this.initialTab === 'string' && this.initialTab.length > 0) {
+				const exists = this.tabs.some(t => t && t.id === this.initialTab)
+				if (exists) return this.initialTab
+			}
+			const first = this.tabs[0]
+			return first && typeof first.id === 'string' ? first.id : ''
+		},
+
+		/**
+		 * Handle a tab button click. Switches the active tab and
+		 * emits `@tab-change` so consumers can react (e.g. persist the
+		 * active tab in their preference store, update the URL hash).
+		 * (manifest-settings-orchestration REQ-MSO-5.)
+		 *
+		 * @param {object} tab The clicked tab definition.
+		 * @param {number} tabIndex The tab's index in `tabs[]`.
+		 */
+		onTabClick(tab, tabIndex) {
+			if (!tab || typeof tab.id !== 'string') return
+			if (this.activeTabId === tab.id) return
+			this.activeTabId = tab.id
+			this.$emit('tab-change', { tabId: tab.id, tabIndex })
+		},
+
 		/**
 		 * Re-emit a widget's `widget-event` (caught by the local
 		 * CnSettingsWidgetMount helper) as a top-level `widget-event`
@@ -653,6 +873,65 @@ export default {
 	gap: 8px;
 }
 
+/*
+ * Tab strip for the orchestration shape (manifest-settings-
+ * orchestration REQ-MSO-5). Uses Nextcloud CSS variables only — no
+ * hex literals, no rgba overrides on the elements themselves.
+ */
+.cn-settings-page__tabs {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 4px;
+	border-bottom: 1px solid var(--color-border);
+	padding-bottom: 0;
+	margin-bottom: 8px;
+}
+
+.cn-settings-page__tab {
+	background: transparent;
+	border: 0;
+	border-bottom: 3px solid transparent;
+	padding: 8px 16px;
+	margin: 0;
+	cursor: pointer;
+	color: var(--color-text-maxcontrast);
+	font-weight: normal;
+	border-radius: var(--border-radius-large) var(--border-radius-large) 0 0;
+	transition: background-color 0.1s ease-in-out, color 0.1s ease-in-out, border-color 0.1s ease-in-out;
+}
+
+.cn-settings-page__tab:hover,
+.cn-settings-page__tab:focus-visible {
+	background-color: var(--color-background-hover);
+	color: var(--color-main-text);
+	outline: none;
+}
+
+.cn-settings-page__tab--active {
+	color: var(--color-primary-element);
+	border-bottom-color: var(--color-primary-element);
+	font-weight: bold;
+}
+
+@media (max-width: 768px) {
+	.cn-settings-page__tabs {
+		flex-direction: column;
+		gap: 0;
+		border-bottom: 0;
+	}
+
+	.cn-settings-page__tab {
+		border-bottom: 1px solid var(--color-border);
+		border-radius: 0;
+		text-align: left;
+	}
+
+	.cn-settings-page__tab--active {
+		border-bottom-width: 1px;
+		background-color: var(--color-background-hover);
+	}
+}
+
 .cn-settings-page__fields {
 	display: flex;
 	flex-direction: column;

package/src/composables/useAppManifest.js

@@ -2,19 +2,26 @@ import { ref } from 'vue'
 import axios from '@nextcloud/axios'
 import { generateUrl } from '@nextcloud/router'
 import { validateManifest } from '../utils/validateManifest.js'
+import { resolveManifestSentinels } from '../utils/resolveManifestSentinels.js'
 
 /**
- * Composable that loads and validates a Conduction app manifest.
+ * Composable that loads, resolves, and validates a Conduction app manifest.
  *
- * The composable implements the three-phase flow specified in
- * REQ-JMR-002 of the json-manifest-renderer capability:
+ * The composable implements the four-phase flow specified in
+ * REQ-JMR-002 of the json-manifest-renderer capability + the
+ * substitution step from the `manifest-resolve-sentinel` capability:
  *
  *  1. Synchronous bundled load — `bundledManifest` is the immediate value.
  *  2. Async backend merge — fetches `/index.php/apps/{appId}/api/manifest`
  *     and deep-merges any 200 response over the bundled manifest. 4xx /
  *     5xx / network errors are silently ignored so apps work without a
  *     backend endpoint.
- *  3. Validation — the merged result is validated against
+ *  3. Sentinel resolution — `@resolve:<key>` strings under
+ *     `pages[].config` are substituted with `IAppConfig` values via the
+ *     `resolveManifestSentinels` utility (see its module docs for the
+ *     resolution source chain). Unresolved keys surface on the
+ *     returned `unresolvedSentinels` ref.
+ *  4. Validation — the resolved result is validated against
  *     `app-manifest.schema.json`. On failure, the bundled manifest is
  *     kept and a `console.warn` is emitted with the error list.
  *
@@ -22,7 +29,8 @@ import { validateManifest } from '../utils/validateManifest.js'
  * can hot-swap the manifest without a page reload.
  *
  * @param {string} appId Nextcloud app ID. Used to build the default
- *   backend endpoint URL via `@nextcloud/router`.
+ *   backend endpoint URL via `@nextcloud/router` and to scope
+ *   IAppConfig lookups for `@resolve:<key>` sentinels.
  * @param {object} bundledManifest The manifest shipped with the app (the
  *   default value, available synchronously).
  * @param {object} [options] Configuration options.
@@ -32,7 +40,10 @@ import { validateManifest } from '../utils/validateManifest.js'
  *   return a promise resolving to `{ status: number, data: object }`.
  *   Defaults to `axios.get` from `@nextcloud/axios` (which inherits the
  *   Nextcloud CSRF token automatically).
- * @return {{ manifest: import('vue').Ref<object>, isLoading: import('vue').Ref<boolean>, validationErrors: import('vue').Ref<string[]|null> }}
+ * @param {Function} [options.getAppConfigValue] Override the
+ *   IAppConfig resolver consumed by `resolveManifestSentinels`. Useful
+ *   for tests that want to mount a fixture-driven config map.
+ * @return {{ manifest: import('vue').Ref<object>, isLoading: import('vue').Ref<boolean>, validationErrors: import('vue').Ref<string[]|null>, unresolvedSentinels: import('vue').Ref<string[]> }}
  *
  * @example Basic usage (Composition API)
  * const { manifest, isLoading } = useAppManifest('decidesk', bundled)
@@ -49,11 +60,17 @@ import { validateManifest } from '../utils/validateManifest.js'
  *   endpoint: '/custom/manifest/url',
  *   fetcher: (url) => Promise.resolve({ status: 200, data: { ... } }),
  * })
+ *
+ * @example With sentinel resolution + admin warning surface
+ * const { manifest, unresolvedSentinels } = useAppManifest('softwarecatalog', bundled)
+ * // unresolvedSentinels.value is e.g. ['voorzieningen_register']
+ * // when that IAppConfig key is unset on the tenant.
  */
 export function useAppManifest(appId, bundledManifest, options = {}) {
 	const manifest = ref(bundledManifest)
 	const isLoading = ref(true)
 	const validationErrors = ref(null)
+	const unresolvedSentinels = ref([])
 
 	const endpoint = options.endpoint ?? generateUrl(`/apps/${appId}/api/manifest`)
 	const fetcher = options.fetcher ?? ((url) => axios.get(url))
@@ -65,7 +82,18 @@ export function useAppManifest(appId, bundledManifest, options = {}) {
 				return
 			}
 			const merged = deepMerge(bundledManifest, response.data)
-			const result = validateManifest(merged)
+
+			// Sentinel resolution runs BEFORE validation per
+			// REQ-MRS-002: the validator MUST NEVER observe an
+			// unresolved sentinel at runtime. Resolution failures
+			// (unset IAppConfig keys) substitute null and accumulate
+			// on `unresolvedSentinels`; they do NOT block validation.
+			const { manifest: resolved, unresolved } = await resolveManifestSentinels(merged, appId, {
+				getAppConfigValue: options.getAppConfigValue,
+			})
+			unresolvedSentinels.value = unresolved
+
+			const result = validateManifest(resolved)
 			if (!result.valid) {
 				validationErrors.value = result.errors
 				// eslint-disable-next-line no-console
@@ -75,7 +103,7 @@ export function useAppManifest(appId, bundledManifest, options = {}) {
 				)
 				return
 			}
-			manifest.value = merged
+			manifest.value = resolved
 		} catch (err) {
 			// Silent fallback on 404, network errors, non-200 responses.
 			// Apps without a backend endpoint should keep working.
@@ -84,7 +112,7 @@ export function useAppManifest(appId, bundledManifest, options = {}) {
 		}
 	})()
 
-	return { manifest, isLoading, validationErrors }
+	return { manifest, isLoading, validationErrors, unresolvedSentinels }
 }
 
 /**

package/src/index.js

@@ -119,4 +119,5 @@ export { registerTranslations } from './l10n/index.js'
 export { buildHeaders, buildQueryString, parseResponseError, networkError, genericError } from './utils/index.js'
 export { columnsFromSchema, formatValue, filtersFromSchema, fieldsFromSchema, validateValue } from './utils/index.js'
 export { validateManifest } from './utils/validateManifest.js'
+export { resolveManifestSentinels, clearResolveCache } from './utils/resolveManifestSentinels.js'
 export { filterWidgetsByVisibility, isWidgetVisible, getCurrentUserId, getCurrentUserGroups, resetVisibilityCache } from './utils/index.js'

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

@@ -127,7 +127,7 @@
 				},
 				"config": {
 					"type": "object",
-					"description": "Type-specific configuration. For type='index': { register, schema, columns, actions, sidebar?, cardComponent? }. The optional `cardComponent` is a string referencing a key in the consuming app's `customComponents` registry (the same registry that powers `type:'custom'` pages). When set AND the page is in card-grid view mode AND the parent has not provided a `#card` scoped slot, CnIndexPage mounts the registry-resolved component for each row instead of the schema-driven CnObjectCard, passing `{ item, object, schema, register, selected }` props and forwarding `click` + `select` events. An unknown name logs a console warning and falls back to CnObjectCard so a misconfigured manifest never blanks the grid. The optional `sidebar` is an object `{ enabled: boolean, show?: boolean, columnGroups?: array, facets?: object, showMetadata?: boolean, search?: object }` that, when `enabled`, makes CnIndexPage auto-mount its embedded CnIndexSidebar. `show` (default true) suppresses the embedded sidebar without removing config when set false. For type='detail': { register, schema, sidebar?, sidebarProps? }. The `sidebar` field accepts EITHER a Boolean (legacy: true/false toggles the external CnObjectSidebar) OR an Object mirroring the index shape plus detail-specific fields `{ show?: boolean, enabled?: boolean, register?, schema?, hiddenTabs?, title?, subtitle?, tabs? }`. `config.sidebar.show: false` suppresses the embedded sidebar on either index or detail pages. The optional `sidebarProps.tabs` is an open-enum array of tab definitions `{ id, label, icon?, widgets?, component?, order? }` that overrides CnObjectSidebar's hard-coded built-in tab set; each tab declares either a list of widgets (`type: 'data' | 'metadata' | <registry-name>`) or a registry component name. For type='dashboard': { widgets, layout }. For type='logs': { register?, schema?, source?, columns? } — one of register+schema OR source MUST be set. For type='settings': { sections: array<Section>, saveEndpoint? } where each Section declares EXACTLY ONE of `fields[]` (back-compat flat-field body), `component: <registry-name>` + optional `props` (mounts a customComponents-resolved component as the section body), OR `widgets: array<{ type, props? }>` (mounts one or more widgets in sequence; built-in widget types `version-info` → CnVersionInfoCard and `register-mapping` → CnRegisterMapping resolve first, falling back to the customComponents registry). Widget events bubble through CnSettingsPage's `@widget-event` so consumers wire one page-level handler (see manifest-settings-rich-sections spec). For type='chat': { conversationSource?, postUrl?, schema? } — one of conversationSource OR postUrl MUST be set. For type='files': { folder, allowedTypes? }. For type='form': { fields: array<formField>, submitHandler? OR submitEndpoint?, submitMethod?, mode?, submitLabel?, successMessage?, initialValue? }. Exactly one of `submitHandler` (registry name resolved against customComponents) OR `submitEndpoint` (URL string; `:paramName` segments resolve against `$route.params`) MUST be set. `submitMethod` (default POST) MUST be one of POST | PUT | PATCH when set. `mode` (default public) MUST be one of edit | create | public when set. The `fields[]` array `$ref`s the same `formField` $def `pages[].config.sections[].fields[]` consumes for type='settings'. See manifest-form-page-type spec. For type='custom': any shape the custom component expects. As of schema version 1.2.0, the recurring sub-shapes (`columns[]`, `actions[]`, `widgets[]`, `layout[]`, `sections[].fields[]`, `sidebar.columnGroups[]`, `sidebar.tabs[]`, `sidebarProps.tabs[]`) `$ref` the seven `$defs` (`column`, `action`, `widgetDef`, `layoutItem`, `formField`, `sidebarSection`, `sidebarTab`). The OUTER `config` block keeps `additionalProperties: true` so per-type scalars (`register`, `schema`, `source`, `folder`, `saveEndpoint`, …) and consumer-app extension keys remain free-form.",
+					"description": "Type-specific configuration. For type='index': { register, schema, columns, actions, sidebar?, cardComponent? }. The optional `cardComponent` is a string referencing a key in the consuming app's `customComponents` registry (the same registry that powers `type:'custom'` pages). When set AND the page is in card-grid view mode AND the parent has not provided a `#card` scoped slot, CnIndexPage mounts the registry-resolved component for each row instead of the schema-driven CnObjectCard, passing `{ item, object, schema, register, selected }` props and forwarding `click` + `select` events. An unknown name logs a console warning and falls back to CnObjectCard so a misconfigured manifest never blanks the grid. The optional `sidebar` is an object `{ enabled: boolean, show?: boolean, columnGroups?: array, facets?: object, showMetadata?: boolean, search?: object }` that, when `enabled`, makes CnIndexPage auto-mount its embedded CnIndexSidebar. `show` (default true) suppresses the embedded sidebar without removing config when set false. For type='detail': { register, schema, sidebar?, sidebarProps? }. The `sidebar` field accepts EITHER a Boolean (legacy: true/false toggles the external CnObjectSidebar) OR an Object mirroring the index shape plus detail-specific fields `{ show?: boolean, enabled?: boolean, register?, schema?, hiddenTabs?, title?, subtitle?, tabs? }`. `config.sidebar.show: false` suppresses the embedded sidebar on either index or detail pages. The optional `sidebarProps.tabs` is an open-enum array of tab definitions `{ id, label, icon?, widgets?, component?, order? }` that overrides CnObjectSidebar's hard-coded built-in tab set; each tab declares either a list of widgets (`type: 'data' | 'metadata' | <registry-name>`) or a registry component name. For type='dashboard': { widgets, layout }. For type='logs': { register?, schema?, source?, columns? } — one of register+schema OR source MUST be set. For type='settings': { sections?: array<Section>, tabs?: array<Tab>, saveEndpoint? } where EXACTLY ONE of `sections` or `tabs` MUST be set (XOR — see manifest-settings-orchestration spec). Each Section declares EXACTLY ONE of `fields[]` (back-compat flat-field body), `component: <registry-name>` + optional `props` (mounts a customComponents-resolved component as the section body), OR `widgets: array<{ type, props?, componentName? }>` (mounts one or more widgets in sequence; built-in widget types `version-info` → CnVersionInfoCard, `register-mapping` → CnRegisterMapping, and `component` (with `componentName: <registry-name>`) → customComponents-resolved component). Each Tab is `{ id, label, icon?, sections: array<Section> }` and CnSettingsPage renders a tab strip switching between them. Widget events bubble through CnSettingsPage's `@widget-event` so consumers wire one page-level handler (see manifest-settings-rich-sections spec). For type='chat': { conversationSource?, postUrl?, schema? } — one of conversationSource OR postUrl MUST be set. For type='files': { folder, allowedTypes? }. For type='form': { fields: array<formField>, submitHandler? OR submitEndpoint?, submitMethod?, mode?, submitLabel?, successMessage?, initialValue? }. Exactly one of `submitHandler` (registry name resolved against customComponents) OR `submitEndpoint` (URL string; `:paramName` segments resolve against `$route.params`) MUST be set. `submitMethod` (default POST) MUST be one of POST | PUT | PATCH when set. `mode` (default public) MUST be one of edit | create | public when set. The `fields[]` array `$ref`s the same `formField` $def `pages[].config.sections[].fields[]` consumes for type='settings'. See manifest-form-page-type spec. For type='custom': any shape the custom component expects. As of schema version 1.2.0, the recurring sub-shapes (`columns[]`, `actions[]`, `widgets[]`, `layout[]`, `sections[].fields[]`, `sidebar.columnGroups[]`, `sidebar.tabs[]`, `sidebarProps.tabs[]`) `$ref` the seven `$defs` (`column`, `action`, `widgetDef`, `layoutItem`, `formField`, `sidebarSection`, `sidebarTab`). The OUTER `config` block keeps `additionalProperties: true` so per-type scalars (`register`, `schema`, `source`, `folder`, `saveEndpoint`, …) and consumer-app extension keys remain free-form.",
 					"additionalProperties": true,
 					"properties": {
 						"columns": {
@@ -162,7 +162,7 @@
 						},
 						"sections": {
 							"type": "array",
-							"description": "Settings sections consumed by CnSettingsPage (for type='settings'). Each section declares EXACTLY ONE of `fields[]` / `component` / `widgets[]` (FE-validated mutual exclusion). The outer section object keeps `additionalProperties: true`; only `fields[]` is typed via $ref formField. Settings widgets use a thinner shape `{ type, props? }` (NOT the same as dashboard widgetDef) and are NOT typed by this schema.",
+							"description": "Settings sections consumed by CnSettingsPage (for type='settings'). Each section declares EXACTLY ONE of `fields[]` / `component` / `widgets[]` (FE-validated mutual exclusion). The outer section object keeps `additionalProperties: true`; only `fields[]` is typed via $ref formField. Settings widgets use a thinner shape `{ type, props?, componentName? }` (NOT the same as dashboard widgetDef) and are NOT typed by this schema. Mutually exclusive with `tabs[]` at the page level — see manifest-settings-orchestration.",
 							"items": {
 								"type": "object",
 								"additionalProperties": true,
@@ -175,6 +175,44 @@
 								}
 							}
 						},
+						"tabs": {
+							"type": "array",
+							"description": "Settings tabs consumed by CnSettingsPage (for type='settings'). When set, CnSettingsPage renders a tab strip and the active tab's `sections[]` flow into the same renderer used by the flat shape. Mutually exclusive with `sections[]` at the page level (XOR). Each tab is `{ id: string, label: string, icon?: string, sections: array<Section> }`. See manifest-settings-orchestration spec.",
+							"items": {
+								"type": "object",
+								"additionalProperties": true,
+								"required": ["id", "label", "sections"],
+								"properties": {
+									"id": {
+										"type": "string",
+										"description": "Tab identifier — addressable by `initialTab` and emitted in `@tab-change`. MUST be non-empty and unique within the page."
+									},
+									"label": {
+										"type": "string",
+										"description": "Tab button label (i18n translation key — passed through `translate()` if a translate prop is wired on CnSettingsPage)."
+									},
+									"icon": {
+										"type": "string",
+										"description": "Optional MDI component name prepended to the tab button (e.g. \"Cog\")."
+									},
+									"sections": {
+										"type": "array",
+										"description": "Sections rendered when this tab is active. Same shape and rules as the flat `sections[]` case.",
+										"items": {
+											"type": "object",
+											"additionalProperties": true,
+											"properties": {
+												"fields": {
+													"type": "array",
+													"description": "Flat field-body for this section. Each item references the `formField` $def.",
+													"items": { "$ref": "#/$defs/formField" }
+												}
+											}
+										}
+									}
+								}
+							}
+						},
 						"sidebar": {
 							"description": "Index/detail sidebar configuration. For type='index': an object with `columnGroups[]` ($ref sidebarSection) plus open scalars (enabled, show, facets, search, showMetadata). For type='detail': either a Boolean (legacy on/off) OR an object whose `tabs[]` references the `sidebarTab` $def — the rest of the object (`register`, `schema`, `title`, `subtitle`, `hiddenTabs`, `show`, `enabled`) stays free-form via `additionalProperties: true`.",
 							"oneOf": [