@heycys/gallery 0.1.1 → 0.2.0

package/packs/gallery/note/component.json

@@ -0,0 +1,14 @@
+{
+  "id": "gallery/note",
+  "apiVersion": 1,
+  "version": "2.0.0",
+  "name": { "zh": "便签", "en": "Note" },
+  "description": { "zh": "几行随手记，在卡片上直接写，存在页面里", "en": "A few lines jotted down, typed on the card and kept in the page" },
+  "words": "bianqian note memo sticky 便签 笔记 随手记 记事",
+  "parts": {
+    "note": { "at": ":scope > script", "edit": "data" }
+  },
+  "runtime": { "generated": [":scope > .gallery-note-head", ":scope > .gallery-note-field", ":scope > .gallery-note-foot"] },
+  "places": ["page"],
+  "card": { "sizes": [[4, 2], [2, 2], [4, 4]], "min": { "w": 2, "h": 2 }, "max": { "w": 4, "h": 8 }, "resize": true }
+}

package/packs/gallery/note/example.html

@@ -0,0 +1,3 @@
+<div data-doc-component="gallery/note">
+  <script type="application/json">{"text":"周五前把季度报告发给王经理\n买牛奶、鸡蛋\n下周二下午三点 牙医"}</script>
+</div>

package/packs/gallery/note/kit.js

@@ -0,0 +1,129 @@
+// gallery/note (便签): a few lines of free text, kept in the instance's data part, a script of JSON,
+// { "text": "…" }, and typed on the card itself, in a <textarea> the block draws under its head.
+// The field is the kit's (DocKit.input): what the reader typed goes to the file once they are done with
+// it, as they leave the field or press Ctrl+Enter (⌘Enter on a Mac; Enter alone is a new line), never
+// while an input method composes, and never a value it holds already; Esc puts back what the file holds.
+// Each of those is one context.editJSON, one undo step, the JSON written back on one line as it was. It
+// draws from the part on every `source` (an Agent's write, an undo), the words the reader is typing kept
+// where they are. Where nothing takes its writes (an export, a page that has not come to edit yet:
+// context.canEdit() false) the field is read-only, and shows the same words. An empty note says 写点什么….
+// Above the field its head (the pack's design B: the kit's card tokens): the chip, a pencil, its name,
+// 便签, and its quiet meta after it, how many characters the field holds (its blanks not counted, said
+// again as the reader types; none on a card two cells wide, `data-layout` "narrow" by context.size, read
+// again on `layout`). Its lines are ruled faintly, a hint that it takes writing (style.css); while the
+// reader types, a line under the field says the two keys (Ctrl+Enter 保存, Esc 还原; ⌘Enter on a Mac), and
+// the card is ringed in the accent's wash; scrolled down, the field's top fades (data-scrolled). Nothing of
+// the head or the foot is written.
+
+const WORDS = {
+  zh: { empty: "写点什么…", label: "便签", count: (/** @type {number} */ count) => `${count} 字`, save: "保存", undo: "还原" },
+  en: { empty: "Write something…", label: "Note", count: (/** @type {number} */ count) => `${count} ${count === 1 ? "character" : "characters"}`, save: "save", undo: "revert" },
+};
+
+/** The language the page speaks: the UI's where Gallery says it (data-ge-language), else its lang's. */
+function languageOf(/** @type {HTMLElement} */ root) {
+  const ui = root.getAttribute("data-ge-language");
+  return (ui !== null ? ui === "en" : /^en(?:-|$)/i.test(root.lang)) ? "en" : "zh";
+}
+
+/**
+ * The words a note's data holds (context.readJSON's): its `text`, "" where it has none yet; throws
+ * saying why for data that is no note, which the block does not draw over.
+ * @param {any} data
+ * @returns {string}
+ */
+function textOf(data) {
+  if (data === null || typeof data !== "object" || Array.isArray(data)) throw new Error("its data is no object: a note holds { \"text\": \"…\" }");
+  if (data.text === undefined) return "";
+  if (typeof data.text !== "string") throw new Error("its text is no string");
+  return data.text;
+}
+
+/**
+ * The note made to hold `text`, one write (context.editJSON): what a reader's words, once they are done
+ * with the field, call, and the example too. Whether it was taken.
+ * @param {DocComponentContext} context
+ * @param {string} text
+ */
+function writeNote(context, text) {
+  return context.editJSON("note", (data) => {
+    textOf(data);
+    data.text = text;
+  });
+}
+
+/** How many characters `text` holds, its blanks (spaces, new lines) not counted. @param {string} text */
+const countOf = (text) => [...text.replace(/\s+/g, "")].length;
+
+DocKit.component({
+  id: "gallery/note",
+  on: ["source", "editable", "layout"],
+  mount(host, context) {
+    const words = WORDS[languageOf(document.documentElement)];
+    const head = document.createElement("div");
+    head.className = "gallery-note-head";
+    head.setAttribute("aria-hidden", "true");
+    const chip = document.createElement("span");
+    chip.className = "gallery-note-chip";
+    chip.innerHTML = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round"><path d="M4.5 19.5h3.8L19 8.8a2.4 2.4 0 0 0-3.4-3.4L4.9 16.1z"/><path d="M14 7l3 3"/></svg>';
+    const title = document.createElement("span");
+    title.className = "gallery-note-title";
+    title.textContent = words.label;
+    // Its quiet meta after the title: how many characters the field holds (its blanks not counted), as the reader types too.
+    const meta = document.createElement("span");
+    meta.className = "gallery-note-meta";
+    head.append(chip, title, meta);
+    const field = document.createElement("textarea");
+    field.className = "gallery-note-field";
+    field.placeholder = words.empty;
+    field.spellcheck = false;
+    field.setAttribute("aria-label", words.label);
+    // While the reader types: the two keys, Ctrl+Enter (⌘Enter on a Mac) and Esc.
+    const foot = document.createElement("div");
+    foot.className = "gallery-note-foot";
+    foot.setAttribute("aria-hidden", "true");
+    const key = (/** @type {string} */ name, /** @type {string} */ does) => {
+      const said = document.createElement("span");
+      const bold = document.createElement("b");
+      bold.textContent = name;
+      said.append(bold, ` ${does}`);
+      return said;
+    };
+    foot.append(key(document.documentElement.dataset.docPlatform === "mac" ? "⌘Enter" : "Ctrl+Enter", words.save), key("Esc", words.undo));
+    host.append(head, field, foot);
+    const typed = DocKit.input(field, { signal: context.signal, commit: (value) => writeNote(context, value) });
+    const recount = () => {
+      const count = countOf(field.value);
+      const said = count > 0 ? words.count(count) : "";
+      if (meta.textContent !== said) meta.textContent = said;
+    };
+    field.addEventListener("input", recount);
+    context.signal?.addEventListener("abort", () => field.removeEventListener("input", recount), { once: true });
+    // Scrolled down, its top fades (style.css), so that a line it scrolled past is never cut hard.
+    const scrolled = () => field.toggleAttribute("data-scrolled", field.scrollTop > 0);
+    field.addEventListener("scroll", scrolled, { passive: true });
+    context.signal?.addEventListener("abort", () => field.removeEventListener("scroll", scrolled), { once: true });
+    const draw = (/** @type {string} */ reason = "") => {
+      const layout = context.size && context.size.w <= 2 ? "narrow" : "wide";
+      if (head.dataset.layout !== layout) head.dataset.layout = layout;
+      if (reason === "layout") return;
+      const data = context.readJSON("note");
+      if (data === undefined) return; // no JSON: the instance has failed, and Gallery shows what it holds
+      let text;
+      try {
+        text = textOf(data);
+      } catch (error) {
+        return context.fail(error);
+      }
+      field.readOnly = !context.canEdit();
+      typed.set(text);
+      recount();
+      scrolled();
+    };
+    draw();
+    return { update: draw };
+  },
+  example(host, context) {
+    writeNote(context, `${textOf(context.readJSON("note"))}\n再加一行`);
+  },
+});

package/packs/gallery/note/preview.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 240 120"><rect width="240" height="120" rx="8" fill="#f3f3f1"/><rect x="16.5" y="12.5" width="207" height="95" rx="8" fill="#ffffff" stroke="#e6e6e3"/><rect x="28" y="22" width="10" height="10" rx="3" fill="#efefed"/><rect x="42" y="24.5" width="22" height="5" rx="2.5" fill="#37352f"/><rect x="68" y="24.5" width="18" height="5" rx="2.5" fill="#d4d3cf"/><line x1="28" x2="212" y1="57" y2="57" stroke="#ededeb"/><rect x="28" y="47" width="24" height="6" rx="3" fill="#37352f"/><line x1="28" x2="212" y1="73" y2="73" stroke="#ededeb"/><rect x="28" y="63" width="112" height="6" rx="3" fill="#37352f"/><line x1="28" x2="212" y1="89" y2="89" stroke="#ededeb"/><rect x="28" y="79" width="96" height="6" rx="3" fill="#37352f"/></svg>

package/packs/gallery/note/style.css

@@ -0,0 +1,97 @@
+/* Every selector starts at the instance and goes down a step at a time (>), so that nothing here
+   reaches the rest of the page. The pack's design B, in the kit's card tokens: its head (the chip, a
+   pencil, and 便签, how many characters it holds its quiet meta after it, none on a narrow card), its end
+   clear of the card's grip, and under it the field the script draws, the rest of the note's face: no
+   border and no fill of its own, words half a size larger than the other cards' on wide lines (26px, a
+   faint rule under each, scrolling with them: a hint that it takes writing), its placeholder (写点什么…)
+   faint, the caret the accent's. While the reader types the card is ringed in the accent's wash and a line
+   under the field says its two keys; scrolled down, the field's top fades over 8px. On a custom page it is the card's whole face, taken out over the card's padding so that
+   its ring is the card's edge; where no card is around it (a document, as gallery block check shows it) the
+   instance frames itself, a few lines high. Light and dark. */
+[data-doc-component="gallery/note"] {
+  --gallery-note-rule: light-dark(rgb(55 53 47 / 7.5%), rgb(255 255 255 / 6%));
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  padding: 16px;
+  border-radius: var(--gallery-card-radius);
+  box-shadow: var(--gallery-card-shadow);
+  font-family: var(--gallery-font);
+  font-size: 13px;
+  line-height: 1.5;
+  color: var(--gallery-text);
+  > .gallery-note-head {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    flex: none;
+    height: 20px;
+    min-width: 0;
+    padding-inline-end: var(--gallery-grip-room, 0px);
+  }
+  > .gallery-note-head > .gallery-note-chip {
+    flex: none;
+    display: grid;
+    place-items: center;
+    width: var(--gallery-chip-size);
+    height: var(--gallery-chip-size);
+    border-radius: var(--gallery-chip-radius);
+    background: var(--gallery-fill);
+    color: var(--gallery-muted);
+  }
+  > .gallery-note-head > .gallery-note-chip > svg { display: block; width: var(--gallery-chip-icon); height: var(--gallery-chip-icon); }
+  > .gallery-note-head > .gallery-note-title {
+    min-width: 0;
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+    font-size: var(--gallery-title-size);
+    line-height: var(--gallery-title-line);
+    font-weight: 600;
+    color: var(--gallery-text);
+  }
+  > .gallery-note-head > .gallery-note-meta { flex: none; font-size: var(--gallery-meta-size); color: var(--gallery-faint); white-space: nowrap; font-variant-numeric: tabular-nums; }
+  > .gallery-note-head[data-layout="narrow"] > .gallery-note-meta { display: none; }
+  > .gallery-note-field {
+    display: block;
+    flex: 1 1 auto;
+    box-sizing: border-box;
+    width: 100%;
+    min-height: 104px;
+    margin: 8px 0 0;
+    padding: 0;
+    border: 0;
+    outline: 0;
+    resize: none;
+    background: transparent linear-gradient(to bottom, transparent 25px, var(--gallery-note-rule) 25px, var(--gallery-note-rule) 26px, transparent 26px) 0 0 / 100% 26px local;
+    font: inherit;
+    font-size: 13.5px;
+    line-height: 26px;
+    color: var(--gallery-text);
+    caret-color: var(--gallery-accent);
+    overflow-wrap: break-word;
+    scrollbar-width: none;
+  }
+  > .gallery-note-field[data-scrolled] { mask-image: linear-gradient(to bottom, transparent, #000 8px); }
+  > .gallery-note-head[data-layout="narrow"] ~ .gallery-note-field { font-size: 13px; }
+  > .gallery-note-field::placeholder { color: var(--gallery-faint); opacity: 1; }
+  > .gallery-note-field:read-only { cursor: default; }
+  > .gallery-note-foot { display: none; flex: none; gap: 12px; padding-top: 6px; font-size: 11.5px; line-height: 16px; color: var(--gallery-faint); white-space: nowrap; }
+  > .gallery-note-foot b { font-weight: 600; color: var(--gallery-muted); }
+  > .gallery-note-field:focus:not(:read-only) + .gallery-note-foot { display: flex; }
+  &:has(> .gallery-note-field:focus:not(:read-only)) { box-shadow: var(--gallery-card-shadow), 0 0 0 2px var(--gallery-accent-wash); }
+}
+/* On a custom page the board draws the frame: the note is the card's whole face, out over its padding, its
+   ring (while the reader types) at the card's edge, inside it. */
+.gallery-card > [data-doc-component="gallery/note"] {
+  height: calc(100% + 2 * var(--gallery-card-pad));
+  margin: calc(-1 * var(--gallery-card-pad));
+  padding: var(--gallery-card-pad);
+  box-shadow: none;
+  /* The field as high as whole lines fit under the head (20px and 8px), and over the keys' line (22px) while
+     the reader types, so that a line scrolled to is never cut at the top: on a 4 × 2 card three lines,
+     two while typing. */
+  > .gallery-note-field { flex: none; min-height: 0; height: max(26px, round(down, calc(100% - 28px), 26px)); }
+  > .gallery-note-field:focus:not(:read-only) { height: max(26px, round(down, calc(100% - 50px), 26px)); }
+  &:has(> .gallery-note-field:focus:not(:read-only)) { box-shadow: inset 0 0 0 2px var(--gallery-accent-wash); }
+}

package/packs/gallery/note/template.html

@@ -0,0 +1,3 @@
+<div data-doc-component="gallery/note">
+  <script type="application/json">{"text":""}</script>
+</div>

package/packs/gallery/note/writing.md

@@ -0,0 +1,18 @@
+# 便签 (gallery/note)
+
+A card for a custom page (its places are `page`): a few lines the user types on the card itself, kept in the page. Use it where the user wants to jot something down beside the rest of a page (a reminder, a list for today).
+
+## How to write it
+
+Put it on a custom page as a card of its board, `<section class="gallery-card" data-card-id="…" data-x data-y data-w data-h>`, holding one instance, after `gallery block add note`, the instance as template.html has it: its data part, a `<script type="application/json">` holding `{"text":"…"}` (on one line and compact, as the block writes it back), the note's words, lines apart with `\n`; `{"text":""}` for an empty one, which shows 写点什么.
+
+- Leave the words of a note that is there alone: they are the user's. To start one with words of yours (a list the user asked for), write them in `text`, as example.html does.
+- Sizes: 4 × 2 (the default), 2 × 2 (no count of characters) and 4 × 4 are the ones its menu lists; any height from 2 to 8 cells, 2 to 4 wide, is one too (the card's corner reaches each). Words that do not fit scroll inside the card.
+
+## What the user does
+
+They click the card and type. What they typed is written to the page once they leave the card, or press Ctrl+Enter (⌘Enter on a Mac); Enter alone starts a new line, and Esc puts back what was there. Each write is one step of the page's undo. Nothing is written while a Chinese input method is composing.
+
+## How it looks
+
+In Gallery 风格's look (the kit's card tokens, light and dark): a head of a small gray chip and a title, its end clear of the card's grip; one hero; the rest small and gray; the accent on the data and on today alone. Its head is a pencil's chip, 便签 and how many characters it holds; under it the words, half a size larger than the other cards' on wide 26px lines, each ruled faintly (a hint that it takes writing, not a yellow paper). While the reader types the card is ringed in the accent's wash and a line under the field says the two keys (Ctrl+Enter 保存, Esc 还原; ⌘Enter on a Mac). Empty, it says 写点什么… faintly.

package/packs/gallery/pack.json

@@ -0,0 +1,8 @@
+{
+  "id": "gallery",
+  "name": { "zh": "Gallery 风格", "en": "Gallery style" },
+  "description": { "zh": "Gallery 自己的样子：克制、清楚的首页卡片，以及文档里用的看板、指标、图表、卡片和图表卡。", "en": "Gallery's own look: quiet, clear cards for the home page, and the board, metric, chart, card and chart card for documents." },
+  "version": "1.0.0",
+  "author": "Gallery",
+  "icon": "🗂️"
+}

package/packs/gallery/recent/component.json

@@ -0,0 +1,13 @@
+{
+  "id": "gallery/recent",
+  "apiVersion": 1,
+  "version": "2.0.0",
+  "name": { "zh": "最近编辑", "en": "Recently edited" },
+  "description": { "zh": "最近改过的文档，点一篇就打开它", "en": "The documents edited last: click one to open it" },
+  "words": "zuijinbianji zuijin bianji recent recently edited documents 最近 最近编辑 文档 改过",
+  "parts": {},
+  "runtime": { "generated": [":scope > .gallery-recent-face"] },
+  "places": ["page"],
+  "card": { "sizes": [[4, 4], [4, 2], [4, 6]], "min": { "w": 4, "h": 2 }, "max": { "w": 4, "h": 8 }, "resize": true },
+  "needs": ["workspace"]
+}

package/packs/gallery/recent/example.html

@@ -0,0 +1 @@
+<div data-doc-component="gallery/recent"></div>

package/packs/gallery/recent/kit.js

@@ -0,0 +1,293 @@
+// gallery/recent (最近编辑): the workspace's documents edited last, the last first, read through
+// context.workspace.query("recent") (its manifest's needs hold "workspace"; and "stats", for how many
+// there are in all): each its page icon, its title and when it was edited. A click opens the document
+// (context.workspace.open: the workbench goes there). It reads again whenever the workspace says the list
+// changed (the `data` signal, "recent": a document written, renamed, given another icon, made or gone), and
+// says the times again each minute (the kit's clock). It holds no part and writes nothing: all it shows is
+// drawn (the manifest's `runtime`). Where the workspace cannot be read (an exported file, where it has no
+// server; a server that does not answer) it says so. The words are the page's language (the UI's where
+// Gallery says it, else the page's lang).
+//
+// Its face (the pack's design B, in the kit's card tokens): a head of the chip (a clock), 最近编辑 and how
+// many of them were edited today, its quiet meta (今天 3 篇); then rows like the sidebar's, grouped by
+// when (今天, 昨天, 本周, 更早: `groupOf`), each its icon, its title and its time at its end, said by its
+// group (`whenOf`: today's 12 分钟前, or the hour once an hour has gone, 08:05; yesterday's its hour; this
+// week's its weekday, 周二; earlier ones the date, 11月7日); under them, faint, how many more there are (还有
+// 20 篇). The card shows whole rows only, as many as the room under its head holds with their groups'
+// titles (`fit`, measured again as the card changes size: its own ResizeObserver on the face). A card two
+// cells high (`data-layout` "short", by context.size) lists the last three, no groups, their times as a
+// person says them (昨天, 周二). No document yet: the cards' empty face.
+//
+// A document's icon is drawn as Gallery's sidebar draws it, from the server that shows the page (its icon
+// route, /__gallery/edit/icon, one picture of any icon's value): an emoji or a picture of its folder as a
+// picture, one of Gallery's glyphs as a mask in the muted color, which follows the theme; a document with
+// none a page drawn in its line.
+
+const WORDS = {
+  zh: {
+    title: "最近编辑",
+    empty: ["还没有文档", "新建一篇，或者让 Agent 写一篇"],
+    offline: ["在 Gallery 里打开时显示", "这里会列出最近改过的文档"],
+    failed: ["读不到工作区的文档", "过一会儿会再读"],
+    more: (/** @type {number} */ count) => `还有 ${count} 篇`,
+    today: (/** @type {number} */ count) => `今天 ${count} 篇`,
+    open: (/** @type {string} */ title) => `打开「${title}」`,
+    groups: { today: "今天", yesterday: "昨天", week: "本周", earlier: "更早" },
+    now: "刚刚",
+    minutes: (/** @type {number} */ count) => `${count} 分钟前`,
+    yesterday: "昨天",
+    weekdays: ["周日", "周一", "周二", "周三", "周四", "周五", "周六"],
+    date: (/** @type {Date} */ date, /** @type {boolean} */ thisYear) => (thisYear ? `${date.getMonth() + 1}月${date.getDate()}日` : `${date.getFullYear()}年${date.getMonth() + 1}月${date.getDate()}日`),
+  },
+  en: {
+    title: "Recently edited",
+    empty: ["No documents yet", "Make one, or ask your Agent to write one"],
+    offline: ["Shown when opened in Gallery", "The documents edited last show here"],
+    failed: ["The workspace's documents could not be read", "It reads them again in a while"],
+    more: (/** @type {number} */ count) => `${count} more`,
+    today: (/** @type {number} */ count) => `${count} today`,
+    open: (/** @type {string} */ title) => `Open “${title}”`,
+    groups: { today: "Today", yesterday: "Yesterday", week: "This week", earlier: "Earlier" },
+    now: "just now",
+    minutes: (/** @type {number} */ count) => `${count} min ago`,
+    yesterday: "Yesterday",
+    weekdays: ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"],
+    date: (/** @type {Date} */ date, /** @type {boolean} */ thisYear) => `${["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"][date.getMonth()]} ${date.getDate()}${thisYear ? "" : `, ${date.getFullYear()}`}`,
+  },
+};
+/** The documents it asks for: as many as the tallest card shows, and more. */
+const LIMIT = 50;
+/** A group's title and a row, in px (style.css). */
+const GROUP_HEIGHT = 26;
+const ROW_HEIGHT = 30;
+
+/** The language the page speaks: the UI's where Gallery says it (data-ge-language), else its lang's. */
+function languageOf(/** @type {HTMLElement} */ root) {
+  const ui = root.getAttribute("data-ge-language");
+  return (ui !== null ? ui === "en" : /^en(?:-|$)/i.test(root.lang)) ? "en" : "zh";
+}
+
+/** A local day, as a number of days. @param {Date} date */
+const dayNumber = (date) => Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()) / 86_400_000;
+
+/**
+ * Which group a document edited at `edited` (an ISO time) is in, from `now` (the reader's clock): "today",
+ * "yesterday", "week" (earlier this week, from its Monday) or "earlier".
+ * @param {string} edited
+ * @param {Date} now
+ */
+function groupOf(edited, now) {
+  const then = new Date(edited);
+  const days = dayNumber(now) - dayNumber(then);
+  if (days <= 0) return "today";
+  if (days === 1) return "yesterday";
+  return days <= (now.getDay() + 6) % 7 ? "week" : "earlier";
+}
+
+/**
+ * When `edited` (an ISO time) was, from `now` (the reader's clock), in `language`: within the hour 刚刚
+ * and N 分钟前, then today's hour (08:05); yesterday's hour where its group says yesterday (`grouped`),
+ * else 昨天; a day earlier this week its weekday (周二); else its date, the year said when it is another.
+ * @param {string} edited
+ * @param {Date} now
+ * @param {"zh" | "en"} language
+ * @param {boolean} [grouped]
+ */
+function whenOf(edited, now, language, grouped = true) {
+  const words = WORDS[language];
+  const then = new Date(edited);
+  const minutes = Math.floor((now.getTime() - then.getTime()) / 60_000);
+  if (!Number.isFinite(minutes)) return "";
+  const two = (/** @type {number} */ value) => String(value).padStart(2, "0");
+  const hour = `${two(then.getHours())}:${two(then.getMinutes())}`;
+  const group = groupOf(edited, now);
+  if (group === "today") return minutes < 1 ? words.now : minutes < 60 ? words.minutes(minutes) : hour;
+  if (group === "yesterday") return grouped ? hour : words.yesterday;
+  if (group === "week") return words.weekdays[then.getDay()];
+  return words.date(then, then.getFullYear() === now.getFullYear());
+}
+
+/** What a document's icon is, as Gallery writes its value: a glyph (/icons/…), a picture of its folder (assets/…), an emoji, or none. @param {string | null} value */
+function iconKindOf(value) {
+  if (typeof value !== "string" || !value) return null;
+  if (value.startsWith("/icons/")) return "glyph";
+  if (value.startsWith("assets/")) return "image";
+  return "emoji";
+}
+
+/**
+ * An element of the face, of `kind` (its class).
+ * @template {keyof HTMLElementTagNameMap} K
+ * @param {K} tag
+ * @param {string} kind
+ * @param {string} [text]
+ */
+function made(tag, kind, text) {
+  const node = document.createElement(tag);
+  node.className = `gallery-recent-${kind}`;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+// A document's icon: its picture from the server's icon route, a glyph masked, or none (the page CSS draws).
+function iconFor(/** @type {string} */ slug, /** @type {string | null} */ value) {
+  const kind = iconKindOf(value);
+  const icon = made("span", "icon");
+  if (!kind || value === null) return icon;
+  const address = `/__gallery/edit/icon?value=${encodeURIComponent(value)}&slug=${encodeURIComponent(slug)}`;
+  if (kind === "glyph") {
+    icon.classList.add("gallery-recent-glyph");
+    icon.style.setProperty("--gallery-recent-icon", `url("${address}")`);
+    return icon;
+  }
+  const picture = document.createElement("img");
+  picture.alt = "";
+  picture.src = address;
+  picture.decoding = "async";
+  icon.classList.add("gallery-recent-picture");
+  icon.append(picture);
+  return icon;
+}
+
+DocKit.component({
+  id: "gallery/recent",
+  on: ["data", "clock", "layout"],
+  mount(host, context) {
+    const language = languageOf(document.documentElement);
+    const words = WORDS[language];
+    const face = made("div", "face");
+    const list = made("ul", "list");
+    const head = made("div", "head");
+    const chip = made("span", "chip");
+    chip.setAttribute("aria-hidden", "true");
+    chip.innerHTML = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="8.5"/><path d="M12 7.5V12l3 1.8"/></svg>';
+    // Its quiet meta after the title: how many of the documents were edited today.
+    const meta = made("span", "meta");
+    head.append(chip, made("span", "title", words.title), meta);
+    const more = made("p", "more");
+    more.hidden = true;
+    // No document, or no workspace: the cards' empty face.
+    const empty = made("div", "empty");
+    const emptyPicture = made("span", "empty-picture");
+    emptyPicture.setAttribute("aria-hidden", "true");
+    emptyPicture.innerHTML = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"><path d="M7 3.5h6.5L18 8v11a1.5 1.5 0 0 1-1.5 1.5h-9.5A1.5 1.5 0 0 1 5.5 19V5A1.5 1.5 0 0 1 7 3.5z"/><path d="M13.5 3.5V8H18"/></svg>';
+    const line = made("p", "line");
+    const hint = made("p", "hint");
+    empty.append(emptyPicture, line, hint);
+    empty.hidden = true;
+    face.append(head, list, more, empty);
+    host.append(face);
+    const workspace = context.workspace;
+    if (!workspace) return void context.fail(new Error("its manifest's needs hold \"workspace\": context.workspace is not there"));
+    /** @type {Array<{ slug: string, title: string, icon: string | null, edited: string }> | null} */
+    let documents = null;
+    let total = 0;
+    /** @type {Array<{ node: HTMLElement, edited: string }>} */
+    let times = [];
+    let shown = -1;
+    const short = () => Boolean(context.size && context.size.h <= 2);
+    const say = (/** @type {string[] | null} */ said) => {
+      empty.hidden = said === null;
+      list.hidden = said !== null;
+      if (said === null) return;
+      line.textContent = said[0];
+      hint.textContent = said[1] ?? "";
+    };
+    // Each time said again, only where its words are others; the head's count of today's too.
+    const retime = () => {
+      const now = new Date();
+      for (const { node, edited } of times) {
+        const said = whenOf(edited, now, language, !short());
+        if (node.textContent !== said) node.textContent = said;
+      }
+      const today = (documents ?? []).filter(({ edited }) => groupOf(edited, now) === "today").length;
+      const counted = today > 0 ? words.today(today) : "";
+      if (meta.textContent !== counted) meta.textContent = counted;
+    };
+    // The rows the room under the head holds, whole, with their groups' titles (none on a short card), and
+    // a line of how many more there are: drawn again only when that is another number.
+    const fit = (/** @type {boolean} */ again = false) => {
+      if (!documents) return;
+      const layout = short() ? "short" : "full";
+      face.dataset.layout = layout;
+      const now = new Date();
+      // The room: the face's height under the head and the line of more (none measured where nothing lays it out: every row).
+      const room = face.clientHeight > 0 ? face.clientHeight - head.offsetHeight - (layout === "short" ? 4 : 6) - (layout === "short" ? 0 : 24) : Infinity;
+      let count = 0;
+      if (layout === "short") count = Math.min(3, documents.length);
+      else {
+        let used = 0;
+        let group = "";
+        for (const entry of documents) {
+          const next = groupOf(entry.edited, now);
+          const cost = (next !== group ? GROUP_HEIGHT : 0) + ROW_HEIGHT;
+          if (used + cost > room) break;
+          used += cost;
+          group = next;
+          count++;
+        }
+      }
+      const key = `${layout}:${count}`;
+      if (!again && String(shown) === key) return;
+      shown = /** @type {any} */ (key);
+      times = [];
+      let group = "";
+      list.replaceChildren(...documents.slice(0, count).flatMap((entry) => {
+        const rows = [];
+        const next = groupOf(entry.edited, now);
+        if (layout === "full" && next !== group) {
+          rows.push(made("li", "group", words.groups[/** @type {keyof typeof words.groups} */ (next)]));
+          group = next;
+        }
+        const item = made("li", "item");
+        const button = made("button", "document");
+        button.type = "button";
+        button.title = words.open(entry.title);
+        const when = made("time", "when");
+        when.dateTime = entry.edited;
+        times.push({ node: when, edited: entry.edited });
+        button.append(iconFor(entry.slug, entry.icon), made("span", "name", entry.title), when);
+        button.addEventListener("click", () => workspace.open({ slug: entry.slug }));
+        item.append(button);
+        rows.push(item);
+        return rows;
+      }));
+      const below = Math.max(0, total - count);
+      more.hidden = below === 0 || layout === "short";
+      more.textContent = below > 0 ? words.more(below) : "";
+      retime();
+    };
+    const watch = typeof ResizeObserver === "function" ? new ResizeObserver(() => fit()) : null;
+    watch?.observe(face);
+    context.signal?.addEventListener("abort", () => watch?.disconnect(), { once: true });
+    let asking = 0; // the last read asked: an older answer that comes after it is dropped
+    const read = () => {
+      const ticket = ++asking;
+      const counted = workspace.query("stats").then(({ data }) => data?.documents ?? null, () => null);
+      workspace.query("recent", { limit: LIMIT }).then(async ({ data }) => {
+        const all = await counted;
+        if (ticket !== asking || context.signal.aborted) return;
+        documents = data;
+        total = typeof all === "number" ? Math.max(all, data.length) : data.length;
+        say(data.length === 0 ? words.empty : null);
+        fit(true);
+      }, (/** @type {any} */ error) => {
+        if (ticket !== asking || context.signal.aborted) return;
+        documents = null;
+        times = [];
+        meta.textContent = "";
+        list.replaceChildren();
+        more.hidden = true;
+        say(error?.code === "offline" ? words.offline : words.failed);
+      });
+    };
+    read();
+    return {
+      update(reason, detail) {
+        if (reason === "data" && detail === "recent") read();
+        else if (reason === "clock") retime();
+        else if (reason === "layout") fit();
+      },
+    };
+  },
+});

package/packs/gallery/recent/preview.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 240 120"><rect width="240" height="120" rx="8" fill="#f3f3f1"/><rect x="60.5" y="6.5" width="119" height="107" rx="8" fill="#ffffff" stroke="#e6e6e3"/><rect x="70" y="14" width="10" height="10" rx="3" fill="#efefed"/><rect x="84" y="16.5" width="30" height="5" rx="2.5" fill="#37352f"/><rect x="118" y="16.5" width="16" height="5" rx="2.5" fill="#d4d3cf"/><rect x="70" y="32" width="12" height="4" rx="2" fill="#a6a5a1"/><rect x="70" y="41" width="7" height="7" rx="2" fill="#f6c264"/><rect x="81" y="42" width="52" height="5" rx="2.5" fill="#37352f"/><rect x="158" y="42.5" width="12" height="4" rx="2" fill="#d4d3cf"/><rect x="70" y="54" width="7" height="7" rx="2" fill="#e8a3a3"/><rect x="81" y="55" width="44" height="5" rx="2.5" fill="#37352f"/><rect x="158" y="55.5" width="12" height="4" rx="2" fill="#d4d3cf"/><rect x="70" y="67" width="7" height="7" rx="2" fill="#9fc3ef"/><rect x="81" y="68" width="38" height="5" rx="2.5" fill="#37352f"/><rect x="158" y="68.5" width="12" height="4" rx="2" fill="#d4d3cf"/><rect x="70" y="88" width="7" height="7" rx="2" fill="#b8d79a"/><rect x="81" y="89" width="48" height="5" rx="2.5" fill="#37352f"/><rect x="158" y="89.5" width="12" height="4" rx="2" fill="#d4d3cf"/><rect x="70" y="101" width="7" height="7" rx="2" fill="#c9b3ec"/><rect x="81" y="102" width="36" height="5" rx="2.5" fill="#37352f"/><rect x="158" y="102.5" width="12" height="4" rx="2" fill="#d4d3cf"/><rect x="70" y="79" width="12" height="4" rx="2" fill="#a6a5a1"/></svg>