@refrakt-md/svelte 0.1.0

package/package.json

@@ -0,0 +1,35 @@
+{
+	"name": "@refrakt-md/svelte",
+	"description": "Svelte renderer for refrakt.md content",
+	"version": "0.1.0",
+	"type": "module",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/refrakt-md/refrakt.git",
+		"directory": "packages/svelte"
+	},
+	"bugs": "https://github.com/refrakt-md/refrakt/issues",
+	"homepage": "https://github.com/refrakt-md/refrakt",
+	"publishConfig": {
+		"access": "public"
+	},
+	"svelte": "src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"svelte": "./src/index.ts",
+			"default": "./src/index.ts"
+		}
+	},
+	"files": [
+		"src"
+	],
+	"dependencies": {
+		"@markdoc/markdoc": "0.4.0",
+		"@refrakt-md/types": "0.1.0"
+	},
+	"peerDependencies": {
+		"svelte": "^5.0.0"
+	}
+}

package/src/Renderer.svelte

@@ -0,0 +1,69 @@
+<script lang="ts" module>
+	export type { SerializedTag, RendererNode } from './types.js';
+</script>
+
+<script lang="ts">
+	import type { Component } from 'svelte';
+	import type { SerializedTag, RendererNode } from './types.js';
+	import { getComponent, getElementOverrides } from './context.js';
+	import Renderer from './Renderer.svelte';
+
+	let { node, overrides }: { node: RendererNode; overrides?: Record<string, Component<any>> } = $props();
+
+	function isTag(n: unknown): n is SerializedTag {
+		return n !== null && typeof n === 'object' && (n as any).$$mdtype === 'Tag';
+	}
+
+	/** Filter out attributes that shouldn't be rendered as HTML attributes */
+	function htmlAttrs(attrs: Record<string, any>): Record<string, any> {
+		const result: Record<string, any> = {};
+		for (const [k, v] of Object.entries(attrs)) {
+			if (v === undefined || v === null || v === false) continue;
+			result[k] = v === true ? '' : String(v);
+		}
+		return result;
+	}
+
+	const globalOverrides = getElementOverrides();
+	const merged = overrides
+		? { ...globalOverrides, ...overrides }
+		: globalOverrides;
+</script>
+
+{#if Array.isArray(node)}
+	{#each node as child}
+		<Renderer node={child} overrides={merged} />
+	{/each}
+{:else if node === null || node === undefined}
+	<!-- empty -->
+{:else if typeof node === 'string'}
+	{node}
+{:else if typeof node === 'number'}
+	{String(node)}
+{:else if isTag(node)}
+	{@const Component = node.attributes?.typeof ? getComponent(node.attributes.typeof) : undefined}
+	{@const ElementOverride = !Component && merged?.[node.name] ? merged[node.name] : undefined}
+	{#if Component}
+		<Component tag={node}>
+			{#each node.children as child}
+				<Renderer node={child} overrides={merged} />
+			{/each}
+		</Component>
+	{:else if ElementOverride}
+		<ElementOverride tag={node}>
+			{#each node.children as child}
+				<Renderer node={child} overrides={merged} />
+			{/each}
+		</ElementOverride>
+	{:else}
+		<svelte:element this={node.name} {...htmlAttrs(node.attributes)}>
+			{#each node.children as child}
+				{#if node.attributes?.['data-codeblock'] && typeof child === 'string'}
+					{@html child}
+				{:else}
+					<Renderer node={child} overrides={merged} />
+				{/if}
+			{/each}
+		</svelte:element>
+	{/if}
+{/if}

package/src/ThemeShell.svelte

@@ -0,0 +1,41 @@
+<script lang="ts">
+	import type { SvelteTheme } from './theme.js';
+	import { setRegistry, setElementOverrides } from './context.js';
+	import { setContext } from 'svelte';
+	import { matchRouteRule } from './route-rules.js';
+
+	interface PageData {
+		title: string;
+		description: string;
+		regions: Record<string, { name: string; mode: string; content: any[] }>;
+		renderable: any;
+		pages: Array<{ url: string; title: string; draft: boolean }>;
+		url: string;
+	}
+
+	let { theme, page }: { theme: SvelteTheme; page: PageData } = $props();
+
+	// Wire theme into Svelte context
+	setRegistry(theme.components);
+	if (theme.elements) setElementOverrides(theme.elements);
+	setContext('pages', page.pages);
+
+	// Pick layout via route rules (reactive so layout updates on client-side navigation)
+	const layoutName = $derived(matchRouteRule(page.url, theme.manifest.routeRules));
+	const Layout = $derived(theme.layouts[layoutName] ?? theme.layouts['default']);
+</script>
+
+<svelte:head>
+	{#if page.title}<title>{page.title}</title>{/if}
+	{#if page.description}<meta name="description" content={page.description} />{/if}
+</svelte:head>
+
+{#if Layout}
+	<Layout
+		title={page.title}
+		description={page.description}
+		regions={page.regions}
+		renderable={page.renderable}
+		pages={page.pages}
+	/>
+{/if}

package/src/context.ts

@@ -0,0 +1,28 @@
+import { getContext, setContext } from 'svelte';
+import type { Component } from 'svelte';
+
+export type ComponentRegistry = Record<string, Component<any>>;
+export type ElementOverrides = Record<string, Component<any>>;
+
+const REGISTRY_KEY = Symbol('refrakt-registry');
+const ELEMENT_OVERRIDES_KEY = Symbol('refrakt-element-overrides');
+
+/** Set the component registry in Svelte context. Call during component init (e.g. in a layout). */
+export function setRegistry(registry: ComponentRegistry): void {
+	setContext(REGISTRY_KEY, registry);
+}
+
+/** Look up a component by its typeof name from the context registry. */
+export function getComponent(typeName: string): Component<any> | undefined {
+	return getContext<ComponentRegistry>(REGISTRY_KEY)?.[typeName];
+}
+
+/** Set theme-global element overrides in Svelte context. */
+export function setElementOverrides(overrides: ElementOverrides): void {
+	setContext(ELEMENT_OVERRIDES_KEY, overrides);
+}
+
+/** Get theme-global element overrides from Svelte context. */
+export function getElementOverrides(): ElementOverrides | undefined {
+	return getContext<ElementOverrides>(ELEMENT_OVERRIDES_KEY);
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export { default as Renderer } from './Renderer.svelte';
+export { default as ThemeShell } from './ThemeShell.svelte';
+export type { SerializedTag, RendererNode } from './types.js';
+export { serialize, serializeTree } from './serialize.js';
+export { setRegistry, getComponent, setElementOverrides, getElementOverrides } from './context.js';
+export type { ComponentRegistry, ElementOverrides } from './context.js';
+export type { SvelteTheme } from './theme.js';
+export { matchRouteRule } from './route-rules.js';

package/src/route-rules.ts

@@ -0,0 +1,31 @@
+import type { RouteRule } from '@refrakt-md/types';
+
+/**
+ * Match a URL against an ordered list of route rules.
+ * Returns the layout name from the first matching rule, or 'default' if none match.
+ *
+ * Pattern syntax:
+ * - "docs/**" matches /docs/anything and /docs/nested/deep
+ * - "blog/*" matches /blog/post but not /blog/nested/deep
+ * - "**" matches everything (catch-all)
+ * - "about" matches /about exactly
+ */
+export function matchRouteRule(url: string, rules: RouteRule[]): string {
+	const normalized = url.startsWith('/') ? url.slice(1) : url;
+
+	for (const rule of rules) {
+		if (matchPattern(normalized, rule.pattern)) {
+			return rule.layout;
+		}
+	}
+	return 'default';
+}
+
+function matchPattern(url: string, pattern: string): boolean {
+	const regexStr = pattern
+		.replace(/[.+^${}()|[\]\\]/g, '\\$&')  // escape regex special chars (except * and ?)
+		.replace(/\*\*/g, '{{GLOBSTAR}}')
+		.replace(/\*/g, '[^/]*')
+		.replace(/\{\{GLOBSTAR\}\}/g, '.*');
+	return new RegExp(`^${regexStr}$`).test(url);
+}

package/src/serialize.ts

@@ -0,0 +1,24 @@
+import Markdoc from '@markdoc/markdoc';
+import type { RenderableTreeNode, RenderableTreeNodes } from '@markdoc/markdoc';
+const { Tag } = Markdoc;
+
+/** Convert a Markdoc Tag instance to a plain serializable object */
+export function serialize(node: RenderableTreeNode): unknown {
+	if (node === null || node === undefined) return node;
+	if (typeof node === 'string' || typeof node === 'number') return node;
+	if (Tag.isTag(node)) {
+		return {
+			$$mdtype: 'Tag',
+			name: node.name,
+			attributes: node.attributes,
+			children: node.children.map(serialize),
+		};
+	}
+	return node;
+}
+
+/** Convert a Markdoc tree (single node or array) to serializable POJOs */
+export function serializeTree(tree: RenderableTreeNodes): unknown {
+	if (Array.isArray(tree)) return tree.map(serialize);
+	return serialize(tree);
+}

package/src/theme.ts

@@ -0,0 +1,16 @@
+import type { ThemeManifest } from '@refrakt-md/types';
+import type { Component } from 'svelte';
+
+/**
+ * A resolved Svelte theme: the manifest plus live component references.
+ * This is the runtime contract between a theme package and the Svelte adapter.
+ */
+export interface SvelteTheme {
+	manifest: ThemeManifest;
+	/** Layout name → Svelte component */
+	layouts: Record<string, Component<any>>;
+	/** typeof name → Svelte component (the component registry) */
+	components: Record<string, Component<any>>;
+	/** HTML element name → Svelte component (element-level overrides) */
+	elements?: Record<string, Component<any>>;
+}

package/src/types.ts

@@ -0,0 +1,9 @@
+/** A serialized Markdoc Tag (plain object, not a class instance) */
+export interface SerializedTag {
+	$$mdtype: 'Tag';
+	name: string;
+	attributes: Record<string, any>;
+	children: RendererNode[];
+}
+
+export type RendererNode = SerializedTag | string | number | null | undefined | RendererNode[];