@cosmicdrift/kumiko-bundled-features 0.394.0 → 0.396.0

package/dist/template-resolver/web/content-tree-provider.js

@@ -0,0 +1,197 @@
+// Content tree behind the text-block and collection navs: loads the blocks from the
+// by-tenant (or a collection's list) query, groups them by their `folder` field and
+// emits them as TreeNode[].
+//
+// **Folder grouping**: block.folder !== null puts the node under a container
+// node labelled with the folder; folder === null keeps it at the root.
+//
+// **State**: TreeNode.state = "filled" when content is set, otherwise "stub"
+// (a hint that the slug exists but is empty).
+import { CSRF_HEADER_NAME, readCsrfToken } from "@cosmicdrift/kumiko-renderer/live";
+import { collectionQueryName, TemplateResolverQueries } from "./qualified-names.js";
+import { TENANT_OVERRIDE_DENIED_REASON } from "./tenant-override.js";
+function newFolderNode() {
+    return { leaves: [], subFolders: new Map() };
+}
+function attachBlock(root, block, tenantIdOverride, collectionId) {
+    const leaf = {
+        label: block.title || block.slug,
+        icon: "file",
+        target: {
+            featureId: "template-resolver",
+            action: "edit",
+            // tenantIdOverride and collectionId travel with the node → the editor
+            // reads and writes through the same tenant and the same collection the
+            // tree was loaded from. Omitted → session tenant, public text-blocks.
+            args: {
+                slug: block.slug,
+                locale: block.locale,
+                ...(tenantIdOverride !== undefined && { tenantIdOverride }),
+                ...(collectionId !== undefined && { collectionId }),
+            },
+        },
+        state: block.content ? "filled" : "stub",
+    };
+    let cur = root;
+    for (const segment of block.folder === null ? [] : block.folder.split("/")) {
+        let next = cur.subFolders.get(segment);
+        if (next === undefined) {
+            next = newFolderNode();
+            cur.subFolders.set(segment, next);
+        }
+        cur = next;
+    }
+    cur.leaves.push(leaf);
+}
+function renderFolderNode(node) {
+    // Leaves first (root items), then folders alphabetically.
+    const result = [...node.leaves];
+    for (const folderName of [...node.subFolders.keys()].sort()) {
+        const subNode = node.subFolders.get(folderName);
+        if (subNode === undefined)
+            continue;
+        result.push({
+            label: folderName,
+            icon: "folder",
+            state: "filled",
+            children: renderFolderNode(subNode),
+        });
+    }
+    return result;
+}
+export function groupBlocksByFolder(blocks, tenantIdOverride, collectionId) {
+    const root = newFolderNode();
+    for (const block of blocks) {
+        attachBlock(root, block, tenantIdOverride, collectionId);
+    }
+    const rendered = renderFolderNode(root);
+    if (rendered.length === 0)
+        return [];
+    return [
+        {
+            label: "Content",
+            icon: "folder",
+            state: "filled",
+            children: rendered,
+        },
+    ];
+}
+// A save in the editor re-fires the tree of the collection it wrote to. The
+// SSE refresh does not cover every collection: per-user entries carry no
+// entity signal, because naming their ids to every collection reader would
+// reveal when colleagues change their own entries.
+export const TEXT_BLOCK_TREE_KEY = "";
+const treeRefreshListeners = new Map();
+function onTreeRefresh(treeKey, listener) {
+    const listeners = treeRefreshListeners.get(treeKey) ?? new Set();
+    listeners.add(listener);
+    treeRefreshListeners.set(treeKey, listeners);
+    return () => listeners.delete(listener);
+}
+export function refreshTree(treeKey) {
+    for (const listener of treeRefreshListeners.get(treeKey) ?? [])
+        listener();
+}
+async function postBlockList(queryType, tenantIdOverride) {
+    // CSRF header is mandatory on authenticated requests (auth-middleware
+    // double-submit pattern). Anonymous/pre-login has no token → header
+    // omitted → the server takes the anonymous path.
+    const headers = { "content-type": "application/json" };
+    const csrf = readCsrfToken();
+    if (csrf !== undefined)
+        headers[CSRF_HEADER_NAME] = csrf;
+    // kumiko-lint-ignore no-raw-hooks not yet converted to the framework hook set
+    const response = await fetch("/api/query", {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+            type: queryType,
+            payload: tenantIdOverride !== undefined ? { tenantIdOverride } : {},
+        }),
+    });
+    if (!response.ok) {
+        return {
+            ok: false,
+            status: response.status,
+            body: await response.text().catch(() => response.statusText),
+        };
+    }
+    const data = await response.json();
+    return { ok: true, blocks: data.data.blocks };
+}
+// The dispatcher accepts tenantIdOverride from a SystemAdmin only, and the
+// provider cannot see the session roles. Everyone else gets this exact denial
+// and reads their session tenant instead, which is the only tenant they may
+// edit anyway.
+function isTenantOverrideDenied(result) {
+    return !result.ok && result.status === 403 && result.body.includes(TENANT_OVERRIDE_DENIED_REASON);
+}
+async function loadBlocks(queryType, tenantIdOverride) {
+    let result = await postBlockList(queryType, tenantIdOverride);
+    let effectiveOverride = tenantIdOverride;
+    if (tenantIdOverride !== undefined && isTenantOverrideDenied(result)) {
+        result = await postBlockList(queryType, undefined);
+        effectiveOverride = undefined;
+    }
+    if (!result.ok) {
+        // 403 (CSRF/auth) or 5xx — explicit error instead of silent empty.
+        throw new Error(`text-block load failed: ${result.status} ${result.body}`);
+    }
+    return {
+        blocks: result.blocks,
+        ...(effectiveOverride !== undefined && { tenantIdOverride: effectiveOverride }),
+    };
+}
+// tenantIdOverride (SystemAdmin-only) lets an app point the content tree at a
+// tenant other than the session's — publicstatus seeds marketing/legal blocks
+// on SYSTEM_TENANT_ID, so its SystemAdmin must read that tenant, not their own.
+// Without a collection: the anonymous-capable by-tenant query, so a public
+// page keeps its content sidebar without a session. With one: that
+// collection's own list handler, which carries the collection's access rule.
+export function makeTreeProvider(tenantIdOverride, collection) {
+    const collectionId = collection?.id;
+    const queryType = collectionId === undefined
+        ? TemplateResolverQueries.byTenant
+        : collectionQueryName(collectionId, "list");
+    // A per-user entry belongs to its author in the session tenant; pointing the
+    // tree at another tenant would only hide the author's own entries.
+    const requestedOverride = collection?.ownership === "user" ? undefined : tenantIdOverride;
+    return () => (emit, emitError) => {
+        let active = true;
+        // Each denial logs a client-fault warning on the server, so a reload after a
+        // save does not ask again once this subscription learned the answer.
+        let override = requestedOverride;
+        const load = () => {
+            loadBlocks(queryType, override)
+                .then(({ blocks, tenantIdOverride: effectiveOverride }) => {
+                // skip: subscription was cancelled while the request was in flight
+                if (!active)
+                    return;
+                override = effectiveOverride;
+                // The app-side r.nav node IS the "Content" container → the provider's
+                // children are the folders/leaves below it, not the wrapper.
+                const content = groupBlocksByFolder(blocks, effectiveOverride, collectionId)[0];
+                emit(content !== undefined && Array.isArray(content.children) ? content.children : []);
+            })
+                .catch((e) => {
+                // skip: subscription was cancelled while the request was in flight
+                if (!active)
+                    return;
+                // Explicit error signal via emitError; ProviderBranch shows a banner
+                // plus retry. Falls back to emit([]) for consumers without emitError.
+                if (emitError) {
+                    emitError(e instanceof Error ? e : new Error(String(e)));
+                }
+                else {
+                    emit([]);
+                }
+            });
+        };
+        load();
+        const unsubscribe = onTreeRefresh(collectionId ?? TEXT_BLOCK_TREE_KEY, load);
+        return () => {
+            active = false;
+            unsubscribe();
+        };
+    };
+}

package/dist/template-resolver/web/document-reference-name.d.ts

@@ -0,0 +1 @@
+export declare function isDocumentReferenceName(value: string): boolean;

package/dist/template-resolver/web/document-reference-name.js

@@ -0,0 +1,9 @@
+const REFERENCE_NAME = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+const FORBIDDEN_REFERENCE_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
+// Segments that hit the prototype chain are refused: the renderer later walks
+// the dotted path into a data object. Kept apart from document-schema so client code
+// can validate a name without loading tiptap.
+export function isDocumentReferenceName(value) {
+    return (REFERENCE_NAME.test(value) &&
+        !value.split(".").some((segment) => FORBIDDEN_REFERENCE_SEGMENTS.has(segment)));
+}

package/dist/template-resolver/web/document-schema.d.ts

@@ -1,7 +1,8 @@
 import { Extension, type Extensions, Node } from "@tiptap/core";
+import { isDocumentReferenceName } from "./document-reference-name.ts";
+export { isDocumentReferenceName };
 export declare function isDocumentPlaceholderHref(href: string): boolean;
 export declare function isAllowedDocumentLinkHref(href: string): boolean;
-export declare function isDocumentReferenceName(value: string): boolean;
 export declare function isDocumentResourceKey(value: string): boolean;
 export declare const DOCUMENT_NODE_NAMES: readonly ["variable", "resource", "button", "divider", "pageBreak", "steps", "images"];
 export declare const DocumentVariable: Node<any, any>;

package/dist/template-resolver/web/document-schema.js

@@ -8,17 +8,17 @@ import { Link } from "@tiptap/extension-link";
 import { Table, TableCell, TableHeader, TableRow } from "@tiptap/extension-table";
 import StarterKit from "@tiptap/starter-kit";
 import { createDocumentImagesNode } from "./document-images.js";
+import { isDocumentReferenceName } from "./document-reference-name.js";
 import { createDocumentStepsNode } from "./document-steps.js";
 const PLACEHOLDER_HREF = /^\{\{(.+)\}\}$/;
-const REFERENCE_NAME = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/;
 const RESOURCE_KEY = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
 const ALLOWED_LINK_SCHEMES = ["https://", "http://", "mailto:", "tel:"];
+export { isDocumentReferenceName };
 export function isDocumentPlaceholderHref(href) {
     const name = PLACEHOLDER_HREF.exec(href)?.[1];
     return name !== undefined && isDocumentReferenceName(name);
 }
 const UNSAFE_URL_CHARACTERS = new Set(["<", ">", '"']);
-const FORBIDDEN_REFERENCE_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
 function hasUnsafeUrlCharacter(value) {
     return Array.from(value).some((character) => {
         const code = character.charCodeAt(0);
@@ -49,12 +49,6 @@ export function isAllowedDocumentLinkHref(href) {
         return false;
     return hasAllowedLinkScheme(href) || isDocumentPlaceholderHref(href);
 }
-// Segments that hit the prototype chain are refused: the renderer later walks
-// the dotted path into a data object.
-export function isDocumentReferenceName(value) {
-    return (REFERENCE_NAME.test(value) &&
-        !value.split(".").some((segment) => FORBIDDEN_REFERENCE_SEGMENTS.has(segment)));
-}
 export function isDocumentResourceKey(value) {
     return RESOURCE_KEY.test(value);
 }

package/dist/template-resolver/web/i18n.js

@@ -134,6 +134,12 @@ export const defaultTranslations = {
         "template-resolver.editor.networkError": "Network error while saving.",
         "template-resolver.editor.loading": "Loading current version…",
         "template-resolver.editor.loadFailed": "Could not load block",
+        "template-resolver.editor.create": "Create",
+        "template-resolver.editor.newEntry": "New entry",
+        "template-resolver.editor.newEntryTitle": "New {label}",
+        "template-resolver.editor.slugLabel": "Slug",
+        "template-resolver.editor.slugInvalid": "Use lowercase letters, digits and dashes only; start with a letter or digit.",
+        "templateResolver.errors.collection.slugExists": "An entry with the slug “{detail}” already exists. Pick another one.",
         "template-resolver.editor.readOnly": "Read-only. Your role does not allow changes here.",
     },
 };

package/dist/template-resolver/web/legacy-variable-text.d.ts

@@ -0,0 +1 @@
+export declare function convertLegacyVariableText(html: string): string;

package/dist/template-resolver/web/legacy-variable-text.js

@@ -0,0 +1,23 @@
+import { escapeHtmlAttr } from "@cosmicdrift/kumiko-renderer/headless";
+import { isDocumentReferenceName } from "./document-reference-name.js";
+// Matches tags with quoted attribute values, so a `>` inside an attribute does not end the tag.
+// The unquoted branch excludes `<` so a scan stops at the next tag start (no quadratic backtracking).
+const HTML_TAG = /(<(?:"[^"]*"|'[^']*'|[^"'<>])*>)/;
+// Triple braces are raw output and `{{else}}`/`{{this}}` belong to blocks; neither is a variable.
+const TEXT_VARIABLE = /(?<!\{)\{\{\s*([^{}\s]+)\s*\}\}(?!\})/g;
+const BLOCK_KEYWORDS = new Set(["else", "this"]);
+function isLegacyVariableName(name) {
+    return isDocumentReferenceName(name) && !BLOCK_KEYWORDS.has(name);
+}
+// Content saved by the old editors holds `{{name}}` as plain text; the document editor
+// keeps variables as data-variable nodes and would show it as literal text.
+export function convertLegacyVariableText(html) {
+    return html
+        .split(HTML_TAG)
+        .map((part, index) => index % 2 === 1
+        ? part
+        : part.replace(TEXT_VARIABLE, (match, name) => isLegacyVariableName(name)
+            ? `<span data-variable="${escapeHtmlAttr(name)}"></span>`
+            : match))
+        .join("");
+}

package/dist/template-resolver/web/tenant-override.d.ts

@@ -0,0 +1,3 @@
+import type { DispatcherError } from "@cosmicdrift/kumiko-renderer/headless";
+export declare const TENANT_OVERRIDE_DENIED_REASON = "tenant_override_requires_system_admin";
+export declare function isTenantOverrideDeniedError(error: DispatcherError): boolean;

package/dist/template-resolver/web/tenant-override.js

@@ -0,0 +1,4 @@
+export const TENANT_OVERRIDE_DENIED_REASON = "tenant_override_requires_system_admin";
+export function isTenantOverrideDeniedError(error) {
+    return error.details?.["reason"] === TENANT_OVERRIDE_DENIED_REASON;
+}

package/dist/template-resolver/web/text-block-editor.d.ts

@@ -0,0 +1,6 @@
+import type { TargetRef } from "@cosmicdrift/kumiko-framework/engine";
+import type { ReactNode } from "react";
+export declare function TextBlockEditor({ target, }: {
+    readonly target: TargetRef;
+    readonly onClose: () => void;
+}): ReactNode;

package/dist/template-resolver/web/text-block-editor.js

@@ -0,0 +1,22 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { FormScreenLayout, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { ContentField } from "./content-field.js";
+import { useTextBlockEditor } from "./use-text-block-editor.js";
+function LoadBanners({ state }) {
+    const { Banner } = usePrimitives();
+    const t = useTranslation();
+    return (_jsxs(_Fragment, { children: [state.loading && _jsx(Banner, { variant: "loading", children: t("template-resolver.editor.loading") }), state.loadError !== null && (_jsxs(Banner, { variant: "error", children: [t("template-resolver.editor.loadFailed"), ": ", state.loadError.code] })), !state.canWrite && !state.loading && (_jsx(Banner, { variant: "info", children: t("template-resolver.editor.readOnly") }))] }));
+}
+function SaveBanners({ state }) {
+    const { Banner } = usePrimitives();
+    return (_jsxs(_Fragment, { children: [state.saveError !== null && _jsx(Banner, { variant: "error", children: state.saveError }), state.savedMsg !== null && _jsx(Banner, { variant: "info", children: state.savedMsg })] }));
+}
+export function TextBlockEditor({ target, }) {
+    const { Button, Field, Input, PageHeader, Section } = usePrimitives();
+    const t = useTranslation();
+    const state = useTextBlockEditor(target);
+    const headerTitle = state.title || state.slug || undefined;
+    return (_jsxs(_Fragment, { children: [PageHeader !== undefined && headerTitle !== undefined && _jsx(PageHeader, { title: headerTitle }), _jsx(FormScreenLayout, { onSubmit: () => {
+                    void state.save();
+                }, testId: "text-block-editor", description: state.locale !== "" ? `${state.slug} · (${state.locale})` : state.slug, actions: state.canWrite ? (_jsx(Button, { type: "submit", loading: state.submitting, disabled: state.disabled, children: t(state.saveLabelKey) })) : undefined, children: _jsxs(Section, { children: [_jsx(LoadBanners, { state: state }), _jsx(Field, { id: "text-block-title", label: t("template-resolver.editor.titleLabel"), required: true, children: _jsx(Input, { kind: "text", id: "text-block-title", name: "text-block-title", value: state.title, onChange: state.setTitle, disabled: state.disabled, required: true }) }), _jsx(ContentField, { editorContext: state.editorContext, value: state.content, onChange: state.setContent, disabled: state.disabled }), _jsx(SaveBanners, { state: state })] }) })] }));
+}

package/dist/template-resolver/web/use-collection-editor-context.d.ts

@@ -0,0 +1,14 @@
+import { type ContentEditorComponent } from "@cosmicdrift/kumiko-renderer";
+import { type ContentCollectionSchema } from "./collection-lookup.ts";
+import type { DocumentToolbarBlock } from "./document-blocks.ts";
+export type CollectionEditorContext = {
+    readonly collection: ContentCollectionSchema | undefined;
+    readonly contentFormat: ContentCollectionSchema["contentFormat"];
+    readonly ContentEditor: ContentEditorComponent;
+    readonly documentBlocks: readonly DocumentToolbarBlock[];
+    /** The collection's fixed variable names with the example value the preview substitutes. */
+    readonly variableExamples: Readonly<Record<string, string>>;
+    readonly variables: readonly string[];
+    readonly canWrite: boolean;
+};
+export declare function useCollectionEditorContext(collectionId?: string): CollectionEditorContext;

package/dist/template-resolver/web/use-collection-editor-context.js

@@ -0,0 +1,21 @@
+import { useShellUser } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/web";
+import { useAppFeatures, useContentEditor, } from "@cosmicdrift/kumiko-renderer";
+import { canWriteContent, findCollection, } from "./collection-lookup.js";
+import { documentBlocksForKind } from "./document-toolbar-blocks.js";
+// No collection (the hand-wired text-block tree) → plain editor, no variables.
+export function useCollectionEditorContext(collectionId) {
+    const features = useAppFeatures();
+    const user = useShellUser();
+    const collection = findCollection(features, collectionId);
+    const contentFormat = collection?.contentFormat;
+    const variableExamples = collection?.variableSchema ?? {};
+    return {
+        collection,
+        contentFormat,
+        ContentEditor: useContentEditor(contentFormat),
+        documentBlocks: documentBlocksForKind(collection?.kind),
+        variableExamples,
+        variables: Object.keys(variableExamples),
+        canWrite: canWriteContent(collection, user?.roles),
+    };
+}

package/dist/template-resolver/web/use-collection-entry-create.d.ts

@@ -0,0 +1,18 @@
+import type { TargetRef } from "@cosmicdrift/kumiko-framework/engine";
+export declare function useCollectionEntryCreate(target: TargetRef, tenantId: string | undefined): {
+    editorContext: import("./use-collection-editor-context.ts").CollectionEditorContext;
+    headerTitle: string;
+    slug: string;
+    setSlug: import("react").Dispatch<import("react").SetStateAction<string>>;
+    title: string;
+    setTitle: import("react").Dispatch<import("react").SetStateAction<string>>;
+    content: string;
+    setContent: import("react").Dispatch<import("react").SetStateAction<string>>;
+    slugValid: boolean;
+    createDisabled: boolean;
+    slugInvalid: boolean;
+    disabled: boolean;
+    submitting: boolean;
+    error: string | null;
+    create: () => Promise<void>;
+};

package/dist/template-resolver/web/use-collection-entry-create.js

@@ -0,0 +1,78 @@
+import { useLocale, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { useDispatchTarget } from "@cosmicdrift/kumiko-renderer/web";
+import { useState } from "react";
+import { SLUG_MAX_LENGTH, SLUG_PATTERN } from "./constants.js";
+import { refreshTree } from "./content-tree-provider.js";
+import { collectionHandlerName } from "./qualified-names.js";
+import { useCollectionEditorContext } from "./use-collection-editor-context.js";
+import { useContentWrite } from "./use-content-write.js";
+function readCreateTargetArgs(target) {
+    // @cast-boundary visual-tree-args — same de-erasure as the edit resolver; a missing
+    // collectionId (hand-edited URL) leaves the form without a collection to write to.
+    const args = target.args;
+    const folder = args?.folder !== undefined && args.folder !== "" ? args.folder : null;
+    return { collectionId: args?.collectionId, folder };
+}
+export function useCollectionEntryCreate(target, tenantId) {
+    const { collectionId, folder } = readCreateTargetArgs(target);
+    const t = useTranslation();
+    const locale = useLocale().locale();
+    const dispatchTarget = useDispatchTarget();
+    const editorContext = useCollectionEditorContext(collectionId);
+    const { collection, canWrite } = editorContext;
+    const { submitting, error, writeScoped } = useContentWrite();
+    const [slug, setSlug] = useState("");
+    const [title, setTitle] = useState("");
+    const [content, setContent] = useState("");
+    const slugValid = slug.length <= SLUG_MAX_LENGTH && SLUG_PATTERN.test(slug);
+    const disabled = submitting || !canWrite || collectionId === undefined;
+    const headerTitle = t("template-resolver.editor.newEntryTitle", {
+        label: collection !== undefined ? t(collection.nav.label) : "",
+    });
+    const create = async () => {
+        // skip: nothing to write to, or the slug is invalid (the field already shows the issue)
+        if (collectionId === undefined || !slugValid)
+            return;
+        const requestedOverride = collection?.ownership === "user" ? undefined : tenantId;
+        const written = await writeScoped(collectionHandlerName(collectionId), {
+            slug,
+            locale,
+            title,
+            content: content.length > 0 ? content : null,
+            folder,
+            createOnly: true,
+        }, requestedOverride);
+        // skip: useContentWrite already set the failure text
+        if (written === null)
+            return;
+        const { response, tenantIdOverride } = written;
+        refreshTree(collectionId);
+        dispatchTarget({
+            featureId: "template-resolver",
+            action: "edit",
+            args: {
+                slug: response.slug,
+                locale: response.locale,
+                collectionId,
+                ...(tenantIdOverride !== undefined && { tenantIdOverride }),
+            },
+        });
+    };
+    return {
+        editorContext,
+        headerTitle,
+        slug,
+        setSlug,
+        title,
+        setTitle,
+        content,
+        setContent,
+        slugValid,
+        createDisabled: disabled || !slugValid || title === "",
+        slugInvalid: slug !== "" && !slugValid,
+        disabled,
+        submitting,
+        error,
+        create,
+    };
+}

package/dist/template-resolver/web/use-content-write.d.ts

@@ -0,0 +1,17 @@
+export type TenantScopedWrite = {
+    readonly response: ContentWriteResponse;
+    /** The override the write was accepted with; undefined after a denied override fell back to the session tenant. */
+    readonly tenantIdOverride: string | undefined;
+};
+export type ContentWriteResponse = {
+    readonly slug: string;
+    readonly locale: string;
+    readonly isNew: boolean;
+};
+export declare function useContentWrite(): {
+    submitting: boolean;
+    error: string | null;
+    clearError: () => void;
+    write: (handler: string, payload: Readonly<Record<string, unknown>>) => Promise<ContentWriteResponse | null>;
+    writeScoped: (handler: string, payload: Readonly<Record<string, unknown>>, requestedOverride: string | undefined) => Promise<TenantScopedWrite | null>;
+};

package/dist/template-resolver/web/use-content-write.js

@@ -0,0 +1,54 @@
+import { dispatcherErrorText, useDispatcher, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { useCallback, useState } from "react";
+import { isTenantOverrideDeniedError } from "./tenant-override.js";
+// A validation failure names the offending field with its own message; prefer that over the generic one.
+function writeErrorText(error, t) {
+    const issue = error.details?.fields?.[0];
+    if (issue !== undefined) {
+        const translated = t(issue.i18nKey, issue.params);
+        if (translated !== issue.i18nKey)
+            return translated;
+    }
+    return dispatcherErrorText(error, t) || t("template-resolver.editor.saveFailed");
+}
+// Dispatches a content set and keeps the submit state; `write` resolves to the response,
+// or null after the failure text has been set in `error`.
+export function useContentWrite() {
+    const dispatcher = useDispatcher();
+    const t = useTranslation();
+    const [submitting, setSubmitting] = useState(false);
+    const [error, setError] = useState(null);
+    const writeScoped = async (handler, payload, requestedOverride) => {
+        setSubmitting(true);
+        setError(null);
+        try {
+            let tenantIdOverride = requestedOverride;
+            let result = await dispatcher.write(handler, {
+                ...payload,
+                ...(tenantIdOverride !== undefined && { tenantIdOverride }),
+            });
+            if (!result.isSuccess &&
+                tenantIdOverride !== undefined &&
+                isTenantOverrideDeniedError(result.error)) {
+                tenantIdOverride = undefined;
+                result = await dispatcher.write(handler, payload);
+            }
+            if (result.isSuccess)
+                return { response: result.data, tenantIdOverride };
+            setError(writeErrorText(result.error, t));
+            return null;
+        }
+        catch (e) {
+            // Network blip / dispatcher throw — otherwise submitting stays true and
+            // the save button is locked forever with no feedback.
+            setError(e instanceof Error ? e.message : t("template-resolver.editor.networkError"));
+            return null;
+        }
+        finally {
+            setSubmitting(false);
+        }
+    };
+    const write = async (handler, payload) => (await writeScoped(handler, payload, undefined))?.response ?? null;
+    const clearError = useCallback(() => setError(null), []);
+    return { submitting, error, clearError, write, writeScoped };
+}

package/dist/template-resolver/web/use-text-block-editor.d.ts

@@ -0,0 +1,19 @@
+import type { TargetRef } from "@cosmicdrift/kumiko-framework/engine";
+export declare function useTextBlockEditor(target: TargetRef): {
+    slug: string;
+    locale: string;
+    editorContext: import("./use-collection-editor-context.ts").CollectionEditorContext;
+    canWrite: boolean;
+    loading: boolean;
+    loadError: import("@cosmicdrift/kumiko-renderer/headless").DispatcherError | null;
+    submitting: boolean;
+    saveError: string | null;
+    savedMsg: string | null;
+    disabled: boolean;
+    saveLabelKey: string;
+    title: string;
+    setTitle: import("react").Dispatch<import("react").SetStateAction<string>>;
+    content: string;
+    setContent: import("react").Dispatch<import("react").SetStateAction<string>>;
+    save: () => Promise<void>;
+};

package/dist/template-resolver/web/use-text-block-editor.js

@@ -0,0 +1,85 @@
+import { useQuery, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { useEffect, useState } from "react";
+import { refreshTree, TEXT_BLOCK_TREE_KEY } from "./content-tree-provider.js";
+import { convertLegacyVariableText } from "./legacy-variable-text.js";
+import { collectionHandlerName, collectionQueryName, TemplateResolverHandlers, TemplateResolverQueries, } from "./qualified-names.js";
+import { useCollectionEditorContext } from "./use-collection-editor-context.js";
+import { useContentWrite } from "./use-content-write.js";
+export function useTextBlockEditor(target) {
+    // @cast-boundary visual-tree-args — TargetRef.args is erased to
+    // Record<string, unknown>; the resolver knows the action shape (see the
+    // treeActions.edit definition in feature.ts) and de-erases per action, the
+    // same way event payloads do. Optional chaining absorbs missing fields so a
+    // hand-edited URL cannot crash the editor.
+    const args = target.args;
+    const slug = args?.slug ?? "";
+    const locale = args?.locale ?? "";
+    const tenantIdOverride = args?.tenantIdOverride;
+    // Which collection the node came from. Absent → the public text-block pair,
+    // which is what the hand-wired content tree uses.
+    const collectionId = args?.collectionId;
+    const t = useTranslation();
+    const editorContext = useCollectionEditorContext(collectionId);
+    const { contentFormat, canWrite } = editorContext;
+    const { submitting, error: saveError, clearError, write } = useContentWrite();
+    // Same split as the tree provider: a node without a collection reads through
+    // the public by-slug, a collection node through that collection's handlers.
+    const readQuery = collectionId === undefined
+        ? TemplateResolverQueries.bySlug
+        : collectionQueryName(collectionId, "item");
+    const writeHandler = collectionId === undefined ? TemplateResolverHandlers.set : collectionHandlerName(collectionId);
+    const { data: loaded, loading, error: loadError, } = useQuery(readQuery, { slug, locale, ...(tenantIdOverride !== undefined && { tenantIdOverride }) }, { enabled: slug !== "" && locale !== "" });
+    const [title, setTitle] = useState("");
+    const [content, setContent] = useState("");
+    const [savedMsg, setSavedMsg] = useState(null);
+    // Sync loaded data into the form state. loaded === null means the block does
+    // not exist yet — empty form for the create flow.
+    // kumiko-lint-ignore no-raw-hooks not yet converted to the framework hook set
+    useEffect(() => {
+        // skip: keep the form untouched until the query settles
+        if (loading)
+            return;
+        const loadedContent = loaded?.content ?? "";
+        setTitle(loaded?.title ?? "");
+        setContent(contentFormat === "document" ? convertLegacyVariableText(loadedContent) : loadedContent);
+        clearError();
+        setSavedMsg(null);
+    }, [loading, loaded, contentFormat, clearError]);
+    const save = async () => {
+        setSavedMsg(null);
+        const response = await write(writeHandler, {
+            slug,
+            locale,
+            title,
+            content: content.length > 0 ? content : null,
+            folder: loaded?.folder ?? null,
+            // A collection derives its storage format on the server; the public set keeps what was saved.
+            ...(collectionId === undefined &&
+                loaded?.contentFormat !== undefined && { contentFormat: loaded.contentFormat }),
+            ...(tenantIdOverride !== undefined && { tenantIdOverride }),
+        });
+        // skip: useContentWrite already set the failure text
+        if (response === null)
+            return;
+        refreshTree(collectionId ?? TEXT_BLOCK_TREE_KEY);
+        setSavedMsg(response.isNew ? t("template-resolver.editor.created") : t("template-resolver.editor.saved"));
+    };
+    return {
+        slug,
+        locale,
+        editorContext,
+        canWrite,
+        loading,
+        loadError,
+        submitting,
+        saveError,
+        savedMsg,
+        disabled: submitting || loading || !canWrite,
+        saveLabelKey: submitting ? "template-resolver.editor.saving" : "template-resolver.editor.save",
+        title,
+        setTitle,
+        content,
+        setContent,
+        save,
+    };
+}