@nuasite/collections-admin 0.43.0-beta.1 → 0.43.0-beta.3

package/src/form-model.ts

@@ -0,0 +1,182 @@
+/**
+ * Pure draft model + field coercion for the entry editor (cms-headless F3.2).
+ *
+ * The sidecar speaks two slightly different frontmatter shapes:
+ *  - `GET …/entries/:slug` returns `frontmatter: Record<string, { value: string; line: number }>`,
+ *    where `value` is already stringified (objects/arrays are JSON).
+ *  - `PATCH …` accepts `frontmatter?: Record<string, unknown>` of *native* values (merged), and a
+ *    `409` `serverFrontmatter` is likewise native (not stringified).
+ *
+ * The editor works on a single native draft (`EntryDraft`): `frontmatter` is a
+ * `Record<string, unknown>` of native JS values keyed by field name, plus the
+ * markdown `body`. This module converts to/from the wire and coerces raw input
+ * (form strings) into the native value a `FieldType` expects. Keeping it pure
+ * (no React/DOM) makes the mapping unit-testable.
+ */
+
+import type { CollectionEntry, FieldDefinition, FieldType } from '@nuasite/cms-types'
+
+/** The editor's in-memory state: native frontmatter values + the markdown body. */
+export interface EntryDraft {
+	frontmatter: Record<string, unknown>
+	body: string
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Parse one stringified frontmatter `value` (from `GET …/entries/:slug`) into the
+ * native value a field of `type` expects. Structural types (object/array) and
+ * unknowns fall back to a best-effort `JSON.parse`; scalars are coerced per type.
+ */
+export function parseWireValue(type: FieldType, raw: string): unknown {
+	switch (type) {
+		case 'boolean':
+			return raw === 'true' || raw === '1' || raw.toLowerCase() === 'yes'
+		case 'number':
+		case 'year':
+		case 'month': {
+			const n = Number(raw)
+			return raw.trim() === '' || Number.isNaN(n) ? raw : n
+		}
+		case 'array':
+		case 'object':
+			return parseJsonLoose(raw)
+		default:
+			return raw
+	}
+}
+
+/** `JSON.parse` for structural values, falling back to the raw string when invalid. */
+function parseJsonLoose(raw: string): unknown {
+	const trimmed = raw.trim()
+	if (trimmed === '') return undefined
+	if (!(trimmed.startsWith('{') || trimmed.startsWith('[') || trimmed.startsWith('"'))) return raw
+	try {
+		return JSON.parse(trimmed)
+	} catch {
+		return raw
+	}
+}
+
+/**
+ * Build a native draft from a loaded entry, driven by the collection's fields.
+ * Frontmatter keys present on the entry but absent from the inferred schema are
+ * preserved verbatim (as raw strings) so a save never silently drops them.
+ */
+export function draftFromEntry(entry: CollectionEntry, fields: FieldDefinition[]): EntryDraft {
+	const byName = new Map(fields.map(f => [f.name, f] as const))
+	const frontmatter: Record<string, unknown> = {}
+	for (const [key, cell] of Object.entries(entry.frontmatter)) {
+		const field = byName.get(key)
+		frontmatter[key] = field ? parseWireValue(field.type, cell.value) : cell.value
+	}
+	return { frontmatter, body: entry.body }
+}
+
+/**
+ * Build a fresh draft for a create form from the collection's fields, seeding
+ * each field with its `defaultValue` (when present) or a type-appropriate blank.
+ */
+export function draftForCreate(fields: FieldDefinition[]): EntryDraft {
+	const frontmatter: Record<string, unknown> = {}
+	for (const field of fields) {
+		if (field.hidden) continue
+		if (field.defaultValue !== undefined) {
+			frontmatter[field.name] = field.defaultValue
+			continue
+		}
+		frontmatter[field.name] = blankValue(field.type)
+	}
+	return { frontmatter, body: '' }
+}
+
+/** A type-appropriate empty value used to seed create forms. */
+export function blankValue(type: FieldType): unknown {
+	switch (type) {
+		case 'boolean':
+			return false
+		case 'array':
+			return []
+		case 'object':
+			return {}
+		default:
+			return ''
+	}
+}
+
+/**
+ * Adopt a server-provided native frontmatter map (from a `409` `serverFrontmatter`)
+ * into a draft, re-coercing per field where a definition exists.
+ */
+export function draftFromServerFrontmatter(
+	serverFrontmatter: Record<string, unknown>,
+	serverBody: string | undefined,
+	fields: FieldDefinition[],
+): EntryDraft {
+	const byName = new Map(fields.map(f => [f.name, f] as const))
+	const frontmatter: Record<string, unknown> = {}
+	for (const [key, value] of Object.entries(serverFrontmatter)) {
+		const field = byName.get(key)
+		// Server values are already native; only re-coerce when the value arrived as
+		// a string for a numeric/boolean field (e.g. YAML quirks).
+		frontmatter[key] = field && typeof value === 'string' ? parseWireValue(field.type, value) : value
+	}
+	return { frontmatter, body: serverBody ?? '' }
+}
+
+/**
+ * Coerce a raw form-control string into the native value a field expects. Used by
+ * the widgets, whose `<input>` values are always strings.
+ */
+export function coerceInput(type: FieldType, raw: string): unknown {
+	switch (type) {
+		case 'boolean':
+			return raw === 'true'
+		case 'number': {
+			if (raw.trim() === '') return undefined
+			const n = Number(raw)
+			return Number.isNaN(n) ? raw : n
+		}
+		case 'year':
+		case 'month': {
+			if (raw.trim() === '') return undefined
+			const n = Number(raw)
+			return Number.isNaN(n) ? raw : n
+		}
+		default:
+			return raw
+	}
+}
+
+/** Render a native value back to a string for a text/number/date/select control. */
+export function valueToInput(value: unknown): string {
+	if (value === undefined || value === null) return ''
+	if (typeof value === 'string') return value
+	if (typeof value === 'number' || typeof value === 'boolean') return String(value)
+	return JSON.stringify(value)
+}
+
+/** Read a value as a boolean for toggle widgets, tolerating string encodings. */
+export function valueToBoolean(value: unknown): boolean {
+	if (typeof value === 'boolean') return value
+	if (typeof value === 'string') return value === 'true' || value === '1' || value.toLowerCase() === 'yes'
+	return Boolean(value)
+}
+
+/** Read a value as an array of items for repeater widgets. */
+export function valueToArray(value: unknown): unknown[] {
+	return Array.isArray(value) ? value : []
+}
+
+/** Read a value as an object for nested-group widgets. */
+export function valueToObject(value: unknown): Record<string, unknown> {
+	return isRecord(value) ? value : {}
+}
+
+/** Immutably set a top-level frontmatter key in a draft. */
+export function setDraftField(draft: EntryDraft, name: string, value: unknown): EntryDraft {
+	return { ...draft, frontmatter: { ...draft.frontmatter, [name]: value } }
+}

package/src/index.ts

@@ -1,8 +1,9 @@
 /**
- * `@nuasite/collections-admin` — read-only collections SPA over the cms-sidecar
- * `/cms/v1` HTTP contract (cms-headless F3.1). Host-agnostic: mount
- * `<CollectionsAdminApp apiBase={…} />` and it drives its own internal view-state
- * navigation. Self-contained styles ship at `./styles.css` (imported by the app).
+ * `@nuasite/collections-admin` — collections SPA over the cms-sidecar `/cms/v1`
+ * HTTP contract (cms-headless F3.1 read-only + F3.2 editing). Host-agnostic:
+ * mount `<CollectionsAdminApp apiBase={…} />` and it drives its own internal
+ * view-state navigation (list → entries → editor/create), debounced optimistic
+ * save and `409` conflict resolution. Self-contained styles ship at `./styles.css`.
  */
 
 export { CollectionsAdminApp, type CollectionsAdminAppProps } from './app'
@@ -15,10 +16,17 @@ export {
 	type CmsCapabilities,
 	type CmsClient,
 	CmsClientError,
+	type CmsConflict,
 	type CmsEntriesListResult,
 	type CmsErrorCode,
 	type CmsPageEntry,
 	type CmsProjectModel,
 	createClient,
+	type CreateEntryInput,
 	type GetEntriesOptions,
+	isMediaUnavailable,
+	type MediaContext,
+	type UpdateEntryInput,
+	type UpdateEntryResult,
 } from './client'
+export type { EntryDraft } from './form-model'

package/src/media-picker.tsx

@@ -0,0 +1,130 @@
+/**
+ * Media picker widget for `image`/`file`/`astroImage` fields (cms-headless F3.2).
+ *
+ * Holds a single URL string value. Lets the user paste/clear a URL and (when the
+ * sidecar has a media adapter) upload a file via `POST …/media`.
+ *
+ * Graceful degradation: the deployed sidecar may have NO media adapter wired and
+ * answers media routes with `501 unsupported`. The picker probes once via
+ * `listMedia`; on `unsupported`/`501` it disables upload and shows a hint while
+ * keeping the manual URL field fully usable — the editor is never blocked on media.
+ */
+
+import { useEffect, useRef, useState } from 'react'
+import { type CmsClient, isMediaUnavailable } from './client'
+
+interface MediaPickerProps {
+	client: CmsClient
+	value: string
+	collection: string
+	entry?: string
+	field: string
+	accept?: string
+	onChange: (url: string) => void
+}
+
+type MediaState =
+	| { kind: 'probing' }
+	| { kind: 'ready' }
+	| { kind: 'unavailable' }
+	| { kind: 'uploading' }
+	| { kind: 'error'; message: string }
+
+export function MediaPicker({ client, value, collection, entry, field, accept, onChange }: MediaPickerProps) {
+	const [state, setState] = useState<MediaState>({ kind: 'probing' })
+	const fileInputRef = useRef<HTMLInputElement>(null)
+
+	// Probe media availability once. We don't render the gallery (out of scope for
+	// F3.2) — we only need to know whether uploads are supported.
+	useEffect(() => {
+		let active = true
+		client.listMedia({ limit: 1 }).then(
+			() => {
+				if (active) setState({ kind: 'ready' })
+			},
+			(err: unknown) => {
+				if (!active) return
+				setState(isMediaUnavailable(err) ? { kind: 'unavailable' } : { kind: 'ready' })
+			},
+		)
+		return () => {
+			active = false
+		}
+	}, [client])
+
+	const onFile = async (file: File) => {
+		setState({ kind: 'uploading' })
+		try {
+			const result = await client.uploadMedia(file, { collection, entry, field })
+			if (result.success && result.url) {
+				onChange(result.url)
+				setState({ kind: 'ready' })
+			} else {
+				setState({ kind: 'error', message: result.error ?? 'Upload failed' })
+			}
+		} catch (err: unknown) {
+			if (isMediaUnavailable(err)) {
+				setState({ kind: 'unavailable' })
+				return
+			}
+			setState({ kind: 'error', message: err instanceof Error ? err.message : 'Upload failed' })
+		}
+	}
+
+	const looksLikeUrl = value !== '' && /^(https?:\/\/|\/)/.test(value)
+	const canUpload = state.kind === 'ready' || state.kind === 'error'
+
+	return (
+		<div className="nua-cadmin-media">
+			{looksLikeUrl ? <img className="nua-cadmin-img" src={value} alt="" /> : null}
+			<div className="nua-cadmin-media-row">
+				<input
+					type="text"
+					className="nua-cadmin-input"
+					value={value}
+					placeholder="Image URL or path"
+					onChange={e => onChange(e.target.value)}
+				/>
+				{value !== ''
+					? (
+						<button type="button" className="nua-cadmin-icon-btn" aria-label="Clear" onClick={() => onChange('')}>
+							×
+						</button>
+					)
+					: null}
+			</div>
+
+			{state.kind === 'uploading' ? <div className="nua-cadmin-field-loading">Uploading…</div> : null}
+			{state.kind === 'unavailable' ? <div className="nua-cadmin-media-hint">Media uploads unavailable — paste a URL or path instead.</div> : null}
+			{state.kind === 'error' ? <div className="nua-cadmin-media-error">{state.message}</div> : null}
+
+			{canUpload || state.kind === 'probing'
+				? (
+					<>
+						<input
+							ref={fileInputRef}
+							type="file"
+							accept={accept}
+							className="nua-cadmin-file-input"
+							disabled={!canUpload}
+							onChange={e => {
+								const file = e.target.files?.[0]
+								if (file) void onFile(file)
+								// Reset so re-selecting the same file fires `change` again.
+								e.target.value = ''
+							}}
+						/>
+						<button
+							type="button"
+							className="nua-cadmin-add-btn"
+							disabled={!canUpload}
+							onClick={() => fileInputRef.current?.click()}
+						>
+							Upload file
+						</button>
+					</>
+				)
+				: null}
+		</div>
+	)
+}