@heycys/gallery 0.1.1 → 0.2.0

package/browser/editor/page/board/hint.mjs

@@ -0,0 +1,182 @@
+import { language, t } from "../../../shared/i18n/index.mjs";
+import { postAnswer } from "../post.mjs";
+import { say } from "../notices.mjs";
+import { addStyle, element } from "../ui.mjs";
+
+// A custom page's first-open note (notes/plans/component-pages-plan-2026-11-07.md §5.2; docs/render.md
+// "A custom page", **Notes of a page**): at the top of a page whose page.json says `hint` (the default home
+// page's), while the page map says `hint` (src/server/routes.mjs: its note not yet closed in this
+// workspace), a short note on its cards: how to move one (the grip at its top-right: drag it), open its
+// menu (a click on the same grip: 大小, 设置, 删除), add one (添加自定义块: the first item of the ··· menu at the
+// top right of the workbench's bar; a page open alone in a tab has it at the top right of its board) and
+// take one out (the menu's 删除), and that a new card or a new page is the Agent's to make, with a sentence
+// the reader can copy and say to one (its 复制 button). Its × closes it for good, for the workspace (POST
+// /__gallery/pages/<slug>/hint: .gallery/hints.json), whichever browser shows the page next. In the
+// editor's look: grays alone, a quiet fill, no colour; the kit's own light and dark through the
+// editor's tokens (look.mjs).
+//
+// Its note of new default cards (showNews: the plan's 3.4), on a page with the default cards (its page.json's
+// defaultCards) made before some of them, while the page map says `news`: which default cards it does not
+// hold that came since, and that 加到这一页 puts them in the empty spots as 恢复默认卡片 in the page's menu
+// does (the board's restoreDefaults: what is missing alone, the cards there untouched, one step of the
+// page's undo). A page already made is never changed by itself: the reader is told once, at the top of
+// the page, where the first-open note stands, and nothing moves on the board until they ask. Its × (or
+// 加到这一页) says it for the workspace (POST /__gallery/pages/<slug>/hint with { cards: true }), which
+// 恢复默认卡片 does too.
+//
+// And the middle of a blank page (showBlank: the workbench's 新建页面, which no one has written yet, while
+// the page map says `blank`): that an Agent writes a custom page, any page it likes, a board of cards or
+// not, with a request the reader can copy and say to one, as the first-open note's. Nothing of it is the
+// file's: once an Agent writes page.html the page is shown again without it.
+const STYLE = `
+  .ge-home-hint { box-sizing: border-box; max-width: var(--gallery-board-width, 944px); margin: 0 auto 12px; }
+  .ge-home-hint-box { position: relative; box-sizing: border-box; max-width: 720px; padding: 14px 44px 14px 16px; border-radius: 10px;
+    background: light-dark(rgb(55 53 47 / 4%), rgb(255 255 255 / 4.5%)); color: var(--ge-tx);
+    font: 14px/1.6 ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI Variable Text", "Segoe UI", Helvetica, "PingFang SC", "Microsoft YaHei", Arial, sans-serif; }
+  .ge-home-hint-box p { margin: 0; }
+  .ge-home-hint-box p + p { margin-top: 4px; }
+  .ge-home-hint-title { font-weight: 600; }
+  .ge-home-hint-box .ge-home-hint-ask { margin-top: 10px; color: var(--ge-tx2); }
+  .ge-home-hint-icon { display: inline-flex; align-items: center; justify-content: center; width: 18px; height: 18px; margin: 0 2px; vertical-align: -3px; border-radius: 4px; background: var(--ge-hover); color: var(--ge-ico2); }
+  .ge-home-hint-icon svg { display: block; width: 10px; height: 12px; fill: currentColor; }
+  .ge-home-hint-say { display: flex; align-items: center; gap: 8px; margin-top: 6px; padding: 6px 6px 6px 12px; border-radius: 6px; background: var(--ge-bg); }
+  .ge-home-hint-say span { flex: 1; min-width: 0; color: var(--ge-tx); user-select: text; }
+  .ge-home-hint-copy, .ge-home-hint-close { flex: none; display: inline-flex; align-items: center; justify-content: center; box-sizing: border-box; border: 0; border-radius: 6px; background: transparent; color: var(--ge-tx2); font: inherit; cursor: pointer; user-select: none; }
+  .ge-home-hint-copy { height: 28px; padding: 0 10px; font-size: 13px; }
+  .ge-home-hint-copy:hover, .ge-home-hint-close:hover { background: var(--ge-hover); color: var(--ge-tx); }
+  .ge-home-hint-copy:active, .ge-home-hint-close:active { background: var(--ge-press); }
+  .ge-home-hint-close { position: absolute; top: 10px; right: 10px; width: 24px; height: 24px; color: var(--ge-ico3); }
+  .ge-home-hint-close svg { display: block; width: 14px; height: 14px; fill: none; stroke: currentColor; stroke-width: 1.5; stroke-linecap: round; }
+  .ge-home-hint-act { margin-top: 8px; }
+  .ge-home-hint-box .ge-home-hint-add { margin-left: -2px; background: var(--ge-btn-primary); color: var(--ge-btn-primary-text); }
+  .ge-home-hint-box .ge-home-hint-add:hover:not(:disabled) { background: var(--ge-btn-primary-hover); color: var(--ge-btn-primary-text); }
+  .ge-home-hint-box .ge-home-hint-add:disabled { opacity: .5; cursor: default; }
+  .ge-page-blank { box-sizing: border-box; display: flex; justify-content: center; padding: max(48px, 18vh) 16px 48px; }
+  .ge-page-blank .ge-home-hint-box { width: 100%; max-width: 520px; padding: 20px 20px 18px; }
+  .ge-page-blank .ge-home-hint-title { font-size: 16px; }
+`;
+
+const DOTS = '<svg viewBox="0 0 10 16" aria-hidden="true"><circle cx="2.5" cy="2" r="1.25"/><circle cx="7.5" cy="2" r="1.25"/><circle cx="2.5" cy="8" r="1.25"/><circle cx="7.5" cy="8" r="1.25"/><circle cx="2.5" cy="14" r="1.25"/><circle cx="7.5" cy="14" r="1.25"/></svg>';
+const CLOSE = '<svg viewBox="0 0 16 16" aria-hidden="true"><path d="M4 4l8 8M12 4l-8 8"/></svg>';
+
+// `template` (t's words, {0}, {1}… where `nodes` go) as the nodes of a line.
+function filled(template, nodes) {
+  return template.split(/\{(\d+)\}/).map((piece, index) => (index % 2 ? nodes[Number(piece)] ?? "" : piece)).filter((piece) => piece !== "");
+}
+const icon = (html) => element("span", { class: "ge-home-hint-icon", html });
+// A note at the top of the home page, of the editor's UI (never the file's): `kind` its class beside ge-home-hint, `label` what it is called.
+const noteOf = (kind, label, box) => element("div", { class: `ge-home-hint${kind ? ` ${kind}` : ""}`, role: "note", "aria-label": label, "data-doc-dev": "" }, box);
+
+/**
+ * The note of new default cards, on the home page whose map says `news` ([{ block, name }]), at the top of
+ * the page, after the first-open note where that is shown; `restore`, the board's restoreDefaults. Returns
+ * the note, or null where none is shown.
+ */
+export function showNews(map, { restore }) {
+  const main = document.querySelector("main.gallery-page");
+  if (!map?.news?.length || !main) return null;
+  addStyle(STYLE);
+  const named = ({ block, name }) => name?.[language === "en" ? "en" : "zh"] ?? name?.zh ?? block;
+  const add = element("button", { type: "button", class: "ge-home-hint-copy ge-home-hint-add", text: t("加到这一页") });
+  const close = element("button", { type: "button", class: "ge-home-hint-close", "aria-label": t("关闭这条说明"), title: t("关闭"), html: CLOSE });
+  const box = element("div", { class: "ge-home-hint-box" },
+    element("p", { class: "ge-home-hint-title", text: t("有了新的默认卡片") }),
+    element("p", { text: map.news.map(named).join(t("、")) }),
+    element("p", { class: "ge-home-hint-ask", text: t("点「加到这一页」放进空位，已有的卡片不动。以后也可以在这一页的菜单中点「恢复默认卡片」。") }),
+    element("div", { class: "ge-home-hint-act" }, add),
+    close);
+  const note = noteOf("ge-home-news", t("新的默认卡片"), box);
+  for (const button of [add, close]) button.addEventListener("mousedown", (event) => event.preventDefault());
+  const told = () => postAnswer(`/__gallery/pages/${map.slug}/hint`, map.token, { cards: true });
+  add.addEventListener("click", async () => {
+    add.disabled = true;
+    const answer = await restore();
+    if (!answer?.ok) {
+      add.disabled = false;
+      return say(t("没能把卡片放到这一页"), "error");
+    }
+    note.remove();
+    const added = answer.added ?? [];
+    say(added.length ? t("已放回默认卡片：{0}", added.map(named).join(t("、"))) : t("默认卡片都在，没有要放回的"));
+  });
+  close.addEventListener("click", async () => {
+    note.remove();
+    const answer = await told();
+    if (!answer?.ok) say(t("没能记下这条说明已关闭"), "error");
+  });
+  const first = main.querySelector(":scope > .ge-home-hint");
+  if (first) first.after(note);
+  else main.prepend(note);
+  return note;
+}
+
+/**
+ * The note shown, on the page whose map (`map`: slug, token) says `hint`, at the top of the page
+ * (`main.gallery-page`, before what the page holds). `hosted`: the page stands in a workbench, whose top
+ * bar's ··· menu has 添加自定义块 (the words say so), else the page's own at the top right of its board. Returns the
+ * note, or null where none is shown.
+ */
+export function showHint(map, { hosted = false } = {}) {
+  const main = document.querySelector("main.gallery-page");
+  if (!map?.hint || !main) return null;
+  addStyle(STYLE);
+  // The sentence offered: one that names Gallery, so that the Agent takes up its skill.
+  const ask = t("用 Gallery 在「{0}」这一页加一张卡片，记我每天喝了几杯水。别动我摆好的卡片。", map.title ?? document.title);
+  const copy = element("button", { type: "button", class: "ge-home-hint-copy", text: t("复制") });
+  const close = element("button", { type: "button", class: "ge-home-hint-close", "aria-label": t("关闭这条说明"), title: t("关闭"), html: CLOSE });
+  const box = element("div", { class: "ge-home-hint-box" },
+    element("p", { class: "ge-home-hint-title", text: t("这一页的卡片可以自己摆") }),
+    element("p", {}, ...filled(hosted ? t("拖卡片右上角的 {0} 移动它，点一下它打开菜单（大小、设置、删除），点页面右上角的 ··· 里的「添加自定义块」加一张。") : t("拖卡片右上角的 {0} 移动它，点一下它打开菜单（大小、设置、删除），点页面右上方的「添加自定义块」加一张。"), [icon(DOTS)])),
+    element("p", { class: "ge-home-hint-ask", text: t("想要新卡片或新页面，跟 Agent 说，比如：") }),
+    element("div", { class: "ge-home-hint-say" }, element("span", { text: ask }), copy),
+    close);
+  const note = noteOf("", t("这一页的说明"), box);
+  for (const button of [copy, close]) button.addEventListener("mousedown", (event) => event.preventDefault());
+  copy.addEventListener("click", () => {
+    // The frame given the focus first: in a workbench a press its mousedown keeps from moving the focus
+    // leaves it in the workbench, and Chrome refuses a clipboard write to a document without it
+    // ("Document is not focused"), as the board's grip takes it for the page's keys.
+    window.focus();
+    navigator.clipboard?.writeText(ask).then(() => {
+      copy.textContent = t("已复制");
+      say(t("已复制这句话，发给 Agent 就行"));
+    }, () => say(t("没能复制：浏览器不允许写剪贴板。"), "error"));
+  });
+  close.addEventListener("click", async () => {
+    note.remove();
+    const answer = await postAnswer(`/__gallery/pages/${map.slug}/hint`, map.token, {});
+    if (!answer?.ok) say(t("没能记下这条说明已关闭"), "error");
+  });
+  main.prepend(note);
+  return note;
+}
+
+/**
+ * The middle of a blank page (the page map's `blank`: the workbench's 新建页面, which no one has written yet):
+ * that an Agent writes it, any page it likes, with a request to copy and say to one. Returns the note, or
+ * null where none is shown (no blank page, or no main.gallery-page to show it in).
+ */
+export function showBlank(map) {
+  const main = document.querySelector("main.gallery-page");
+  if (!map?.blank || !main) return null;
+  addStyle(STYLE);
+  const title = map.title ?? document.title;
+  const ask = t("用 Gallery 把「{0}」这个自定义页写出来：放上我这周的待办，和离月底还有几天。", title);
+  const copy = element("button", { type: "button", class: "ge-home-hint-copy", text: t("复制") });
+  const box = element("div", { class: "ge-home-hint-box" },
+    element("p", { class: "ge-home-hint-title", text: t("这一页还是空的") }),
+    element("p", { text: t("自定义页由 Agent 来写：可以是一页卡片，也可以是它为你做的任何网页。") }),
+    element("p", { class: "ge-home-hint-ask", text: t("跟 Agent 说你想在这里放什么，比如：") }),
+    element("div", { class: "ge-home-hint-say" }, element("span", { text: ask }), copy));
+  const note = noteOf("ge-page-blank", t("空白的自定义页"), box);
+  copy.addEventListener("mousedown", (event) => event.preventDefault());
+  copy.addEventListener("click", () => {
+    window.focus(); // as the first-open note's 复制: Chrome writes no clipboard of a document without the focus
+    navigator.clipboard?.writeText(ask).then(() => {
+      copy.textContent = t("已复制");
+      say(t("已复制这句话，发给 Agent 就行"));
+    }, () => say(t("没能复制：浏览器不允许写剪贴板。"), "error"));
+  });
+  main.append(note);
+  return note;
+}

package/browser/editor/page/board/history.mjs

@@ -0,0 +1,119 @@
+// A custom page's own undo and redo (docs/render.md "A custom page", the board's editing): what the
+// page did, each step a list of what to send the page service to take it back or do it again, never
+// a copy of the file. Kept in the tab's sessionStorage by the page's slug, so that a page shown again
+// (the hidden frame's swap after a card is added from the library, or after someone else wrote
+// page.html) undoes what this one did: the next page takes the steps up, and forgets those of a card
+// someone else changed meanwhile (`forgetChanged`: its base, as the page knew it last, is not the one
+// it is served with), whose undo would write over what they did. Each step names its cards by id; what
+// it sends is held to each card's base as the page knows it then, so a card someone else changed is
+// refused by the service whenever the page has not yet heard of it.
+//
+// A step is one of:
+//   { kind: "cells", cards: [{ id, before: { x, y, w, h }, after: { x, y, w, h } }] }  moved, resized, pushed
+//   { kind: "edit", id, parts: { <name>: { was, now } } }                             a block's data or its settings
+//   { kind: "remove", id, board, html }                                                 a card taken out
+//   { kind: "add", id, board, html }                                                    a card put in
+//   { kind: "group", steps: [step, …] }                                                 several at once (恢复默认卡片's cards)
+//   { kind: "checked", slug, ref, done }                                                   a to-do of document `slug` checked (done) or not by a block
+
+const MOST = 100; // steps kept each way
+
+const read = (key) => {
+  try {
+    const value = JSON.parse(sessionStorage.getItem(key) ?? "null");
+    return value && Array.isArray(value.undo) && Array.isArray(value.redo) && value.bases && typeof value.bases === "object" ? value : null;
+  } catch {
+    return null;
+  }
+};
+
+/** The page `slug`'s steps. */
+export function createHistory(slug) {
+  const key = `gallery-edit:${slug}:page-history`; // an editor key as the others (gallery-edit:<slug>:<kind>, shared/renamed-storage.mjs): made after the rename, so no old name
+  const kept = read(key);
+  let undo = kept?.undo ?? [];
+  let redo = kept?.redo ?? [];
+  let bases = kept?.bases ?? {}; // a card's id -> its base as this page knew it last
+  let measure = kept?.measure ?? null; // a card just added whose height its content gives, to measure once shown
+  const save = () => {
+    try {
+      sessionStorage.setItem(key, JSON.stringify({ undo, redo, bases, measure }));
+    } catch {} // no storage: the steps last as long as the page
+  };
+  const touches = (step, id) => (step.kind === "group" ? step.steps.some((one) => touches(one, id)) : step.kind === "cells" ? step.cards.some((card) => card.id === id) : step.id === id);
+  const rename = (step, from, to) => {
+    if (step.kind === "group") for (const one of step.steps) rename(one, from, to);
+    else if (step.kind === "cells") for (const card of step.cards) card.id = card.id === from ? to : card.id;
+    else if (step.id === from) step.id = to;
+  };
+  return {
+    /** A step done: undo takes it back first; what was undone cannot be done again any more. */
+    push(step) {
+      undo.push(step);
+      if (undo.length > MOST) undo.shift();
+      redo = [];
+      save();
+    },
+    /** The step undo takes back now, left where it is (null: none). */
+    nextUndo: () => undo.at(-1) ?? null,
+    /** The step undo takes back now, taken off (null: none). */
+    takeUndo: () => {
+      const step = undo.pop() ?? null;
+      save();
+      return step;
+    },
+    takeRedo: () => {
+      const step = redo.pop() ?? null;
+      save();
+      return step;
+    },
+    /** A step undone (it can be done again) or done again (it can be undone again). */
+    undone(step) {
+      redo.push(step);
+      save();
+    },
+    redone(step) {
+      undo.push(step);
+      save();
+    },
+    /** Card `from` goes by `to` now (put back under another id): the steps say so. */
+    renamed(from, to) {
+      for (const step of [...undo, ...redo]) rename(step, from, to);
+      save();
+    },
+    /** The cards' bases as this page knows them now ({ id: base }), for the next page to hold its own against. */
+    know(now) {
+      bases = { ...now };
+      save();
+    },
+    /**
+     * The page shown again: the steps of each card whose base (`served`, { id: base }) is not the one the
+     * page before knew are forgotten, someone else's change of it standing; so is a card gone or come.
+     */
+    forgetChanged(served) {
+      const changed = Object.keys(bases).filter((id) => served[id] !== bases[id]);
+      const gone = (step) => changed.some((id) => touches(step, id));
+      undo = undo.filter((step) => !gone(step));
+      redo = redo.filter((step) => !gone(step));
+      bases = { ...served };
+      save();
+    },
+    /** A card added whose height is its content's: measured once the next page shows it (`take`: and forgotten). */
+    toMeasure(id) {
+      measure = id;
+      save();
+    },
+    takeMeasure() {
+      const id = measure;
+      measure = null;
+      save();
+      return id;
+    },
+    get canUndo() {
+      return undo.length > 0;
+    },
+    get canRedo() {
+      return redo.length > 0;
+    },
+  };
+}