caracms 0.4.0 → 0.5.0

package/README.md

@@ -80,6 +80,20 @@ renders on demand uses `documentAt(site, pathname)`. A collection needs no route
 own; a prefix collection whose base keeps its own route file is left out of the reader,
 and a route with parameters left at a held collection's address is a `validate` error.
 
+## Arranging pages
+
+The editor's Pages tree reads Home first, then the pages and groups with pages (or a held
+collection) under them, then the rest, each A–Z. To change that, "Arrange pages…" in the
+tree's header opens a screen at `/admin/arrange`: drag pages to order them, nest one under
+a page or group, make and rename groups, then review every old → new address and apply it
+as one change, with one tick for redirects from the old addresses. Nothing changes until
+Apply, and if the pages change underneath it, Apply refuses and shows the review again.
+
+The order is saved in Site Settings as `pageOrder` (each parent's path → its children's
+slugs), so no site field can use that name. It orders the editor's tree, the Inside picker
+and `listDocuments(site, 'pages')`; the site's menus stay lists in Site Settings.
+`caracms validate` warns on an entry that names no page, and `--fix` prunes it.
+
 ## Hosting
 
 caracms runs on any host that keeps one Node server running behind HTTPS: Railway,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caracms",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A visual CMS for Astro sites, with content in git.",
   "license": "MIT",
   "type": "module",

package/src/cli/validate.ts

@@ -33,7 +33,9 @@ import { fieldWarnings, parseDay, richTextOptions, type Field, type Fields, type
 import { measureLockup } from '../measure.ts';
 import { isFileKey } from '../files.ts';
 import { readRichText } from '../rich-text.ts';
-import { savedForm } from '../serialize.ts';
+import { applyKeyedEdits, savedForm } from '../serialize.ts';
+import { isOrderedCollection, prunedOrder, unknownOrderEntries } from '../page-order.ts';
+import { SITE_SETTINGS_FILE } from '../reserved.ts';
 import { SCHEMA_KEY, schemaRef } from '../schema-key.ts';
 import { sameAddress } from '../slug.ts';
 import { hiddenDocuments, hiddenPages } from '../links.ts';
@@ -331,7 +333,7 @@ function checkDocument(c: Context, collection: ResolvedCollection, raw: unknown)
 			else checkBlock(c, raw.block, 'block', null);
 			return;
 		case 'settings': {
-			checkFields(c, own, raw, '', 'Site Settings', 0, [SCHEMA_KEY, 'title', 'editors', 'brand', 'seo', 'googleTag', 'formRecipients', 'redirects', 'holds']);
+			checkFields(c, own, raw, '', 'Site Settings', 0, [SCHEMA_KEY, 'title', 'editors', 'brand', 'seo', 'googleTag', 'formRecipients', 'redirects', 'pageOrder', 'holds']);
 			if (raw.holds !== undefined) error(c, 'holds', HOLDS_ON_A_PAGE);
 			if (raw.editors !== undefined && !strings(raw.editors)) error(c, 'editors', `Expected a list of email addresses, found ${what(raw.editors)}.`);
 			if (raw.brand !== undefined) {
@@ -354,6 +356,9 @@ function checkDocument(c: Context, collection: ResolvedCollection, raw: unknown)
 			if (raw.redirects !== undefined && !(Array.isArray(raw.redirects) && raw.redirects.every((r) => isObject(r) && typeof r.from === 'string' && typeof r.to === 'string'))) {
 				error(c, 'redirects', 'Expected a list of { "from": "/old", "to": "/new" }.');
 			}
+			if (raw.pageOrder !== undefined && !(isObject(raw.pageOrder) && Object.values(raw.pageOrder).every(strings))) {
+				error(c, 'pageOrder', 'Expected { "<parent path>": ["slug", …] }.');
+			}
 			return;
 		}
 	}
@@ -450,6 +455,19 @@ export async function validateSite(site: Site, codeRoutes: readonly CodeRoute[]
 		}
 	}
 
+	// Arrange pages (Decision 6): a saved order's entry that names no page or group (the reader ignores it).
+	const order = savedOrderOf(site);
+	if (order) {
+		for (const u of unknownOrderEntries(order, orderedPaths(site, entries))) {
+			const where = u.key === '' ? 'the top level' : `/${u.key}`;
+			report.warnings.push({
+				file: SITE_SETTINGS_FILE,
+				path: `pageOrder[${JSON.stringify(u.key)}]`,
+				message: u.slug === null ? `The Pages tree's order names ${where}, where there are no pages. \`caracms validate --fix\` prunes it.` : `The Pages tree's order names "${u.slug}" in ${where}, where there's no page or group by that name. \`caracms validate --fix\` prunes it.`,
+			});
+		}
+	}
+
 	for (const change of schemaFileChanges(site)) {
 		report.warnings.push({
 			file: change.file,
@@ -460,6 +478,38 @@ export async function validateSite(site: Site, codeRoutes: readonly CodeRoute[]
 	return report;
 }
 
+/** The Pages collection's paths (page-order.ts → isOrderedCollection). */
+const orderedPaths = (site: Pick<ResolvedSite, 'collections'>, entries: readonly DocumentEntry[]) =>
+	entries.filter((e) => isOrderedCollection(site.collections[e.collection]!)).map((e) => e.path);
+
+/** Site Settings' `pageOrder` as the file has it, or null (no file, no key, or it doesn't parse). */
+function savedOrderOf(site: Pick<ResolvedSite, 'root'>): Record<string, string[]> | null {
+	try {
+		const raw = JSON.parse(readFileSync(join(site.root, SITE_SETTINGS_FILE), 'utf8')) as unknown;
+		const order = isObject(raw) ? raw.pageOrder : undefined;
+		if (!isObject(order) || !Object.values(order).every(strings)) return null;
+		return order as Record<string, string[]>;
+	} catch {
+		return null;
+	}
+}
+
+/** Arrange pages (Decision 6): `--fix` takes the saved order's entries that name nothing out of Site Settings. Returns how many went. */
+export async function prunePageOrder(site: Pick<ResolvedSite, 'root' | 'collections' | 'blocks'>): Promise<number> {
+	const order = savedOrderOf(site);
+	const settings = Object.values(site.collections).find((c) => c.kind === 'settings');
+	if (!order || !settings) return 0;
+	const { order: kept, pruned } = prunedOrder(order, orderedPaths(site, await listDocuments(site)));
+	if (pruned === 0) return 0;
+	const file = join(site.root, SITE_SETTINGS_FILE);
+	const text = readFileSync(file, 'utf8');
+	const raw = JSON.parse(text) as Record<string, unknown>;
+	writeFileSync(file, applyKeyedEdits(text, { title: typeof raw.title === 'string' ? raw.title : '', data: { pageOrder: kept } }, settings));
+	return pruned;
+}
+
+const pruneReport = (n: number) => (n ? `caracms validate --fix:\n  pruned ${n} page-order ${n === 1 ? 'entry' : 'entries'} (${SITE_SETTINGS_FILE})\n` : '');
+
 const REFORMAT_MESSAGE = "This file isn't laid out the way the editor saves it (two-space JSON, a trailing newline), so the editor's next save would reformat it and mix the two. `caracms validate --fix` rewrites it the editor's way, changing no values.";
 
 /**
@@ -504,7 +554,7 @@ export function formatReport(report: Report): string {
 export async function command(root: string, options: { fix?: boolean; json?: boolean } = {}): Promise<{ code: number; out: string; err?: string }> {
 	const site = await loadSite(root);
 	let fixed = '';
-	if (options.fix) fixed = schemasReport(await runSchemas(site)) + reformatReport(await reformatContent(site));
+	if (options.fix) fixed = schemasReport(await runSchemas(site)) + reformatReport(await reformatContent(site)) + pruneReport(await prunePageOrder(site));
 	const report = await validateSite(site);
 	const code = report.errors.length ? 1 : 0;
 	if (options.json) return { code, out: `${JSON.stringify(report, null, 2)}\n`, err: options.fix ? fixed : undefined };

package/src/content-schema.ts

@@ -150,6 +150,7 @@ export function collectionSchema(site: Pick<ResolvedSite, 'blocks'> & Partial<Pi
 					googleTag: string,
 					formRecipients: { type: 'object', additionalProperties: strings },
 					redirects: { type: 'array', items: closed({ from: string, to: string }, ['from', 'to']) },
+					pageOrder: { type: 'object', additionalProperties: strings, description: "The Pages tree's order in the editor: a parent's path (\"\" for the top level) → its children's slugs. Written by Arrange pages." },
 					...own,
 				},
 				['title'],

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
@@ -39,6 +41,8 @@ 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';
@@ -82,6 +86,11 @@ 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.
@@ -251,7 +260,9 @@ 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);
@@ -276,6 +287,21 @@ 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;
@@ -409,7 +435,7 @@ 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] : [])))];
@@ -450,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;
@@ -475,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);
 }
 
@@ -493,10 +518,6 @@ 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) ────────────────
 

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 {
@@ -128,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) } : {}),

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;