@heycys/gallery 0.0.0-stage → 0.1.1

package/browser/editor/page/fold/index.mjs

@@ -0,0 +1,348 @@
+import { IN_LAYER } from "../../../shared/layers.mjs";
+import { FOLD_ARROW } from "../../../shared/code-folds.mjs";
+import { t } from "../../../shared/i18n/index.mjs";
+import { ELEMENT_ID, UNIT, identityOf, unitsOf, withLeads } from "../core.mjs";
+import { caretAt } from "../caret.mjs";
+import { HEADING } from "../outline/read.mjs";
+import { foldsOf, keepFolds } from "../outline/folds.mjs";
+import { drawAt, shapeOf } from "../overlay-layer.mjs";
+import { own } from "../overlays.mjs";
+import { local } from "../storage.mjs";
+import { shortcut, tooltip } from "../tooltip.mjs";
+import { addStyle, element } from "../ui.mjs";
+import { FOLDED, hiddenByFold, setFoldOpener } from "../folded.mjs";
+import { foldable, headingOf, keyOf, sectionAfter, stepOver, takenWith } from "./rule.mjs";
+
+// Folding a heading's section (docs/editor.md, "Folding a heading's section"): a small rounded triangle
+// a gap right of a heading's last line, shown while the pointer is at the heading (always while it is
+// folded), folds what the heading's section is (rule.mjs: the outline's nesting, in its box) out of
+// sight; Ctrl/⌘+Enter in its words does the same (components/heading/page.mjs). A fold is the reader's
+// view, never the file's: no undo step, no commit; kept per report in the browser
+// (gallery-edit:heading-folds, as the outline's folds are), so the page shown again after an Agent's
+// write folds what was folded. While the page lives, what is folded is the headings' identities
+// (data-ge-id: a heading turned into another level, or put back by undo, stays folded); what a fold
+// hides is marked data-ge-folded (the outermost folded heading's identity), shown as nothing.
+//
+// What asks it: the block tools (blocks.mjs) draw the triangles each frame (place, beside the handle:
+// handle.pointed), and take a folded heading's section with it wherever blocks are taken away whole
+// (takenWith: drag/, selection/delete.mjs, clipboard/, block-menu/'s 组成新分区; groupsOf and
+// stepOver: drag/ moveBy; withHidden: a row of columns made around it, columns/ and drag/);
+// selection/ keeps what is hidden out of the selection; typing/ opens a fold before Backspace or
+// Delete would join hidden words; editor.mjs opens the folds around the caret, and
+// every path that opens what hides a block goes through reveal() (page/folded.mjs). One rule opens a fold
+// of itself: a block a change of the page puts into a folded section (or one that was in sight and is not
+// now) opens it, unless the block came onto the page with its heading in that same change (undo
+// putting a folded section back, a folded section dragged).
+
+const STORE = "gallery-edit:heading-folds";
+// The button is what a press finds, drawn as nothing but its triangle; 16px (it was 20, filled under the
+// pointer: the user's, 2026-11-07), its triangle's middle 14px past the words as before.
+const SIZE = 16;
+const GAP = 6; // from the end of the heading's last line to the button
+// A press held that began off the triangles (words being selected, a box drawn, a block dragged): the
+// triangles take no pointer until it ends. Under the pointer one stood for the place of the drag: the
+// browser, finding a node outside the heading's editable text, put the selection's moving end at the
+// heading's start (the whole heading selected while the pointer crossed the triangle, the user's
+// 2026-11-07 第 6 条), and it darkened as if it were to be pressed.
+const HELD = "data-ge-fold-held";
+// What a fold hides is display: none !important: none of it shows, whatever display its blocks have
+// of their own (a row of columns' grid, a card's flex, a rule of the report's own).
+const STYLE = `
+  [data-ge-editing] [${FOLDED}] { display: none !important; }
+  .ge-fold { position: absolute; left: 0; top: 0; z-index: ${IN_LAYER.button}; box-sizing: border-box; display: flex; align-items: center; justify-content: center; width: ${SIZE}px; height: ${SIZE}px; border-radius: 4px; color: var(--ge-ico3); cursor: pointer; pointer-events: auto; user-select: none; }
+  html[${HELD}] .ge-fold { pointer-events: none; }
+  /* No fill under the pointer, the triangle darker (as the outline's), a short one while pressed (as a code block's arrow). */
+  .ge-fold:hover { color: var(--ge-ico2); }
+  .ge-fold:active { background: var(--ge-press); }
+  /* Open it points down; folded, left, at the heading's words (it stands right of them), turned clockwise. */
+  .ge-fold svg { display: block; width: 12px; height: 12px; fill: currentColor; transition: transform .2s ease-out; }
+  .ge-fold[aria-expanded="false"] svg { transform: rotate(90deg); }
+  @media (prefers-reduced-motion: reduce) { .ge-fold svg { transition: none; } }
+`;
+
+/** Where a heading's button stands (window coordinates): 6px right of its last line's end, on that line's middle; null where it shows no words. */
+export function foldRectOf(heading) {
+  const range = document.createRange();
+  range.selectNodeContents(heading);
+  const end = [...range.getClientRects()].filter((rect) => rect.width > 0 && rect.height > 0).at(-1);
+  if (!end) return null;
+  const left = end.right + GAP;
+  const top = (end.top + end.bottom) / 2 - SIZE / 2;
+  return { left, top, right: left + SIZE, bottom: top + SIZE };
+}
+
+/**
+ * slug: the report's. selection: selection/index.mjs (what is hidden leaves it). active(): whether
+ * the block tools may show. schedule(): the block tools' next frame.
+ */
+export function createFolds({ slug, selection, active, schedule }) {
+  addStyle(STYLE);
+  const folded = new Set(); // the identities of the headings folded
+  let heads = []; // the folded headings on the page at the last apply, in document order
+  let hidden = new Set(); // the units hidden at the last apply
+  let started = false;
+  let observer = null;
+  const buttons = new Map(); // heading -> its button
+  const holds = (node) => [...buttons.values()].some((button) => button.contains(node));
+
+  const main = () => document.querySelector("main");
+  const idOf = (node) => node?.getAttribute?.(ELEMENT_ID) ?? null;
+  const isFolded = (node) => node?.nodeType === 1 && folded.has(idOf(node)) && foldable(node);
+  const headings = () => [...(main()?.querySelectorAll(HEADING) ?? [])].filter(foldable);
+  // The units a folded heading hides (with those of folds inside it): those of its box marked with it.
+  const hiddenBy = (heading) => (heading.parentElement ? unitsOf(heading.parentElement).filter((unit) => unit.getAttribute(FOLDED) === idOf(heading)) : []);
+
+  function load() {
+    const keys = foldsOf(local, slug, STORE);
+    if (keys.size === 0) return;
+    const all = headings();
+    for (const key of keys) {
+      const heading = headingOf(key, all);
+      if (heading) folded.add(identityOf(heading));
+    }
+  }
+
+  // What is folded, kept by the keys the headings have now (only those still on the page).
+  function save() {
+    if (!started) return;
+    const all = headings();
+    keepFolds(local, slug, new Set(all.filter((heading) => folded.has(idOf(heading))).map((heading) => keyOf(heading, all))), null, STORE);
+  }
+
+  // What each folded heading hides now: unit -> the outermost folded heading over it. A folded heading
+  // with no words is folded no more; one hidden by a fold around it starts no section of its own.
+  function wanted(root) {
+    const want = new Map();
+    const found = [];
+    for (const heading of root.querySelectorAll(HEADING)) {
+      const id = idOf(heading);
+      if (!folded.has(id)) continue;
+      if (!foldable(heading)) {
+        folded.delete(id);
+        continue;
+      }
+      found.push(heading);
+      let under = false;
+      for (let node = heading; node && node !== root && !under; node = node.parentElement) under = want.has(node);
+      if (under) continue;
+      for (const unit of sectionAfter(heading)) want.set(unit, heading);
+    }
+    return { want, found };
+  }
+
+  /**
+   * The marks set again as the folds are now. `added`: the elements a change of the page put in (null:
+   * a fold toggled, or the page begun), for the rule that opens a fold: a unit hidden now that was not
+   * opens the folds over it, unless it came in with its heading.
+   */
+  function apply({ added = null } = {}) {
+    const root = main();
+    if (!root) return;
+    const within = (node) => {
+      for (let at = node; at && at !== root; at = at.parentElement) if (added.has(at)) return true;
+      return false;
+    };
+    const count = folded.size;
+    let result;
+    for (let round = 0; round < 16; round++) {
+      result = wanted(root);
+      if (added === null) break;
+      const opened = new Set();
+      for (const [unit, heading] of result.want) {
+        if (!hidden.has(unit) && !(within(unit) && within(heading))) opened.add(heading);
+      }
+      if (opened.size === 0) break;
+      for (const heading of opened) folded.delete(idOf(heading));
+    }
+    const marks = new Map();
+    for (const [unit, heading] of result.want) for (const part of withLeads(unit)) marks.set(part, idOf(heading));
+    for (const node of root.querySelectorAll(`[${FOLDED}]`)) if (!marks.has(node)) node.removeAttribute(FOLDED);
+    for (const [node, id] of marks) if (node.getAttribute(FOLDED) !== id) node.setAttribute(FOLDED, id);
+    heads = result.found;
+    hidden = new Set(result.want.keys());
+    if (added !== null && folded.size !== count) save(); // a fold opened of itself
+    schedule();
+  }
+
+  // A change of the page: blocks put in or taken out (a container's children, or a node that is or
+  // holds a block) apply the folds again; words typed in a heading too (emptied, its fold opens; a
+  // heading in a box may now end a section). Words typed elsewhere are nothing to it.
+  function changed(records) {
+    if (folded.size === 0 && hidden.size === 0) return;
+    const added = new Set();
+    let again = false;
+    for (const record of records) {
+      const target = record.target.nodeType === 1 ? record.target : record.target.parentElement;
+      if (target?.closest?.(HEADING)) again = true;
+      if (record.type !== "childList") continue;
+      if (target?.hasAttribute?.("data-ge-box")) again = true;
+      for (const node of record.addedNodes) {
+        if (node.nodeType !== 1) continue;
+        added.add(node);
+        if (!again && (node.matches(UNIT) || node.querySelector(UNIT))) again = true;
+      }
+      if (!again) for (const node of record.removedNodes) if (node.nodeType === 1 && (node.matches(UNIT) || node.querySelector(UNIT))) again = true;
+    }
+    if (again) apply({ added });
+  }
+
+  // The caret, or an end of a text selection, in what a fold now hides goes to the end of its heading;
+  // what is selected of it leaves the selection.
+  function stepOut(heading) {
+    const picked = selection.picked;
+    const kept = picked.filter((node) => !hiddenByFold(node));
+    if (kept.length !== picked.length) {
+      if (kept.length) selection.select(kept, { quiet: true });
+      else selection.clear();
+    }
+    const text = getSelection();
+    if (text?.rangeCount && (hiddenByFold(text.anchorNode) || hiddenByFold(text.focusNode))) caretAt(heading, "end");
+  }
+
+  /** Fold or unfold a heading's section. Whether it is one that folds. */
+  function toggle(heading) {
+    if (!started || !foldable(heading)) return false;
+    const id = identityOf(heading);
+    if (!folded.delete(id)) folded.add(id);
+    apply();
+    if (folded.has(id)) stepOut(heading);
+    save();
+    return true;
+  }
+
+  /** The folds over `node` opened, outermost first, until it shows. Whether any was. */
+  function showAround(node) {
+    let opened = false;
+    for (let round = 0; round < 16 && hiddenByFold(node); round++) {
+      const marked = (node.nodeType === 1 ? node : node.parentElement).closest(`[${FOLDED}]`);
+      if (!folded.delete(marked.getAttribute(FOLDED))) marked.removeAttribute(FOLDED); // no fold of this page's
+      opened = true;
+      apply();
+    }
+    if (opened) save();
+    return opened;
+  }
+
+  // ---------- the buttons ----------
+
+  // A press held that began off the triangles (HELD): set on the window before any tool sees the
+  // press, gone with the press (let go, cancelled, the window left, or a move with no button down
+  // where its end was missed). The triangles shown stay shown, as the handle's block stays while a
+  // button is down (handle/ onMove), and take the pointer again once it is let go.
+  let held = false;
+  const hold = (on) => {
+    if (held === on) return;
+    held = on;
+    document.documentElement.toggleAttribute(HELD, on);
+  };
+  addEventListener("pointerdown", (event) => hold(!holds(event.target)), true);
+  for (const type of ["pointerup", "pointercancel"]) addEventListener(type, () => hold(false), true);
+  addEventListener("blur", () => hold(false));
+  addEventListener("pointermove", (event) => { if (held && event.buttons === 0) hold(false); }, { capture: true, passive: true });
+
+  function make(heading) {
+    const node = element("div", { class: "ge-fold", role: "button", html: FOLD_ARROW });
+    tooltip(node, () => (isFolded(heading) ? t("展开") : t("折叠")), shortcut("mod+enter"));
+    // No caret moves, no box selection starts, the focus stays (blocks.mjs passes presses on it by).
+    node.addEventListener("pointerdown", (event) => event.preventDefault());
+    node.addEventListener("click", (event) => {
+      event.preventDefault();
+      toggle(heading);
+    });
+    own(node, "heading fold", { owner: heading, alive: () => buttons.get(heading) === node && heading.isConnected && started && active(), expected: () => foldRectOf(heading) });
+    return node;
+  }
+
+  function drop(heading) {
+    buttons.get(heading)?.remove();
+    buttons.delete(heading);
+  }
+
+  /** A frame: a button by each folded heading in sight, and by the heading the pointer is at (`pointed`). */
+  function place(pointed) {
+    const want = new Set(started ? heads.filter((heading) => heading.isConnected && isFolded(heading)) : []);
+    if (started && pointed && foldable(pointed) && !hiddenByFold(pointed)) want.add(pointed);
+    for (const heading of [...buttons.keys()]) if (!want.has(heading)) drop(heading);
+    for (const heading of want) {
+      const shape = shapeOf(heading);
+      const rect = shape && foldRectOf(heading);
+      if (!rect) {
+        drop(heading);
+        continue;
+      }
+      let node = buttons.get(heading);
+      if (!node) {
+        node = make(heading);
+        buttons.set(heading, node);
+      }
+      const open = !isFolded(heading);
+      if (node.getAttribute("aria-expanded") !== String(open)) {
+        node.setAttribute("aria-expanded", String(open));
+        node.setAttribute("aria-label", open ? t("折叠") : t("展开"));
+      }
+      drawAt(node, shape.layer, rect.left - shape.origin.left, rect.top - shape.origin.top);
+    }
+  }
+
+  function hide() {
+    for (const heading of [...buttons.keys()]) drop(heading);
+  }
+
+  const folds = {
+    /** Editing begins: what was folded folded again, in the task editing begins in (no frame shows it open). */
+    start() {
+      if (started) return;
+      started = true;
+      setFoldOpener(showAround);
+      load();
+      apply();
+      observer = new MutationObserver(changed);
+      const root = main();
+      if (root) observer.observe(root, { childList: true, subtree: true, characterData: true });
+      addEventListener("pagehide", save);
+    },
+    /** Editing ends: every fold shown open (what is folded is kept). */
+    stop() {
+      if (!started) return;
+      save();
+      started = false;
+      observer?.disconnect();
+      for (const node of document.querySelectorAll(`[${FOLDED}]`)) node.removeAttribute(FOLDED);
+      heads = [];
+      hidden = new Set();
+      hide();
+    },
+    place,
+    hide,
+    /** A button shows (the frames go on following the headings). */
+    get showing() { return buttons.size > 0; },
+    holds,
+    toggle,
+    isFolded,
+    hidden: hiddenByFold,
+    showAround,
+    /** `units` with what each folded heading among them hides (a section it covers whole instead): rule.mjs takenWith. */
+    takenWith: (units) => takenWith(units, { isFolded, hiddenBy }),
+    /** A block with what it hides (a folded heading's section, folds inside it too), in document order: what goes into a column with it (columns/ split, drag/ besideTo). */
+    withHidden: (unit) => (isFolded(unit) ? [unit, ...hiddenBy(unit)] : [unit]),
+    /** The last block of a block and what it hides (a folded heading's last hidden block), for a place after it. */
+    lastOf: (unit) => (isFolded(unit) ? hiddenBy(unit).at(-1) ?? unit : unit),
+    /** The blocks of `list` as the reader sees them: each shown block, a folded heading with what it hides. */
+    groupsOf(list) {
+      const groups = [];
+      for (const unit of list) {
+        if (unit.hasAttribute(FOLDED) && groups.length > 0) groups.at(-1).push(unit);
+        else groups.push([unit]);
+      }
+      return groups;
+    },
+    /** Where Ctrl+Shift+↑/↓ takes a folded heading (rule.mjs stepOver). */
+    stepOver,
+    /** What the status line calls `targets` taken for `picked` (named: block-info.mjs's): 标题和折叠的 N 块. */
+    namedWith(picked, targets, named) {
+      const extra = targets.length - picked.length;
+      return extra > 0 && picked.every((node) => targets.includes(node)) ? t("{0}和折叠的 {1} 块", named(picked), extra) : named(targets);
+    },
+  };
+  return folds;
+}

package/browser/editor/page/fold/rule.mjs

@@ -0,0 +1,125 @@
+import { HEADING, LEFT_OUT, headingText } from "../outline/read.mjs";
+import { UNIT, unitsOf } from "../core.mjs";
+import { CHAPTER, LEADS_CHAPTER } from "../../components/registry.mjs";
+import { FOLDED } from "../folded.mjs";
+
+// What folding a heading's section takes (docs/editor.md, "Folding a heading's section"), pure so the
+// unit tests hold it (tests/unit/heading-folds.mjs); the tool that folds is index.mjs. A heading the
+// outline lists, standing straight in a box, folds what follows it in that box up to the first block
+// that ends it: a heading of its level or higher, or a block holding one the outline lists (a section,
+// a tabs area, a row of columns, a disclosure, a highlight block…), the outline's rule of what nests
+// under a heading (outline/tree.mjs treeOf), so the fold and the outline say the same of a section.
+
+export { FOLDED };
+
+/** A heading's level, 1-4. */
+export const levelOf = (heading) => Number(heading.localName[1]);
+
+const kindOf = (node) => node.getAttribute("data-ge-unit-kind");
+
+/** Whether a node is a heading that folds: one the outline lists, standing straight in a box, with words. */
+export function foldable(node) {
+  return node?.nodeType === 1 && node.matches(HEADING) && node.matches(UNIT) && !node.closest(LEFT_OUT)
+    && Boolean(node.parentElement?.hasAttribute("data-ge-box")) && headingText(node) !== "";
+}
+
+/** Whether `unit` ends a section of level `level`: a heading of that level or higher, or a block holding one the outline lists. */
+export function ends(unit, level) {
+  if (unit.matches(HEADING)) return levelOf(unit) <= level;
+  for (const heading of unit.querySelectorAll(HEADING)) {
+    if (levelOf(heading) <= level && !heading.closest(LEFT_OUT) && headingText(heading) !== "") return true;
+  }
+  return false;
+}
+
+/** The units after `heading` in its box that are its section (at `level`, its own by default), the one ending it not among them. */
+export function sectionAfter(heading, level = levelOf(heading)) {
+  const box = heading.parentElement;
+  if (!box) return [];
+  const out = [];
+  let past = false;
+  for (const unit of unitsOf(box)) {
+    if (!past) {
+      past = unit === heading;
+      continue;
+    }
+    if (ends(unit, level)) break;
+    out.push(unit);
+  }
+  return out;
+}
+
+/** Nodes in document order, each once, none inside another. */
+export function inOrder(nodes) {
+  const set = [...new Set(nodes)];
+  return set.filter((node) => !set.some((other) => other !== node && other.contains(node)))
+    .sort((a, b) => (a.compareDocumentPosition(b) & 4 ? -1 : 1)); // 4: DOCUMENT_POSITION_FOLLOWING
+}
+
+/**
+ * What an operation that takes blocks away whole takes for `units`: each folded heading with what it
+ * hides (isFolded(heading), hiddenBy(heading): the units its fold hides, those of folds inside it too),
+ * in document order. A folded heading whose box is a chapter (a section) of which it and what it hides
+ * are every unit, but for dividers before it, stands for that section: the section is taken.
+ */
+export function takenWith(units, { isFolded, hiddenBy }) {
+  const out = [];
+  for (const unit of units) {
+    out.push(unit);
+    if (isFolded(unit)) out.push(...hiddenBy(unit));
+  }
+  for (const unit of [...out]) {
+    const box = unit.parentElement;
+    if (!isFolded(unit) || !box?.matches(UNIT) || !CHAPTER.has(kindOf(box))) continue;
+    const covered = new Set([unit, ...hiddenBy(unit)]);
+    const all = unitsOf(box);
+    const at = all.indexOf(unit);
+    if (all.every((each, index) => covered.has(each) || (index < at && LEADS_CHAPTER.has(kindOf(each))))) out.push(box);
+  }
+  return inOrder(out);
+}
+
+/**
+ * Where Ctrl+Shift+↑/↓ takes a folded heading (its section with it): past the next section of its
+ * level going down (the block after what it hides, which ends it, and what follows that up to the
+ * next block ending a section of its level), past the one before going up (back to the block ending a
+ * section of its level, or the box's first block, up to the block before it). `list`: the blocks it
+ * moves among, in order. { first, last } of what it goes past, or null where there is none.
+ */
+export function stepOver(heading, delta, list = unitsOf(heading.parentElement)) {
+  const level = levelOf(heading);
+  const at = list.indexOf(heading);
+  if (at < 0) return null;
+  if (delta > 0) {
+    const from = at + 1 + sectionAfter(heading).length;
+    if (from >= list.length) return null;
+    let to = from;
+    while (to + 1 < list.length && !ends(list[to + 1], level)) to++;
+    return { first: list[from], last: list[to] };
+  }
+  if (at === 0) return null;
+  let from = at - 1;
+  while (from > 0 && !ends(list[from], level)) from--;
+  return { first: list[from], last: list[at - 1] };
+}
+
+/**
+ * The key a folded heading is kept by: `b:<block id>`, or with none `t:<tag>:<words>#<n>`, n its place
+ * among the foldable headings of its tag and words (`all`, in document order; with an id or not).
+ */
+export function keyOf(heading, all) {
+  const id = heading.getAttribute("data-block-id");
+  if (id) return `b:${id}`;
+  const text = headingText(heading);
+  const same = all.filter((each) => each.localName === heading.localName && headingText(each) === text);
+  return `t:${heading.localName}:${text}#${Math.max(0, same.indexOf(heading))}`;
+}
+
+/** The heading of `all` a key names (keyOf), or null: by its block id, or the n-th of its tag and words, with an id or not. */
+export function headingOf(key, all) {
+  if (key.startsWith("b:")) return all.find((each) => each.getAttribute("data-block-id") === key.slice(2)) ?? null;
+  const match = /^t:(h[1-4]):([\s\S]*)#(\d+)$/.exec(key);
+  if (!match) return null;
+  const [, tag, text, n] = match;
+  return all.filter((each) => each.localName === tag && headingText(each) === text)[Number(n)] ?? null;
+}

package/browser/editor/page/folded.mjs

@@ -0,0 +1,23 @@
+// What the other tools ask of the headings' folds (fold/ folds a heading's section, docs/editor.md
+// "Folding a heading's section"): the mark on what a fold hides, whether a node is hidden by one, and
+// reveal(), what every path that brings a block into sight goes through (a link to a block, the
+// outline, a 批注, a conflict's card): the folds over it opened, then what the kit opens.
+
+/** What marks a unit (and its leads) a fold hides: the identity (data-ge-id) of the outermost heading folded over it. */
+export const FOLDED = "data-ge-folded";
+
+/** Whether a node (or the block it is in) is hidden by a fold. */
+export const hiddenByFold = (node) => Boolean((node?.nodeType === 1 ? node : node?.parentElement)?.closest?.(`[${FOLDED}]`));
+
+let opener = null; // the page's fold tool's showAround, once editing begins
+
+/** The page's fold tool: what opens the folds over a node (fold/ showAround). */
+export function setFoldOpener(open) {
+  opener = open;
+}
+
+/** What hides `target` opened: the folds over it first, then what the kit opens (DocKit.reveal: a disclosure, a tab, a detail card). */
+export function reveal(target) {
+  opener?.(target);
+  globalThis.DocKit?.reveal(target);
+}