caracms 0.0.0-stage → 0.2.0

package/src/skipped.ts

@@ -0,0 +1,35 @@
+/**
+ * The mark a preview render leaves where a block it skips would be (M3 Decision 17;
+ * Blocks.astro): an HTML comment, `<!--cms-skipped 3 type=carousel-->` (with
+ * ` shared=footer` for a shared-block entry), never an element. A site's sibling CSS
+ * (`+`, `:has(+ …)`) matches across a comment, so the preview's blocks join as the
+ * public page's do, where there's nothing for the block at all. The editor finds the
+ * comment (preview/markers.ts → skippedAnchor) and draws its mark in the overlay layer.
+ *
+ * The type and shared name are percent-encoded, so no `--` or `>` from a content
+ * file can end the comment early.
+ */
+
+const PREFIX = 'cms-skipped ';
+
+/** The comment for block `index`, skipped, as HTML. */
+export function skippedMarker(index: number, skipped: { type: string; shared?: string }): string {
+	const shared = skipped.shared !== undefined ? ` shared=${encodeURIComponent(skipped.shared)}` : '';
+	return `<!--${PREFIX}${index} type=${encodeURIComponent(skipped.type)}${shared}-->`;
+}
+
+/** A comment's text read back, or null when it isn't a skipped block's. */
+export function parseSkipped(text: string): { index: number; type: string; shared?: string } | null {
+	if (!text.startsWith(PREFIX)) return null;
+	const [index, ...rest] = text.slice(PREFIX.length).trim().split(' ');
+	if (!/^\d+$/.test(index ?? '')) return null;
+	const out: { index: number; type: string; shared?: string } = { index: Number(index), type: '' };
+	for (const part of rest) {
+		const eq = part.indexOf('=');
+		const key = part.slice(0, eq);
+		const value = decodeURIComponent(part.slice(eq + 1));
+		if (key === 'type') out.type = value;
+		else if (key === 'shared') out.shared = value;
+	}
+	return out;
+}

package/src/slug.ts

@@ -0,0 +1,121 @@
+/**
+ * Addresses from names, and the rules a new document's address follows (M5a
+ * Decision 11). **Browser-safe** (its one import, code-routes.ts, is too): Phase 5's New page dialog shows the
+ * address before creating with `slugify`, and can check it with `addressProblem`;
+ * the create route (editor/server/create.ts) applies the same two, so the dialog and
+ * the server never disagree.
+ *
+ * - **`slugify(name)`**: lower case, accents folded (NFKD, marks dropped, plus the few
+ *   letters that don't decompose: ß ss, æ ae, œ oe, ø o, ł l, đ/ð d, þ th, ı i), `&`
+ *   as "and", every other run of characters that aren't letters or digits as one
+ *   hyphen, hyphens trimmed from both ends, at most 60 characters (cut, then trimmed
+ *   again). Letters and digits are Unicode's (`\p{L}`, `\p{N}`), as the decision words
+ *   it, so a name in another script keeps its letters. A name that leaves nothing
+ *   (only symbols) gives `''`, which the dialog and the route refuse.
+ * - **`isSlug(part)`**: a part of an address that `slugify` leaves as it is.
+ * - **`addressProblem(url, …)`**: why a new document can't have this public address,
+ *   or null: under the editor's own `/admin` or `/_caracms`, or the library's files'
+ *   `/files` (M6c Decision 3, served by files-route.ts); strictly below another
+ *   collection's non-root `urlBase` (exactly at it is allowed: the Work page at
+ *   `/work`); or another document's address already, in any collection.
+ */
+import { codeRouteAt, codeRouteMessage, type CodeRoute } from './code-routes.ts';
+
+/** The longest an address part may be (Decision 11). */
+export const SLUG_MAX = 60;
+
+/** `index` is Home's file name (M3 Decision 8), so no part of a new address can be it. */
+export const RESERVED_SLUG = 'index';
+
+const FOLD: Record<string, string> = { ß: 'ss', æ: 'ae', œ: 'oe', ø: 'o', ł: 'l', đ: 'd', ð: 'd', þ: 'th', ı: 'i' };
+
+/** A name as an address part: `Kiln & Co.` → `kiln-and-co`, `Café Ölé` → `cafe-ole`. `''` when nothing is left. */
+export function slugify(name: string): string {
+	let s = String(name).normalize('NFKD').replace(/\p{M}+/gu, '').toLowerCase();
+	s = s.replace(/[ßæœøłđðþı]/g, (c) => FOLD[c]!);
+	s = s.replace(/&/g, ' and ');
+	s = s.replace(/[^\p{L}\p{N}]+/gu, '-').replace(/^-+|-+$/g, '');
+	s = s.normalize('NFC');
+	const chars = [...s];
+	if (chars.length > SLUG_MAX) s = chars.slice(0, SLUG_MAX).join('').replace(/-+$/, '');
+	return s;
+}
+
+/** Is this an address part `slugify` leaves unchanged (and not empty)? */
+export function isSlug(part: string): boolean {
+	return typeof part === 'string' && part.length > 0 && slugify(part) === part;
+}
+
+/** The message for a name that leaves no address (only symbols). */
+export const NO_ADDRESS_MESSAGE = 'That name has no letters or numbers to make an address from.';
+
+/** The message for `index` as an address. */
+export const INDEX_MESSAGE = '"index" is kept for Home, so it can\'t be an address. Choose another name.';
+
+/** What `addressProblem` needs of a collection. */
+export interface AddressCollection {
+	name: string;
+	label: string;
+	/** Starts and ends with `/`; null for collections with no pages (shared blocks, Site Settings). */
+	urlBase: string | null;
+}
+
+/** What `addressProblem` needs of a document. */
+export interface AddressDocument {
+	collection: string;
+	path: string;
+	url: string | null;
+}
+
+export type AddressProblemCode = 'reserved-address' | 'below-collection' | 'address-taken';
+
+export interface AddressProblem {
+	code: AddressProblemCode;
+	message: string;
+}
+
+/** An address compared with others: lower case, no trailing slash (`/` stays `/`). */
+export const sameAddress = (url: string): string => {
+	const lower = url.toLowerCase();
+	return lower.length > 1 ? lower.replace(/\/+$/, '') : lower;
+};
+
+/**
+ * Why a new document in `collection` can't be at `url` (its public address), or null.
+ * `documents` is every document there is now, in every collection.
+ */
+export function addressProblem(
+	url: string,
+	collection: string,
+	collections: readonly AddressCollection[],
+	documents: readonly AddressDocument[],
+	codeRoutes?: readonly CodeRoute[],
+): AddressProblem | null {
+	const at = sameAddress(url);
+	for (const reserved of ['/admin', '/_caracms']) {
+		if (at === reserved || at.startsWith(`${reserved}/`)) {
+			return { code: 'reserved-address', message: `${url} is the editor's own address, so a page can't go there.` };
+		}
+	}
+	const files = '/files';
+	if (at === files || at.startsWith(`${files}/`)) {
+		return { code: 'reserved-address', message: `${url} is where the library's files are served, so a page can't go there.` };
+	}
+	// M8 Decision 10: a URL the site's own code serves.
+	const route = codeRouteAt(url, codeRoutes);
+	if (route) return { code: 'reserved-address', message: codeRouteMessage(url, route) };
+	for (const other of collections) {
+		if (other.name === collection || other.urlBase === null) continue;
+		const base = sameAddress(other.urlBase);
+		if (base === '/') continue;
+		if (at.startsWith(`${base}/`)) {
+			return {
+				code: 'below-collection',
+				message: `${url} is under ${other.label} (${other.urlBase}), so it can't be a page here. Create it in ${other.label} instead.`,
+			};
+		}
+	}
+	const taken = documents.find((d) => d.url !== null && sameAddress(d.url) === at);
+	if (taken) return { code: 'address-taken', message: `There's already a page at ${url}.` };
+	return null;
+}

package/src/text-styles.ts

@@ -0,0 +1,62 @@
+/**
+ * Text styles (Spec → Text: "defined once per site"). The same definition drives
+ *   - the CSS (the Lockup component reads it into custom properties, and the
+ *     integration registers its font with Astro's fonts API),
+ *   - the measurement (measure.ts shapes text with these axes, tracking and transform),
+ *   - and the editor's "Too long for mobile" warning (Phase 3), which compares the
+ *     phone preview's computed size with `minSizePx` (exposed on the lockup in
+ *     preview renders as `data-cms-min-size`).
+ *
+ * Plain data with no imports, so a site's config, components, tests and the editor
+ * can all import it.
+ */
+
+export type TextTransform = 'none' | 'uppercase' | 'lowercase';
+
+export interface TextStyle {
+	/** The CSS font-family name the fonts API registers. */
+	family: string;
+	/** The CSS variable Astro's fonts API defines for the family, e.g. `--font-display`. */
+	cssVariable: `--${string}`;
+	/** Font files, relative to the site's root. */
+	fontFile: {
+		/** The file measured at render (harfbuzzjs reads TTF/OTF, not WOFF2). */
+		measure: string;
+		/** The file the page serves, through Astro's fonts API. */
+		web: string;
+	};
+	/** The `@font-face` weight range of a variable web font, e.g. `"200 800"`. */
+	weightRange: string;
+	/**
+	 * Every variable axis pinned to one value (M1 → E4). Set in CSS with
+	 * `font-variation-settings` (plus `font-optical-sizing: none`) and used by the
+	 * shaper, so the em width doesn't change with the font size. A static font: `{}`.
+	 */
+	axes: Record<string, number>;
+	/** The design size in px. The fit never goes above it. */
+	sizePx: number;
+	/** Editorial minimum in px. Not a CSS floor (Spec → Text); the editor's warning reads it. */
+	minSizePx: number;
+	/** Letter-spacing in em, so it scales with the font size. */
+	trackingEm: number;
+	/** Line height, unitless. */
+	leading: number;
+	/** Applied before shaping, as the browser does. */
+	textTransform: TextTransform;
+	/** Fallback families after the web font. Default `['sans-serif']`. */
+	fallbacks?: string[];
+}
+
+/** A style plus its name in the site's config, and its font files resolved to absolute paths. */
+export interface ResolvedTextStyle extends TextStyle {
+	name: string;
+	/** Absolute paths, resolved against the site's root by the integration. */
+	resolvedFontFile: { measure: string; web: string };
+}
+
+/** CSS `font-variation-settings` value for a style's pinned axes (`normal` if none). */
+export function variationSettings(style: Pick<TextStyle, 'axes'>): string {
+	const entries = Object.entries(style.axes);
+	if (entries.length === 0) return 'normal';
+	return entries.map(([tag, value]) => `"${tag}" ${value}`).join(', ');
+}

package/src/virtual.d.ts

@@ -0,0 +1,28 @@
+// Types for the integration's virtual modules (see index.ts). A site gets these
+// through `.astro/types.d.ts` (the integration's injectTypes).
+
+declare module 'virtual:caracms/config' {
+	export const site: import('./config.ts').ResolvedSite;
+}
+
+declare module 'virtual:caracms/public' {
+	/** M6: the site's address, Turnstile's site key and the build's kind, as the integration read them at build. */
+	export const build: import('./index.ts').PublicBuild;
+}
+
+declare module 'virtual:caracms/blocks' {
+	/** Block type → its Astro component. */
+	export const blocks: Record<string, (props: import('./document.ts').BlockProps<any>) => any>;
+}
+
+declare module 'virtual:caracms/page' {
+	/** The site's page component. */
+	export const Page: (props: import('./document.ts').PageProps) => any;
+}
+
+declare module 'virtual:caracms/collections' {
+	/** A list-of-fields collection's name → its Astro component (M5a Decision 7). */
+	export const components: Record<string, (props: import('./document.ts').FieldsDocumentProps<any>) => any>;
+}
+
+declare module 'virtual:caracms/lockup.css' {}