@nuasite/cms 0.26.0 → 0.28.0

package/src/editor/components/markdown-inline-editor.tsx

@@ -4,7 +4,6 @@ import {
 	commonmark,
 	liftListItemCommand,
 	toggleEmphasisCommand,
-	toggleLinkCommand,
 	toggleStrongCommand,
 	wrapInBlockquoteCommand,
 	wrapInBulletListCommand,
@@ -13,10 +12,12 @@ import {
 import { gfm, toggleStrikethroughCommand } from '@milkdown/preset-gfm'
 import { callCommand, insert, replaceAll } from '@milkdown/utils'
 import { useCallback, useEffect, useRef, useState } from 'preact/hooks'
+import { useLinkPopover } from '../hooks/useLinkPopover'
 import { uploadMedia } from '../markdown-api'
 import { insertMdxComponentCommand, mdxComponentPlugin } from '../milkdown-mdx-plugin'
 import { type ActiveFormats, defaultActiveFormats, isInListType, setupFormatTracking, toggleHeading } from '../milkdown-utils'
 import { config, mdxComponentPickerOpen, openMediaLibraryWithCallback, resetMarkdownEditorState, showToast, updateMarkdownContent } from '../signals'
+import { LinkEditPopover } from './link-edit-popover'
 import { MdxComponentIcon } from './mdx-block-view'
 import { MdxComponentPicker } from './mdx-component-picker'
 
@@ -46,6 +47,15 @@ export function MarkdownInlineEditor({
 
 	// Track active formatting for toolbar highlighting
 	const [activeFormats, setActiveFormats] = useState<ActiveFormats>(defaultActiveFormats)
+	const {
+		linkPopoverState,
+		linkPopoverOpen,
+		closeLinkPopover,
+		toggleLinkPopover,
+		applyLink,
+		removeLink,
+		pageSuggestions,
+	} = useLinkPopover(editorInstanceRef, activeFormats)
 
 	// Store initial content in ref to avoid stale closure issues
 	const initialContentRef = useRef(initialContent)
@@ -202,54 +212,6 @@ export function MarkdownInlineEditor({
 		}
 	}, [runCommand, checkInList])
 
-	const handleInsertLink = useCallback(() => {
-		if (!editorInstanceRef.current) return
-
-		// If already in a link, remove it
-		if (activeFormats.link) {
-			try {
-				// Use toggleLinkCommand with empty href to remove link
-				editorInstanceRef.current.action(
-					callCommand(toggleLinkCommand.key, { href: '' }),
-				)
-				return
-			} catch (error) {
-				console.error('Failed to remove link:', error)
-			}
-		}
-
-		// Get selected text from editor
-		let selectedText = ''
-		try {
-			const view = editorInstanceRef.current.ctx.get(editorViewCtx)
-			const { state } = view
-			const { from, to } = state.selection
-			if (from !== to) {
-				selectedText = state.doc.textBetween(from, to, ' ')
-			}
-		} catch {
-			// Ignore errors
-		}
-
-		// Prompt for URL (pre-fill with existing URL if editing)
-		const defaultUrl = activeFormats.linkHref || ''
-		const url = prompt('Enter URL:', defaultUrl)
-		if (url) {
-			try {
-				// Use toggleLinkCommand to add/update link
-				editorInstanceRef.current.action(
-					callCommand(toggleLinkCommand.key, { href: url }),
-				)
-			} catch (error) {
-				console.error('Failed to add link:', error)
-				// Fallback: use markdown insertion
-				const linkText = selectedText || prompt('Enter link text:', 'Link') || 'Link'
-				const linkMarkdown = `[${linkText}](${url})`
-				editorInstanceRef.current.action(insert(linkMarkdown))
-			}
-		}
-	}, [activeFormats.link, activeFormats.linkHref])
-
 	const handleInsertHeading = useCallback((level: number) => {
 		if (!editorInstanceRef.current) return
 		try {
@@ -575,9 +537,9 @@ export function MarkdownInlineEditor({
 				{/* Links & Images */}
 				<div class="flex items-center gap-0.5">
 					<ToolbarButton
-						onClick={handleInsertLink}
-						title={activeFormats.link ? 'Remove Link' : 'Insert Link'}
-						active={activeFormats.link}
+						onClick={toggleLinkPopover}
+						title={activeFormats.link ? 'Edit Link' : 'Insert Link'}
+						active={activeFormats.link || linkPopoverOpen}
 					>
 						<svg
 							class="w-4 h-4"
@@ -620,6 +582,17 @@ export function MarkdownInlineEditor({
 				</div>
 			</div>
 
+			{/* Link edit popover — rendered outside the toolbar stacking context so it layers above the sidebar */}
+			{linkPopoverState && (
+				<LinkEditPopover
+					initialUrl={linkPopoverState.href}
+					suggestions={pageSuggestions}
+					onApply={applyLink}
+					onRemove={linkPopoverState.isEdit ? removeLink : undefined}
+					onClose={closeLinkPopover}
+				/>
+			)}
+
 			{/* Editor */}
 			<div
 				class={`flex-1 min-h-0 overflow-auto relative transition-colors ${isDragging ? 'bg-cms-primary/10' : ''}`}

package/src/editor/components/mdx-block-view.tsx

@@ -4,18 +4,22 @@ import {
 	commonmark,
 	liftListItemCommand,
 	toggleEmphasisCommand,
-	toggleLinkCommand,
 	toggleStrongCommand,
 	wrapInBlockquoteCommand,
 	wrapInBulletListCommand,
 	wrapInOrderedListCommand,
 } from '@milkdown/preset-commonmark'
 import { gfm, toggleStrikethroughCommand } from '@milkdown/preset-gfm'
-import { callCommand, insert, replaceAll } from '@milkdown/utils'
+import { callCommand, replaceAll } from '@milkdown/utils'
 import type { ComponentChildren } from 'preact'
-import { useCallback, useEffect, useRef, useState } from 'preact/hooks'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'preact/hooks'
+import { useLinkPopover } from '../hooks/useLinkPopover'
+import { getComponentDefinition } from '../manifest'
 import { MDX_EXPR_PREFIX } from '../milkdown-mdx-plugin'
 import { type ActiveFormats, defaultActiveFormats, isInListType, setupFormatTracking, toggleHeading } from '../milkdown-utils'
+import { manifest, openMediaLibraryWithCallback } from '../signals'
+import type { ComponentProp } from '../types'
+import { LinkEditPopover } from './link-edit-popover'
 
 const MDX_COMPONENT_ICON_PATH =
 	'M14 10l-2 1m0 0l-2-1m2 1v2.5M20 7l-2 1m2-1l-2-1m2 1v2.5M14 4l-2-1-2 1M4 7l2-1M4 7l2 1M4 7v2.5M12 21l-2-1m2 1l2-1m-2 1v-2.5M6 18l-2-1v-2.5M18 18l2-1v-2.5'
@@ -75,6 +79,7 @@ function MiniMilkdownEditor({ value, onChange }: { value: string; onChange: (v:
 	const latestMarkdown = useRef(value)
 	const isFocused = useRef(false)
 	const [formats, setFormats] = useState<ActiveFormats>(defaultActiveFormats)
+	const link = useLinkPopover(editorRef, formats)
 
 	useEffect(() => {
 		const el = containerRef.current
@@ -141,18 +146,6 @@ function MiniMilkdownEditor({ value, onChange }: { value: string; onChange: (v:
 		return false
 	}, [])
 
-	const handleLink = useCallback(() => {
-		if (!editorRef.current) return
-		const url = prompt('Enter URL:', 'https://')
-		if (!url) return
-		try {
-			editorRef.current.action(callCommand(toggleLinkCommand.key, { href: url }))
-		} catch {
-			const linkText = window.getSelection()?.toString() || 'Link'
-			editorRef.current.action(insert(`[${linkText}](${url})`))
-		}
-	}, [])
-
 	const handleHeadingToggle = useCallback((level: number) => {
 		if (!editorRef.current) return
 		try {
@@ -239,7 +232,7 @@ function MiniMilkdownEditor({ value, onChange }: { value: string; onChange: (v:
 				<div class="w-px h-4 bg-white/15 mx-0.5" />
 
 				{/* Link */}
-				<MiniToolbarButton onClick={handleLink} title="Link" active={formats.link}>
+				<MiniToolbarButton onClick={link.toggleLinkPopover} title="Link" active={formats.link || link.linkPopoverOpen}>
 					<svg class="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2">
 						<path
 							stroke-linecap="round"
@@ -250,6 +243,19 @@ function MiniMilkdownEditor({ value, onChange }: { value: string; onChange: (v:
 				</MiniToolbarButton>
 			</div>
 
+			{link.linkPopoverState && (
+				<div class="mb-1.5">
+					<LinkEditPopover
+						inline
+						initialUrl={link.linkPopoverState.href}
+						suggestions={link.pageSuggestions}
+						onApply={link.applyLink}
+						onRemove={link.linkPopoverState.isEdit ? link.removeLink : undefined}
+						onClose={link.closeLinkPopover}
+					/>
+				</div>
+			)}
+
 			{/* Editor */}
 			<div
 				ref={(el) => {
@@ -301,6 +307,101 @@ function InlineInput({ value, onChange, placeholder }: { value: string; onChange
 	)
 }
 
+const INLINE_INPUT_TYPES: Record<string, string> = {
+	number: 'number',
+	url: 'url',
+	date: 'date',
+	datetime: 'datetime-local',
+	time: 'time',
+	email: 'email',
+}
+const inputClass =
+	'w-full bg-white/5 border border-white/10 rounded-cms-sm px-2.5 py-1.5 text-[13px] text-white/80 placeholder:text-white/30 outline-none focus:border-white/25 transition-colors'
+
+function InlinePropField(
+	{ name, value, propDef, onChange }: { name: string; value: string; propDef?: ComponentProp; onChange: (v: string) => void },
+) {
+	const typeLower = propDef?.type.toLowerCase() ?? ''
+
+	if (typeLower === 'boolean') {
+		return (
+			<div class="flex items-center gap-2">
+				<label class="text-[11px] text-white/40 font-medium w-20 shrink-0 text-right">{name}</label>
+				<label class="flex items-center gap-2 cursor-pointer py-1">
+					<input
+						type="checkbox"
+						checked={value === 'true'}
+						onChange={(e) => onChange((e.target as HTMLInputElement).checked ? 'true' : 'false')}
+						class="accent-cms-primary w-4 h-4 rounded"
+					/>
+					<span class="text-[12px] text-white/60">{value === 'true' ? 'Yes' : 'No'}</span>
+				</label>
+			</div>
+		)
+	}
+
+	if (typeLower === 'image') {
+		return (
+			<div class="flex items-center gap-2">
+				<label class="text-[11px] text-white/40 font-medium w-20 shrink-0 text-right">{name}</label>
+				<div class="flex gap-1.5 flex-1">
+					<InlineInput value={value} onChange={onChange} placeholder="Select an image..." />
+					<button
+						type="button"
+						onClick={() => openMediaLibraryWithCallback((url: string) => onChange(url))}
+						class="px-2 py-1.5 bg-white/5 border border-white/10 text-white/50 hover:text-white hover:bg-white/10 rounded-cms-sm transition-colors shrink-0"
+						title="Browse media"
+					>
+						<svg class="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2">
+							<path
+								stroke-linecap="round"
+								stroke-linejoin="round"
+								d="M4 16l4.586-4.586a2 2 0 012.828 0L16 16m-2-2l1.586-1.586a2 2 0 012.828 0L20 14m-6-6h.01M6 20h12a2 2 0 002-2V6a2 2 0 00-2-2H6a2 2 0 00-2 2v12a2 2 0 002 2z"
+							/>
+						</svg>
+					</button>
+				</div>
+			</div>
+		)
+	}
+
+	if (typeLower === 'color') {
+		return (
+			<div class="flex items-center gap-2">
+				<label class="text-[11px] text-white/40 font-medium w-20 shrink-0 text-right">{name}</label>
+				<div class="flex gap-1.5 flex-1 items-center">
+					<input
+						type="color"
+						value={value || '#000000'}
+						onInput={(e) => onChange((e.target as HTMLInputElement).value)}
+						class="w-7 h-7 rounded-cms-sm border border-white/10 bg-transparent cursor-pointer shrink-0"
+					/>
+					<InlineInput value={value} onChange={onChange} placeholder="#000000" />
+				</div>
+			</div>
+		)
+	}
+
+	const htmlType = INLINE_INPUT_TYPES[typeLower]
+
+	return (
+		<div class="flex items-center gap-2">
+			<label class="text-[11px] text-white/40 font-medium w-20 shrink-0 text-right">{name}</label>
+			{htmlType
+				? (
+					<input
+						type={htmlType}
+						value={value}
+						onInput={(e) => onChange((e.target as HTMLInputElement).value)}
+						placeholder={`Enter ${name}...`}
+						class={inputClass}
+					/>
+				)
+				: <InlineInput value={value} onChange={onChange} placeholder={`Enter ${name}...`} />}
+		</div>
+	)
+}
+
 // ============================================================================
 // Block Card
 // ============================================================================
@@ -311,6 +412,14 @@ export function MdxBlockCard({ componentName, props, hasExpressions, slotContent
 	const expressionProps = propEntries.filter(([_, v]) => v.startsWith(MDX_EXPR_PREFIX))
 
 	const hasSlotContent = onSlotContentChange != null
+	const definition = getComponentDefinition(manifest.value, componentName)
+	const propTypes = useMemo(() => {
+		const map = new Map<string, ComponentProp>()
+		if (definition?.props) {
+			for (const p of definition.props) map.set(p.name, p)
+		}
+		return map
+	}, [definition])
 
 	const handlePropChange = (name: string, newValue: string) => {
 		if (onPropsChange) {
@@ -320,31 +429,33 @@ export function MdxBlockCard({ componentName, props, hasExpressions, slotContent
 
 	return (
 		<div
-			class="my-3 mx-0 bg-white/5 border border-white/15 rounded-cms-md overflow-hidden select-none"
+			class="my-3 mx-0 bg-white/5 border border-white/15 rounded-cms-md select-none"
 			data-cms-ui
 		>
 			{/* Header */}
-			<div class="flex items-center justify-between px-4 py-2.5 bg-white/5 border-b border-white/10">
+			<div class="flex items-center justify-between px-4 py-2.5 bg-white/5 border-b border-white/10 rounded-t-cms-md">
 				<div class="flex items-center gap-2">
 					<MdxComponentIcon />
 					<span class="text-[13px] font-semibold text-white">{componentName}</span>
 					{hasExpressions && <span class="text-[10px] px-1.5 py-0.5 bg-amber-500/20 text-amber-300 rounded font-mono">expr</span>}
 				</div>
-				<button
-					type="button"
-					data-mdx-action="remove"
-					onClick={onRemove}
-					class="p-1.5 rounded-cms-sm text-white/50 hover:text-red-400 hover:bg-red-500/10 transition-colors"
-					title="Remove block"
-				>
-					<svg class="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2">
-						<path
-							stroke-linecap="round"
-							stroke-linejoin="round"
-							d="M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16"
-						/>
-					</svg>
-				</button>
+				<div class="flex items-center gap-1">
+					<button
+						type="button"
+						data-mdx-action="remove"
+						onClick={onRemove}
+						class="p-1.5 rounded-cms-sm text-white/50 hover:text-red-400 hover:bg-red-500/10 transition-colors"
+						title="Remove block"
+					>
+						<svg class="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2">
+							<path
+								stroke-linecap="round"
+								stroke-linejoin="round"
+								d="M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16"
+							/>
+						</svg>
+					</button>
+				</div>
 			</div>
 
 			{/* Slot content editor */}
@@ -361,14 +472,13 @@ export function MdxBlockCard({ componentName, props, hasExpressions, slotContent
 			{onPropsChange && editableProps.length > 0 && (
 				<div class="px-4 py-3 space-y-2" data-mdx-action="props">
 					{editableProps.map(([name, value]) => (
-						<div key={name} class="flex items-center gap-2">
-							<label class="text-[11px] text-white/40 font-medium w-20 shrink-0 text-right">{name}</label>
-							<InlineInput
-								value={value}
-								onChange={(v) => handlePropChange(name, v)}
-								placeholder={`Enter ${name}...`}
-							/>
-						</div>
+						<InlinePropField
+							key={name}
+							name={name}
+							value={value}
+							propDef={propTypes.get(name)}
+							onChange={(v) => handlePropChange(name, v)}
+						/>
 					))}
 				</div>
 			)}

package/src/editor/hooks/useLinkPopover.ts

@@ -0,0 +1,64 @@
+import type { Editor } from '@milkdown/core'
+import { editorViewCtx } from '@milkdown/core'
+import { toggleLinkCommand, updateLinkCommand } from '@milkdown/preset-commonmark'
+import { callCommand } from '@milkdown/utils'
+import type { RefObject } from 'preact'
+import { useCallback, useMemo, useState } from 'preact/hooks'
+import type { LinkSuggestion } from '../components/link-edit-popover'
+import type { ActiveFormats } from '../milkdown-utils'
+import { removeLinkMark } from '../milkdown-utils'
+import { manifest } from '../signals'
+
+export interface LinkPopoverState {
+	href: string
+	isEdit: boolean
+}
+
+export function useLinkPopover(editorRef: RefObject<Editor | null>, activeFormats: ActiveFormats) {
+	const [linkPopoverState, setLinkPopoverState] = useState<LinkPopoverState | null>(null)
+	const linkPopoverOpen = linkPopoverState !== null
+	const closeLinkPopover = useCallback(() => setLinkPopoverState(null), [])
+
+	const pageSuggestions = useMemo<LinkSuggestion[]>(() =>
+		(manifest.value.pages || []).map(p => ({
+			value: p.pathname,
+			label: p.title || p.pathname,
+			description: p.title ? p.pathname : undefined,
+		})), [manifest.value.pages])
+
+	const toggleLinkPopover = useCallback(() => {
+		if (!editorRef.current) return
+		setLinkPopoverState((prev) => prev !== null ? null : { href: activeFormats.linkHref || 'https://', isEdit: activeFormats.link })
+	}, [activeFormats.link, activeFormats.linkHref, editorRef])
+
+	const applyLink = useCallback((url: string) => {
+		if (!editorRef.current) return
+		const isEdit = linkPopoverState?.isEdit ?? false
+		closeLinkPopover()
+		try {
+			const view = editorRef.current.ctx.get(editorViewCtx)
+			view.focus()
+			if (isEdit) {
+				editorRef.current.action(callCommand(updateLinkCommand.key, { href: url }))
+			} else {
+				editorRef.current.action(callCommand(toggleLinkCommand.key, { href: url }))
+			}
+		} catch (error) {
+			console.error('Failed to apply link:', error)
+		}
+	}, [linkPopoverState, closeLinkPopover, editorRef])
+
+	const removeLink = useCallback(() => {
+		if (!editorRef.current) return
+		closeLinkPopover()
+		try {
+			const view = editorRef.current.ctx.get(editorViewCtx)
+			view.focus()
+			removeLinkMark(view)
+		} catch (error) {
+			console.error('Failed to remove link:', error)
+		}
+	}, [closeLinkPopover, editorRef])
+
+	return { linkPopoverState, linkPopoverOpen, closeLinkPopover, toggleLinkPopover, applyLink, removeLink, pageSuggestions }
+}

package/src/editor/milkdown-mdx-plugin.tsx

@@ -240,6 +240,11 @@ export const mdxComponentView = $view(mdxComponentNode, () => {
 		const renderCard = (node: PmNode) => {
 			const componentName = node.attrs.componentName as string
 			const propsJson = node.attrs.props as string
+
+			// Store attrs on the wrapper so preview mode can read them from copied DOM
+			container.setAttribute('data-mdx-component', componentName)
+			container.setAttribute('data-mdx-props', propsJson)
+			container.setAttribute('data-mdx-children', (node.attrs.children as string) || '')
 			const props: Record<string, string> = JSON.parse(propsJson)
 			const hasExpressions = node.attrs.hasExpressions as boolean
 			const children = (node.attrs.children as string) || ''

package/src/editor/milkdown-utils.ts

@@ -121,6 +121,27 @@ export function toggleHeading(view: EditorView, level: number): void {
 	view.focus()
 }
 
+/**
+ * Remove the link mark around the current cursor position.
+ * Finds the text node with a link mark at/near the selection and dispatches a removeMark transaction.
+ */
+export function removeLinkMark(view: EditorView): void {
+	const { state } = view
+	const { from, to } = state.selection
+	const linkType = state.schema.marks.link
+	if (!linkType) return
+	let linkFrom = from
+	let linkTo = to
+	state.doc.nodesBetween(from, from === to ? to + 1 : to, (node, pos) => {
+		if (linkType.isInSet(node.marks)) {
+			linkFrom = pos
+			linkTo = pos + node.nodeSize
+			return false
+		}
+	})
+	view.dispatch(state.tr.removeMark(linkFrom, linkTo, linkType))
+}
+
 function formatsEqual(a: ActiveFormats, b: ActiveFormats): boolean {
 	return a.bold === b.bold
 		&& a.italic === b.italic

package/src/field-types.ts

@@ -1,47 +1,129 @@
 import { z } from 'astro/zod'
 
 /**
- * Semantic field type schemas for content collections.
+ * Schema helpers for content collections.
  *
- * Each method returns a `z.string()` schema that Astro resolves
- * statically (concrete return type, no generics). The CMS collection
- * scanner detects them by name in the source and renders the
- * appropriate editor input.
+ * Combines Zod passthrough methods with CMS-aware semantic types,
+ * so a content config can import only `n` instead of both `n` and `z`.
  *
- * Chain Zod methods as usual (`.optional()`, `.default()`, etc.).
+ * Pass an options object to configure editor hints and Zod validation
+ * in one place. Chain `.orderBy('asc' | 'desc')` to mark the ordering field.
  *
  * @example
  * ```ts
  * import { n } from '@nuasite/cms'
- * import { z } from 'astro/zod'
  *
- * const schema = z.object({
+ * const schema = n.object({
+ *   title: n.text({ placeholder: "Enter title", maxLength: 120 }),
  *   photo: n.image(),
- *   website: n.url().optional(),
- *   contact: n.email(),
- *   accent: n.color(),
- *   publishedAt: n.date(),
- *   startsAt: n.datetime(),
- *   opensAt: n.time(),
- *   bio: n.textarea(),
+ *   bio: n.textarea({ rows: 4, maxLength: 500 }),
+ *   order: n.number({ min: 1, max: 100, step: 1 }).orderBy('asc'),
+ *   date: n.date().orderBy('desc'),
+ *   tags: n.array(n.string()),
+ *   featured: n.boolean().default(false),
  * })
  * ```
  */
+
+// --- Per-type hint interfaces ---
+
+export interface NumberHints {
+	min?: number
+	max?: number
+	step?: number
+	placeholder?: string
+}
+
+export interface TextHints {
+	placeholder?: string
+	maxLength?: number
+	minLength?: number
+}
+
+export interface TextareaHints {
+	placeholder?: string
+	maxLength?: number
+	rows?: number
+}
+
+export interface DateHints {
+	min?: string
+	max?: string
+}
+
+export interface ImageHints {
+	accept?: string
+}
+
+// --- Internals ---
+
+type OrderByDirection = 'asc' | 'desc'
+type WithOrderBy<T> = T & { orderBy(direction?: OrderByDirection): T }
+
+/** Normalize YAML Date objects to ISO date strings (YYYY-MM-DD) */
+const toISODate = (v: unknown) => (v instanceof Date ? v.toISOString().slice(0, 10) : v)
+/** Normalize YAML Date objects to ISO datetime strings */
+const toISODatetime = (v: unknown) => (v instanceof Date ? v.toISOString() : v)
+
+/** Add a chainable `.orderBy()` method to a Zod schema. The scanner detects it from source code. */
+function withOrderBy<T extends z.ZodTypeAny>(schema: T): WithOrderBy<T> {
+	const s = schema as WithOrderBy<T>
+	s.orderBy = (_direction?: OrderByDirection) => schema
+	return s
+}
+
+/** Build a CMS string field with optional length validation. Shared by text, url, email, textarea. */
+function stringField(cmsType: string, hints?: { minLength?: number; maxLength?: number }) {
+	let schema = z.string()
+	if (hints?.minLength != null) schema = schema.min(hints.minLength)
+	if (hints?.maxLength != null) schema = schema.max(hints.maxLength)
+	return withOrderBy(schema.describe(`cms:${cmsType}`))
+}
+
 export const n = {
-	/** Image picker (opens media library) */
-	image: () => z.string().describe('cms:image'),
+	// --- Zod passthroughs ---
+	/** Object schema */
+	object: <T extends z.ZodRawShape>(shape: T) => z.object(shape),
+	/** Array schema */
+	array: <T extends z.ZodTypeAny>(schema: T) => z.array(schema),
+	/** Enum schema */
+	enum: <U extends string, T extends [U, ...U[]]>(values: T) => z.enum(values),
+	/** Coerce namespace — parses input into the target type */
+	coerce: {
+		date: () => withOrderBy(z.coerce.date()),
+		number: () => withOrderBy(z.coerce.number()),
+		string: () => withOrderBy(z.coerce.string()),
+		boolean: () => withOrderBy(z.coerce.boolean()),
+	},
+
+	// --- CMS semantic types ---
+	/** Boolean / checkbox */
+	boolean: () => withOrderBy(z.boolean().describe('cms:checkbox')),
+	/** Number input with optional min/max/step */
+	number: (hints?: NumberHints) => {
+		let schema = z.number()
+		if (hints?.min != null) schema = schema.min(hints.min)
+		if (hints?.max != null) schema = schema.max(hints.max)
+		return withOrderBy(schema.describe('cms:number'))
+	},
+	/** Image picker (opens media library). Accepts hints for the scanner; no Zod validation applied. */
+	image: (_hints?: ImageHints) => withOrderBy(z.string().describe('cms:image')),
 	/** URL input */
-	url: () => z.string().describe('cms:url'),
+	url: (hints?: TextHints) => stringField('url', hints),
 	/** Email input */
-	email: () => z.string().describe('cms:email'),
+	email: (hints?: TextHints) => stringField('email', hints),
 	/** Color picker */
-	color: () => z.string().describe('cms:color'),
-	/** Date picker */
-	date: () => z.string().describe('cms:date'),
-	/** Date + time picker */
-	datetime: () => z.string().describe('cms:datetime'),
-	/** Time picker */
-	time: () => z.string().describe('cms:time'),
+	color: () => withOrderBy(z.string().describe('cms:color')),
+	/** Date picker (handles YAML Date coercion → ISO date string). Accepts hints for the scanner; no Zod validation applied. */
+	date: (_hints?: DateHints) => withOrderBy(z.preprocess(toISODate, z.string()).describe('cms:date')),
+	/** Date + time picker (handles YAML Date coercion → ISO datetime string). Accepts hints for the scanner; no Zod validation applied. */
+	datetime: (_hints?: DateHints) => withOrderBy(z.preprocess(toISODatetime, z.string()).describe('cms:datetime')),
+	/** Time picker. Accepts hints for the scanner; no Zod validation applied. */
+	time: (_hints?: DateHints) => withOrderBy(z.string().describe('cms:time')),
 	/** Multiline textarea */
-	textarea: () => z.string().describe('cms:textarea'),
+	textarea: (hints?: TextareaHints) => stringField('textarea', hints),
+	/** Text input */
+	text: (hints?: TextHints) => stringField('text', hints),
+	/** Plain string (no CMS type hint — type inferred from values) */
+	string: () => withOrderBy(z.string()),
 }