@quoin-cms/admin 0.1.0

package/src/lib/router/matcher.ts

@@ -0,0 +1,52 @@
+/**
+ * Tiny path pattern matcher — no dependency, no regex in callers.
+ *
+ *   pattern "/collections/:slug"             matches  "/collections/posts"
+ *   pattern "/collections/:slug/records/:id" matches  "/collections/posts/records/123"
+ *   pattern "/pages/*"                       matches  "/pages/anything/nested"
+ *
+ * Named segments `:name` capture into `params.name`. A trailing `*` captures
+ * the remainder into `params.rest`.
+ */
+
+export interface RoutePattern {
+	pattern: string
+}
+
+export interface RouteMatch {
+	params: Record<string, string>
+}
+
+export function matchRoute(path: string, route: RoutePattern): RouteMatch | null {
+	const patternParts = splitPath(route.pattern)
+	const pathParts = splitPath(path)
+
+	const params: Record<string, string> = {}
+
+	for (let i = 0; i < patternParts.length; i++) {
+		const pp = patternParts[i]
+
+		if (pp === '*') {
+			params.rest = pathParts.slice(i).join('/')
+			return { params }
+		}
+
+		const pathSeg = pathParts[i]
+		if (pathSeg === undefined) return null
+
+		if (pp.startsWith(':')) {
+			params[pp.slice(1)] = decodeURIComponent(pathSeg)
+			continue
+		}
+
+		if (pp !== pathSeg) return null
+	}
+
+	// Exact length match (no trailing pattern segments, no leftover path segments).
+	if (patternParts.length !== pathParts.length) return null
+	return { params }
+}
+
+function splitPath(p: string): string[] {
+	return p.split('/').filter(Boolean)
+}

package/src/lib/stores/branding.svelte.ts

@@ -0,0 +1,74 @@
+import { getGlobal } from '$lib/api/globals.js'
+import { getQuoinContext } from '$lib/context.svelte.js'
+
+/**
+ * Reactive branding store.
+ *
+ * Source precedence (later overrides earlier):
+ *   1. Library fallback ("Quoin", no logo)
+ *   2. Consumer's `admin.config.ts` → config.brand
+ *   3. site-settings global in Postgres (via loadBranding())
+ *
+ * Layer 3 lets operators edit the site name / logo through the admin UI
+ * itself without redeploying. Layer 2 is for defaults that ship with the
+ * consumer's build.
+ */
+interface Branding {
+	siteName: string
+	logoUrl: string | null
+	faviconUrl: string | null
+}
+
+export const branding = $state<Branding>({
+	siteName: 'Quoin',
+	logoUrl: null,
+	faviconUrl: null,
+})
+
+let loaded = false
+
+/**
+ * Seed the branding store from the quoin context (config.brand). Call once
+ * from AdminRoot right after context is set, before site-settings load.
+ */
+export function seedBrandingFromConfig(): void {
+	try {
+		const ctx = getQuoinContext()
+		if (ctx.config.brand.name) branding.siteName = ctx.config.brand.name
+		if (ctx.config.brand.logo) branding.logoUrl = ctx.config.brand.logo
+	} catch {
+		// Context not yet set — caller should have seeded after setQuoinContext().
+	}
+}
+
+/**
+ * Fetch branding overrides from site-settings global. Called once on admin
+ * app mount. Falls back silently if site-settings isn't present or the
+ * consumer's schema doesn't define it.
+ */
+export async function loadBranding(): Promise<void> {
+	if (loaded) return
+	loaded = true
+
+	const result = await getGlobal('site-settings')
+	if (!result.ok) return
+
+	const data = result.data ?? {}
+
+	if (typeof data.siteName === 'string' && data.siteName.trim()) {
+		branding.siteName = data.siteName.trim()
+	}
+
+	// Logo is a file field — returns { url, filename } object or null
+	if (data.logo && typeof data.logo === 'object' && typeof data.logo.url === 'string') {
+		branding.logoUrl = data.logo.url
+	} else if (typeof data.logo === 'string' && data.logo) {
+		branding.logoUrl = data.logo
+	}
+
+	if (data.favicon && typeof data.favicon === 'object' && typeof data.favicon.url === 'string') {
+		branding.faviconUrl = data.favicon.url
+	} else if (typeof data.favicon === 'string' && data.favicon) {
+		branding.faviconUrl = data.favicon
+	}
+}

package/src/lib/stores/schema.svelte.ts

@@ -0,0 +1,17 @@
+import type { CollectionSchema, GlobalSchema } from '$lib/types/schema.js'
+
+export interface SchemaData {
+	collections: CollectionSchema[]
+	globals: GlobalSchema[]
+}
+
+// Module-level reactive state — shared across all components.
+// This avoids Svelte context timing issues entirely.
+export const schema: SchemaData = $state({ collections: [], globals: [] })
+
+export function getCollectionByKey(
+	collections: CollectionSchema[],
+	key: string
+): CollectionSchema | undefined {
+	return collections.find((c) => c.key === key)
+}

package/src/lib/types/schema.ts

@@ -0,0 +1,126 @@
+export type FieldType =
+	| 'text'
+	| 'textarea'
+	| 'number'
+	| 'email'
+	| 'select'
+	| 'checkbox'
+	| 'date'
+	| 'richtext'
+	| 'relationship'
+	| 'file'
+	| 'upload'
+	| 'slug'
+	| 'color'
+	| 'json'
+	| 'tags'
+	| 'tabs'
+	| 'row'
+	| 'url'
+	| 'uuid'
+
+export interface FieldSchema {
+	name: string
+	type: FieldType
+	label: string
+	required: boolean
+	hidden?: boolean
+	/** Sub-variant for text fields (e.g. "password"). Phase 21 D-06.
+	 * Emitted by field.Text.ToJSON() when Text.Type != "". */
+	variant?: string
+	// Text/Textarea
+	minLength?: number
+	maxLength?: number
+	pattern?: string
+	defaultValue?: any
+	unique?: boolean
+	indexed?: boolean
+	// Number
+	min?: number
+	max?: number
+	integerOnly?: boolean
+	// Select
+	options?: { value: string; label: string }[]
+	// Relationship / Upload
+	relatesTo?: string
+	relationType?: 'belongsTo' | 'manyToMany'
+	/** Discriminator emitted by field.Upload.ToJSON; absent for plain field.Relationship. */
+	_upload?: boolean
+	// File
+	multiple?: boolean
+	accept?: string[]
+	maxSizeKB?: number
+	maxFiles?: number
+	// Slug
+	fromField?: string
+	// Tags
+	maxItems?: number
+	// Visual grouping
+	group?: string
+	// Tabs (only when type === 'tabs')
+	tabs?: { label: string; fields: FieldSchema[] }[]
+	// Row (only when type === 'row') — children rendered side-by-side
+	fields?: FieldSchema[]
+}
+
+export interface TabsFieldSchema extends FieldSchema {
+	type: 'tabs'
+	tabs: { label: string; fields: FieldSchema[] }[]
+}
+
+export interface VersionsSchema {
+	maxPerDoc: number
+	drafts?: {
+		autosave?: { interval: number }
+		validate?: boolean
+		schedulePublish?: boolean
+	}
+}
+
+export interface AdminConfig {
+	useAsTitle?: string
+	defaultColumns?: string[]
+	defaultSort?: string
+	group?: string
+	sidebarFields?: string[]
+	description?: string
+}
+
+export interface CollectionSchema {
+	key: string
+	label: string
+	labelPlural?: string
+	fields: FieldSchema[]
+	admin?: AdminConfig
+	versions?: VersionsSchema
+}
+
+export interface GlobalSchema {
+	key: string
+	label: string
+	fields: FieldSchema[]
+}
+
+export interface SchemaResponse {
+	collections: CollectionSchema[]
+	globals: GlobalSchema[]
+}
+
+export interface PaginatedResponse<T> {
+	records: T[]
+	page: number
+	perPage: number
+	totalRecords: number
+	totalPages: number
+}
+
+export interface AuthUser {
+	id: string
+	username: string
+	role: string
+}
+
+export interface ApiError {
+	error: string
+	details?: Record<string, string>
+}

package/src/lib/utils/cn.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs))
+}

package/src/lib/utils/diff.ts

@@ -0,0 +1,112 @@
+export interface DiffSegment {
+	type: 'equal' | 'add' | 'delete'
+	value: string
+}
+
+export function valuesEqual(a: unknown, b: unknown): boolean {
+	if (a === b) return true
+	if (a == null && b == null) return true
+	if (a == null || b == null) return false
+	if (typeof a === 'object' && typeof b === 'object') {
+		return JSON.stringify(a) === JSON.stringify(b)
+	}
+	return false
+}
+
+export function toStringValue(val: unknown): string {
+	if (val == null) return ''
+	if (typeof val === 'boolean') return val ? 'true' : 'false'
+	if (Array.isArray(val)) return val.join(', ')
+
+	// JSON string — try to parse and re-process
+	if (typeof val === 'string' && val.startsWith('{')) {
+		try {
+			const parsed = JSON.parse(val)
+			return toStringValue(parsed)
+		} catch {
+			return val
+		}
+	}
+
+	if (typeof val === 'object') {
+		const obj = val as Record<string, any>
+		// Lexical/TipTap richtext: extract plain text from node tree
+		if (obj.root && obj.root.children) {
+			return extractTextFromNodes(obj.root.children)
+		}
+		// File object: show filename
+		if (obj.url && obj.filename) return obj.filename
+		if (obj.url) return obj.url
+		return JSON.stringify(val, null, 2)
+	}
+	return String(val)
+}
+
+function extractTextFromNodes(nodes: any[]): string {
+	const lines: string[] = []
+	for (const node of nodes) {
+		if (node.text) {
+			lines.push(node.text)
+		} else if (node.children) {
+			const childText = extractTextFromNodes(node.children)
+			if (childText) lines.push(childText)
+		}
+	}
+	return lines.join('\n')
+}
+
+function tokenize(str: string): string[] {
+	return str.match(/\S+|\s+/g) ?? []
+}
+
+export function diffWords(oldStr: string, newStr: string): DiffSegment[] {
+	const oldTokens = tokenize(oldStr)
+	const newTokens = tokenize(newStr)
+	const oldLen = oldTokens.length
+	const newLen = newTokens.length
+
+	// Build LCS matrix
+	const dp: number[][] = Array.from({ length: oldLen + 1 }, () => Array(newLen + 1).fill(0))
+	for (let i = 1; i <= oldLen; i++) {
+		for (let j = 1; j <= newLen; j++) {
+			if (oldTokens[i - 1] === newTokens[j - 1]) {
+				dp[i][j] = dp[i - 1][j - 1] + 1
+			} else {
+				dp[i][j] = Math.max(dp[i - 1][j], dp[i][j - 1])
+			}
+		}
+	}
+
+	// Backtrack
+	const segments: DiffSegment[] = []
+	let i = oldLen
+	let j = newLen
+
+	const raw: DiffSegment[] = []
+	while (i > 0 || j > 0) {
+		if (i > 0 && j > 0 && oldTokens[i - 1] === newTokens[j - 1]) {
+			raw.push({ type: 'equal', value: oldTokens[i - 1] })
+			i--
+			j--
+		} else if (j > 0 && (i === 0 || dp[i][j - 1] >= dp[i - 1][j])) {
+			raw.push({ type: 'add', value: newTokens[j - 1] })
+			j--
+		} else {
+			raw.push({ type: 'delete', value: oldTokens[i - 1] })
+			i--
+		}
+	}
+
+	raw.reverse()
+
+	// Merge consecutive same-type segments
+	for (const seg of raw) {
+		if (segments.length > 0 && segments[segments.length - 1].type === seg.type) {
+			segments[segments.length - 1].value += seg.value
+		} else {
+			segments.push({ ...seg })
+		}
+	}
+
+	return segments
+}

package/src/lib/utils/dirty.svelte.ts

@@ -0,0 +1,50 @@
+import { onMount } from 'svelte'
+import { beforeNavigate } from '$lib/router/index.svelte.js'
+
+function deepEqual(a: unknown, b: unknown): boolean {
+	if (a === b) return true
+	if (typeof a !== typeof b) return false
+	if (a === null || b === null) return false
+	if (typeof a !== 'object') return false
+	const ak = Object.keys(a as object)
+	const bk = Object.keys(b as object)
+	if (ak.length !== bk.length) return false
+	for (const k of ak) {
+		if (!deepEqual((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k])) return false
+	}
+	return true
+}
+
+export function useDirtyState<T extends Record<string, unknown>>(
+	getCurrent: () => T,
+	getInitial: () => T
+) {
+	const isDirty = $derived.by(() => !deepEqual(getCurrent(), getInitial()))
+	let bypass = false
+
+	onMount(() => {
+		function handler(e: BeforeUnloadEvent) {
+			if (!isDirty || bypass) return
+			e.preventDefault()
+			e.returnValue = ''
+		}
+		window.addEventListener('beforeunload', handler)
+		return () => window.removeEventListener('beforeunload', handler)
+	})
+
+	beforeNavigate(({ cancel }) => {
+		if (bypass) return
+		if (isDirty && !confirm('You have unsaved changes. Leave anyway?')) {
+			cancel()
+		}
+	})
+
+	return {
+		get isDirty() {
+			return isDirty
+		},
+		allowNavigation() {
+			bypass = true
+		},
+	}
+}

package/src/lib/utils/format.ts

@@ -0,0 +1,28 @@
+export function formatDate(dateStr: string): string {
+	if (!dateStr) return ''
+	try {
+		const date = new Date(dateStr)
+		return date.toLocaleDateString('en-US', {
+			year: 'numeric',
+			month: 'short',
+			day: 'numeric',
+			hour: '2-digit',
+			minute: '2-digit',
+		})
+	} catch {
+		return dateStr
+	}
+}
+
+export function formatFileSize(bytes: number): string {
+	if (bytes === 0) return '0 B'
+	const k = 1024
+	const sizes = ['B', 'KB', 'MB', 'GB']
+	const i = Math.floor(Math.log(bytes) / Math.log(k))
+	return `${parseFloat((bytes / k ** i).toFixed(1))} ${sizes[i]}`
+}
+
+export function truncate(str: string, maxLength: number = 50): string {
+	if (!str || str.length <= maxLength) return str || ''
+	return `${str.slice(0, maxLength)}...`
+}

package/src/lib/utils/json-highlight.ts

@@ -0,0 +1,34 @@
+// Tiny JSON syntax highlighter — returns an HTML string with span wrappers.
+// No external deps. Use for read-only display only (assumes input is valid JSON).
+const ESC: Record<string, string> = {
+	'&': '&amp;',
+	'<': '&lt;',
+	'>': '&gt;',
+	'"': '&quot;',
+	"'": '&#39;',
+}
+
+function escape(s: string): string {
+	return s.replace(/[&<>"']/g, (c) => ESC[c])
+}
+
+export function highlightJson(json: string): string {
+	const tokenRE =
+		/("(?:\\.|[^"\\])*"\s*:?)|\b(true|false|null)\b|(-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)/g
+	const escaped = escape(json)
+	return escaped.replace(tokenRE, (match) => {
+		if (match.startsWith('"')) {
+			if (match.trimEnd().endsWith(':')) {
+				return `<span class="text-amber-700">${match}</span>`
+			}
+			return `<span class="text-emerald-700">${match}</span>`
+		}
+		if (match === 'true' || match === 'false') {
+			return `<span class="text-blue-700">${match}</span>`
+		}
+		if (match === 'null') {
+			return `<span class="text-stone-500">${match}</span>`
+		}
+		return `<span class="text-violet-700">${match}</span>`
+	})
+}

package/src/lib/utils/slug.ts

@@ -0,0 +1,8 @@
+export function slugify(text: string): string {
+	return text
+		.toLowerCase()
+		.replace(/[^\w\s-]/g, '')
+		.replace(/[\s_]+/g, '-')
+		.replace(/^-+|-+$/g, '')
+		.trim()
+}

package/src/main.ts

@@ -0,0 +1,32 @@
+import { mount } from 'svelte'
+import AdminRoot from './AdminRoot.svelte'
+import { setBasePath, startRouter } from './lib/router/index.svelte.js'
+import './app.css'
+
+/**
+ * Svelte SPA entry point. Boots the client-side router and mounts AdminRoot.
+ *
+ * Config comes from virtual modules injected by @quoin-cms/cli's Vite plugin:
+ *   - `virtual:quoin-config`      → ResolvedQuoinConfig
+ *   - `virtual:quoin-import-map`  → { [absPath]: () => import(absPath) }
+ *
+ * When the admin package is run standalone (from inside @quoin-cms/admin for
+ * library development), the library's own vite.config.ts provides stub
+ * modules so `pnpm dev` still works against a local Go backend.
+ */
+
+// @ts-expect-error — virtual module resolved by @quoin-cms/cli / vite plugin
+import config from 'virtual:quoin-config'
+// @ts-expect-error — virtual module resolved by @quoin-cms/cli / vite plugin
+import importMap from 'virtual:quoin-import-map'
+
+setBasePath(config.basePath)
+startRouter()
+
+const target = document.getElementById('app')
+if (!target) throw new Error('#app mount target not found in index.html')
+
+mount(AdminRoot, {
+	target,
+	props: { config, importMap },
+})

package/src/views/AdminLayout.svelte

@@ -0,0 +1,73 @@
+<script lang="ts">
+import { goto } from '$lib/router/index.svelte.js'
+import { resolve } from '$lib/router/index.svelte.js'
+import { getMe } from '$lib/api/auth.js'
+import { fetchSchema } from '$lib/api/schema.js'
+import { schema } from '$lib/stores/schema.svelte.js'
+import { loadBranding } from '$lib/stores/branding.svelte.js'
+import AdminSidebar from '$lib/components/AdminSidebar.svelte'
+import AdminHeader from '$lib/components/AdminHeader.svelte'
+import { onMount } from 'svelte'
+import { page } from '$lib/router/index.svelte.js'
+import type { AuthUser } from '$lib/types/schema.js'
+import { BookOpen } from 'lucide-svelte'
+
+let { children } = $props()
+
+let isDocPage = $derived(/^\/(admin\/)?[^/]+\/(new|[^/]+)$/.test(page.url.pathname.replace(/^\/admin/, '')))
+
+let isLoading = $state(true)
+let user = $state<AuthUser | null>(null)
+let sidebarOpen = $state(true)
+
+onMount(async () => {
+	const meResult = await getMe()
+	if (!meResult.ok) {
+		await goto(resolve('/login'))
+		return
+	}
+	user = meResult.data
+
+	const schemaResult = await fetchSchema()
+	if (!schemaResult.ok) {
+		await goto(resolve('/login'))
+		return
+	}
+	schema.collections = schemaResult.data.collections
+	schema.globals = schemaResult.data.globals
+
+	// Fetch branding (logo, site name) from site-settings global
+	loadBranding()
+
+	isLoading = false
+})
+</script>
+
+{#if isLoading}
+  <div class="flex h-screen flex-col items-center justify-center gap-4 bg-background">
+    <div class="flex items-center gap-3">
+      <div class="flex h-10 w-10 items-center justify-center rounded-xl bg-primary/10">
+        <BookOpen class="h-5 w-5 text-primary animate-spin-slow" />
+      </div>
+    </div>
+    <p class="text-sm text-muted-foreground">Loading admin panel...</p>
+  </div>
+{:else}
+  <div class="flex h-screen overflow-hidden bg-background">
+    <AdminSidebar collections={schema.collections} globals={schema.globals} {user} bind:open={sidebarOpen} />
+    <div class="flex flex-1 flex-col overflow-hidden">
+      {#if !isDocPage}
+        <AdminHeader collections={schema.collections} globals={schema.globals} bind:sidebarOpen />
+      {/if}
+      <main class="flex-1 overflow-y-auto {isDocPage ? '' : 'p-6'}">
+        {#if isDocPage}
+          {@render children()}
+        {:else}
+          <div class="mx-auto max-w-7xl animate-fade-in">
+            {@render children()}
+          </div>
+        {/if}
+      </main>
+    </div>
+  </div>
+{/if}