@purview-dev/astroc4 0.0.0-stage → 1.0.0-prerelease.2

package/src/components/LikeC4ProjectView.tsx

@@ -0,0 +1,153 @@
+// LikeC4ProjectView.tsx
+// path: src/components/LikeC4ProjectView.tsx
+// React island that loads a LikeC4 project model (via the `likec4:*` virtual
+// modules provided by LikeC4VitePlugin) and renders one view from it.
+// Browser-only: mount it with `client:only="react"`.
+
+import { type ElementIconRenderer, getProjectIcons } from 'likec4:icons';
+import { loadModel } from 'likec4:model';
+import { projects } from 'likec4:projects';
+import type { aux, UnknownLayouted } from 'likec4/model';
+import { LikeC4View as GenericLikeC4View, LikeC4ModelProvider } from 'likec4/react';
+import { useEffect, useMemo, useRef, useState } from 'react';
+
+import ErrorBoundary from './ErrorBoundary';
+import { DEFAULT_LABELS, type IslandLabels } from './labels';
+import { withImageIcons } from './render-icon';
+import {
+	getAvailableProjectIds,
+	resolveProjectId,
+	toLoadErrorMessage,
+	validateViewId,
+} from './utils';
+
+type Props = {
+	viewId: string;
+	projectId?: string;
+	/** Translated on the server; defaults to English. */
+	labels?: IslandLabels;
+};
+
+type LoadedProjectModel = Awaited<ReturnType<typeof loadModel>>;
+
+type LoadedLikeC4ViewProps = {
+	loadedProjectModel: LoadedProjectModel;
+	viewId: string;
+	iconRenderer?: ElementIconRenderer;
+};
+
+function LoadedLikeC4View({ loadedProjectModel, viewId, iconRenderer }: LoadedLikeC4ViewProps) {
+	const model = loadedProjectModel.useLikeC4Model();
+
+	return (
+		<LikeC4ModelProvider likec4model={model}>
+			<GenericLikeC4View
+				viewId={viewId as aux.ViewId<UnknownLayouted>}
+				controls={false}
+				renderIcon={iconRenderer}
+				browser={{
+					enableFocusMode: false,
+					enableSearch: false,
+				}}
+			/>
+		</LikeC4ModelProvider>
+	);
+}
+
+function LikeC4ProjectViewContent({ viewId, projectId, labels }: Props & { labels: IslandLabels }) {
+	const [loadedProjectModel, setLoadedProjectModel] = useState<LoadedProjectModel | null>(null);
+	const [error, setError] = useState<string | null>(null);
+	// Guards against an older, slower load resolving after a newer one.
+	const loadRequestIdRef = useRef(0);
+
+	const availableProjectIds = useMemo(() => getAvailableProjectIds(projects), []);
+	const viewIdError = useMemo(() => validateViewId(viewId, labels), [viewId, labels]);
+
+	const projectResolution = useMemo(
+		() => resolveProjectId(projectId, availableProjectIds, labels),
+		[projectId, availableProjectIds, labels],
+	);
+
+	const resolvedProjectId = projectResolution.resolvedProjectId;
+
+	const iconRenderer = useMemo(() => {
+		if (!resolvedProjectId) {
+			return undefined;
+		}
+
+		return withImageIcons(getProjectIcons(resolvedProjectId));
+	}, [resolvedProjectId]);
+
+	useEffect(() => {
+		let isActive = true;
+		const currentRequestId = ++loadRequestIdRef.current;
+
+		if (viewIdError) {
+			setError(viewIdError);
+			setLoadedProjectModel(null);
+			return () => {
+				isActive = false;
+			};
+		}
+
+		if (projectResolution.error || !resolvedProjectId) {
+			setError(projectResolution.error ?? labels.unresolvedProject);
+			setLoadedProjectModel(null);
+			return () => {
+				isActive = false;
+			};
+		}
+
+		setError(null);
+		setLoadedProjectModel(null);
+
+		loadModel(resolvedProjectId)
+			.then((projectModel) => {
+				if (!isActive || currentRequestId !== loadRequestIdRef.current) {
+					return;
+				}
+
+				setLoadedProjectModel(projectModel);
+			})
+			.catch((err: unknown) => {
+				if (!isActive || currentRequestId !== loadRequestIdRef.current) {
+					return;
+				}
+
+				setError(toLoadErrorMessage(err, resolvedProjectId, labels));
+				setLoadedProjectModel(null);
+			});
+
+		return () => {
+			isActive = false;
+		};
+	}, [projectResolution.error, resolvedProjectId, viewIdError, labels]);
+
+	if (error) {
+		return (
+			<p role="alert" aria-live="polite">
+				{error}
+			</p>
+		);
+	}
+
+	if (!loadedProjectModel) {
+		return <p aria-live="polite">{labels.loading}</p>;
+	}
+
+	return (
+		<LoadedLikeC4View
+			loadedProjectModel={loadedProjectModel}
+			viewId={viewId}
+			iconRenderer={iconRenderer}
+		/>
+	);
+}
+
+export default function LikeC4ProjectView({ labels = DEFAULT_LABELS, ...props }: Props) {
+	return (
+		<ErrorBoundary labels={labels}>
+			<LikeC4ProjectViewContent {...props} labels={labels} />
+		</ErrorBoundary>
+	);
+}

package/src/components/LikeC4View.astro

@@ -0,0 +1,80 @@
+---
+// LikeC4View.astro
+// path: src/components/LikeC4View.astro
+// Docs-facing wrapper around the LikeC4 React island. Use this from .mdx pages:
+//   import LikeC4View from '@purview-dev/astroc4/components/LikeC4View.astro';
+//   <LikeC4View viewId="index" />
+//   <LikeC4View viewId="edge" projectId="my-project" height={560} />
+
+import DiagramFrame from './DiagramFrame.astro';
+import DiagramShell from './DiagramShell.astro';
+import LikeC4ProjectView from './LikeC4ProjectView';
+import LoadingPlaceholder from './LoadingPlaceholder.astro';
+import { getIslandLabels, getTranslator } from './labels';
+
+interface Props {
+	/** View id inside the selected LikeC4 project. */
+	viewId: string;
+	/** Optional project id (maps to `likec4:react/<projectId>`). */
+	projectId?: string;
+	/** Shell heading. */
+	title?: string;
+	description?: string;
+	/** Rendered height in pixels. */
+	height?: number;
+	collapsible?: boolean;
+	defaultOpen?: boolean;
+}
+
+const t = getTranslator(Astro.locals.t);
+const labels = getIslandLabels(t, 'likec4.view.loading');
+
+const {
+	viewId,
+	projectId,
+	title = t('likec4.view.title'),
+	description = t('likec4.view.description'),
+	height = 480,
+	collapsible = true,
+	defaultOpen = true,
+} = Astro.props;
+---
+
+<DiagramShell
+	title={title}
+	description={description}
+	hint={t('likec4.view.hint')}
+	collapsible={collapsible}
+	defaultOpen={defaultOpen}
+>
+	<div class="likec4-badge">
+		<span aria-hidden="true">🖱️</span>
+		<span>{t('likec4.view.badge')}</span>
+	</div>
+
+	<DiagramFrame height={height}>
+		<LikeC4ProjectView viewId={viewId} projectId={projectId} labels={labels} client:only="react">
+			{
+				/* `slot="fallback"` is required: default-slot children of a `client:only`
+			    island are parked in an inert <template> and never painted. */
+			}
+			<LoadingPlaceholder slot="fallback" label={labels.loading} />
+		</LikeC4ProjectView>
+	</DiagramFrame>
+</DiagramShell>
+
+<style>
+	.likec4-badge {
+		display: inline-flex;
+		align-items: center;
+		gap: 0.5rem;
+		margin-bottom: 0.75rem;
+		border: 1px solid var(--sl-color-gray-5);
+		border-radius: 9999px;
+		background: var(--sl-color-bg);
+		padding: 0.25rem 0.75rem;
+		font-size: 0.75rem;
+		line-height: 1rem;
+		color: var(--sl-color-gray-2);
+	}
+</style>

package/src/components/LoadingPlaceholder.astro

@@ -0,0 +1,67 @@
+---
+// LoadingPlaceholder.astro
+// path: src/components/LoadingPlaceholder.astro
+// Slot fallback rendered server-side while a `client:only` island hydrates.
+// Reserves roughly the right amount of space so the page doesn't jump.
+
+interface Props {
+	label: string;
+}
+
+const { label } = Astro.props;
+---
+
+<div class="likec4-loading" role="status" aria-live="polite" aria-busy="true">
+	<div class="likec4-loading__label">{label}</div>
+
+	<div class="likec4-loading__lines" aria-hidden="true">
+		<div class="likec4-loading__line" style="width: 75%"></div>
+		<div class="likec4-loading__line" style="width: 83.333%"></div>
+		<div class="likec4-loading__line" style="width: 66.667%"></div>
+	</div>
+</div>
+
+<style>
+	.likec4-loading {
+		border: 1px dashed var(--sl-color-gray-5);
+		border-radius: 0.5rem;
+		background: var(--sl-color-bg);
+		padding: 1.25rem;
+	}
+
+	.likec4-loading__label {
+		margin-bottom: 1rem;
+		font-size: 0.875rem;
+		line-height: 1.25rem;
+		font-weight: 500;
+		color: var(--sl-color-gray-2);
+	}
+
+	.likec4-loading__lines {
+		display: grid;
+		gap: 0.5rem;
+	}
+
+	.likec4-loading__line {
+		height: 1rem;
+		border-radius: 0.25rem;
+		background: var(--sl-color-gray-6);
+		animation: likec4-pulse 1.6s ease-in-out infinite;
+	}
+
+	@keyframes likec4-pulse {
+		0%,
+		100% {
+			opacity: 1;
+		}
+		50% {
+			opacity: 0.45;
+		}
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.likec4-loading__line {
+			animation: none;
+		}
+	}
+</style>

package/src/components/icon-source.ts

@@ -0,0 +1,68 @@
+// icon-source.ts
+// path: src/components/icon-source.ts
+// Works out how an element's `icon` value should be rendered.
+//
+// LikeC4 resolves a *relative* icon path against the .c4 file and stores an
+// absolute `file://` URL in the compiled model. That path is baked into the
+// client bundle, so the icon 404s for every visitor and the author's local
+// directory structure ships with the site.
+//
+// Files under `public/` are the exception worth supporting: Astro serves them
+// verbatim at the site root, so the absolute path can be rewritten back to the
+// URL it will actually be served from.
+
+/** Everything after a `/public/` segment, which Astro serves at the site root. */
+const PUBLIC_SEGMENT = /\/public\/(.+)$/;
+
+/** A path the compiler resolved on the build machine, rather than a pack id. */
+const LOCAL_PATH = /^(file:\/\/|virtual:\/)/;
+
+export type IconSource =
+	| { kind: 'pack' }
+	| { kind: 'url'; src: string }
+	| { kind: 'unresolvable'; path: string };
+
+/**
+ * Classify an icon value from the compiled model.
+ *
+ * - `pack`          — a bundled icon id (`tech:nginx`, `aws:…`, …)
+ *                     or anything else the LikeC4 renderer handles itself.
+ * - `url`           — render directly as an `<img src>`.
+ * - `unresolvable`  — a build-machine path with no web equivalent. Rendering
+ *                     nothing is better than a broken image, and the caller
+ *                     warns so it is not silently wrong.
+ */
+export function classifyIcon(icon: string | null | undefined): IconSource {
+	const value = icon?.trim();
+
+	if (!value) {
+		return { kind: 'pack' };
+	}
+
+	// Absolute URLs (and protocol-relative ones) are already web-addressable.
+	if (/^(https?:)?\/\//i.test(value)) {
+		return { kind: 'url', src: value };
+	}
+
+	if (!LOCAL_PATH.test(value)) {
+		return { kind: 'pack' };
+	}
+
+	// `file:///c%3A/.../public/likec4-icons/x.svg` -> `/likec4-icons/x.svg`
+	const decoded = safeDecode(value);
+	const match = PUBLIC_SEGMENT.exec(decoded);
+
+	if (match) {
+		return { kind: 'url', src: `/${match[1]}` };
+	}
+
+	return { kind: 'unresolvable', path: decoded };
+}
+
+function safeDecode(value: string): string {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return value;
+	}
+}

package/src/components/labels.ts

@@ -0,0 +1,62 @@
+// labels.ts
+// path: src/components/labels.ts
+// Resolves the plugin's UI strings for a page. The Astro wrappers translate on
+// the server and pass the islands plain strings, because `Astro.locals.t` does
+// not exist in the browser.
+
+import { translations } from '../translations.mjs';
+
+export type TranslationKey = keyof (typeof translations)['en'];
+export type Translate = (key: TranslationKey) => string;
+
+/** Every string an island can show after hydration. */
+export type IslandLabels = {
+	loading: string;
+	errorTitle: string;
+	errorBody: string;
+	errorRetry: string;
+	viewIdRequired: string;
+	noProjects: string;
+	/** Template: `{projectId}`, `{available}`. */
+	unknownProject: string;
+	unresolvedProject: string;
+	/** Template: `{projectId}`. */
+	loadFailed: string;
+};
+
+const english: Translate = (key) => translations.en[key];
+
+/**
+ * Wrap `Astro.locals.t`, falling back to English when it is absent — which it
+ * is on any page Starlight does not render, such as a plain `src/pages/` route.
+ */
+export function getTranslator(t: unknown): Translate {
+	if (typeof t !== 'function') return english;
+
+	return (key) => {
+		const value: unknown = t(key);
+
+		return typeof value === 'string' && value.length > 0 ? value : english(key);
+	};
+}
+
+export function getIslandLabels(t: Translate, loadingKey: TranslationKey): IslandLabels {
+	return {
+		loading: t(loadingKey),
+		errorTitle: t('likec4.error.title'),
+		errorBody: t('likec4.error.body'),
+		errorRetry: t('likec4.error.retry'),
+		viewIdRequired: t('likec4.error.viewIdRequired'),
+		noProjects: t('likec4.error.noProjects'),
+		unknownProject: t('likec4.error.unknownProject'),
+		unresolvedProject: t('likec4.error.unresolvedProject'),
+		loadFailed: t('likec4.error.loadFailed'),
+	};
+}
+
+export const DEFAULT_LABELS: IslandLabels = getIslandLabels(english, 'likec4.view.loading');
+
+/** Fill `{name}` placeholders. Unknown names are left in place so they show up. */
+export function format(template: string, values: Record<string, string>): string {
+	return template.replace(/\{(\w+)\}/g, (match, name: string) => values[name] ?? match);
+}

package/src/components/render-icon.tsx

@@ -0,0 +1,41 @@
+// render-icon.tsx
+// path: src/components/render-icon.tsx
+// Shared icon renderer for both the project-model and inline-fence islands.
+
+import type { ElementIconRenderer } from 'likec4:icons';
+
+import { classifyIcon } from './icon-source';
+
+/**
+ * Wrap the bundled-icon renderer so elements can also use an image URL, or a
+ * local file kept under `public/`. Anything else local has no web equivalent —
+ * warn rather than render a broken image.
+ */
+export function withImageIcons(packRenderer: ElementIconRenderer): ElementIconRenderer {
+	return function IconRenderer(props) {
+		const source = classifyIcon(props.node.icon);
+
+		if (source.kind === 'url') {
+			// The virtual `likec4:icons` module's props carry no className, so size
+			// the image to its slot explicitly rather than relying on a class.
+			return (
+				<img
+					src={source.src}
+					alt=""
+					loading="lazy"
+					style={{ width: '100%', height: '100%', objectFit: 'contain' }}
+				/>
+			);
+		}
+
+		if (source.kind === 'unresolvable') {
+			console.warn(
+				`[likec4] Element "${props.node.id}" has icon "${source.path}", which only exists on the machine that built the site. ` +
+					'Use a bundled icon (azure:, aws:, gcp:, tech:, bootstrap:), an absolute URL, or a file under public/.',
+			);
+			return null;
+		}
+
+		return packRenderer(props);
+	};
+}

package/src/components/utils.ts

@@ -0,0 +1,69 @@
+// utils.ts
+// path: src/components/utils.ts
+// Pure resolution/validation helpers for <LikeC4View>. Separated from the React
+// component so the error-message behaviour can be tested without a DOM.
+
+import { DEFAULT_LABELS, format, type IslandLabels } from './labels';
+
+type ErrorLabels = Pick<
+	IslandLabels,
+	'viewIdRequired' | 'noProjects' | 'unknownProject' | 'loadFailed'
+>;
+
+export function getAvailableProjectIds(
+	projectDefinitions: ReadonlyArray<{ id: unknown }>,
+): string[] {
+	return projectDefinitions
+		.map((project) => String(project.id).trim())
+		.filter((id) => id.length > 0);
+}
+
+export function validateViewId(viewId: string, labels: ErrorLabels = DEFAULT_LABELS): string | null {
+	if (!viewId || viewId.trim().length === 0) {
+		return labels.viewIdRequired;
+	}
+
+	return null;
+}
+
+export function resolveProjectId(
+	projectId: string | undefined,
+	availableProjectIds: string[],
+	labels: ErrorLabels = DEFAULT_LABELS,
+) {
+	if (availableProjectIds.length === 0) {
+		return {
+			resolvedProjectId: null,
+			error: labels.noProjects,
+		};
+	}
+
+	const resolvedProjectId = projectId?.trim() || availableProjectIds[0]!;
+
+	if (!availableProjectIds.includes(resolvedProjectId)) {
+		return {
+			resolvedProjectId: null,
+			error: format(labels.unknownProject, {
+				projectId: resolvedProjectId,
+				available: availableProjectIds.join(', ') || '(none)',
+			}),
+		};
+	}
+
+	return {
+		resolvedProjectId,
+		error: null,
+	};
+}
+
+export function toLoadErrorMessage(
+	err: unknown,
+	resolvedProjectId: string,
+	labels: ErrorLabels = DEFAULT_LABELS,
+): string {
+	if (err instanceof Error && err.message.trim().length > 0) {
+		return err.message;
+	}
+
+	return format(labels.loadFailed, { projectId: resolvedProjectId });
+}

package/src/expressive-code.d.mts

@@ -0,0 +1,28 @@
+// expressive-code.d.mts
+// path: src/expressive-code.d.mts
+// Types for src/expressive-code.mjs — see src/index.d.mts for why they exist.
+
+import type { LanguageRegistration } from 'shiki';
+
+/** Shiki registration for LikeC4, under `likec4` with a `c4` alias. */
+export declare const likec4Language: LanguageRegistration & { aliases: string[] };
+
+/**
+ * Resolve the grammar from likec4/likec4 at the requested ref and return it as
+ * a Shiki language registration.
+ */
+export declare function loadLikeC4Language(options?: {
+	ref?: string;
+	repo?: string;
+	offline?: boolean;
+	onError?: 'fail' | 'warn' | 'silent';
+	cacheTtl?: number;
+	refresh?: boolean;
+	cacheDir?: string;
+	baseUrl?: string;
+	timeout?: number;
+	root?: string;
+}): Promise<LanguageRegistration & { aliases: string[] }>;
+
+export default likec4Language;
+

package/src/expressive-code.mjs

@@ -0,0 +1,46 @@
+// expressive-code.mjs
+// path: src/expressive-code.mjs
+// LikeC4 syntax highlighting for Expressive Code (Starlight's code blocks).
+// Shiki ships no LikeC4 grammar, so without this .c4 source renders as plain
+// text.
+//
+// The Starlight plugin injects this language into the site's Expressive Code
+// options for you (see src/index.mjs) resolved from the live Langium grammar.
+// The exports here cover the two cases the plugin cannot:
+//
+//   - a site that already has an `ec.config.mjs`, which can add the bundled
+//     grammar with one line:
+//
+//       import { likec4Language } from '@purview-dev/astroc4/expressive-code';
+//       export default defineEcConfig({ shiki: { langs: [likec4Language] } });
+//
+//   - anything else that needs the grammar programmatically, e.g. a Markdown
+//     pipeline of its own: `await loadLikeC4Language({ ref: 'v1.59.4' })`.
+//
+// `likec4Language` is the bundled snapshot, so it works without network
+// access; `loadLikeC4Language` fetches the ref you ask for.
+
+import grammar from './grammar/likec4.tmLanguage.json' with { type: 'json' };
+import { resolveLikeC4Grammar } from './grammar/source.mjs';
+import { LANGUAGE_ALIASES, LANGUAGE_NAME } from './grammar/textmate.mjs';
+
+/** @type {import('shiki').LanguageRegistration} */
+export const likec4Language = {
+	...grammar,
+	name: LANGUAGE_NAME,
+	aliases: [...LANGUAGE_ALIASES],
+};
+
+/**
+ * Resolve the grammar from likec4/likec4 at the ref you ask for and return it
+ * as a Shiki language registration.
+ * @param {import('./grammar/source.mjs').GrammarSourceOptions} [options]
+ * @returns {Promise<import('shiki').LanguageRegistration>}
+ */
+export async function loadLikeC4Language(options) {
+	const { grammar: resolved } = await resolveLikeC4Grammar(options);
+
+	return { ...resolved, name: LANGUAGE_NAME, aliases: [...LANGUAGE_ALIASES] };
+}
+
+export default likec4Language;