@conduction/nextcloud-vue 1.0.0-beta.17 → 1.0.0-beta.18

package/src/composables/cnFormFieldRenderer.js

@@ -0,0 +1,256 @@
+/**
+ * cnFormFieldRenderer — shared field-renderer helper used by
+ * `CnFormPage` (and, in a follow-up, `CnSettingsPage`'s bare-fields
+ * branch).
+ *
+ * Maps a `formField` shape (the `$def` shared by
+ * `pages[].config.sections[].fields[]` for `type: "settings"` and
+ * `pages[].config.fields[]` for `type: "form"`) to one of the
+ * library's input components. Emitted to keep the input-rendering
+ * logic in one place — the settings page used to inline this switch
+ * (and still does, until a follow-up DRY pass migrates it); the form
+ * page consumes the shared helper from day one.
+ *
+ * Field shapes:
+ *
+ *  | `field.type`  | Component / behaviour                              |
+ *  |---------------|----------------------------------------------------|
+ *  | `boolean`     | NcCheckboxRadioSwitch                              |
+ *  | `number`      | NcTextField type=number, value coerced to Number   |
+ *  | `password`    | NcTextField type=password                          |
+ *  | `string`      | NcTextField (default), or NcTextArea when         |
+ *  |               | `field.widget === "textarea"`                      |
+ *  | `enum`        | NcSelect, options shaped from `field.enum`/`field.options` |
+ *  | `json`        | CnJsonViewer (read-only display in this rev)       |
+ *
+ * Unknown `field.type` values fall back to NcTextField and emit a
+ * single `console.warn` so the consumer notices the typo.
+ *
+ * The helper exports a render-function — components consume it via
+ * `<component :is="cnRenderFormField(...).renderer" v-bind="cnRenderFormField(...).bindings" />`
+ * — but for Vue 2 + the test toolchain we use a small functional
+ * resolver pattern: the helper returns `{ tag, props, listeners }`
+ * the parent template binds via `<component :is>`. This keeps the
+ * template trivially mountable in jest with the same component stubs
+ * tests already use for CnSettingsPage.
+ *
+ * @param {object} args
+ * @param {object} args.field   The formField shape.
+ * @param {*}      args.value   Current value for `field.key`.
+ * @param {Function} args.onInput Callback invoked with the new value.
+ * @param {Function} [args.t]   Optional translator for `field.label`.
+ * @param {object}  [args.componentMap] Optional override map from
+ *   widget id → Vue component. Defaults to the library's standard
+ *   set (`NcCheckboxRadioSwitch`, `NcTextField`, `NcTextArea`,
+ *   `NcSelect`, `CnJsonViewer`).
+ *
+ * @return {{ tag: object, props: object, listeners: object }}
+ */
+import {
+	NcCheckboxRadioSwitch,
+	NcSelect,
+	NcTextField,
+} from '@nextcloud/vue'
+import CnJsonViewer from '../components/CnJsonViewer/CnJsonViewer.vue'
+
+// NcTextArea is not always exported under the same path across
+// @nextcloud/vue versions; falling back to NcTextField with a
+// `multiline` prop hint keeps this resilient. The actual textarea
+// rendering is delegated to the textarea fallback below.
+let NcTextArea = null
+try {
+	// eslint-disable-next-line global-require
+	NcTextArea = require('@nextcloud/vue').NcTextArea ?? null
+} catch (_e) {
+	NcTextArea = null
+}
+
+const DEFAULT_COMPONENT_MAP = Object.freeze({
+	boolean: NcCheckboxRadioSwitch,
+	number: NcTextField,
+	password: NcTextField,
+	string: NcTextField,
+	'string-textarea': NcTextArea,
+	enum: NcSelect,
+	json: CnJsonViewer,
+})
+
+const KNOWN_TYPES = ['boolean', 'number', 'password', 'string', 'enum', 'json']
+
+const warned = new Set()
+
+/**
+ * Coerce an enum field's options into the `{ label, value }` shape
+ * NcSelect expects. Accepts:
+ *  - `field.enum: ['a', 'b']` (preferred per the formField $def)
+ *  - `field.options: [{ label, value }]` (legacy CnSettingsPage shape)
+ *  - mixed `[{ label, value }, 'literal']`
+ *
+ * @param {object} field
+ * @return {Array<{label: string, value: *}>}
+ */
+function resolveEnumOptions(field) {
+	const raw = Array.isArray(field.enum)
+		? field.enum
+		: (Array.isArray(field.options) ? field.options : [])
+	return raw.map((entry) => {
+		if (entry && typeof entry === 'object' && 'value' in entry) {
+			return { label: String(entry.label ?? entry.value), value: entry.value }
+		}
+		return { label: String(entry), value: entry }
+	})
+}
+
+/**
+ * Resolve render bindings for a single form field.
+ *
+ * @param {object} args See module docblock.
+ * @return {{ tag: object|string, props: object, listeners: object, kind: string }}
+ */
+export function cnRenderFormField({ field, value, onInput, t, componentMap } = {}) {
+	if (!field || typeof field !== 'object' || typeof field.key !== 'string') {
+		return null
+	}
+	const map = { ...DEFAULT_COMPONENT_MAP, ...(componentMap || {}) }
+	const translate = typeof t === 'function' ? t : (k) => k
+	const label = translate(field.label || field.key)
+
+	if (field.type === 'boolean') {
+		return {
+			kind: 'boolean',
+			tag: map.boolean,
+			props: {
+				checked: !!value,
+				label,
+			},
+			listeners: {
+				'update:checked': (next) => onInput(next),
+			},
+			labelText: label,
+		}
+	}
+
+	if (field.type === 'number') {
+		return {
+			kind: 'number',
+			tag: map.number,
+			props: {
+				label,
+				type: 'number',
+				value: value === null || value === undefined ? '' : String(value),
+			},
+			listeners: {
+				'update:value': (next) => onInput(next === '' ? null : Number(next)),
+			},
+		}
+	}
+
+	if (field.type === 'password') {
+		return {
+			kind: 'password',
+			tag: map.password,
+			props: {
+				label,
+				type: 'password',
+				value: value === null || value === undefined ? '' : String(value),
+			},
+			listeners: {
+				'update:value': (next) => onInput(next),
+			},
+		}
+	}
+
+	if (field.type === 'enum') {
+		const options = resolveEnumOptions(field)
+		const selected = options.find((o) => o.value === value) ?? null
+		return {
+			kind: 'enum',
+			tag: map.enum,
+			props: {
+				inputLabel: label,
+				options,
+				value: selected,
+			},
+			listeners: {
+				input: (next) => onInput(next?.value),
+			},
+		}
+	}
+
+	if (field.type === 'json') {
+		return {
+			kind: 'json',
+			tag: map.json,
+			props: {
+				value: value ?? null,
+				label,
+			},
+			listeners: {},
+		}
+	}
+
+	if (field.type === 'string') {
+		const isTextarea = field.widget === 'textarea'
+		if (isTextarea) {
+			// NcTextArea is preferred; otherwise fall back to a plain
+			// <textarea> rendered via the host template. The renderer
+			// returns `tag: 'textarea'` so the consumer's `<component :is>`
+			// resolves to the native element.
+			return {
+				kind: 'string-textarea',
+				tag: map['string-textarea'] || 'textarea',
+				props: {
+					label,
+					value: value === null || value === undefined ? '' : String(value),
+					rows: 4,
+				},
+				listeners: {
+					'update:value': (next) => onInput(next),
+					input: (event) => {
+						// Native textarea path — `event` is the InputEvent.
+						const next = event && event.target ? event.target.value : event
+						onInput(next)
+					},
+				},
+			}
+		}
+		return {
+			kind: 'string',
+			tag: map.string,
+			props: {
+				label,
+				value: value === null || value === undefined ? '' : String(value),
+			},
+			listeners: {
+				'update:value': (next) => onInput(next),
+			},
+		}
+	}
+
+	// Unknown type — warn ONCE per type and fall back to NcTextField.
+	if (!KNOWN_TYPES.includes(field.type)) {
+		if (!warned.has(field.type)) {
+			warned.add(field.type)
+			// eslint-disable-next-line no-console
+			console.warn(
+				`[cnRenderFormField] Unknown field.type "${field.type}" for field "${field.key}". Falling back to NcTextField. Known types: ${KNOWN_TYPES.join(', ')}.`,
+			)
+		}
+		return {
+			kind: 'fallback',
+			tag: map.string,
+			props: {
+				label,
+				value: value === null || value === undefined ? '' : String(value),
+			},
+			listeners: {
+				'update:value': (next) => onInput(next),
+			},
+		}
+	}
+
+	// Should be unreachable given KNOWN_TYPES check above.
+	return null
+}
+
+export default cnRenderFormField

package/src/composables/index.js

@@ -5,3 +5,4 @@ export { useDashboardView } from './useDashboardView.js'
 export { useContextMenu } from './useContextMenu.js'
 export { useAppManifest } from './useAppManifest.js'
 export { useAppStatus } from './useAppStatus.js'
+export { cnRenderFormField } from './cnFormFieldRenderer.js'

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

@@ -119,7 +119,7 @@
 				},
 				"type": {
 					"type": "string",
-					"description": "Page type. Must match a key in the renderer's `pageTypes` registry (library defaults: \"index\", \"detail\", \"dashboard\", \"logs\", \"settings\", \"chat\", \"files\") OR be \"custom\" — in which case `component` resolves against the customComponents registry. Library extensions add their built-in types to `defaultPageTypes`; consumer apps pass a merged map via the `pageTypes` prop on CnAppRoot / CnPageRenderer."
+					"description": "Page type. Must match a key in the renderer's `pageTypes` registry (library defaults: \"index\", \"detail\", \"dashboard\", \"logs\", \"settings\", \"chat\", \"files\", \"form\") OR be \"custom\" — in which case `component` resolves against the customComponents registry. Library extensions add their built-in types to `defaultPageTypes`; consumer apps pass a merged map via the `pageTypes` prop on CnAppRoot / CnPageRenderer. The \"form\" type was added by `manifest-form-page-type` and renders a manifest-declared field set with submit/save handlers — see the type='form' note in `pages[].config` for the dispatch contract."
 				},
 				"title": {
 					"type": "string",
@@ -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='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>, 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.",
 					"additionalProperties": true,
 					"properties": {
 						"columns": {
@@ -155,6 +155,11 @@
 							"description": "Dashboard layout entries consumed by CnDashboardGrid / CnDashboardPage (for type='dashboard'). Each item references the `layoutItem` $def.",
 							"items": { "$ref": "#/$defs/layoutItem" }
 						},
+						"fields": {
+							"type": "array",
+							"description": "Form fields consumed by CnFormPage (for type='form'). Each item references the `formField` $def — the same shape `pages[].config.sections[].fields[]` uses for type='settings'.",
+							"items": { "$ref": "#/$defs/formField" }
+						},
 						"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.",

package/src/utils/validateManifest.js

@@ -254,6 +254,42 @@ function validateTypeConfig(page, index, errors) {
 		}
 		break
 	}
+	case 'form': {
+		// `manifest-form-page-type` REQ-MFPT-* — runtime form pages
+		// MUST declare a non-empty fields[] array and exactly one of
+		// submitHandler | submitEndpoint as the dispatch destination.
+		// Optional submitMethod and mode are constrained to closed
+		// enums so manifest typos surface at validate time.
+		const hasFields = cfg && Array.isArray(cfg.fields) && cfg.fields.length > 0
+		if (!hasFields) {
+			errors.push(`${pathSlash}/fields: ${pathBracket}: form pages must declare a non-empty fields[] array`)
+		} else {
+			validateFieldsArray(cfg.fields, `${pathSlash}/fields`, errors)
+		}
+
+		const hasHandler = cfg && typeof cfg.submitHandler === 'string' && cfg.submitHandler.length > 0
+		const hasEndpoint = cfg && typeof cfg.submitEndpoint === 'string' && cfg.submitEndpoint.length > 0
+		const dispatchCount = (hasHandler ? 1 : 0) + (hasEndpoint ? 1 : 0)
+		if (dispatchCount !== 1) {
+			errors.push(`${pathSlash}: ${pathBracket}: form pages must declare exactly one of submitHandler | submitEndpoint`)
+		}
+
+		if (cfg && cfg.submitMethod !== undefined) {
+			const allowed = ['POST', 'PUT', 'PATCH']
+			const upper = typeof cfg.submitMethod === 'string' ? cfg.submitMethod.toUpperCase() : null
+			if (!upper || !allowed.includes(upper)) {
+				errors.push(`${pathSlash}/submitMethod: ${pathBracket}.submitMethod: must be one of POST | PUT | PATCH`)
+			}
+		}
+
+		if (cfg && cfg.mode !== undefined) {
+			const allowedModes = ['edit', 'create', 'public']
+			if (typeof cfg.mode !== 'string' || !allowedModes.includes(cfg.mode)) {
+				errors.push(`${pathSlash}/mode: ${pathBracket}.mode: must be one of edit | create | public`)
+			}
+		}
+		break
+	}
 	default:
 		// No per-type rules for index/detail/dashboard/custom or
 		// consumer-defined types; their `config` shape is enforced