@purview-dev/astroc4 1.0.0-prerelease.5 → 1.0.0-prerelease.7

package/src/components/LikeC4View.astro

@@ -1,47 +1,87 @@
 ---
-// 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} />
+// The project is resolved on the server, so a bad `project` fails the build
+// rather than rendering an error box.
+
+import { likec4IdFor, projectNames } from 'virtual:astroc4/projects';
 
 import DiagramFrame from './DiagramFrame.astro';
 import DiagramShell from './DiagramShell.astro';
+import LikeC4InlineView from './LikeC4InlineView';
 import LikeC4ProjectView from './LikeC4ProjectView';
 import LoadingPlaceholder from './LoadingPlaceholder.astro';
 import { getIslandLabels, getTranslator } from './labels';
+import { fileKey, resolveProjectId } from './utils';
 
 interface Props {
-	/** View id inside the selected LikeC4 project. */
 	viewId: string;
-	/** Optional project id (maps to `likec4:react/<projectId>`). */
+	/** A project named in the plugin's `projects` option, or discovered under the site root. */
+	project?: string;
+	/** @deprecated Use `project`. */
 	projectId?: string;
-	/** Shell heading. */
+	/** A single `.c4` file, relative to the site's `src/` folder. */
+	file?: string;
 	title?: string;
 	description?: string;
-	/** Rendered height in pixels. */
+	/** Height in pixels. */
 	height?: number;
 	collapsible?: boolean;
 	defaultOpen?: boolean;
 }
 
-// Starlight augments `App.Locals` with `t`; a plain Astro page has no such
-// property (and an empty `Locals` interface, so naming it would not type-check),
-// which is why this is read as `unknown` and `getTranslator` falls back to
-// English when it is absent.
+// `t` is Starlight's; outside Starlight `App.Locals` is empty, hence `unknown`.
 const t = getTranslator((Astro.locals as { t?: unknown }).t);
 const labels = getIslandLabels(t, 'likec4.view.loading');
 
 const {
 	viewId,
+	project,
 	projectId,
+	file,
 	title = t('likec4.view.title'),
 	description = t('likec4.view.description'),
 	height = 480,
 	collapsible = true,
 	defaultOpen = true,
 } = Astro.props;
+
+let inlineModel: unknown;
+let likec4Id: string | undefined;
+
+if (file !== undefined) {
+	// Compiled on import by the file-layout plugin.
+	const layouts = import.meta.glob<{ dump: unknown; viewIds: string[] }>('/src/**/*.c4', {
+		query: '?astroc4-layout',
+		import: 'default',
+	});
+	const key = fileKey(file);
+	const load = key ? layouts[key] : undefined;
+
+	if (!load) {
+		throw new Error(
+			`[astroc4] <LikeC4View file="${file}"> must name a .c4 file under src/` +
+				(key ? `; ${key} does not exist.` : '.'),
+		);
+	}
+
+	const layout = await load();
+
+	if (!layout.viewIds.includes(viewId)) {
+		throw new Error(`[astroc4] ${key} has no view "${viewId}". Declared: ${layout.viewIds.join(', ')}.`);
+	}
+
+	inlineModel = layout.dump;
+} else if (projectNames.length > 0) {
+	const resolution = resolveProjectId(project ?? projectId, projectNames, labels);
+
+	if (resolution.error) {
+		throw new Error(`[astroc4] <LikeC4View viewId="${viewId}">: ${resolution.error}`);
+	}
+
+	likec4Id = likec4IdFor[resolution.resolvedProjectId!];
+} else {
+	// The site took discovery over, so only the island knows the projects.
+	likec4Id = project ?? projectId;
+}
 ---
 
 <DiagramShell
@@ -57,33 +97,38 @@ const {
 	</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>
+		{
+			inlineModel !== undefined ? (
+				<LikeC4InlineView model={inlineModel} viewId={viewId} labels={labels} client:only="react">
+					<LoadingPlaceholder slot="fallback" label={labels.loading} />
+				</LikeC4InlineView>
+			) : (
+				<LikeC4ProjectView viewId={viewId} projectId={likec4Id} labels={labels} client:only="react">
+					{/* Without `slot="fallback"`, Astro parks it in an inert <template>. */}
+					<LoadingPlaceholder slot="fallback" label={labels.loading} />
+				</LikeC4ProjectView>
+			)
+		}
 	</DiagramFrame>
 </DiagramShell>
 
 <style>
-	/* Same token contract as DiagramShell (see the note there). */
+	/* See DiagramShell for the token contract. */
 	.likec4-badge {
-		--likec4-border: var(--sl-color-gray-5, rgba(128, 128, 128, 0.35));
-		--likec4-surface: var(--sl-color-bg, transparent);
-		--likec4-text-muted: var(--sl-color-gray-2, rgba(128, 128, 128, 0.95));
+		--_likec4-border: var(--likec4-border, var(--sl-color-gray-5, rgba(128, 128, 128, 0.35)));
+		--_likec4-surface: var(--likec4-surface, var(--sl-color-bg, transparent));
+		--_likec4-text-muted: var(--likec4-text-muted, var(--sl-color-gray-2, rgba(128, 128, 128, 0.95)));
 
 		display: inline-flex;
 		align-items: center;
 		gap: 0.5rem;
 		margin-bottom: 0.75rem;
-		border: 1px solid var(--likec4-border);
+		border: 1px solid var(--_likec4-border);
 		border-radius: 9999px;
-		background: var(--likec4-surface);
+		background: var(--_likec4-surface);
 		padding: 0.25rem 0.75rem;
 		font-size: 0.75rem;
 		line-height: 1rem;
-		color: var(--likec4-text-muted);
+		color: var(--_likec4-text-muted);
 	}
 </style>

package/src/components/LoadingPlaceholder.astro

@@ -1,9 +1,4 @@
 ---
-// 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;
 }
@@ -22,16 +17,16 @@ const { label } = Astro.props;
 </div>
 
 <style>
-	/* Same token contract as DiagramShell/DiagramFrame (see the note there). */
+	/* See DiagramShell for the token contract. */
 	.likec4-loading {
-		--likec4-border: var(--sl-color-gray-5, rgba(128, 128, 128, 0.35));
-		--likec4-surface: var(--sl-color-bg, transparent);
-		--likec4-text-muted: var(--sl-color-gray-2, rgba(128, 128, 128, 0.95));
-		--likec4-skeleton: var(--sl-color-gray-6, rgba(128, 128, 128, 0.18));
+		--_likec4-border: var(--likec4-border, var(--sl-color-gray-5, rgba(128, 128, 128, 0.35)));
+		--_likec4-surface: var(--likec4-surface, var(--sl-color-bg, transparent));
+		--_likec4-text-muted: var(--likec4-text-muted, var(--sl-color-gray-2, rgba(128, 128, 128, 0.95)));
+		--_likec4-skeleton: var(--likec4-skeleton, var(--sl-color-gray-6, rgba(128, 128, 128, 0.18)));
 
-		border: 1px dashed var(--likec4-border);
+		border: 1px dashed var(--_likec4-border);
 		border-radius: 0.5rem;
-		background: var(--likec4-surface);
+		background: var(--_likec4-surface);
 		padding: 1.25rem;
 	}
 
@@ -40,7 +35,7 @@ const { label } = Astro.props;
 		font-size: 0.875rem;
 		line-height: 1.25rem;
 		font-weight: 500;
-		color: var(--likec4-text-muted);
+		color: var(--_likec4-text-muted);
 	}
 
 	.likec4-loading__lines {
@@ -51,7 +46,7 @@ const { label } = Astro.props;
 	.likec4-loading__line {
 		height: 1rem;
 		border-radius: 0.25rem;
-		background: var(--likec4-skeleton);
+		background: var(--_likec4-skeleton);
 		animation: likec4-pulse 1.6s ease-in-out infinite;
 	}
 

package/src/components/icon-source.ts

@@ -1,20 +1,10 @@
-// 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.
+// Local icons are normally rewritten to `/_astroc4/…` URLs at build time by
+// src/icon-plugin.ts; a `file://` value reaching here is one the build could
+// not attribute to a project.
 
 /** 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 =
@@ -23,14 +13,8 @@ export type IconSource =
 	| { 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.
+ * `pack` is anything the LikeC4 renderer handles itself; `unresolvable` is a
+ * build-machine path with no web equivalent, which renders nothing (and warns).
  */
 export function classifyIcon(icon: string | null | undefined): IconSource {
 	const value = icon?.trim();
@@ -39,7 +23,6 @@ export function classifyIcon(icon: string | null | undefined): IconSource {
 		return { kind: 'pack' };
 	}
 
-	// Absolute URLs (and protocol-relative ones) are already web-addressable.
 	if (/^(https?:)?\/\//i.test(value)) {
 		return { kind: 'url', src: value };
 	}

package/src/components/labels.ts

@@ -1,19 +1,13 @@
-// 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.
+// The Astro wrappers translate on the server and pass islands plain strings,
+// because `Astro.locals.t` does not exist in the browser.
 
-// Ships alongside this file: `files` publishes `src/components` *and*
-// `src/translations.ts`, so the components stay self-contained source. The
-// specifier keeps its `.js` extension because that is what the emitted
-// declarations carry and what the site's bundler maps back to this `.ts` file.
-import { translations } from '../translations.js';
+// `files` publishes `src/translations.ts` next to `src/components`, so this
+// resolves in an installed package.
+import { translations } from '../translations.ts';
 
 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;
@@ -23,6 +17,8 @@ export type IslandLabels = {
 	noProjects: string;
 	/** Template: `{projectId}`, `{available}`. */
 	unknownProject: string;
+	/** Template: `{available}`. */
+	projectRequired: string;
 	unresolvedProject: string;
 	/** Template: `{projectId}`. */
 	loadFailed: string;
@@ -30,10 +26,7 @@ export type IslandLabels = {
 
 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.
- */
+/** `t` is absent on any page Starlight does not render, so English is the fallback. */
 export function getTranslator(t: unknown): Translate {
 	if (typeof t !== 'function') return english;
 
@@ -53,6 +46,7 @@ export function getIslandLabels(t: Translate, loadingKey: TranslationKey): Islan
 		viewIdRequired: t('likec4.error.viewIdRequired'),
 		noProjects: t('likec4.error.noProjects'),
 		unknownProject: t('likec4.error.unknownProject'),
+		projectRequired: t('likec4.error.projectRequired'),
 		unresolvedProject: t('likec4.error.unresolvedProject'),
 		loadFailed: t('likec4.error.loadFailed'),
 	};
@@ -60,7 +54,7 @@ export function getIslandLabels(t: Translate, loadingKey: TranslationKey): Islan
 
 export const DEFAULT_LABELS: IslandLabels = getIslandLabels(english, 'likec4.view.loading');
 
-/** Fill `{name}` placeholders. Unknown names are left in place so they show up. */
+/** Unknown placeholders 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/md-fences.tsx

@@ -0,0 +1,37 @@
+// Mounts the islands into the placeholders src/fences.ts writes for .md pages.
+
+import { likec4IdFor, projectNames } from 'virtual:astroc4/projects';
+import { createRoot } from 'react-dom/client';
+
+import { DEFAULT_LABELS } from './labels';
+import LikeC4InlineView from './LikeC4InlineView';
+import LikeC4ProjectView from './LikeC4ProjectView';
+import { resolveProjectId } from './utils';
+
+const SELECTOR = '[data-astroc4-fence]:not([data-astroc4-mounted])';
+
+export function mountFences(root: ParentNode = document): void {
+	for (const placeholder of root.querySelectorAll<HTMLElement>(SELECTOR)) {
+		placeholder.dataset.astroc4Mounted = '';
+
+		const frame = placeholder.querySelector<HTMLElement>('.likec4-frame') ?? placeholder;
+		const { viewId = '', model, project } = placeholder.dataset;
+
+		createRoot(frame).render(
+			model !== undefined ? (
+				<LikeC4InlineView model={JSON.parse(model)} viewId={viewId} labels={DEFAULT_LABELS} />
+			) : (
+				<LikeC4ProjectView viewId={viewId} projectId={likec4Id(project)} labels={DEFAULT_LABELS} />
+			),
+		);
+	}
+}
+
+/** A page's project name as LikeC4's id; anything unknown is left for the island to report. */
+function likec4Id(project: string | undefined): string | undefined {
+	if (projectNames.length === 0) return project;
+
+	const { resolvedProjectId } = resolveProjectId(project, projectNames, DEFAULT_LABELS);
+
+	return resolvedProjectId ? likec4IdFor[resolvedProjectId] : project;
+}

package/src/components/render-icon.tsx

@@ -1,16 +1,7 @@
-// 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);

package/src/components/utils.ts

@@ -1,13 +1,8 @@
-// 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'
+	'viewIdRequired' | 'noProjects' | 'unknownProject' | 'projectRequired' | 'loadFailed'
 >;
 
 export function getAvailableProjectIds(
@@ -38,7 +33,18 @@ export function resolveProjectId(
 		};
 	}
 
-	const resolvedProjectId = projectId?.trim() || availableProjectIds[0]!;
+	const requested = projectId?.trim();
+
+	// With several projects, "the first one found" depends on folder order —
+	// a reorder would silently change the diagram — so the page has to say.
+	if (!requested && availableProjectIds.length > 1) {
+		return {
+			resolvedProjectId: null,
+			error: format(labels.projectRequired, { available: availableProjectIds.join(', ') }),
+		};
+	}
+
+	const resolvedProjectId = requested || availableProjectIds[0]!;
 
 	if (!availableProjectIds.includes(resolvedProjectId)) {
 		return {
@@ -56,6 +62,33 @@ export function resolveProjectId(
 	};
 }
 
+/**
+ * The `import.meta.glob` key for `<LikeC4View file="…">`, or `null`. Only files
+ * under `src/` can match the glob, so a path that climbs out loads nothing.
+ */
+export function fileKey(file: string): string | null {
+	// Absolute paths (`/etc/x.c4`, `C:/x.c4`, `\\server\x.c4`) are never relative to src/.
+	if (/^[\\/]/.test(file) || /^[a-z]:/i.test(file)) return null;
+
+	const segments: string[] = [];
+
+	for (const segment of file.split(/[\\/]+/)) {
+		if (segment === '' || segment === '.') continue;
+
+		if (segment === '..') {
+			if (segments.length === 0) return null;
+			segments.pop();
+			continue;
+		}
+
+		segments.push(segment);
+	}
+
+	const path = segments.join('/');
+
+	return path.toLowerCase().endsWith('.c4') ? `/src/${path}` : null;
+}
+
 export function toLoadErrorMessage(
 	err: unknown,
 	resolvedProjectId: string,

package/src/translations.ts

@@ -1,13 +1,5 @@
-// translations.mjs
-// path: src/translations.mjs
-// UI strings for the diagram components, injected into Starlight's i18n system
-// by the plugin's `i18n:setup` hook. A site overrides or adds a language the
-// same way it does for Starlight's own strings — a `src/content/i18n/<lang>.json`
-// containing any of these keys.
-//
-// Placeholders are `{name}`, not i18next's `{{name}}`: some values (the list of
-// available projects, say) are only known in the browser, so the template has
-// to reach the island unformatted. See `format()` in src/components/labels.ts.
+// Placeholders are `{name}`, not i18next's `{{name}}`: some values are only
+// known in the browser, so the template has to reach the island unformatted.
 
 export const translations = {
 	en: {
@@ -25,6 +17,7 @@ export const translations = {
 		'likec4.error.viewIdRequired': 'A LikeC4 viewId is required to render the diagram.',
 		'likec4.error.noProjects': 'No LikeC4 projects are available in this workspace.',
 		'likec4.error.unknownProject': 'Unknown LikeC4 projectId "{projectId}". Available projects: {available}.',
+		'likec4.error.projectRequired': 'Several LikeC4 projects exist ({available}); pass project="…".',
 		'likec4.error.unresolvedProject': 'Unable to resolve a LikeC4 project.',
 		'likec4.error.loadFailed': 'Unable to load LikeC4 project "{projectId}".',
 	},