@quoin-cms/admin 0.1.0

package/src/lib/api/client.ts

@@ -0,0 +1,73 @@
+export type ApiResult<T> =
+	| { ok: true; data: T }
+	| { ok: false; error: string; details?: Record<string, string>; status: number }
+
+async function request<T>(path: string, options: RequestInit = {}): Promise<ApiResult<T>> {
+	const url = `/api${path}`
+	const res = await fetch(url, {
+		...options,
+		credentials: 'include',
+		headers: {
+			...(options.body && typeof options.body === 'string'
+				? { 'Content-Type': 'application/json' }
+				: {}),
+			...options.headers,
+		},
+	})
+
+	if (!res.ok) {
+		try {
+			const err = await res.json()
+			return {
+				ok: false,
+				error: err.error || 'Request failed',
+				details: err.details,
+				status: res.status,
+			}
+		} catch {
+			return {
+				ok: false,
+				error: `Request failed with status ${res.status}`,
+				status: res.status,
+			}
+		}
+	}
+
+	// Handle 204 No Content
+	if (res.status === 204) {
+		return { ok: true, data: undefined as T }
+	}
+
+	const data = await res.json()
+	return { ok: true, data }
+}
+
+export function get<T>(path: string): Promise<ApiResult<T>> {
+	return request<T>(path)
+}
+
+export function post<T>(path: string, body?: unknown): Promise<ApiResult<T>> {
+	return request<T>(path, {
+		method: 'POST',
+		body: body !== undefined ? JSON.stringify(body) : undefined,
+	})
+}
+
+export function put<T>(path: string, body: unknown): Promise<ApiResult<T>> {
+	return request<T>(path, {
+		method: 'PUT',
+		body: JSON.stringify(body),
+	})
+}
+
+export function del<T>(path: string): Promise<ApiResult<T>> {
+	return request<T>(path, { method: 'DELETE' })
+}
+
+export function upload<T>(path: string, formData: FormData): Promise<ApiResult<T>> {
+	return request<T>(path, {
+		method: 'POST',
+		body: formData,
+		// Don't set Content-Type for FormData -- browser sets it with boundary
+	})
+}

package/src/lib/api/files.ts

@@ -0,0 +1,56 @@
+import { upload, type ApiResult } from './client.js'
+
+export interface UploadResult {
+	url: string
+	filename: string
+	mimeType: string
+	size: number
+}
+
+export function uploadFile(file: File): Promise<ApiResult<UploadResult>> {
+	const formData = new FormData()
+	formData.append('file', file)
+	return upload<UploadResult>('/upload/media', formData)
+}
+
+/**
+ * UploadRecord is a record returned by `POST /api/upload/{collection}`.
+ * Combines the auto-injected upload metadata (url, filename, mimeType, size,
+ * width?, height?) with whatever user-declared fields the upload collection
+ * carries (alt, caption, etc.). The shape varies per collection — only
+ * the metadata fields are guaranteed.
+ */
+export interface UploadRecord {
+	id: string
+	url: string
+	filename: string
+	mimeType: string
+	size: number
+	width?: number
+	height?: number
+	[k: string]: unknown
+}
+
+export interface UploadToCollectionOptions {
+	/** Optional user-metadata form fields to include alongside `file`. */
+	extra?: Record<string, string>
+}
+
+/**
+ * POST /api/upload/{collection} — multipart upload into an upload-flagged
+ * collection. The server persists bytes via the storage adapter, then
+ * creates a record with auto-injected metadata + any `extra` form fields.
+ * Returns the freshly-created record.
+ */
+export function uploadToCollection(
+	collection: string,
+	file: File,
+	opts: UploadToCollectionOptions = {},
+): Promise<ApiResult<UploadRecord>> {
+	const fd = new FormData()
+	fd.append('file', file)
+	for (const [k, v] of Object.entries(opts.extra ?? {})) {
+		fd.append(k, v)
+	}
+	return upload<UploadRecord>(`/upload/${encodeURIComponent(collection)}`, fd)
+}

package/src/lib/api/globals.ts

@@ -0,0 +1,13 @@
+import { get, put } from './client.js'
+import type { ApiResult } from './client.js'
+
+export function getGlobal(key: string): Promise<ApiResult<Record<string, any>>> {
+	return get<Record<string, any>>(`/globals/${key}`)
+}
+
+export function updateGlobal(
+	key: string,
+	data: Record<string, any>
+): Promise<ApiResult<Record<string, any>>> {
+	return put<Record<string, any>>(`/globals/${key}`, data)
+}

package/src/lib/api/records.ts

@@ -0,0 +1,102 @@
+import { get, post, put, del } from './client.js'
+import type { PaginatedResponse } from '$lib/types/schema.js'
+import type { ApiResult } from './client.js'
+
+export interface ListParams {
+	page?: number
+	perPage?: number
+	sort?: string
+	filter?: string
+	search?: string
+	expand?: string
+	fields?: string
+}
+
+export function listRecords(
+	key: string,
+	params: ListParams = {}
+): Promise<ApiResult<PaginatedResponse<Record<string, any>>>> {
+	const searchParams = new URLSearchParams()
+	if (params.page) searchParams.set('page', String(params.page))
+	if (params.perPage) searchParams.set('perPage', String(params.perPage))
+	if (params.sort) searchParams.set('sort', params.sort)
+	if (params.filter) searchParams.set('filter', params.filter)
+	if (params.search) searchParams.set('search', params.search)
+	if (params.expand) searchParams.set('expand', params.expand)
+	if (params.fields) searchParams.set('fields', params.fields)
+
+	const qs = searchParams.toString()
+	return get<PaginatedResponse<Record<string, any>>>(
+		`/collections/${key}/records${qs ? `?${qs}` : ''}`
+	)
+}
+
+export function getRecord(
+	key: string,
+	id: string,
+	expand?: string,
+	opts?: { draft?: boolean }
+): Promise<ApiResult<Record<string, any>>> {
+	const params = new URLSearchParams()
+	if (expand) params.set('expand', expand)
+	if (opts?.draft) params.set('draft', 'true')
+	const qs = params.toString()
+	return get<Record<string, any>>(`/collections/${key}/records/${id}${qs ? '?' + qs : ''}`)
+}
+
+export function createRecord(
+	key: string,
+	data: Record<string, any>,
+	opts?: { draft?: boolean; autosave?: boolean }
+): Promise<ApiResult<Record<string, any>>> {
+	const params = new URLSearchParams()
+	if (opts?.draft) params.set('draft', 'true')
+	if (opts?.autosave) params.set('autosave', 'true')
+	const qs = params.toString()
+	return post<Record<string, any>>(`/collections/${key}/records${qs ? '?' + qs : ''}`, data)
+}
+
+export function updateRecord(
+	key: string,
+	id: string,
+	data: Record<string, any>,
+	opts?: { draft?: boolean; autosave?: boolean }
+): Promise<ApiResult<Record<string, any>>> {
+	const params = new URLSearchParams()
+	if (opts?.draft) params.set('draft', 'true')
+	if (opts?.autosave) params.set('autosave', 'true')
+	const qs = params.toString()
+	return put<Record<string, any>>(`/collections/${key}/records/${id}${qs ? '?' + qs : ''}`, data)
+}
+
+export function deleteRecord(key: string, id: string): Promise<ApiResult<void>> {
+	return del<void>(`/collections/${key}/records/${id}`)
+}
+
+export function unpublishRecord(
+	key: string,
+	id: string,
+): Promise<ApiResult<Record<string, any>>> {
+	return post<Record<string, any>>(`/collections/${key}/records/${id}/unpublish`, {})
+}
+
+export interface LockInfo {
+	locked: boolean
+	lock?: {
+		userId: string
+		userName: string
+		lockedAt: string
+	}
+}
+
+export function acquireLock(key: string, id: string): Promise<ApiResult<LockInfo>> {
+	return post<LockInfo>(`/collections/${key}/records/${id}/lock`, {})
+}
+
+export function releaseLock(key: string, id: string): Promise<ApiResult<void>> {
+	return del<void>(`/collections/${key}/records/${id}/lock`)
+}
+
+export function checkLockStatus(key: string, id: string): Promise<ApiResult<LockInfo>> {
+	return get<LockInfo>(`/collections/${key}/records/${id}/lock`)
+}

package/src/lib/api/schema.ts

@@ -0,0 +1,7 @@
+import { get } from './client.js'
+import type { SchemaResponse } from '$lib/types/schema.js'
+import type { ApiResult } from './client.js'
+
+export function fetchSchema(): Promise<ApiResult<SchemaResponse>> {
+	return get<SchemaResponse>('/_schema')
+}

package/src/lib/api/versions.ts

@@ -0,0 +1,40 @@
+import { get, post, type ApiResult } from './client.js'
+
+export interface Version {
+	id: string
+	parent: string
+	version: Record<string, any>
+	_status?: string
+	latest?: boolean
+	createdAt: string
+	updatedAt: string
+}
+
+export function listVersions(
+	collection: string,
+	recordId: string,
+	params?: { page?: number; limit?: number },
+): Promise<ApiResult<{ versions: Version[]; totalRecords: number }>> {
+	const qs = new URLSearchParams()
+	if (params?.page) qs.set('page', String(params.page))
+	if (params?.limit) qs.set('limit', String(params.limit))
+	const suffix = qs.toString() ? `?${qs.toString()}` : ''
+	return get<{ versions: Version[]; totalRecords: number }>(`/collections/${collection}/records/${recordId}/versions${suffix}`)
+}
+
+export function getVersion(
+	collection: string,
+	recordId: string,
+	versionId: string,
+): Promise<ApiResult<Version>> {
+	return get<Version>(`/collections/${collection}/records/${recordId}/versions/${versionId}`)
+}
+
+export function restoreVersion(
+	collection: string,
+	recordId: string,
+	versionId: string,
+	asDraft = true,
+): Promise<ApiResult<Record<string, any>>> {
+	return post<Record<string, any>>(`/collections/${collection}/records/${recordId}/versions/${versionId}/restore?draft=${asDraft}`, {})
+}

package/src/lib/components/AdminHeader.svelte

@@ -0,0 +1,107 @@
+<script lang="ts">
+import { page } from '$lib/router/index.svelte.js'
+import { resolve } from '$lib/router/index.svelte.js'
+import type { CollectionSchema, GlobalSchema } from '$lib/types/schema.js'
+import { Plus, ChevronRight } from 'lucide-svelte'
+
+let {
+	collections,
+	globals,
+	sidebarOpen = $bindable(true),
+}: {
+	collections: CollectionSchema[]
+	globals: GlobalSchema[]
+	sidebarOpen: boolean
+} = $props()
+
+let pathname = $derived(page.url.pathname)
+
+let breadcrumbs = $derived.by(() => {
+	const parts = pathname.slice(resolve('/').length).split('/').filter(Boolean)
+	const crumbs: { label: string; href?: string }[] = []
+
+	if (parts.length === 0) {
+		crumbs.push({ label: 'Dashboard' })
+		return crumbs
+	}
+
+	if (parts[0] === 'files') {
+		crumbs.push({ label: 'Files' })
+		return crumbs
+	}
+
+	if (parts[0] === 'globals' && parts[1]) {
+		const g = globals.find((gl) => gl.key === parts[1])
+		crumbs.push({ label: 'Settings', href: undefined })
+		crumbs.push({ label: g?.label || parts[1] })
+		return crumbs
+	}
+
+	if (parts[0] === 'login') {
+		crumbs.push({ label: 'Login' })
+		return crumbs
+	}
+
+	const col = collections.find((c) => c.key === parts[0])
+	if (col) {
+		crumbs.push({
+			label: col.labelPlural || col.label,
+			href: resolve(`/${col.key}`),
+		})
+
+		if (parts[1] === 'new') {
+			crumbs.push({ label: 'New' })
+		} else if (parts[1]) {
+			crumbs.push({ label: 'Edit' })
+		}
+	} else {
+		crumbs.push({ label: parts[0] })
+	}
+
+	return crumbs
+})
+
+let showAddNew = $derived.by(() => {
+	const parts = pathname.slice(resolve('/').length).split('/').filter(Boolean)
+	if (parts.length === 1) {
+		return collections.some((c) => c.key === parts[0])
+	}
+	return false
+})
+
+let currentCollectionKey = $derived.by(() => {
+	const parts = pathname.slice(resolve('/').length).split('/').filter(Boolean)
+	if (parts.length >= 1) {
+		const col = collections.find((c) => c.key === parts[0])
+		if (col) return col.key
+	}
+	return null
+})
+</script>
+
+<header class="flex h-14 items-center justify-between border-b border-border/60 bg-card/80 px-6 backdrop-blur-sm {sidebarOpen ? '' : 'pl-14'}">
+  <nav class="flex items-center gap-1.5 text-sm">
+    {#each breadcrumbs as crumb, i}
+      {#if i > 0}
+        <ChevronRight class="h-3 w-3 text-muted-foreground/50" />
+      {/if}
+      {#if crumb.href && i < breadcrumbs.length - 1}
+        <a href={crumb.href} class="text-muted-foreground transition-colors hover:text-foreground">
+          {crumb.label}
+        </a>
+      {:else}
+        <span class="font-medium text-foreground">{crumb.label}</span>
+      {/if}
+    {/each}
+  </nav>
+
+  {#if showAddNew && currentCollectionKey}
+    <a
+      href={resolve(`/${currentCollectionKey}/new`)}
+      class="inline-flex h-8 items-center gap-1.5 rounded-lg bg-primary px-3.5 text-[13px] font-medium text-primary-foreground shadow-sm transition-all hover:bg-primary/90 hover:shadow-md active:scale-[0.98]"
+    >
+      <Plus class="h-3.5 w-3.5" />
+      Add New
+    </a>
+  {/if}
+</header>

package/src/lib/components/AdminSidebar.svelte

@@ -0,0 +1,262 @@
+<script lang="ts">
+import { page } from '$lib/router/index.svelte.js'
+import { resolve } from '$lib/router/index.svelte.js'
+import { logout } from '$lib/api/auth.js'
+import { goto } from '$lib/router/index.svelte.js'
+import { toast } from 'svelte-sonner'
+import { branding } from '$lib/stores/branding.svelte.js'
+import type { CollectionSchema, GlobalSchema, AuthUser } from '$lib/types/schema.js'
+import { getQuoinContext } from '$lib/context.svelte.js'
+import Slot from '$lib/Slot.svelte'
+import {
+	FileText, LogOut, Settings, PanelLeftClose, PanelLeftOpen, BookOpen,
+	PenLine, Users, FolderTree, Tag, BookCopy, Trophy, Megaphone,
+	Mail, StickyNote, Menu, Image, FolderOpen, Tags,
+	MessageSquare, BarChart3, MousePointerClick, Puzzle, type Icon
+} from 'lucide-svelte'
+import type { Component } from 'svelte'
+
+// Consumer-declared custom pages from admin.config.ts. Sidebar auto-renders
+// nav entries for pages with a `nav` block; omit `nav` on a page to hide it
+// (route remains accessible via direct URL).
+const ctx = getQuoinContext()
+const customPagesByGroup = $derived.by(() => {
+	const groups: Record<string, Array<{ slug: string; label: string; icon?: string }>> = {}
+	for (const [slug, entry] of Object.entries(ctx.config.pages)) {
+		if (!entry.nav) continue
+		const group = entry.nav.group ?? 'Tools'
+		if (!groups[group]) groups[group] = []
+		groups[group].push({ slug, label: entry.nav.label, icon: entry.nav.icon })
+	}
+	return groups
+})
+
+const collectionIcons: Record<string, Component> = {
+	posts: PenLine,
+	authors: Users,
+	categories: FolderTree,
+	tags: Tag,
+	series: BookCopy,
+	competitions: Trophy,
+	ads: Megaphone,
+	subscribers: Mail,
+	pages: StickyNote,
+	menus: Menu,
+	media: Image,
+	media_folders: FolderOpen,
+	media_tags: Tags,
+	contact_messages: MessageSquare,
+	ad_impressions: BarChart3,
+	ad_clicks: MousePointerClick,
+}
+
+function getIcon(key: string): Component {
+	return collectionIcons[key] || FileText
+}
+
+let {
+	collections,
+	globals,
+	user,
+	open = $bindable(true),
+}: {
+	collections: CollectionSchema[]
+	globals: GlobalSchema[]
+	user: AuthUser | null
+	open: boolean
+} = $props()
+
+// Group collections by admin.group
+let grouped = $derived.by(() => {
+	const groups: Record<string, CollectionSchema[]> = {}
+	for (const col of collections) {
+		const group = col.admin?.group || 'Collections'
+		if (!groups[group]) groups[group] = []
+		groups[group].push(col)
+	}
+	for (const g of Object.values(groups)) {
+		g.sort((a, b) => a.label.localeCompare(b.label))
+	}
+	return groups
+})
+
+let groupNames = $derived(Object.keys(grouped).sort())
+let currentPath = $derived(page.url.pathname)
+
+function isActive(path: string): boolean {
+	return currentPath === path || currentPath.startsWith(`${path}/`)
+}
+
+async function handleLogout() {
+	const result = await logout()
+	if (result.ok) {
+		await goto(resolve('/login'))
+	} else {
+		toast.error('Logout failed')
+	}
+}
+</script>
+
+{#if open}
+  <aside class="flex h-full w-64 flex-col bg-sidebar-background text-sidebar-foreground">
+    <!-- Brand -->
+    <div class="flex h-16 items-center justify-between px-5">
+      <a href={resolve('/')} class="flex min-w-0 items-center gap-2.5">
+        <!--
+          Slot: consumer-provided logo component.
+          Default: BookOpen icon + siteName + "Admin" subtext.
+          Consumer override receives `{ siteName, logoUrl }` so they can
+          match styling to the library's layout expectations.
+        -->
+        <Slot name="branding.logo" siteName={branding.siteName} logoUrl={branding.logoUrl}>
+          {#snippet children()}
+            {#if branding.logoUrl}
+              <img src={branding.logoUrl} alt={branding.siteName} class="h-9 w-auto max-w-[180px] object-contain" />
+            {:else}
+              <div class="flex h-8 w-8 items-center justify-center rounded-lg bg-sidebar-accent">
+                <BookOpen class="h-4 w-4 text-sidebar-accent-foreground" />
+              </div>
+              <div class="flex flex-col">
+                <span class="text-sm font-semibold tracking-tight text-white" style="font-family: var(--font-display);">{branding.siteName}</span>
+                <span class="text-[10px] uppercase tracking-widest text-sidebar-muted">Admin</span>
+              </div>
+            {/if}
+          {/snippet}
+        </Slot>
+      </a>
+      <button onclick={() => (open = false)} class="rounded-md p-1.5 text-sidebar-muted transition-colors hover:bg-sidebar-accent hover:text-sidebar-accent-foreground" title="Collapse sidebar">
+        <PanelLeftClose class="h-4 w-4" />
+      </button>
+    </div>
+
+    <!-- Divider -->
+    <div class="mx-4 border-t border-sidebar-border"></div>
+
+    <!-- Navigation -->
+    <nav class="flex-1 overflow-y-auto px-3 py-4 scrollbar-hide">
+      {#each groupNames as group}
+        <div class="mb-5">
+          <p class="mb-2 px-3 text-[10px] font-semibold uppercase tracking-[0.15em] text-sidebar-muted">
+            {group}
+          </p>
+          <ul class="space-y-0.5">
+            {#each grouped[group] as col}
+              {@const IconComponent = getIcon(col.key)}
+              <li>
+                <a
+                  href={resolve(`/${col.key}`)}
+                  class="group flex items-center gap-2.5 rounded-lg px-3 py-2 text-[13px] transition-all duration-150
+                    {isActive(resolve(`/${col.key}`))
+                      ? 'bg-sidebar-accent text-sidebar-accent-foreground font-medium shadow-sm'
+                      : 'text-sidebar-foreground hover:bg-white/[0.04] hover:text-white'}"
+                >
+                  <IconComponent class="h-4 w-4 shrink-0 opacity-60 group-hover:opacity-100 {isActive(resolve(`/${col.key}`)) ? 'opacity-100' : ''}" />
+                  {col.labelPlural || col.label}
+                </a>
+              </li>
+            {/each}
+          </ul>
+        </div>
+      {/each}
+
+      <!-- Tools -->
+      <div class="mb-5">
+        <p class="mb-2 px-3 text-[10px] font-semibold uppercase tracking-[0.15em] text-sidebar-muted">
+          Tools
+        </p>
+        <ul class="space-y-0.5">
+          <li>
+            <a
+              href={resolve('/ads-analytics')}
+              class="group flex items-center gap-2.5 rounded-lg px-3 py-2 text-[13px] transition-all duration-150
+                {isActive(resolve('/ads-analytics'))
+                  ? 'bg-sidebar-accent text-sidebar-accent-foreground font-medium shadow-sm'
+                  : 'text-sidebar-foreground hover:bg-white/[0.04] hover:text-white'}"
+            >
+              <BarChart3 class="h-4 w-4 shrink-0 opacity-60 group-hover:opacity-100 {isActive(resolve('/ads-analytics')) ? 'opacity-100' : ''}" />
+              Ad Analytics
+            </a>
+          </li>
+        </ul>
+      </div>
+
+      <!-- Consumer-declared custom pages (from admin.config.ts) -->
+      {#each Object.entries(customPagesByGroup) as [group, pages]}
+        <div class="mb-5">
+          <p class="mb-2 px-3 text-[10px] font-semibold uppercase tracking-[0.15em] text-sidebar-muted">
+            {group}
+          </p>
+          <ul class="space-y-0.5">
+            {#each pages as pg}
+              {@const pgHref = resolve(`/pages/${pg.slug}`)}
+              <li>
+                <a
+                  href={pgHref}
+                  class="group flex items-center gap-2.5 rounded-lg px-3 py-2 text-[13px] transition-all duration-150
+                    {isActive(pgHref)
+                      ? 'bg-sidebar-accent text-sidebar-accent-foreground font-medium shadow-sm'
+                      : 'text-sidebar-foreground hover:bg-white/[0.04] hover:text-white'}"
+                >
+                  <Puzzle class="h-4 w-4 shrink-0 opacity-60 group-hover:opacity-100 {isActive(pgHref) ? 'opacity-100' : ''}" />
+                  {pg.label}
+                </a>
+              </li>
+            {/each}
+          </ul>
+        </div>
+      {/each}
+
+      <!-- Globals -->
+      {#if globals.length > 0}
+        <div class="mb-5">
+          <p class="mb-2 px-3 text-[10px] font-semibold uppercase tracking-[0.15em] text-sidebar-muted">
+            Settings
+          </p>
+          <ul class="space-y-0.5">
+            {#each globals as g}
+              <li>
+                <a
+                  href={resolve(`/globals/${g.key}`)}
+                  class="group flex items-center gap-2.5 rounded-lg px-3 py-2 text-[13px] transition-all duration-150
+                    {isActive(resolve(`/globals/${g.key}`))
+                      ? 'bg-sidebar-accent text-sidebar-accent-foreground font-medium shadow-sm'
+                      : 'text-sidebar-foreground hover:bg-white/[0.04] hover:text-white'}"
+                >
+                  <Settings class="h-4 w-4 shrink-0 opacity-60 group-hover:opacity-100 {isActive(resolve(`/globals/${g.key}`)) ? 'opacity-100' : ''}" />
+                  {g.label}
+                </a>
+              </li>
+            {/each}
+          </ul>
+        </div>
+      {/if}
+    </nav>
+
+    <!-- Footer -->
+    <div class="border-t border-sidebar-border px-4 py-3">
+      <div class="flex items-center justify-between">
+        <div class="flex items-center gap-2.5">
+          <div class="flex h-7 w-7 items-center justify-center rounded-full bg-sidebar-accent text-[11px] font-semibold text-sidebar-accent-foreground">
+            {user?.username?.charAt(0)?.toUpperCase() || '?'}
+          </div>
+          <span class="text-xs text-sidebar-foreground">{user?.username}</span>
+        </div>
+        <button
+          onclick={handleLogout}
+          class="rounded-md p-1.5 text-sidebar-muted transition-colors hover:bg-sidebar-accent hover:text-sidebar-accent-foreground"
+          title="Logout"
+        >
+          <LogOut class="h-3.5 w-3.5" />
+        </button>
+      </div>
+    </div>
+  </aside>
+{:else}
+  <button
+    onclick={() => (open = true)}
+    class="fixed left-3 top-4 z-50 rounded-lg border border-border bg-card p-2 shadow-md transition-colors hover:bg-secondary"
+    title="Open sidebar"
+  >
+    <PanelLeftOpen class="h-4 w-4" />
+  </button>
+{/if}