@heycys/gallery 0.0.0-stage → 0.1.1

package/browser/editor/components/columns/index.mjs

@@ -0,0 +1,104 @@
+import { svg } from "../icons.mjs";
+import { componentOf } from "../../../shared/components/index.mjs";
+import { t } from "../../../shared/i18n/index.mjs";
+
+// 分栏: blocks side by side, as Feishu's columns (src/shared/components/columns.mjs). The row
+// (.doc-columns) holds 2 to 5 columns (.doc-column), each a flow of any blocks but chapters
+// and other rows. Neither gets a handle, as in Feishu: the blocks in the columns do, and "选中外层"
+// from one of them selects the row (to move or delete it whole). A column's width is its share of
+// the row (--doc-column-ratio). page.mjs: making a row (a block dropped beside another, 分栏 in
+// the block menu), a column added, rows kept tidy (a column left empty goes, a row left with one
+// column gives its blocks back), the ratios; file.mjs: a row and its columns in report.html.
+//
+// Where the engines reach it (src/editor/page/ unless named): drag/drop.mjs (a drop beside a block:
+// `aside`), drag/ (making the row), block-menu/ (分栏), columns/ (the gaps: dragging one resizes the
+// two columns beside it, its pin adds a column; the row's tint), history.mjs (a structural step
+// leaves rows tidy: its page object's tidy, which editor.mjs gives it), geometry.mjs (box selection takes
+// the blocks in the columns; a click below a short column writes in it), handle/ (no handle of
+// their own), block-info.mjs (选中外层 passes over a column), commit.mjs (a column's ratio in its
+// node), clipboard/own/ (`clipboard`: copied as itself, made of another program's), ../source/ (a row made on the page).
+// Its look: the kit's styles/columns.css (src/render/kit/).
+export const RATIO = "--doc-column-ratio";
+// How many columns a row holds, and the least share of it a column takes: the shared description's.
+const shared = componentOf("columns");
+export const MIN_COLUMNS = shared.parts.columns.min;
+export const MAX_COLUMNS = shared.parts.columns.max;
+export const MIN_RATIO = shared.shares.min;
+
+/** How many columns, as the menus say it (分两栏, 已分成三栏). */
+export const COUNTS = ["", t("一"), t("两"), t("三"), t("四"), t("五")];
+
+/** A row of `count` columns (the block menu's 分两栏, 分三栏…): a box split by count - 1 lines. */
+export const columnsIcon = (count) => svg(`<rect x="2.75" y="4.75" width="14.5" height="10.5" rx="2"/><path d="${Array.from({ length: count - 1 }, (_, index) => `M${(2.75 + (14.5 * (index + 1)) / count).toFixed(2)} 4.75v10.5`).join("")}"/>`);
+
+export default {
+  name: "columns",
+  glance: { row: 15, name: "分栏", write: "`div.doc-columns`", rule: "Kit blocks" },
+  units: {
+    columns: {
+      name: t("分栏"),
+      icon: columnsIcon(2),
+      match: [{ rank: 60, class: "doc-columns" }],
+      handle: "none", // the blocks in its columns have handles
+      beside: true,
+      copy: "itself",
+    },
+    column: {
+      name: t("栏"),
+      match: [{ rank: 70, class: "doc-column" }],
+      fixed: true, // only in its row
+      sharesHeight: true,
+      block: false, // no block of its own (Feishu's): the blocks in it, or its row, are selected
+      handle: "none",
+      sizes: { [RATIO]: { min: MIN_RATIO, max: 1 } },
+    },
+  },
+  boxes: {
+    columns: { role: "columns", name: t("分栏"), selectAll: { whole: true }, classes: [{ rank: 10, class: "doc-columns" }] },
+    column: { role: "column", name: t("分栏"), groups: true, selectAll: { content: t("这一栏里的全部内容") }, classes: [{ rank: 20, class: "doc-column" }] },
+  },
+  types: {
+    // A row is written once each of its columns has something to write (a new one, its first block:
+    // the empty paragraph it starts with counts, as an empty paragraph is written); a column with
+    // its share of the row.
+    columns: {
+      tag: "div", className: "doc-columns", kind: "columns", box: "columns",
+      // Copied as itself (`copy` above). Elsewhere it comes as this, from another program: its
+      // columns' blocks, each with its share of the row.
+      clipboard: {
+        kind: "flatten",
+        blocks: (unit, { unitsOf }) => unitsOf(unit).flatMap((column) => unitsOf(column)),
+        holds: (block) => (block.columns ?? []).flatMap((column) => column.blocks),
+        check: (block, { valid }) => Array.isArray(block.columns) && block.columns.length >= MIN_COLUMNS && block.columns.length <= MAX_COLUMNS
+          && block.columns.every((column) => column && (column.ratio === undefined || (typeof column.ratio === "number" && column.ratio > 0 && column.ratio <= 1)) && Array.isArray(column.blocks) && column.blocks.every((inner) => valid(inner, "column"))),
+        build({ block, box, inner }) {
+          const row = box();
+          for (const each of block.columns) {
+            const column = box("column");
+            if (each.ratio !== undefined) column.style.setProperty(RATIO, String(each.ratio));
+            column.append(...inner(each.blocks));
+            row.append(column);
+          }
+          return row;
+        },
+        text: (block, lines) => block.columns.flatMap((column) => lines(column.blocks)),
+      },
+      written: (element, children, { unitsOf }) => children.length >= MIN_COLUMNS && children.length === unitsOf(element).length,
+      // Until then, once one of its columns holds something, those that hold nothing are the
+      // reader's to fill: a block not finished (kept, and said so: the column's blankSays).
+      blanks: (element, { nodeOf, unitsOf }) => {
+        const columns = unitsOf(element);
+        const empty = columns.filter((column) => !nodeOf(column));
+        return empty.length > 0 && empty.length < columns.length ? empty : [];
+      },
+    },
+    column: {
+      tag: "div", className: "doc-column", kind: "column", box: "column", clipboard: { kind: "flatten" },
+      blankSays: t("新分栏里还有空着的一栏：每一栏都写上内容后才会保存。"),
+      extras: (element, { sizeValue }) => {
+        const ratio = sizeValue("column", RATIO, element.style.getPropertyValue(RATIO));
+        return ratio ? { ratio } : {};
+      },
+    },
+  },
+};

package/browser/editor/components/columns/page.mjs

@@ -0,0 +1,310 @@
+import { boxKind, newContainer, newHost, placeBefore, unitsOf, withLeads } from "../../page/core.mjs";
+import { begin, done, made } from "../../page/made.mjs";
+import { caretAt } from "../../page/caret.mjs";
+import { accepts, sizeValue } from "../registry.mjs";
+import { COUNTS, MAX_COLUMNS, MIN_RATIO, RATIO } from "./index.mjs";
+import { t } from "../../../shared/i18n/index.mjs";
+
+// 分栏 on the page, as Feishu's grid (feishu-lite's model/grid.ts, commands/grid.ts): a row of
+// 2 to 5 columns side by side, each a flow of blocks. A row is made by dropping blocks beside a
+// block (the block in one column, they in another) or by 分栏 in a block's menu (the block and a
+// new empty paragraph); a column is added by dropping blocks at a column's edge, by 分栏 on a block
+// in a column, or by the pin above a gap (columns/). A column left empty goes, and a row left
+// with one column gives its blocks back where it stood (settleRows, after every structural change:
+// history.mjs). Widths: each column's share of the row (--doc-column-ratio), on every column of
+// a row or on none (equal); a new column takes 1/n and the others make room in proportion, a
+// column gone leaves its share to the others in proportion, and dragging a gap moves only the two
+// columns beside it (ratiosAfterResize).
+
+export const isRow = (node) => boxKind(node) === "columns";
+export const isColumn = (node) => boxKind(node) === "column";
+export const columnsOf = (row) => [...row.children].filter(isColumn);
+
+/** The column a block stands in (directly), or null. */
+export const columnOf = (unit) => (isColumn(unit?.parentElement) ? unit.parentElement : null);
+
+// ---------- widths (Feishu's) ----------
+
+/** n equal shares. */
+export const equalRatios = (n) => Array.from({ length: n }, () => 1 / n);
+
+/** A new column at `index` takes 1/(n+1); the others make room in proportion, none going below the least share. */
+export function ratiosAfterAdd(ratios, index) {
+  const share = 1 / (ratios.length + 1);
+  const shrinkable = ratios.filter((ratio) => ratio * (1 - share) > MIN_RATIO);
+  const total = shrinkable.reduce((sum, ratio) => sum + ratio, 0);
+  const factor = total > 0 ? 1 - share / total : 1;
+  const out = ratios.map((ratio) => (ratio * (1 - share) > MIN_RATIO ? ratio * factor : ratio));
+  out.splice(index, 0, share);
+  return out;
+}
+
+/** The columns at `removed` gone: the others take their shares in proportion. */
+export function ratiosAfterRemove(ratios, removed) {
+  const left = ratios.filter((_, index) => !removed.includes(index));
+  const rest = left.reduce((sum, ratio) => sum + ratio, 0);
+  return rest > 0 ? left.map((ratio) => ratio / rest) : equalRatios(left.length);
+}
+
+/**
+ * The gap after column `index` dragged by `fraction` of the row's width: only the two columns
+ * beside it change, snapping to their equal split or to a tenth of the row for the left one when
+ * within 1%, both keeping the least share (1/24, or more where `least` says so for a part: the
+ * share its content needs, a flowchart's node as narrow as the kit lets it be, page/columns/).
+ * `ratios` are those when the drag started.
+ */
+export function ratiosAfterResize(ratios, index, fraction, least = []) {
+  const left = ratios[index];
+  const right = ratios[index + 1];
+  const low = Math.max(MIN_RATIO, least[index] ?? 0);
+  const high = Math.max(MIN_RATIO, least[index + 1] ?? 0);
+  if (left === undefined || right === undefined || left + right < low + high) return ratios;
+  let moved = fraction;
+  const equal = (left + right) / 2 - left;
+  const step = Math.round(10 * (left + moved)) / 10 - left;
+  if (Math.abs(equal - moved) < 0.01) moved = equal;
+  else if (Math.abs(step - moved) < 0.01) moved = step;
+  moved = Math.min(Math.max(moved, low - left), right - high);
+  const out = [...ratios];
+  out[index] = left + moved;
+  out[index + 1] = right - moved;
+  return out;
+}
+
+/** A row's shares: its columns' own when every one has one, else equal ones. */
+export function ratiosOf(row) {
+  const columns = columnsOf(row);
+  const own = columns.map((column) => Number.parseFloat(column.style.getPropertyValue(RATIO)));
+  if (own.length > 0 && own.every((ratio) => ratio > 0)) {
+    const sum = own.reduce((total, ratio) => total + ratio, 0);
+    return own.map((ratio) => ratio / sum);
+  }
+  return equalRatios(columns.length);
+}
+
+/** Whether a row's columns have shares of their own (none: equal widths). */
+export const sized = (row) => columnsOf(row).some((column) => column.style.getPropertyValue(RATIO).trim() !== "");
+
+/** A row's columns given these shares (written as the file takes them: sizeValue, none below the least), or none (null: equal). */
+export function setRatios(row, ratios) {
+  columnsOf(row).forEach((column, index) => {
+    if (ratios) column.style.setProperty(RATIO, sizeValue("column", RATIO, String(Math.min(1, Math.max(MIN_RATIO, ratios[index])))));
+    else column.style.removeProperty(RATIO);
+    if (column.getAttribute("style") === "") column.removeAttribute("style");
+  });
+}
+
+// ---------- making rows and columns ----------
+
+/**
+ * A new row where `target` stands: `target` (a block, or blocks next to each other: a folded heading
+ * with what it hides) in one column, each of `groups` (lists of nodes: blocks with their leads) in a
+ * column of its own, `side` of it ("left" or "right"); equal widths. Returns { focus: the row, created }.
+ */
+export function rowAround(target, groups, side = "right") {
+  begin();
+  const own = [target].flat();
+  const doc = own[0].ownerDocument;
+  const parts = own.flatMap(withLeads);
+  const row = made(newContainer(doc, "columns"));
+  parts[0].before(row);
+  const column = made(newContainer(doc, "column"));
+  placeBefore(column, parts, null);
+  const others = groups.map((nodes) => {
+    const other = made(newContainer(doc, "column"));
+    placeBefore(other, nodes, null);
+    return other;
+  });
+  row.append(...(side === "left" ? [...others, column] : [column, ...others]));
+  return done(row);
+}
+
+/**
+ * Blocks next to each other (with their leads), each in a column of its own of a new row where they
+ * stood; one may be a list of blocks (a folded heading with what it hides), a column for them all.
+ * Returns { focus: the row, created }.
+ */
+export function rowOf(units) {
+  begin();
+  const groups = units.map((unit) => [unit].flat());
+  const doc = groups[0][0].ownerDocument;
+  const row = made(newContainer(doc, "columns"));
+  withLeads(groups[0][0])[0].before(row);
+  for (const group of groups) {
+    const column = made(newContainer(doc, "column"));
+    placeBefore(column, group.flatMap(withLeads), null);
+    row.append(column);
+  }
+  return done(row);
+}
+
+/**
+ * A new column at `index` of `row`, holding `nodes` (blocks with their leads), or an empty
+ * paragraph; when the row's columns have shares, the new one takes 1/n and the others make room.
+ * Returns { focus: the column's paragraph, or the column; created }.
+ */
+export function addColumn(row, index, nodes = null) {
+  begin();
+  const doc = row.ownerDocument;
+  const ratios = sized(row) ? ratiosAfterAdd(ratiosOf(row), index) : null;
+  const column = made(newContainer(doc, "column"));
+  const paragraph = nodes ? null : newHost(doc, "paragraph");
+  if (nodes) placeBefore(column, nodes, null);
+  else column.append(paragraph);
+  row.insertBefore(column, columnsOf(row)[index] ?? null);
+  if (ratios) setRatios(row, ratios);
+  return done(paragraph ?? column);
+}
+
+/**
+ * 分两栏 (分三栏, 分四栏: `count` columns) with a block alone (or a folded heading with what it hides,
+ * `target` a list: rowAround): a new row, the block in the left column and a new empty paragraph in
+ * each of the others. Returns { focus: the first of them, created }.
+ */
+export function splitBeside(target, count = 2) {
+  const paragraphs = Array.from({ length: count - 1 }, () => newHost([target].flat()[0].ownerDocument, "paragraph"));
+  const { created } = rowAround(target, paragraphs.map((paragraph) => [paragraph]), "right");
+  return { focus: paragraphs[0], created };
+}
+
+// ---------- what may be done ----------
+
+const kindOf = (node) => node?.getAttribute?.("data-ge-unit-kind") ?? null;
+
+/**
+ * Whether `units` (blocks) may go into a column: every one is a block a column takes (no chapter,
+ * no row of columns, no list item on its own).
+ */
+export const fitColumn = (units) => units.length > 0 && units.every((unit) => accepts("column", kindOf(unit)));
+
+/**
+ * "分栏" for blocks (in document order): null when it does not apply, otherwise why it cannot be
+ * done, or "". One block in a column adds a column right of its own; one block elsewhere becomes a
+ * row with a new empty column beside it; several next to each other in one container (not in a
+ * column), a row with a column each. `taken(unit)`: what goes into a unit's column with it (a folded
+ * heading's: it and what it hides, fold/ withHidden), each of which a column must take, and which
+ * stands between the units it joins as they are next to each other for the reader.
+ */
+export function columnsCheck(units, taken = (unit) => [unit]) {
+  if (units.length === 0) return null;
+  const box = units[0].parentElement;
+  if (!box?.hasAttribute("data-ge-box") || units.some((unit) => unit.parentElement !== box)) return null;
+  const column = isColumn(box) ? box : null;
+  if (column) {
+    if (units.length > 1) return null;
+    return columnsOf(column.parentElement).length >= MAX_COLUMNS ? t("一行最多 {0} 栏", MAX_COLUMNS) : "";
+  }
+  const all = units.flatMap(taken);
+  if (!accepts(boxKind(box), "columns") || !fitColumn(all)) return null;
+  if (units.length > MAX_COLUMNS) return t("一行最多 {0} 栏", MAX_COLUMNS);
+  if (units.length === 1) return "";
+  const blocks = unitsOf(box);
+  const first = blocks.indexOf(all[0]);
+  return all.every((unit, index) => blocks[first + index] === unit) ? "" : t("只有相邻的块能并排分栏：中间还有没选中的块");
+}
+
+// ---------- the commands ----------
+
+/**
+ * 分栏 in the block menu and a column added at a gap (columns/), with what the editor gives them:
+ * struct (a structural undo step), say, and blocks() (the block handles and selection, blocks.mjs).
+ */
+export function create({ struct, say, blocks }) {
+  // What goes into a block's column with it: a folded heading's section goes with it (fold/ withHidden).
+  const taken = (unit) => blocks().folds?.withHidden(unit) ?? [unit];
+
+  // Blocks that pass columnsCheck: a block in a column gets a column right of its own; a block
+  // elsewhere becomes a row of `count` columns, it in the first and empty ones beside it (Feishu's
+  // two columns; the block menu's 分两栏, 分三栏, 分四栏); several, a row with a column each, a folded
+  // heading's with what it hides. The caret goes into the first new column's paragraph, or the row is selected.
+  function split(units, count = 2) {
+    blocks().clear();
+    const column = units.length === 1 ? columnOf(units[0]) : null;
+    if (column) {
+      add(column.parentElement, columnsOf(column.parentElement).indexOf(column) + 1);
+      return;
+    }
+    const result = struct([units[0].parentElement], [], () => {
+      const made = units.length === 1 ? splitBeside(taken(units[0]), count) : rowOf(units.map(taken));
+      return { touched: [], focus: made.focus, select: units, created: made.created };
+    });
+    if (units.length === 1) caretAt(result.focus, "start");
+    else blocks().select(result.created[0], { quiet: true });
+    say(t("{0} · 拖动栏间的竖线调宽度 · Ctrl+Z 撤销", units.length === 1 ? t("已分成{0}栏", COUNTS[count]) : t("已把 {0} 块并排分栏", units.length)));
+  }
+
+  // A new column at `index` of `row` holding an empty paragraph, the caret in it.
+  function add(row, index) {
+    if (columnsOf(row).length >= MAX_COLUMNS) {
+      say(t("一行最多 {0} 栏。", MAX_COLUMNS));
+      return;
+    }
+    blocks().clear();
+    const result = struct([row], [], () => {
+      const made = addColumn(row, index);
+      return { touched: [made.focus], focus: made.focus, created: made.created };
+    });
+    caretAt(result.focus, "start");
+    say(t("已新增一栏 · Ctrl+Z 撤销"));
+  }
+
+  return {
+    tidy: tidyRows,
+    // What the block tools and the gaps between columns read and do by themselves (block-menu/, drag/, page/columns/).
+    columnOps: { split, add, columnOf, columnsCheck: (units, take = taken) => columnsCheck(units, take), columnsOf, addColumn, rowAround, ratiosOf, ratiosAfterResize, setRatios, sized },
+  };
+}
+
+// ---------- keeping rows tidy ----------
+
+/** The rows a structural change over these containers may leave untidy: those they are or stand in. */
+export function rowsAround(parents) {
+  const rows = new Set();
+  for (const parent of parents) {
+    if (isRow(parent)) rows.add(parent);
+    else if (isColumn(parent) && isRow(parent.parentElement)) rows.add(parent.parentElement);
+  }
+  return [...rows];
+}
+
+/** What a structural change over `rows` touches besides: their columns and where each row stands. */
+const rowParts = (rows) => rows.flatMap((row) => [row, ...columnsOf(row), ...(row.parentElement ? [row.parentElement] : [])]);
+
+// A column holding nothing but the editor's own nodes is empty.
+const emptyColumn = (column) => ![...column.children].some((child) => !child.hasAttribute("data-doc-dev"));
+
+/**
+ * What a structural step (history.mjs) does around rows of columns, as a tidier: the rows the step
+ * may leave untidy are tidied after it (settleRows), so the rows, their columns and the containers
+ * they stand in are recorded with the step, and the columns' widths (their style) with them.
+ */
+export function tidyRows(parents) {
+  const rows = rowsAround(parents);
+  return { parents: rowParts(rows), attributes: [...new Set(rowParts(rows).filter(isColumn))].map((column) => [column, ["style"]]), settle: () => settleRows(rows) };
+}
+
+/**
+ * After a structural change: a column left empty goes (its share to the others, in proportion), a
+ * row left with one column gives its blocks back where it stood, and one left with none goes.
+ * Returns whether anything changed.
+ */
+export function settleRows(rows) {
+  let changed = false;
+  for (const row of rows) {
+    if (!row.isConnected || !isRow(row)) continue;
+    const columns = columnsOf(row);
+    const empty = columns.flatMap((column, index) => (emptyColumn(column) ? [index] : []));
+    if (empty.length > 0) {
+      const ratios = sized(row) ? ratiosAfterRemove(ratiosOf(row), empty) : null;
+      empty.forEach((index) => columns[index].remove());
+      if (ratios && columnsOf(row).length > 1) setRatios(row, ratios);
+      changed = true;
+    }
+    const left = columnsOf(row);
+    if (left.length > 1) continue;
+    if (left.length === 1) placeBefore(row.parentElement, [...left[0].childNodes].filter((node) => node.nodeType !== 1 || !node.hasAttribute("data-doc-dev")), row);
+    row.remove();
+    changed = true;
+  }
+  return changed;
+}

package/browser/editor/components/details/index.mjs

@@ -0,0 +1,73 @@
+import { svg } from "../icons.mjs";
+import { DETAILS, classOf, stepOf } from "../kit.mjs";
+import { t } from "../../../shared/i18n/index.mjs";
+
+// 折叠列表: the kit's disclosure (details.doc-details). Its title (the summary's label) is a
+// text block that only changes its text; its content region (.doc-details-content) is a box
+// that takes what a section takes. A new one is open while edited; saved, it starts closed.
+// page.mjs: a new one, Enter in its title; file.mjs: its markup in report.html.
+//
+// Where the engines reach it (src/editor/page/ unless named): typing/ (Enter in its title: page.mjs `keys`;
+// its empty title's placeholder: `placeholders` below), editor.mjs (a click in its title does not toggle it: page.mjs `click`), convert.mjs
+// (a block turned into one, one into plain blocks), core.mjs (its title and blocks in a save: nodeOf,
+// an empty title holding the save), clipboard/own/ (copying it: `clipboard`, and `build` in page.mjs), commit.mjs (its content box),
+// drag/ (a closed one opens while a block is dragged over its title), ../source/ (finding
+// its title: the summary label).
+// Its look: the kit's styles/details.css (src/render/kit/). Its title and content region are its
+// description's parts, the label among them (required by the description: src/shared/components/details.mjs,
+// through ../kit.mjs).
+export default {
+  name: "details",
+  listed: () => t("折叠列表"),
+  units: {
+    // Its color (颜色 in the block menu, notion-lite's toggle): a background in place of its own, or
+    // its title's and its blocks' text.
+    details: { name: t("折叠列表"), match: [{ rank: 140, tag: "details" }], boxed: true, removedEmpty: true, colors: ["background"] },
+  },
+  boxes: {
+    // Its content always holds a block (holdsOne): emptied, it keeps an empty paragraph to write in.
+    // Under its last block is its padding: a click there makes no block (endIsPadding).
+    details: { role: "flow", name: t("折叠列表"), groups: true, holdsOne: true, endIsPadding: true, emptyIsNothing: true, selectAll: { content: true }, classes: [{ rank: 30, class: classOf(stepOf(DETAILS.content)) }], find: (unit) => detailsContent(unit) },
+  },
+  placeholders: { label: t("折叠列表标题") },
+  hosts: {
+    label: { name: t("折叠块标题"), opensBefore: true, caps: () => ["empty"], parts: [["details", "label"]] }, // empty, the kit shows nothing but its arrow
+  },
+  types: {
+    details: { // its box is the content region
+      turn: 10, menu: ["basic", 10],
+      tag: "details", className: "doc-details", kind: "details", box: "details", container: "details.doc-details",
+      takesAsIs: true, holder: 1,
+      // Copied with its title and its blocks. Its page.mjs makes it again.
+      clipboard: {
+        kind: "toggle",
+        read: (unit) => ({ title: detailsTitle(unit), content: detailsContent(unit) }),
+        describe(node, { holding, serializeInner }) {
+          if (!node.matches("details.doc-details")) return undefined;
+          const title = detailsTitle(node);
+          const blocks = holding(detailsContent(node));
+          return title && blocks ? { type: "details", html: serializeInner(title), blocks } : null;
+        },
+        endsIn(unit, { blocksIn, serializeInner }) {
+          const title = detailsTitle(unit);
+          return title ? [{ type: "details", html: serializeInner(title), blocks: blocksIn([detailsContent(unit)].filter(Boolean)) }] : undefined;
+        },
+        check: (block, { container, string }) => container(block) && string(block.html),
+        text: (block, lines) => [block.html, ...lines(block.blocks)],
+      },
+      // What the save engines need of it (core.mjs nodeOf, sync-state.mjs): its title (a text block
+      // of its own) and its content region; the summary is part of it. Written empty too (no title,
+      // no blocks: an empty one stays, as Notion's).
+      title: (element) => detailsTitle(element), content: (element) => detailsContent(element), part: "summary",
+      written: () => true,
+      label: t("折叠列表"),
+      icon: svg('<path d="M3.75 4.25 6.75 6l-3 1.75z" fill="currentColor" stroke="none"/><path d="M3.75 12.25l3 1.75-3 1.75z" fill="currentColor" stroke="none"/><path d="M8.75 6h7.75M8.75 14h7.75"/>'),
+      words: "折叠列表 折叠块 折叠 展开 zhedie zhankai zdlb zd toggle details disclosure",
+      glance: { row: 6, name: "折叠列表", write: "`<details><summary>`, never the kit's classes on it", after: "`details.doc-details`", rule: "Text and lists" },
+    },
+  },
+};
+
+/** A disclosure's title and content region. */
+export const detailsTitle = (details) => details.querySelector(DETAILS.label);
+export const detailsContent = (details) => details.querySelector(DETAILS.content);

package/browser/editor/components/details/page.mjs

@@ -0,0 +1,86 @@
+import { firstHost, newHost } from "../../page/core.mjs";
+import { caretAt, editable } from "../../page/caret.mjs";
+import { addStyle } from "../../page/ui.mjs";
+import { capsFor } from "../registry.mjs";
+import { detailsContent, detailsTitle } from "./index.mjs";
+import { t } from "../../../shared/i18n/index.mjs";
+
+// 折叠列表 on the page. A block turned into one goes into its content, the title left empty with the
+// caret in it (convert.mjs); a new one is open while edited, with a content region holding an empty
+// paragraph. Enter in its title puts the caret into its content, opened. Clicking its title to type
+// does not open or close it (`click`).
+
+/** A disclosure made again from the clipboard's description (its type's `build`, builders.mjs). */
+export function build({ doc, block, inline, inner }) {
+  const details = newDetails(doc);
+  detailsTitle(details).append(...inline(block.html));
+  if (block.blocks.length > 0) detailsContent(details).replaceChildren(...inner(block.blocks));
+  return details;
+}
+
+/** A new disclosure, open while edited: its title (a text block) and a content region holding an empty paragraph. */
+export function newDetails(doc, title = "") {
+  const details = doc.createElement("details");
+  details.className = "doc-details";
+  details.open = true;
+  for (const [name, value] of [["data-ge-new", ""], ["data-ge-type", "details"], ["data-ge-unit-kind", "details"]]) details.setAttribute(name, value);
+  const summary = doc.createElement("summary");
+  const label = doc.createElement("span");
+  label.className = "doc-details-summary-label";
+  for (const [name, value] of [["contenteditable", "true"], ["data-ge-new", ""], ["data-ge-kind", "label"], ["data-ge-caps", capsFor("label")]]) label.setAttribute(name, value);
+  label.innerHTML = title;
+  summary.append(label);
+  const content = doc.createElement("div");
+  content.className = "doc-details-content";
+  for (const [name, value] of [["data-ge-box", ""], ["data-ge-box-kind", "details"], ["data-ge-pure", ""]]) content.setAttribute(name, value);
+  content.append(newHost(doc, "paragraph"));
+  details.append(summary, content);
+  return details;
+}
+
+// A content the file has empty (an Agent's: emptied on the page, it keeps an empty paragraph):
+// notion-lite's placeholder, a click on it makes a paragraph there (insert/ clickBlank).
+const EMPTY = `
+  [data-ge-editing] .doc-details-content[data-ge-box]:not(:has(> *))::before { content: ${JSON.stringify(t("空白折叠区块。点击或拖动区块到这里。"))}; display: block; padding: 3px 2px; border-radius: 4px; color: var(--ge-tx3); cursor: pointer; transition: background 20ms ease-in; }
+  [data-ge-editing] .doc-details-content[data-ge-box]:not(:has(> *)):hover::before { background: var(--ge-hover); }
+`;
+
+// A disclosure's title takes no fill under the pointer, hovered or edited: plain, as Notion's and Feishu's.
+// It is text one edits, so the pointer over it is the text cursor, as over a code block's title
+// (code/page.mjs); the summary's arrow keeps the kit's pointer (it opens and closes the block).
+const STYLE = `
+  [data-ge-editing] .doc-details-summary-label[contenteditable="true"] { --ge-text-tint: none; cursor: text; }
+`;
+
+/** A disclosure's title, with what the editor gives it: struct (a structural undo step), say and limitText. */
+export function create({ struct, say, limitText }) {
+  addStyle(STYLE);
+  addStyle(EMPTY);
+  // Enter in a disclosure's title: the caret goes into its content, opened. True when handled.
+  function enter(host) {
+    const details = host.getAttribute("data-ge-kind") === "label" ? host.closest("details") : null;
+    if (!details) return false;
+    details.open = true;
+    const content = detailsContent(details);
+    const first = content && firstHost(content);
+    if (first) caretAt(first, "start");
+    else if (content?.hasAttribute("data-ge-box")) {
+      const paragraph = newHost(document, "paragraph");
+      struct([content], [], () => {
+        content.prepend(paragraph);
+        return { touched: [paragraph], focus: paragraph };
+      });
+      caretAt(paragraph, "start");
+    } else say(limitText(host, "split"));
+    return true;
+  }
+
+  return {
+    keys: { enter: ({ host }) => enter(host) },
+    /** A click in its title, to type there, neither opens nor closes it. */
+    click(event) {
+      if (editable(event.target)?.closest("summary")) event.preventDefault();
+      return false;
+    },
+  };
+}

package/browser/editor/components/dialog/index.mjs

@@ -0,0 +1,84 @@
+// 详情卡片 (detail card): the kit's dialog.doc-dialog, opened by a link to it (#id) in the text.
+// Its content region (.doc-dialog-content) is a box that takes what a section takes, an ordinary
+// editing area: a heading first in it is a block like any other, and nothing binds one to the card.
+// It is a chapter: it stands at the end of the page. page.mjs: a new one from the selected text;
+// file.mjs: its markup in report.html.
+//
+// Where the engines reach it (src/editor/page/ unless named): typing/ (`keys.around`, page.mjs:
+// Esc in an open one closes it), the workbench, undo, 搜索文档 and a page shown again (`modalOps`,
+// page.mjs: the cards open, `show`, `kept`, `reopen`), format-bar/ (the card button), links/ (its entry's card, a click on the entry opening it), core.mjs (saved only while a link opens it: nodeOf; the trigger
+// class on links: serializeNode), commit.mjs (a card has no block id; once written it is taken in as a card of the file: adoptKeyed, keyedAway),
+// drag/, caret.mjs, resize/ (an open card's content stands for the page), ../source/
+// (finding cards: dialog(); ids the file uses; what the file holds of a card a commit made:
+// keyedFacts), src/transfer/ (a page's Markdown: `clipboard`; its charts' pictures: browser.mjs).
+// Its look: the kit's styles/dialog.css, opened by dialogs.js (src/render/kit/). Its content region
+// is its description's part (src/shared/components/dialog.mjs, through ../kit.mjs).
+import { DIALOG, classOf, stepOf } from "../kit.mjs";
+import { DIALOG_ICON } from "../icons.mjs";
+import { t } from "../../../shared/i18n/index.mjs";
+
+/** The class of a link that opens a detail card (dialogs.js). */
+export const DIALOG_TRIGGER = "doc-dialog-trigger";
+
+export default {
+  name: "dialog",
+  // A link in the text that opens a card, a chip as padded as code: Backspace right of it (Delete
+  // left of it) takes it whole, as a chip of the text goes; its words are edited from inside it.
+  entry: { at: `a.${DIALOG_TRIGGER}`, removed: t("入口已移除：页面上没有地方能打开这张详情卡片了 · Ctrl+Z 撤销") },
+  units: {
+    // The server finds detail cards by their element (findUnits). No block of the page's flow, a card
+    // is written after it, as a disclosure: a selection cannot take one, so no copy says a kind.
+    dialog: {
+      chapter: true, fixed: true, boxed: true,
+      clipboard: { kind: "toggle", read: cardInMarkdown, apart: DIALOG.match, reached: (unit) => entryOf(unit) !== null },
+    },
+  },
+  boxes: {
+    // Its content always holds a block (holdsOne): emptied, it keeps an empty paragraph to write in.
+    dialog: { role: "flow", name: t("详情卡片"), groups: true, outer: false, holdsOne: true, selectAll: { content: true, top: true }, classes: [{ rank: 40, class: classOf(stepOf(DIALOG.content)) }] },
+  },
+  types: {
+    dialog: { // its box is the content region
+      tag: "dialog", className: "doc-dialog", kind: "dialog", box: "dialog",
+      fromSelection: { label: t("详情卡片"), icon: DIALOG_ICON },
+      glance: { row: 16, name: "详情卡片", write: "`<a href=\"#x\">` in the text, `<dialog id=\"x\"><h3>…</h3>…</dialog>`", rule: "Kit blocks" },
+      // What the save engines need of it (core.mjs nodeOf, commit.mjs adoptKeyed): no unit but known
+      // by its id (`keyed`), its content region; written only while something opens it.
+      keyed: true, content: (element) => dialogContent(element),
+      written: (element) => entryOf(element) !== null,
+    },
+  },
+};
+
+/** A detail card's content region. */
+export const dialogContent = (dialog) => dialog.querySelector(DIALOG.content);
+
+/** The first heading with words among a detail card's blocks, or null: what the card goes by where it needs a name. */
+export const dialogHeading = (dialog) => [...(dialogContent(dialog)?.children ?? [])].find((block) => block.matches(DIALOG.heading) && block.textContent.trim()) ?? null;
+
+/** What opens a detail card from outside it: the first link to it, or element naming it by data-doc-dialog-open, or null. */
+export function entryOf(dialog) {
+  const named = `#${dialog.id}`;
+  return [...dialog.ownerDocument.querySelectorAll("a[href], [data-doc-dialog-open]")]
+    .find((node) => (node.getAttribute("href") === named || node.getAttribute("data-doc-dialog-open") === named) && !dialog.contains(node)) ?? null;
+}
+
+// A detail card as a disclosure of a page's Markdown, when something opens it (`reached`): its first
+// heading the title, which its body then leaves out, else the words of what opens it.
+function cardInMarkdown(unit) {
+  const heading = dialogHeading(unit);
+  return { title: heading ?? entryOf(unit), content: dialogContent(unit), without: heading };
+}
+
+/** The detail card of `doc` an address in the page (#id) names, or null. */
+export function cardNamed(doc, href) {
+  if (!/^#./.test(href ?? "")) return null;
+  let id = href.slice(1);
+  try {
+    id = decodeURIComponent(id);
+  } catch {
+    // kept as written
+  }
+  const card = doc.getElementById(id);
+  return card?.matches(DIALOG.match) ? card : null;
+}