emdash 0.0.0-a → 0.0.1

package/src/media/types.ts

@@ -0,0 +1,279 @@
+/**
+ * Media Provider Types
+ *
+ * Media providers are pluggable sources for browsing, uploading, and embedding media.
+ * They enable integration with external services (Unsplash, Cloudinary, Mux, etc.)
+ * alongside the built-in local media library.
+ */
+
+/**
+ * Serializable media provider configuration descriptor
+ * Returned by provider config functions (e.g., unsplash(), mux())
+ */
+export interface MediaProviderDescriptor<TConfig = Record<string, unknown>> {
+	/** Unique identifier, used in MediaValue.provider */
+	id: string;
+
+	/** Display name for admin UI */
+	name: string;
+
+	/** Icon for tab UI (emoji or URL) */
+	icon?: string;
+
+	/** Module path exporting createMediaProvider function */
+	entrypoint: string;
+
+	/** Optional React component module for custom admin UI */
+	adminModule?: string;
+
+	/** Capability flags determine UI behavior */
+	capabilities: MediaProviderCapabilities;
+
+	/** Serializable config passed to createMediaProvider at runtime */
+	config: TConfig;
+}
+
+/**
+ * Provider capabilities determine what UI elements to show
+ */
+export interface MediaProviderCapabilities {
+	/** Can list/browse media */
+	browse: boolean;
+	/** Supports text search */
+	search: boolean;
+	/** Can upload new media */
+	upload: boolean;
+	/** Can delete media */
+	delete: boolean;
+}
+
+/**
+ * Options for listing media
+ */
+export interface MediaListOptions {
+	/** Pagination cursor */
+	cursor?: string;
+	/** Max items to return (default 20) */
+	limit?: number;
+	/** Search query (if capabilities.search is true) */
+	query?: string;
+	/** Filter by MIME type prefix, e.g., "image/", "video/" */
+	mimeType?: string;
+}
+
+/**
+ * Result from listing media
+ */
+export interface MediaListResult {
+	items: MediaProviderItem[];
+	nextCursor?: string;
+}
+
+/**
+ * A media item as returned by a provider
+ * This is the provider's view of the item, before it's selected
+ */
+export interface MediaProviderItem {
+	/** Provider-specific ID */
+	id: string;
+	/** Original filename */
+	filename: string;
+	/** MIME type */
+	mimeType: string;
+	/** File size in bytes (if known) */
+	size?: number;
+	/** Dimensions (for images/video) */
+	width?: number;
+	height?: number;
+	/** Accessibility text */
+	alt?: string;
+	/** Preview URL for admin UI thumbnail */
+	previewUrl?: string;
+	/** Provider-specific metadata */
+	meta?: Record<string, unknown>;
+}
+
+/**
+ * Input for uploading media
+ */
+export interface MediaUploadInput {
+	file: File;
+	filename: string;
+	alt?: string;
+}
+
+/**
+ * Options for generating embed
+ */
+export interface EmbedOptions {
+	/** Desired width (provider may use for optimization) */
+	width?: number;
+	/** Desired height */
+	height?: number;
+	/** Image format preference */
+	format?: "webp" | "avif" | "jpeg" | "png" | "auto";
+}
+
+/**
+ * Embed result types
+ */
+export type EmbedResult = ImageEmbed | VideoEmbed | AudioEmbed | ComponentEmbed;
+
+export interface ImageEmbed {
+	type: "image";
+	src: string;
+	srcset?: string;
+	sizes?: string;
+	width?: number;
+	height?: number;
+	alt?: string;
+	/** Base URL without transforms, for responsive image generation */
+	cdnBaseUrl?: string;
+	/** For providers with URL-based transforms (Cloudinary, imgix) */
+	getSrc?: (opts: { width?: number; height?: number; format?: string }) => string;
+}
+
+export interface VideoEmbed {
+	type: "video";
+	/** Single source URL */
+	src?: string;
+	/** Multiple sources for format fallback */
+	sources?: Array<{ src: string; type: string }>;
+	/** Poster/thumbnail image */
+	poster?: string;
+	width?: number;
+	height?: number;
+	/** Player controls */
+	controls?: boolean;
+	autoplay?: boolean;
+	muted?: boolean;
+	loop?: boolean;
+	playsinline?: boolean;
+	preload?: "none" | "metadata" | "auto";
+	crossorigin?: "anonymous" | "use-credentials";
+}
+
+export interface AudioEmbed {
+	type: "audio";
+	src?: string;
+	sources?: Array<{ src: string; type: string }>;
+	controls?: boolean;
+	autoplay?: boolean;
+	muted?: boolean;
+	loop?: boolean;
+	preload?: "none" | "metadata" | "auto";
+}
+
+export interface ComponentEmbed {
+	type: "component";
+	/** Package to import from, e.g., "@mux/player-react" */
+	package: string;
+	/** Named export (default export if not specified) */
+	export?: string;
+	/** Props to pass to the component */
+	props: Record<string, unknown>;
+}
+
+/**
+ * Options for thumbnail generation
+ */
+export interface ThumbnailOptions {
+	/** Desired width */
+	width?: number;
+	/** Desired height */
+	height?: number;
+}
+
+/**
+ * Runtime media provider interface
+ * Implemented by provider entrypoints
+ */
+export interface MediaProvider {
+	/**
+	 * List/search media items
+	 */
+	list(options: MediaListOptions): Promise<MediaListResult>;
+
+	/**
+	 * Get a single item by ID (optional, for refresh/validation)
+	 */
+	get?(id: string): Promise<MediaProviderItem | null>;
+
+	/**
+	 * Upload new media (if capabilities.upload is true)
+	 */
+	upload?(input: MediaUploadInput): Promise<MediaProviderItem>;
+
+	/**
+	 * Delete media (if capabilities.delete is true)
+	 */
+	delete?(id: string): Promise<void>;
+
+	/**
+	 * Get embed information for rendering this media item
+	 * Called at runtime when rendering content
+	 */
+	getEmbed(value: MediaValue, options?: EmbedOptions): Promise<EmbedResult> | EmbedResult;
+
+	/**
+	 * Get a thumbnail URL for admin display
+	 * For images: returns a resized image URL
+	 * For videos: returns a poster/thumbnail URL
+	 */
+	getThumbnailUrl?(id: string, mimeType?: string, options?: ThumbnailOptions): string;
+}
+
+/**
+ * Function signature for provider entrypoint modules
+ */
+export type CreateMediaProviderFn<TConfig = Record<string, unknown>> = (
+	config: TConfig,
+) => MediaProvider;
+
+/**
+ * Media value stored in content fields
+ * This is what gets persisted when media is selected
+ *
+ * For backwards compatibility:
+ * - `provider` defaults to "local" if not specified
+ * - `src` is supported for legacy data or external URLs
+ */
+export interface MediaValue {
+	/** Provider ID, e.g., "local", "unsplash", "mux" (defaults to "local") */
+	provider?: string;
+
+	/** Provider-specific item ID */
+	id: string;
+
+	/** Direct URL (for local media or legacy data) */
+	src?: string;
+
+	/** Preview URL for admin display (external providers) */
+	previewUrl?: string;
+
+	/** Cached metadata for display without runtime lookup */
+	filename?: string;
+	mimeType?: string;
+	width?: number;
+	height?: number;
+	alt?: string;
+
+	/** Provider-specific data needed for embedding */
+	meta?: Record<string, unknown>;
+}
+
+/**
+ * Convert a MediaProviderItem to a MediaValue for storage
+ */
+export function mediaItemToValue(providerId: string, item: MediaProviderItem): MediaValue {
+	return {
+		provider: providerId,
+		id: item.id,
+		filename: item.filename,
+		mimeType: item.mimeType,
+		width: item.width,
+		height: item.height,
+		alt: item.alt,
+		meta: item.meta,
+	};
+}

package/src/menus/index.ts

@@ -0,0 +1,324 @@
+/**
+ * Navigation menu runtime functions
+ *
+ * These are called from templates to query menus and resolve URLs.
+ */
+
+import type { Kysely } from "kysely";
+import { sql } from "kysely";
+
+import type { Database } from "../database/types.js";
+import { getDb } from "../loader.js";
+import type { Menu, MenuItem, MenuItemRow } from "./types.js";
+
+/**
+ * Get menu by name with resolved URLs
+ *
+ * @example
+ * ```ts
+ * import { getMenu } from "emdash";
+ *
+ * const menu = await getMenu("primary");
+ * if (menu) {
+ *   console.log(menu.items); // Array of MenuItem with resolved URLs
+ * }
+ * ```
+ */
+export async function getMenu(name: string): Promise<Menu | null> {
+	const db = await getDb();
+	return getMenuWithDb(name, db);
+}
+
+/**
+ * Get menu by name with resolved URLs (with explicit db)
+ *
+ * @internal Use `getMenu()` in templates. This variant is for admin routes
+ * that already have a database handle.
+ */
+export async function getMenuWithDb(name: string, db: Kysely<Database>): Promise<Menu | null> {
+	// Get menu
+	const menuRow = await db
+		.selectFrom("_emdash_menus")
+		.selectAll()
+		.where("name", "=", name)
+		.executeTakeFirst();
+
+	if (!menuRow) {
+		return null;
+	}
+
+	// Get all menu items
+	const itemRows = await db
+		.selectFrom("_emdash_menu_items")
+		.selectAll()
+		.$castTo<MenuItemRow>()
+		.where("menu_id", "=", menuRow.id)
+		.orderBy("sort_order", "asc")
+		.execute();
+
+	// Resolve URLs and build tree
+	const items = await buildMenuTree(itemRows, db);
+
+	return {
+		id: menuRow.id,
+		name: menuRow.name,
+		label: menuRow.label,
+		items,
+	};
+}
+
+/**
+ * Get all menus (without items - for admin list)
+ *
+ * @example
+ * ```ts
+ * import { getMenus } from "emdash";
+ *
+ * const menus = await getMenus();
+ * console.log(menus); // [{ id, name, label }]
+ * ```
+ */
+export async function getMenus(): Promise<Array<{ id: string; name: string; label: string }>> {
+	const db = await getDb();
+	return getMenusWithDb(db);
+}
+
+/**
+ * Get all menus (with explicit db)
+ *
+ * @internal Use `getMenus()` in templates. This variant is for admin routes
+ * that already have a database handle.
+ */
+export async function getMenusWithDb(
+	db: Kysely<Database>,
+): Promise<Array<{ id: string; name: string; label: string }>> {
+	const rows = await db
+		.selectFrom("_emdash_menus")
+		.select(["id", "name", "label"])
+		.orderBy("name", "asc")
+		.execute();
+
+	return rows;
+}
+
+/**
+ * Build hierarchical menu tree from flat array of items
+ */
+async function buildMenuTree(items: MenuItemRow[], db: Kysely<Database>): Promise<MenuItem[]> {
+	// Pre-load URL patterns for all collections referenced in this menu
+	const collectionSlugs = new Set<string>();
+	for (const item of items) {
+		if (item.reference_collection) {
+			collectionSlugs.add(item.reference_collection);
+		}
+		if (item.type === "page" || item.type === "post") {
+			collectionSlugs.add(item.reference_collection || `${item.type}s`);
+		}
+	}
+
+	const urlPatterns = new Map<string, string | null>();
+	if (collectionSlugs.size > 0) {
+		const rows = await db
+			.selectFrom("_emdash_collections")
+			.select(["slug", "url_pattern"])
+			.where("slug", "in", [...collectionSlugs])
+			.execute();
+		for (const row of rows) {
+			urlPatterns.set(row.slug, row.url_pattern);
+		}
+	}
+
+	// Resolve all URLs first
+	const resolvedItems = await Promise.all(
+		items.map((item) => resolveMenuItem(item, db, urlPatterns)),
+	);
+
+	// Filter out items that couldn't be resolved (e.g., deleted content)
+	const validItems = resolvedItems.filter((item) => item !== null);
+
+	// Build tree structure
+	const itemMap = new Map<string, MenuItem & { children: MenuItem[] }>();
+	const rootItems: MenuItem[] = [];
+
+	// First pass: create all items
+	for (const item of validItems) {
+		itemMap.set(item.id, { ...item, children: [] });
+	}
+
+	// Second pass: build parent-child relationships
+	for (const item of items) {
+		const menuItem = itemMap.get(item.id);
+		if (!menuItem) continue;
+
+		if (item.parent_id) {
+			const parent = itemMap.get(item.parent_id);
+			if (parent) {
+				parent.children.push(menuItem);
+			} else {
+				// Parent not found, treat as root
+				rootItems.push(menuItem);
+			}
+		} else {
+			rootItems.push(menuItem);
+		}
+	}
+
+	return rootItems;
+}
+
+/**
+ * Resolve a single menu item's URL
+ *
+ * Returns null if the referenced content no longer exists (item should be skipped)
+ */
+async function resolveMenuItem(
+	item: MenuItemRow,
+	db: Kysely<Database>,
+	urlPatterns: Map<string, string | null>,
+): Promise<MenuItem | null> {
+	let url: string | null;
+
+	try {
+		switch (item.type) {
+			case "custom":
+				url = item.custom_url || "#";
+				break;
+
+			case "page":
+			case "post":
+				url = await resolveContentUrl(
+					// Default to plural collection name (pages/posts) if not specified
+					item.reference_collection || `${item.type}s`,
+					item.reference_id,
+					db,
+					urlPatterns,
+				);
+				// Skip items where content no longer exists
+				if (url === null) {
+					return null;
+				}
+				break;
+
+			case "taxonomy":
+				url = await resolveTaxonomyUrl(item.reference_id, db);
+				// Skip items where taxonomy no longer exists
+				if (url === null) {
+					return null;
+				}
+				break;
+
+			case "collection":
+				url = `/${item.reference_collection}/`;
+				break;
+
+			default:
+				if (item.reference_collection && item.reference_id) {
+					url = await resolveContentUrl(
+						item.reference_collection,
+						item.reference_id,
+						db,
+						urlPatterns,
+					);
+					if (url === null) {
+						return null;
+					}
+				} else {
+					url = "#";
+				}
+		}
+	} catch (error) {
+		// If resolution fails, skip this item
+		console.error(`Failed to resolve menu item ${item.id}:`, error);
+		return null;
+	}
+
+	return {
+		id: item.id,
+		label: item.label,
+		url,
+		target: item.target || undefined,
+		titleAttr: item.title_attr || undefined,
+		cssClasses: item.css_classes || undefined,
+		children: [], // Will be populated by buildMenuTree
+	};
+}
+
+const SLUG_PLACEHOLDER = /\{slug\}/g;
+const ID_PLACEHOLDER = /\{id\}/g;
+
+/**
+ * Interpolate a URL pattern with entry data
+ *
+ * Replaces `{slug}` and `{id}` placeholders.
+ */
+function interpolateUrlPattern(pattern: string, slug: string, id: string): string {
+	return pattern.replace(SLUG_PLACEHOLDER, slug).replace(ID_PLACEHOLDER, id);
+}
+
+/**
+ * Resolve URL for a content entry (page/post)
+ *
+ * Uses the collection's url_pattern if set, otherwise falls back to /{collection}/{slug}.
+ * Returns null if content not found (item should be skipped).
+ */
+async function resolveContentUrl(
+	collection: string,
+	entryId: string | null,
+	db: Kysely<Database>,
+	urlPatterns: Map<string, string | null>,
+): Promise<string | null> {
+	if (!entryId) {
+		return null;
+	}
+
+	try {
+		// Dynamic content tables (ec_*) aren't in the Database type, so use sql
+		const result = await sql<{ slug: string }>`
+			SELECT slug FROM ${sql.ref(`ec_${collection}`)} WHERE id = ${entryId} LIMIT 1
+		`.execute(db);
+
+		const row = result.rows[0];
+		if (row) {
+			const pattern = urlPatterns.get(collection);
+			if (pattern) {
+				return interpolateUrlPattern(pattern, row.slug, entryId);
+			}
+			return `/${collection}/${row.slug}`;
+		}
+
+		// Content not found, skip item
+		return null;
+	} catch (error) {
+		// Table might not exist or query failed
+		console.error(`Failed to resolve content URL for ${collection}/${entryId}:`, error);
+		return null;
+	}
+}
+
+/**
+ * Resolve URL for a taxonomy term
+ *
+ * Returns null if taxonomy not found (item should be skipped)
+ */
+async function resolveTaxonomyUrl(
+	taxonomyId: string | null,
+	db: Kysely<Database>,
+): Promise<string | null> {
+	if (!taxonomyId) {
+		return null;
+	}
+
+	const taxonomy = await db
+		.selectFrom("taxonomies")
+		.select(["name", "slug"])
+		.where("id", "=", taxonomyId)
+		.executeTakeFirst();
+
+	if (!taxonomy) {
+		// Taxonomy not found, skip item
+		return null;
+	}
+
+	// Use taxonomy name as base (e.g., "categories" or "tags")
+	return `/${taxonomy.name}/${taxonomy.slug}`;
+}

package/src/menus/types.ts

@@ -0,0 +1,112 @@
+/**
+ * Menu item types
+ */
+export type MenuItemType = string;
+
+/**
+ * Menu item as returned to templates (with resolved URL)
+ */
+export interface MenuItem {
+	id: string;
+	label: string;
+	url: string; // Resolved URL
+	target?: string; // '_blank' etc
+	titleAttr?: string; // title="" attribute
+	cssClasses?: string;
+	children: MenuItem[]; // Nested items
+}
+
+/**
+ * Menu as returned to templates
+ */
+export interface Menu {
+	id: string;
+	name: string;
+	label: string;
+	items: MenuItem[];
+}
+
+/**
+ * Menu item as stored in database
+ */
+export interface MenuItemRow {
+	id: string;
+	menu_id: string;
+	parent_id: string | null;
+	sort_order: number;
+	type: MenuItemType;
+	reference_collection: string | null;
+	reference_id: string | null;
+	custom_url: string | null;
+	label: string;
+	title_attr: string | null;
+	target: string | null;
+	css_classes: string | null;
+	created_at: string;
+}
+
+/**
+ * Menu as stored in database
+ */
+export interface MenuRow {
+	id: string;
+	name: string;
+	label: string;
+	created_at: string;
+	updated_at: string;
+}
+
+/**
+ * Input for creating a menu item
+ */
+export interface CreateMenuItemInput {
+	type: MenuItemType;
+	label: string;
+	referenceCollection?: string;
+	referenceId?: string;
+	customUrl?: string;
+	target?: string;
+	titleAttr?: string;
+	cssClasses?: string;
+	parentId?: string;
+	sortOrder?: number;
+}
+
+/**
+ * Input for updating a menu item
+ */
+export interface UpdateMenuItemInput {
+	label?: string;
+	customUrl?: string;
+	target?: string;
+	titleAttr?: string;
+	cssClasses?: string;
+	parentId?: string | null;
+	sortOrder?: number;
+}
+
+/**
+ * Input for creating a menu
+ */
+export interface CreateMenuInput {
+	name: string;
+	label: string;
+}
+
+/**
+ * Input for updating a menu
+ */
+export interface UpdateMenuInput {
+	label?: string;
+}
+
+/**
+ * Input for reordering menu items
+ */
+export interface ReorderMenuItemsInput {
+	items: Array<{
+		id: string;
+		parentId: string | null;
+		sortOrder: number;
+	}>;
+}