caracms 0.3.4 → 0.5.0

package/src/content.ts

@@ -11,9 +11,11 @@
  *   is the URL, `index.json` at the top is the collection's `urlBase`, and an
  *   `index.json` any deeper is an error, listed with a warning and not opened.
  * - **Order** (Decision 8): the reader provides it. `listDocuments` returns a nested
- *   collection in tree order (each level: Home first, then alphabetical by title,
- *   with a folder that has no page of its own sorted by its label), and a flat
- *   collection alphabetically by title. `pageTree` builds the tree itself.
+ *   collection in tree order, and a flat collection alphabetically by title. `pageTree`
+ *   builds the tree itself; each level follows page-order.ts (arrange pages, Decision 7:
+ *   Home first, then Site Settings' saved `pageOrder` for Pages, read from the same
+ *   source first, then what has pages under it, then A–Z, a folder with no page of its
+ *   own sorted by its label).
  * - A file that isn't valid JSON, or has no `title`, is listed with a warning and
  *   can't be opened (Decision 9).
  * - **Two sources, one set of rules** (M4 Current state): the files come from a
@@ -36,6 +38,11 @@ import { isBuiltInColumn } from './columns.ts';
 import { fieldsCover, sectionsCover, type CardCover } from './cards.ts';
 import { own, parseAnyDocument, type AnyDocument, type DocumentKind } from './document.ts';
 import { parseSource } from './json-source.ts';
+import { hasHeld, heldBases, type HeldBase } from './held.ts';
+import { leftBehindMessage, leftBehindRoutes, ownRoutedCollections } from './code-routes.ts';
+import { sameAddress } from './slug.ts';
+import { byLabel, isOrderedCollection, orderSiblings, parsePageOrder, type PageOrder } from './page-order.ts';
+import { SITE_SETTINGS_FILE } from './reserved.ts';
 
 // Posts and tags, Decision 14: a route's reader on the disk (read.ts).
 export { contentReader } from './read.ts';
@@ -79,6 +86,21 @@ export interface DocumentEntry {
 	 */
 	hidden?: true;
 	hiddenBy?: string;
+	/**
+	 * The page's own `"hidden": true`, kept apart from `hiddenBy`: a page hidden itself and also
+	 * under a hidden page has both, and the arrange screen needs to know it stays hidden when moved.
+	 */
+	hiddenSelf?: true;
+	/**
+	 * Collections under pages (Decision 11): set when `hiddenBy` is a page of another collection,
+	 * the page that holds this document's collection (`pages`). Absent: `hiddenBy` is in this one.
+	 */
+	hiddenByCollection?: string;
+	/**
+	 * Collections under pages (Decision 5): a page's `"holds"`, the collection it holds (held.ts).
+	 * Read from a file that can't be opened too, as far as it can be, so a broken holder is named.
+	 */
+	holds?: string;
 	/** A section builder's shared-block entries, by shared block path, in block order, once each (Decision 8). Absent otherwise. */
 	uses?: string[];
 	/** A shared block: its block's type (`''` when it has none). Absent otherwise. */
@@ -220,13 +242,17 @@ export function resolveDocumentFile(site: Pick<ResolvedSite, 'collections'>, col
 	return file;
 }
 
-/** Every document in one collection, or in all of them (in config order), with warnings, in the editor's order. */
+/**
+ * Every document in one collection, in several (in the order given), or in all of them (in
+ * config order), with warnings, in the editor's order. A held collection's documents have
+ * their resolved addresses (held.ts), whichever collections are listed.
+ */
 export async function listDocuments(
 	site: Pick<ResolvedSite, 'collections' | 'root' | 'blocks'>,
-	collectionName?: string,
+	collectionName?: string | readonly string[],
 	source: ContentSource = diskSource,
 ): Promise<DocumentEntry[]> {
-	const names = collectionName ? [collectionName] : Object.keys(site.collections);
+	const names = collectionName === undefined ? Object.keys(site.collections) : typeof collectionName === 'string' ? [collectionName] : [...collectionName];
 	const all: DocumentEntry[] = [];
 	for (const name of names) {
 		const collection = own(site.collections, name);
@@ -234,9 +260,24 @@ export async function listDocuments(
 		const paths = await documentPaths(collection, source);
 		const entries = (await Promise.all(paths.map((path) => entryFor(site, collection, path, source)))).filter((e) => e !== null);
 		if (collection.nested) hideChildren(entries);
-		all.push(...(collection.nested ? flattenTree(pageTree(entries)) : entries.sort(byLabel)));
+		// Arrange pages (Decision 6): Pages follow Site Settings' saved order, read through the same source.
+		const order = isOrderedCollection(collection) ? await savedPageOrder(site, source) : undefined;
+		all.push(...(collection.nested ? flattenTree(pageTree(entries, order)) : entries.sort(byLabel)));
+	}
+	// Collections under pages (Decision 7): a held collection's addresses come from its holder's listing.
+	const held = names.map((n) => site.collections[n]!).filter((c) => c.heldBy);
+	if (held.length) {
+		const holding: DocumentEntry[] = [];
+		for (const by of new Set(held.map((c) => c.heldBy!))) {
+			holding.push(...(names.includes(by) ? all.filter((e) => e.collection === by) : await listDocuments(site, by, source)));
+		}
+		const bases = heldBases(site.collections, holding);
+		for (const entry of all) {
+			const base = own(bases, entry.collection);
+			if (base) placeHeld(entry, base);
+		}
 	}
-	if (!collectionName) {
+	if (collectionName === undefined) {
 		// Decision 8's "used on": every document whose block list has an entry for the shared block.
 		for (const entry of all) {
 			if (entry.kind !== 'shared') continue;
@@ -246,6 +287,59 @@ export async function listDocuments(
 	return all;
 }
 
+/**
+ * Arrange pages (Decision 6): Site Settings' `pageOrder` through `source` (live mode: the
+ * `drafts` copy with the autosaves on top); `{}` when there's none or the file can't be read.
+ */
+export async function savedPageOrder(site: Pick<ResolvedSite, 'root'>, source: ContentSource = diskSource): Promise<PageOrder> {
+	const text = await source.readText(join(site.root, SITE_SETTINGS_FILE)).catch(() => null);
+	if (text === null) return {};
+	try {
+		const raw = JSON.parse(text) as unknown;
+		return raw && typeof raw === 'object' && !Array.isArray(raw) ? parsePageOrder((raw as Record<string, unknown>).pageOrder) : {};
+	} catch {
+		return {};
+	}
+}
+
+/** A held document's address and hidden mark from its collection's resolved base (held.ts). */
+function placeHeld(entry: DocumentEntry, held: HeldBase): void {
+	entry.url = held.base === null ? null : held.base + entry.path;
+	// Decision 11: a hidden holder hides its documents, as a hidden page hides the pages under it.
+	if (held.hidden && held.holder) {
+		entry.hidden = true;
+		entry.hiddenBy = held.holder.path;
+		entry.hiddenByCollection = held.holder.collection;
+	}
+}
+
+/** A held collection's resolved base, from its holder collection's listing through `source`. */
+export async function heldBaseOf(site: Pick<ResolvedSite, 'collections' | 'root' | 'blocks'>, collectionName: string, source: ContentSource = diskSource): Promise<HeldBase | null> {
+	const collection = own(site.collections, collectionName);
+	if (!collection?.heldBy) return null;
+	return heldBases({ [collection.name]: collection }, await listDocuments(site, collection.heldBy, source))[collection.name] ?? null;
+}
+
+/** Every held collection's resolved base (held.ts), from the listings of the collections that hold them; `{}` on a site with none. */
+export async function heldBasesOf(site: Pick<ResolvedSite, 'collections' | 'root' | 'blocks'>, source: ContentSource = diskSource): Promise<Record<string, HeldBase>> {
+	if (!hasHeld(site.collections)) return {};
+	const by = [...new Set(Object.values(site.collections).flatMap((c) => (c.heldBy ? [c.heldBy] : [])))];
+	const holding = (await Promise.all(by.map((name) => listDocuments(site, name, source)))).flat();
+	return heldBases(site.collections, holding);
+}
+
+/**
+ * A document's public address as its listing gives it: `documentUrl` for a collection with a
+ * prefix, the holder's address + `/` + the path for a held one (null while it isn't held).
+ */
+export async function documentAddress(site: Pick<ResolvedSite, 'collections' | 'root' | 'blocks'>, collectionName: string, path: string, source: ContentSource = diskSource): Promise<string | null> {
+	const collection = own(site.collections, collectionName);
+	if (!collection) return null;
+	if (!collection.heldBy) return documentUrl(collection, path);
+	const held = await heldBaseOf(site, collectionName, source);
+	return held?.base ? held.base + path : null;
+}
+
 /** M9 Decision 7: a hidden page's children are hidden with it; `hiddenBy` names the topmost hidden page above. */
 function hideChildren(entries: DocumentEntry[]): void {
 	const hidden = new Set(entries.filter((e) => e.hidden).map((e) => e.path));
@@ -279,6 +373,10 @@ export async function readDocument(
 	if (text === null) throw new DocumentError('not-found', `${collection.label}: no document "${path}".`);
 	const { entry, document } = inspect(site, collection, path, text);
 	if (entry.warning || !document) throw new DocumentError(entry.warning!.code, entry.warning!.message);
+	if (collection.heldBy) {
+		const held = await heldBaseOf(site, collection.name, source);
+		if (held) placeHeld(entry, held);
+	}
 	return { entry, text, document };
 }
 
@@ -312,10 +410,12 @@ function inspect(
 		url: documentUrl(collection, path),
 	};
 	const fileLabel = titleCase(path.split('/').pop()!);
-	const warn = (code: WarningCode, message: string, title = '') => ({
-		entry: { ...base, title, label: title || fileLabel, warning: { code, message } },
-		document: null,
-	});
+	// Decision 13: a broken holder is named, so its `"holds"` is read from the text as far as it can be.
+	const holdsIn = () => (collection.kind === 'sections' ? /"holds"\s*:\s*"([^"\\]*)"/.exec(text)?.[1] : undefined);
+	const warn = (code: WarningCode, message: string, title = '') => {
+		const holds = holdsIn();
+		return { entry: { ...base, title, label: title || fileLabel, warning: { code, message }, ...(holds !== undefined ? { holds } : {}) }, document: null };
+	};
 
 	if (collection.nested && path.endsWith('/index')) {
 		const parent = path.slice(0, -'/index'.length);
@@ -335,7 +435,8 @@ function inspect(
 	}
 	const entry: DocumentEntry = { ...base, title, label: title, warning: null };
 	// M9 Decision 7: the home page is never hidden.
-	if ((document.kind === undefined || document.kind === 'sections') && document.hidden && path !== 'index') entry.hidden = true;
+	if ((document.kind === undefined || document.kind === 'sections') && document.hidden && path !== 'index') entry.hidden = entry.hiddenSelf = true;
+	if ((document.kind === undefined || document.kind === 'sections') && document.holds !== undefined) entry.holds = document.holds;
 	if (document.kind === undefined || document.kind === 'sections') {
 		entry.uses = [...new Set(document.blocks.flatMap((b) => (b.shared !== undefined ? [b.shared] : [])))];
 	} else if (document.kind === 'shared') {
@@ -375,10 +476,11 @@ export type PageTreeNode =
 /**
  * A nested collection's entries as a tree that mirrors their paths. A page with
  * pages under it (`about.json` beside `about/`) is one node with children; a folder
- * with no page is a group. Each level is ordered Home (`index`) first, then
- * alphabetically by label.
+ * with no page is a group. Each level is ordered by page-order.ts → `orderSiblings`
+ * (arrange pages, Decision 7): Home (`index`) first, then the siblings `order` lists
+ * for that level, then those with pages or a held collection under them, then A–Z.
  */
-export function pageTree(entries: readonly DocumentEntry[]): PageTreeNode[] {
+export function pageTree(entries: readonly DocumentEntry[], order: PageOrder = {}): PageTreeNode[] {
 	interface Draft {
 		path: string;
 		entry?: DocumentEntry;
@@ -400,17 +502,15 @@ export function pageTree(entries: readonly DocumentEntry[]): PageTreeNode[] {
 		node.entry = entry;
 	}
 	const build = (draft: Draft): PageTreeNode[] =>
-		[...draft.children.values()]
-			.map((d): PageTreeNode => {
+		orderSiblings(
+			[...draft.children.values()].map((d): PageTreeNode => {
 				const children = build(d);
 				if (d.entry) return { kind: 'page', path: d.path, label: d.entry.label, entry: d.entry, children };
 				return { kind: 'group', path: d.path, label: titleCase(d.path.split('/').pop()!), children };
-			})
-			.sort((a, b) => {
-				if (a.path === 'index' || a.path.endsWith('/index')) return -1;
-				if (b.path === 'index' || b.path.endsWith('/index')) return 1;
-				return byLabel(a, b);
-			});
+			}),
+			Object.hasOwn(order, draft.path) ? order[draft.path] : undefined,
+			(n) => n.children.length > 0 || (n.kind === 'page' && n.entry.holds !== undefined),
+		);
 	return build(top);
 }
 
@@ -418,7 +518,68 @@ function flattenTree(nodes: PageTreeNode[]): DocumentEntry[] {
 	return nodes.flatMap((n) => [...(n.kind === 'page' ? [n.entry] : []), ...flattenTree(n.children)]);
 }
 
-const collator = new Intl.Collator('en', { sensitivity: 'base', numeric: true });
-function byLabel(a: { label: string; path: string }, b: { label: string; path: string }): number {
-	return collator.compare(a.label, b.label) || collator.compare(a.path, b.path);
+
+// ── The catch-all's reader (collections under pages, Decision 14) ────────────────
+
+/** A public page the site's catch-all serves: its collection, its path there, and its address. */
+export interface AddressedDocument {
+	collection: string;
+	path: string;
+	/** `/`, `/about`, `/journal/a-day-on-the-ferry`: no trailing slash, as the listing gives it. */
+	url: string;
+}
+
+/** What the reader reads: the site, and the routes in its `src/pages/` (the integration sets `pageRoutes`). */
+type CatchAllSite = Pick<ResolvedSite, 'collections' | 'root' | 'blocks'> & Partial<Pick<ResolvedSite, 'pageRoutes'>>;
+
+const logged = new Set<string>();
+/** The build's and dev's log, once per sentence per process (Decision 13: logged, never a failed build). */
+function logOnce(message: string): void {
+	if (logged.has(message)) return;
+	logged.add(message);
+	console.warn(`[caracms] ${message}`);
+}
+
+/**
+ * Every public page of every collection with an address, for the site's one catch-all route
+ * (`src/pages/[...path].astro`'s `getStaticPaths`): Pages, every held collection's documents at
+ * their holder's address, and every prefix collection's (`/tags/<slug>`), in config order then
+ * the editor's. Left out: a file that can't be opened, a hidden page (and the documents of a
+ * hidden holder), a held collection no page holds, and a prefix collection whose base has its
+ * own route (`src/pages/tags/[slug].astro`), which that route serves. A holder problem or a
+ * route left at a held base is logged once (`caracms validate` reports both as errors).
+ * `source`: where the files come from (the disk by default, as a build reads them).
+ */
+export async function addressedDocuments(site: CatchAllSite, source: ContentSource = diskSource): Promise<AddressedDocument[]> {
+	const collections = Object.values(site.collections);
+	const routes = site.pageRoutes ?? [];
+	const ownRouted = new Set(ownRoutedCollections(routes, collections).map((c) => c.name));
+	const names = collections.filter((c) => (c.urlBase !== null || c.heldBy) && !ownRouted.has(c.name)).map((c) => c.name);
+	const entries = await listDocuments(site, names, source);
+	if (hasHeld(site.collections)) {
+		const held: { name: string; label: string; base: string; holder: string }[] = [];
+		for (const base of Object.values(await heldBasesOf(site, source))) {
+			if (base.problem) logOnce(base.problem);
+			const c = site.collections[base.collection]!;
+			if (base.base && base.holder) held.push({ name: c.name, label: c.label, base: base.base, holder: base.holder.label });
+		}
+		for (const left of leftBehindRoutes(routes, held)) logOnce(leftBehindMessage(left));
+	}
+	return entries.filter((e): e is DocumentEntry & { url: string } => e.url !== null && !e.warning && !e.hidden).map(({ collection, path, url }) => ({ collection, path, url }));
+}
+
+/**
+ * The document a request's path is (`/journal/a-day-on-the-ferry`, with or without a trailing
+ * slash, URL-encoded or not), for a catch-all that renders on demand; null when no public page
+ * is there (`addressedDocuments` says which are).
+ */
+export async function documentAt(site: CatchAllSite, pathname: string, source: ContentSource = diskSource): Promise<{ collection: string; path: string } | null> {
+	let at: string;
+	try {
+		at = sameAddress(decodeURIComponent(pathname));
+	} catch {
+		return null;
+	}
+	const found = (await addressedDocuments(site, source)).find((d) => sameAddress(d.url) === at);
+	return found ? { collection: found.collection, path: found.path } : null;
 }

package/src/document.ts

@@ -25,6 +25,7 @@ import { parseSource, type ParsedSource } from './json-source.ts';
 import { isFileKey } from './files.ts';
 import { parseMedia } from './media-value.ts';
 import { parseRedirects, type Redirect } from './redirects.ts';
+import { parsePageOrder, type PageOrder } from './page-order.ts';
 import { parseFormRecipients, parseGoogleTag, parseSeo, type Seo } from './seo.ts';
 
 export interface DocumentBlock {
@@ -67,6 +68,13 @@ export interface SiteDocument {
 	 * the key out of the file. The home page (`index`) can't be hidden (content.ts reads it as shown).
 	 */
 	hidden?: boolean;
+	/**
+	 * Collections under pages (Decision 5): the collection this page holds (the file's
+	 * top-level `"holds"`, after `title` and `hidden`): its documents are at this page's
+	 * address + `/` + their slug (held.ts). Edited in the file only, never by the editor,
+	 * whose saves keep it where it is.
+	 */
+	holds?: string;
 	/**
 	 * M6c (G2): the page fields' parsed values, keyed by field, every field of the
 	 * collection's `fields` present (the file's top-level keys after `title`). Present
@@ -121,14 +129,16 @@ export interface SettingsBrand {
 export interface SettingsDocument {
 	kind: 'settings';
 	title: string;
-	data: Record<string, unknown> & { editors: string[]; brand: SettingsBrand; seo?: Seo; googleTag?: string; formRecipients?: Record<string, string[]>; redirects?: Redirect[] };
+	data: Record<string, unknown> & { editors: string[]; brand: SettingsBrand; seo?: Seo; googleTag?: string; formRecipients?: Record<string, string[]>; redirects?: Redirect[]; pageOrder?: PageOrder };
 }
 
 /** M6: Site Settings' search and sharing keys, parsed, each only when `raw` has it. */
-function settingsM6(raw: Record<string, unknown>): { seo?: Seo; googleTag?: string; formRecipients?: Record<string, string[]>; redirects?: Redirect[] } {
+function settingsM6(raw: Record<string, unknown>): { seo?: Seo; googleTag?: string; formRecipients?: Record<string, string[]>; redirects?: Redirect[]; pageOrder?: PageOrder } {
 	return {
 		// Pre-M7 item 8: the redirects changing an address adds (redirects.ts).
 		...(Object.hasOwn(raw, 'redirects') ? { redirects: parseRedirects(raw.redirects) } : {}),
+		// Arrange pages (Decision 6): the Pages tree's saved order (page-order.ts).
+		...(Object.hasOwn(raw, 'pageOrder') ? { pageOrder: parsePageOrder(raw.pageOrder) } : {}),
 		...(Object.hasOwn(raw, 'seo') ? { seo: parseSeo(raw.seo) } : {}),
 		...(Object.hasOwn(raw, 'googleTag') ? { googleTag: parseGoogleTag(raw.googleTag) } : {}),
 		...(Object.hasOwn(raw, 'formRecipients') ? { formRecipients: parseFormRecipients(raw.formRecipients) } : {}),
@@ -225,6 +235,7 @@ export function parseDocument(raw: unknown, site: Pick<ResolvedSite, 'blocks'>):
 		blocks: rawBlocks.map((b, index) => parseBlock(b, index, site)),
 		...seoOf(doc),
 		...(doc.hidden === true ? { hidden: true } : {}),
+		...(typeof doc.holds === 'string' ? { holds: doc.holds } : {}),
 	};
 }
 

package/src/editor/README.md

@@ -131,6 +131,9 @@ client/        the browser (and the shell's server render)
   fields/        the block level's fields: FieldFrame, Text, Select, Lockup, lockup-rules.ts
   shell/         App, Bar, Stage, Popovers, Toast, NarrowNote, Icons
   pane/          Pane.tsx (the frame), parts.tsx (shared pieces), switcher.tsx (Phase 4's seam), levels/*
+  arrange/       Arrange pages (notes/2026-10-25-arrange-pages.md): model.ts (the tree, the plan, the checks, the
+                 re-plan; pure), store.ts (arrangeFor(editor): the screen's state, Apply), ArrangeStage.tsx (the
+                 screen in the preview's place, mouse drag); its pane level is pane/levels/ArrangeLevel.tsx
 styles/        tokens.css (the mockup's :root, as is), editor.css (the mockup's chrome CSS), fonts.css,
                levels/*.css (a level's own CSS, loaded by the admin route)
 fonts/         Instrument Sans and Geist Mono (OFL, licences beside them)

package/src/editor/addresses.ts

@@ -30,7 +30,12 @@ export function inboxFromAddress(pathname: string): { id: string | null } | 'bad
 	return isSubmissionId(rest) ? { id: rest } : 'bad';
 }
 
-export const inboxAddress = (id: string | null): string => (id ? `${SUBMISSIONS_ADDRESS}/${encodeURIComponent(id)}` : SUBMISSIONS_ADDRESS);
+/** Arrange pages' address (Decision 15): the screen, with nothing arranged on a reload. */
+export const ARRANGE_ADDRESS = `${ADMIN}/arrange`;
+
+export const isArrangeAddress = (pathname: string): boolean => pathname.replace(/\/+$/, '') === ARRANGE_ADDRESS;
+
+export const inboxAddress =(id: string | null): string => (id ? `${SUBMISSIONS_ADDRESS}/${encodeURIComponent(id)}` : SUBMISSIONS_ADDRESS);
 
 export function addressOf(ref: DocRef, home: DocRef): string {
 	if (sameDoc(ref, home)) return ADMIN;