caracms 0.0.0-stage → 0.2.0

package/src/editor/client/context.tsx

@@ -0,0 +1,27 @@
+/**
+ * The editor in React: one context holding the editor (editor.ts), and `useStore`
+ * to read any of its stores. A selector must return a stable value (a primitive, or
+ * a part of the state as stored), never a new object, or React re-renders forever.
+ *
+ *   const editor = useEditor();
+ *   const level = useStore(editor.view, (v) => v.level);
+ *   const session = useStore(editor.doc.state);
+ */
+import { createContext, useContext, useSyncExternalStore } from 'react';
+import type { Editor } from './editor.ts';
+import type { Store } from './state/store.ts';
+
+export const EditorContext = createContext<Editor | null>(null);
+
+export function useEditor(): Editor {
+	const editor = useContext(EditorContext);
+	if (!editor) throw new Error('useEditor: no editor (render inside <EditorApp>)');
+	return editor;
+}
+
+export function useStore<T>(store: Store<T>): T;
+export function useStore<T, S>(store: Store<T>, select: (value: T) => S): S;
+export function useStore<T, S>(store: Store<T>, select?: (value: T) => S): T | S {
+	const read = () => (select ? select(store.get()) : store.get());
+	return useSyncExternalStore((onChange) => store.subscribe(onChange), read, read);
+}

package/src/editor/client/documents/DocMenu.tsx

@@ -0,0 +1,154 @@
+/**
+ * The open document's menu in its level header (the mockup's docMenuHTML; #home-menu,
+ * #delete-locked): **View on the live site** (off for a document that isn't live yet)
+ * and **Delete page…** (or Delete <a case study>…, Delete shared block…), which opens
+ * the confirmation (dialogs.tsx). Delete is off, with the reason under it, for Home
+ * ("The home page can't be deleted.") and while someone else is editing it ("Aoife is
+ * editing Contact. It can be deleted once she's done."). A shared block still in use
+ * opens the "still on N pages" dialog instead. Site Settings has no menu.
+ *
+ * Pre-M7 item 8: **Change address…** for a document with an address (a page, a case
+ * study, a journal entry), off for Home or a collection's top page and while someone
+ * else is editing it.
+ *
+ * M6c (G1): a document with no page of its own (a shared block, a fields collection
+ * with no `urlBase`) has neither View on the live site nor Change address…, only Delete.
+ */
+import { useEffect, useRef, useState, type KeyboardEvent } from 'react';
+import { useEditor, useStore } from '../context.tsx';
+import { displayName } from '../live/format.ts';
+import { Icon } from '../shell/Icons.tsx';
+import { docId, sameDoc } from '../../types.ts';
+import { singular } from './actions.ts';
+import { openDialog } from './dialogs.tsx';
+
+export function DocMenu({ label }: { label: string }) {
+	const editor = useEditor();
+	const ref = useStore(editor.doc.state, (s) => s.ref);
+	const entry = useStore(editor.doc.state, (s) => s.entry);
+	const title = useStore(editor.doc.state, (s) => s.document.title || s.entry.label);
+	const documents = useStore(editor.documents);
+	const access = useStore(editor.access);
+	const waiting = useStore(editor.liveState, (s) => s.status?.waiting);
+	const signedOut = useStore(editor.liveState, (s) => !!s.signedOut);
+	const [open, setOpen] = useState(false);
+	const menu = useRef<HTMLDivElement>(null);
+	const button = useRef<HTMLButtonElement>(null);
+	const collection = editor.site.collections.find((c) => c.name === ref.collection);
+
+	useEffect(() => {
+		if (!open) return;
+		menu.current?.querySelector<HTMLButtonElement>('button:not(:disabled)')?.focus();
+		const onDown = (event: MouseEvent) => {
+			const target = event.target as Element | null;
+			if (menu.current?.contains(target) || button.current?.contains(target)) return;
+			setOpen(false);
+		};
+		document.addEventListener('mousedown', onDown);
+		return () => document.removeEventListener('mousedown', onDown);
+	}, [open]);
+	// Another document, another menu.
+	useEffect(() => setOpen(false), [ref]);
+
+	if (!collection || collection.kind === 'settings') return null;
+	const shared = collection.kind === 'shared';
+	const noPage = collection.urlBase === null;
+	const pending = (waiting ?? []).find((w) => w.collection === ref.collection && w.path === ref.path && w.change === 'new');
+	const isNew = !!pending;
+	const listed = documents.find((d) => docId(d) === docId(ref));
+	const home = sameDoc(ref, editor.site.home);
+	const holder = access.lock === 'theirs' && access.holder ? displayName(access.holder.person) : null;
+	const why = home ? "The home page can't be deleted." : holder ? `${holder} is editing ${title}. It can be deleted once they're done.` : access.deleted ? 'It has been deleted already.' : null;
+	const top = collection.nested && ref.path === 'index';
+	const moveWhy = top
+		? home
+			? 'Home is always at /.'
+			: `It's the top of ${collection.label}, so its address is ${collection.label}'s.`
+		: holder
+			? `${holder} is editing it.`
+			: access.held
+				? 'Use mine or Discard mine first.'
+				: signedOut
+					? 'Sign in again first: its unsent changes would be lost.'
+					: !entry.url
+				? "It can't be opened, so its address can't change."
+				: null;
+	const close = () => {
+		setOpen(false);
+		button.current?.focus();
+	};
+	const onKey = (event: KeyboardEvent<HTMLDivElement>) => {
+		if (event.key === 'Escape') {
+			// Closes the menu only; the editor's Esc would go up a level.
+			event.preventDefault();
+			event.stopPropagation();
+			close();
+		} else if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+			event.preventDefault();
+			const items = [...(menu.current?.querySelectorAll<HTMLButtonElement>('button:not(:disabled)') ?? [])];
+			const at = items.indexOf(document.activeElement as HTMLButtonElement);
+			items[(at + (event.key === 'ArrowDown' ? 1 : -1) + items.length) % items.length]?.focus();
+		}
+	};
+	const remove = () => {
+		setOpen(false);
+		if (shared && (listed?.usedOn?.length ?? 0) > 0) openDialog(editor, { kind: 'in-use', ref });
+		else openDialog(editor, { kind: 'delete', ref });
+	};
+	return (
+		<div style={{ position: 'relative' }} data-slot="page-menu">
+			<button
+				ref={button}
+				type="button"
+				className="ib"
+				data-act="doc-menu"
+				aria-label={label}
+				aria-haspopup="menu"
+				aria-expanded={open}
+				onClick={() => setOpen((o) => !o)}
+			>
+				<Icon name="more" />
+			</button>
+			{open ? (
+				<div ref={menu} className="menu" role="menu" style={{ right: 0, top: 'calc(100% + 4px)' }} onKeyDown={onKey}>
+					{noPage ? null : (
+						<>
+							<button
+								type="button"
+								role="menuitem"
+								disabled={isNew || !entry.url}
+								onClick={() => {
+									setOpen(false);
+									if (entry.url) window.open(entry.url, '_blank', 'noopener');
+								}}
+							>
+								<Icon name="ext" />
+								View on the live site
+							</button>
+							{isNew ? <div className="why">Not live yet.</div> : null}
+							<button type="button" role="menuitem" data-act="move-document" disabled={!!moveWhy} onClick={() => (setOpen(false), openDialog(editor, { kind: 'move', ref }))}>
+								<Icon name="arrow-r" />
+								Change address…
+							</button>
+							{moveWhy ? (
+								<div className="why" data-why="move">
+									{moveWhy}
+								</div>
+							) : null}
+							<hr />
+						</>
+					)}
+					<button type="button" role="menuitem" className="danger" data-act="delete-document" disabled={!!why} onClick={remove}>
+						<Icon name="trash" />
+						Delete {shared ? 'shared block' : singular(collection)}…
+					</button>
+					{why ? (
+						<div className="why" data-why="delete">
+							{why}
+						</div>
+					) : null}
+				</div>
+			) : null}
+		</div>
+	);
+}

package/src/editor/client/documents/actions.ts

@@ -0,0 +1,192 @@
+/**
+ * Creating and deleting documents from the editor (M5a Decisions 11 and 12), on Phase
+ * 3's routes (`POST /_caracms/create`, `POST /_caracms/delete`). Nothing here decides a
+ * rule: the dialogs pre-check what they can (slug.ts) and show the server's own
+ * sentence when it refuses.
+ *
+ *   createDocument(editor, request)   → the new document opens at once (its level)
+ *   deleteDocument(editor, ref)       → the tab goes to the level it was listed in
+ *
+ * plus the small pure helpers the dialogs and menus share: what a new page's "Inside"
+ * offers, a collection's singular word, a document's public address.
+ */
+import { titleCase } from '../../../fields.ts';
+import { slugify } from '../../../slug.ts';
+import type { Editor } from '../editor.ts';
+import { docId, ENDPOINTS, MEDIA_ENDPOINTS, TAB_HEADER, sameDoc, type CreateDeleteRefusal, type CreateRequest, type CreateResponse, type DeleteResponse, type DocRef, type MoveResponse, type EditorAnyCollection, type ListedDocument, type ReplaceFileResponse } from '../../types.ts';
+
+export type Refused = { ok: false; status: number; error: string; code: string | null; usedOn: CreateDeleteRefusal['usedOn'] | null };
+
+async function post<T>(editor: Editor, url: string, body: unknown): Promise<{ ok: true; body: T } | Refused> {
+	const headers: Record<string, string> = { 'Content-Type': 'application/json', Accept: 'application/json' };
+	if (editor.liveSession) headers[TAB_HEADER] = editor.liveSession.tab;
+	let response: Response;
+	try {
+		response = await fetch(url, { method: 'POST', headers, body: JSON.stringify(body) });
+	} catch {
+		return { ok: false, status: 0, error: "The server can't be reached. Nothing was changed; try again in a moment.", code: 'offline', usedOn: null };
+	}
+	const said = (await response.json().catch(() => ({}))) as CreateDeleteRefusal & T;
+	if (response.status === 401 && editor.liveSession) editor.liveState.update({ signedOut: said as never });
+	if (!response.ok) {
+		return { ok: false, status: response.status, error: said.error ?? `The server said no (${response.status}).`, code: said.code ?? null, usedOn: said.usedOn ?? null };
+	}
+	return { ok: true, body: said as T };
+}
+
+/** Create a document; on success the list is read again and the new document opens (Decision 11). */
+export async function createDocument(editor: Editor, request: CreateRequest): Promise<{ ok: true; body: CreateResponse } | Refused> {
+	const answer = await post<CreateResponse>(editor, ENDPOINTS.create, request);
+	if (!answer.ok) return answer;
+	await editor.refreshDocuments().catch(() => undefined);
+	await editor.openDocument({ collection: answer.body.collection, path: answer.body.path });
+	editor.announce(`Created ${request.title}.`);
+	return answer;
+}
+
+/**
+ * Delete a document (Decision 12). Its unsent edits are dropped first (they'd only be
+ * refused), then, if it was open, Home opens behind and the pane goes to the level it
+ * was listed in: Pages' documents level, or its collection's own level.
+ */
+export async function deleteDocument(editor: Editor, ref: DocRef, title: string): Promise<{ ok: true; body: DeleteResponse } | Refused> {
+	const id = docId(ref);
+	const open = sameDoc(editor.doc.get().ref, ref);
+	// Its last edits go first (in live mode the lock is this tab's), so nothing is in flight after.
+	await editor.keeper?.flush(id).catch(() => undefined);
+	const answer = await post<DeleteResponse>(editor, ENDPOINTS.delete, { collection: ref.collection, path: ref.path });
+	if (!answer.ok) return answer;
+	editor.keeper?.discard(id);
+	const collection = editor.site.collections.find((c) => c.name === ref.collection);
+	await editor.refreshDocuments().catch(() => undefined);
+	if (open) await editor.openDocument(editor.site.home, { history: 'push' });
+	if (collection && !collection.nested && collection.kind !== 'settings') editor.openCollection(collection.name);
+	else editor.goTo('documents');
+	editor.toast(`Deleted ${title}.`);
+	editor.announce(`Deleted ${title}.`);
+	return answer;
+}
+
+/**
+ * Change a document's address (pre-M7 item 8). Its unsent edits go first (the move
+ * carries them), then the document opens at its new address in place of the old one,
+ * and the list is read again (other documents' links changed too).
+ */
+export async function moveDocument(editor: Editor, ref: DocRef, to: string, title: string): Promise<{ ok: true; body: MoveResponse } | Refused> {
+	const id = docId(ref);
+	const open = sameDoc(editor.doc.get().ref, ref);
+	// Nothing moves while the keeper still holds edits the server hasn't got (a held conflict, a
+	// signed-out session, a refused write): the move would discard them.
+	let flushed = true;
+	await editor.keeper?.flush(id).catch(() => {
+		flushed = false;
+	});
+	if (!flushed || editor.keeper?.dirty(id)) {
+		return { ok: false, status: 0, error: `${title} has changes that haven't been saved yet, so its address can't change. Sort those out first (Use mine or Discard mine, or sign in again), then try again.`, code: 'unsent', usedOn: null };
+	}
+	const answer = await post<MoveResponse>(editor, ENDPOINTS.move, { collection: ref.collection, path: ref.path, to });
+	if (!answer.ok) return answer;
+	editor.keeper?.discard(id);
+	await editor.refreshDocuments().catch(() => undefined);
+	if (open) await editor.openDocument({ collection: answer.body.collection, path: answer.body.path }, { history: 'replace' });
+	const { url, from } = answer.body;
+	editor.toast(`Moved ${title} to ${url}.`, 'check');
+	editor.announce(`Moved ${title} from ${from.url} to ${url}.`);
+	return answer;
+}
+
+/**
+ * M6c G4 (Decision 9): Replace… on a file. Every unsent edit in this tab goes first, and
+ * nothing is replaced while any is still held (a conflict, a refusal, a signed-out
+ * session): Replace changes other documents, so this tab has to be up to date (`unsent`).
+ * Then every link to `from` moves to `to`; the list is read again, and the open document
+ * too when it was one of them (its text changed under it).
+ */
+export async function replaceFile(editor: Editor, from: string, to: string): Promise<{ ok: true; body: ReplaceFileResponse } | Refused> {
+	await editor.keeper?.flush().catch(() => undefined);
+	const keep = editor.keeper?.status.get();
+	if (keep && keep.state !== 'kept') {
+		const n = keep.unsent ?? 0;
+		return { ok: false, status: 0, error: n > 1 ? `Your last ${n} changes haven't reached the server yet` : n === 1 ? "Your last change hasn't reached the server yet" : "This tab has changes that haven't reached the server yet", code: 'unsent', usedOn: null };
+	}
+	const answer = await post<ReplaceFileResponse>(editor, MEDIA_ENDPOINTS.replace, { from, to });
+	if (!answer.ok) return answer;
+	await editor.refreshDocuments().catch(() => undefined);
+	const open = editor.doc.get().ref;
+	if (answer.body.relinked.some((r) => sameDoc(r, open))) await editor.reloadOpen().catch(() => undefined);
+	return answer;
+}
+
+// ── Pure helpers ─────────────────────────────────────────────────────────────
+
+/** A collection's word for one of its documents: "page", "shared block", "case study", "journal entry". */
+export function singular(collection: Pick<EditorAnyCollection, 'kind' | 'nested' | 'label'>): string {
+	if (collection.kind === 'shared') return 'shared block';
+	if (collection.nested) return 'page';
+	const label = collection.label.toLowerCase();
+	if (/ies$/.test(label)) return label.replace(/ies$/, 'y');
+	if (/[^s]s$/.test(label)) return label.slice(0, -1);
+	return `${label} entry`;
+}
+
+/** M6c (G1): a collection with no pages of its own, under its name (as shared blocks' "Edited in one place…"). */
+export const PAGELESS_SUB = 'Shown on other pages; no pages of their own';
+
+/** M6c (G2): the name of a section builder's page fields group: "Page details", "Game details". */
+export function pageFieldsLabel(collection: Pick<EditorAnyCollection, 'kind' | 'nested' | 'label'>): string {
+	const one = singular(collection);
+	return `${one.charAt(0).toUpperCase()}${one.slice(1)} details`;
+}
+
+/** A document's public address in a collection (`/studio/visit`, `/work/kiln-and-co`, Home `/`), or null. */
+export function addressFor(collection: Pick<EditorAnyCollection, 'urlBase'>, path: string): string | null {
+	if (collection.urlBase === null) return null;
+	if (path === 'index') return collection.urlBase;
+	if (path.endsWith('/index')) return `${collection.urlBase}${path.slice(0, -'/index'.length)}`;
+	return `${collection.urlBase}${path}`;
+}
+
+export interface InsideOption {
+	/** The folder's path in the collection ('' for the top level). */
+	path: string;
+	label: string;
+	/** The address a page inside it starts with (`/services/`). */
+	base: string;
+}
+
+/**
+ * New page's "Inside" (Decision 11): the top level, then every folder that holds pages
+ * (a group, or a page with pages under it), at any depth, in tree order.
+ */
+export function insideOptions(collection: Pick<EditorAnyCollection, 'name' | 'urlBase'>, documents: readonly ListedDocument[]): InsideOption[] {
+	const base = collection.urlBase ?? '/';
+	const docs = documents.filter((d) => d.collection === collection.name);
+	const folders = new Set<string>();
+	for (const d of docs) {
+		const parts = d.path.split('/');
+		for (let i = 1; i < parts.length; i++) folders.add(parts.slice(0, i).join('/'));
+	}
+	const labelOf = (path: string) => docs.find((d) => d.path === path)?.label ?? titleCase(path.split('/').pop()!);
+	const options = [...folders]
+		.sort((a, b) => a.localeCompare(b))
+		.map((path) => {
+			const parts = path.split('/');
+			const label = parts.map((_, i) => labelOf(parts.slice(0, i + 1).join('/'))).join(' / ');
+			return { path, label, base: `${base}${path}/` };
+		});
+	return [{ path: '', label: 'Top level', base }, ...options];
+}
+
+/** The pages under a folder (any depth), for "its pages stay" lines. */
+export function pagesUnder(collection: string, path: string, documents: readonly ListedDocument[]): ListedDocument[] {
+	return documents.filter((d) => d.collection === collection && d.path.startsWith(`${path}/`));
+}
+
+/** "A, B and C". */
+export function andList(names: readonly string[]): string {
+	if (names.length <= 1) return names.join('');
+	return `${names.slice(0, -1).join(', ')} and ${names.at(-1)}`;
+}
+
+/** An address part from what's typed, by the name rule (slug.ts). */
+export const partFrom = (typed: string) => slugify(typed);