@heycys/gallery 0.1.1 → 0.1.2

package/browser/shared/extension-sidebar.mjs

@@ -0,0 +1,126 @@
+import { said } from "./i18n/index.mjs";
+import { isExtensionId } from "./outline-shape.mjs";
+import { linkAddress, linkIcon } from "./web-links.mjs";
+
+// The sidebar column an extension provides (docs/workbench.md "Extension columns", references/extensions.md
+// for the Agent that writes one): <workspace>/extensions/<id>/sidebar.json,
+//   { "title": "语雀", "icon": "📗", "entries": [
+//     { "id": "team", "title": "团队知识库", "url": "https://www.yuque.com/team",
+//       "children": [ { "id": "weekly", "title": "周报", "url": "https://www.yuque.com/team/weekly" } ] },
+//     { "id": "panel", "title": "发布面板", "url": "http://127.0.0.1:4318/" } ] }
+// `title` is the column's name (100 characters at most), `icon` an emoji or an icon of the 图标 tab (no
+// picture is ever loaded from the web). An entry has an `id` (1 to 128 of A-Z a-z 0-9 . _ : -, once in
+// the file: the extension keeps it, for it is what an address and an open entry go by), a `title` (200
+// at most), an `url` (http or https, 2048 at most: none, and the entry only holds its `children`, which
+// a click opens and closes), an `icon` and `children` (8 levels, 2000 entries in all, 1 MB the file).
+// Pure and the same wherever it is read (the server answers the workbench with it, gallery extension
+// check prints it); reading the file is ./extensions.mjs's (Node's). What makes the file unusable is a
+// refusal (`error`, said() of a reason: the column then shows one row, 条目读不出来：<reason>); what is
+// only left out of it (an icon that is none) is a note, said by gallery extension check and shown nowhere.
+
+/** The extension's file in its folder. */
+export const SIDEBAR_FILE = "sidebar.json";
+export const SIDEBAR_LIMITS = { bytes: 1_048_576, levels: 8, entries: 2000, id: 128, title: 200, column: 100 };
+export const entryIdPattern = /^[A-Za-z0-9._:-]{1,128}$/;
+
+/** An entry's key in the workbench's address (`#~<extension id>/<entry id>`), and as its row says it. */
+export const extensionKey = (extension, entry) => `~${extension}/${entry}`;
+/** The extension and the entry a key names: { extension, entry }, or null for what is none. */
+export function parseExtensionKey(value) {
+  if (typeof value !== "string" || !value.startsWith("~")) return null;
+  const at = value.indexOf("/");
+  if (at < 0) return null;
+  const extension = value.slice(1, at);
+  const entry = value.slice(at + 1);
+  return isExtensionId(extension) && entryIdPattern.test(entry) ? { extension, entry } : null;
+}
+
+const tidy = (value) => (typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "");
+const refused = (message) => ({ error: message });
+
+/**
+ * What the text of a sidebar.json says: { sidebar: { title, icon?, entries, count }, notes } with each
+ * entry { id, title, icon?, url?, children? } (the address as the URL spells it, a title's white space
+ * run together), or { error } (said(): why the file is no sidebar), the first reason found. `notes`: said()
+ * of what was left out (an icon that is no emoji nor icon of the 图标 tab).
+ */
+export function readSidebarText(text) {
+  const source = String(text);
+  if (source.length > SIDEBAR_LIMITS.bytes) return refused(said("文件超过 1MB"));
+  let value;
+  try {
+    value = JSON.parse(source.replace(/^/, ""));
+  } catch (error) {
+    return refused(said("不是 JSON：{0}", error.message));
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) return refused(said("最外层要是一个对象，有 title 和 entries"));
+  const title = tidy(value.title);
+  if (!title || title.length > SIDEBAR_LIMITS.column) return refused(said("title 要有，是栏的名字（100 个字以内）"));
+  if (!Array.isArray(value.entries)) return refused(said("entries 要是一个列表"));
+  const notes = [];
+  let icon;
+  if (value.icon !== undefined && value.icon !== null && value.icon !== "") {
+    if (linkIcon(value.icon)) icon = value.icon;
+    else notes.push(said("icon 不是表情，也不是图标页签里的图标，没有显示"));
+  }
+  const ids = new Set();
+  let count = 0;
+  const walk = (list, path, level) => {
+    if (level > SIDEBAR_LIMITS.levels && list.length) return { error: said("条目超过 {0} 层（{1}）", SIDEBAR_LIMITS.levels, path) };
+    const made = [];
+    for (const [index, raw] of list.entries()) {
+      const where = `${path}[${index}]`;
+      if (++count > SIDEBAR_LIMITS.entries) return { error: said("条目超过 {0} 个", SIDEBAR_LIMITS.entries) };
+      if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { error: said("{0} 要是一个对象", where) };
+      if (typeof raw.id !== "string" || !entryIdPattern.test(raw.id)) return { error: said("{0} 的 id 不对（1 到 128 个字符，只能用字母、数字和 . _ : -）", where) };
+      if (ids.has(raw.id)) return { error: said("{0} 的 id「{1}」重复了（同一个文件里 id 不能重）", where, raw.id) };
+      ids.add(raw.id);
+      const name = tidy(raw.title);
+      if (!name || name.length > SIDEBAR_LIMITS.title) return { error: said("{0} 要有 title（名称，200 个字以内）", where) };
+      const entry = { id: raw.id, title: name };
+      if (raw.url !== undefined && raw.url !== null && raw.url !== "") {
+        const address = linkAddress(raw.url);
+        if (address.refused === "scheme") return { error: said("{0} 的 url 只能是 http 或 https 的网址", where) };
+        if (address.refused === "long") return { error: said("{0} 的 url 太长了（最多 2048 个字符）", where) };
+        if (address.refused) return { error: said("{0} 的 url 不是一个网址", where) };
+        entry.url = address.url;
+      }
+      if (raw.icon !== undefined && raw.icon !== null && raw.icon !== "") {
+        if (linkIcon(raw.icon)) entry.icon = raw.icon;
+        else notes.push(said("{0} 的 icon 不是表情，也不是图标页签里的图标，没有显示", where));
+      }
+      if (raw.children !== undefined && raw.children !== null) {
+        if (!Array.isArray(raw.children)) return { error: said("{0} 的 children 要是一个列表", where) };
+        const inner = walk(raw.children, `${where}.children`, level + 1);
+        if (inner.error) return inner;
+        if (inner.entries.length) entry.children = inner.entries;
+      }
+      made.push(entry);
+    }
+    return { entries: made };
+  };
+  const walked = walk(value.entries, "entries", 1);
+  if (walked.error) return refused(walked.error);
+  return { sidebar: { title, ...(icon ? { icon } : {}), entries: walked.entries, count }, notes };
+}
+
+/** The entry `id` of `entries` (a tree: children under each), or null. */
+export function entryIn(entries, id) {
+  for (const entry of entries ?? []) {
+    if (entry.id === id) return entry;
+    const inside = entryIn(entry.children, id);
+    if (inside) return inside;
+  }
+  return null;
+}
+
+/**
+ * The entry key `key` (`~<extension id>/<entry id>`, a workbench's hash, decoded) names among `extensions`
+ * (the columns as GET outline lists them: [{ id, entries }]), or null: what a link to an entry's address
+ * opens (one with an `url`) wherever a page reads it (the workbench, a page alone in a tab, 演示视图).
+ */
+export function entryOfKey(extensions, key) {
+  const named = parseExtensionKey(key);
+  const extension = named && (extensions ?? []).find(({ id }) => id === named.extension);
+  return extension ? entryIn(extension.entries, named.entry) : null;
+}

package/browser/shared/extensions.mjs

@@ -0,0 +1,79 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { SIDEBAR_FILE, SIDEBAR_LIMITS, readSidebarText } from "./extension-sidebar.mjs";
+import { said } from "./i18n/index.mjs";
+import { isExtensionId } from "./outline-shape.mjs";
+import { DOCUMENT_FOLDERS, layoutOf } from "./workspace.mjs";
+
+// The extensions of a workspace (docs/workbench.md "Extension columns"): each a folder
+// <workspace>/extensions/<id>/ whose sidebar.json (./extension-sidebar.mjs) gives a column of the sidebar
+// its entries; what else the folder holds (the extension's own server, its code) is none of Gallery's.
+// Read from disk each time it is asked (the workbench's list, the outline's columns, gallery extension):
+// the extension writes the file, the watcher tells the workbench (src/server/routes.mjs changeOf), no
+// state is kept here. Node's built-ins only.
+
+/**
+ * The folders of extensions/ that may be an extension, sorted: no dot name, a name that is an id
+ * (isExtensionId), not assets or materials (a document called extensions, made before they came, keeps those
+ * in its folder), and no link, which leads out of the workspace. [{ id, folder }].
+ */
+export async function extensionFolders(root) {
+  const { extensions } = layoutOf(root);
+  const entries = await fs.readdir(extensions, { withFileTypes: true }).catch(() => []);
+  return entries
+    .filter((entry) => entry.isDirectory() && isExtensionId(entry.name) && !DOCUMENT_FOLDERS.includes(entry.name))
+    .map((entry) => ({ id: entry.name, folder: path.join(extensions, entry.name) }))
+    .sort((a, b) => (a.id < b.id ? -1 : 1));
+}
+
+/** The ids of the extensions that have a sidebar.json (the columns the sidebar has), sorted. */
+export async function extensionColumnIds(root) {
+  const found = await Promise.all((await extensionFolders(root)).map(async ({ id, folder }) => ((await fs.stat(path.join(folder, SIDEBAR_FILE)).then(() => true, () => false)) ? id : null)));
+  return found.filter(Boolean);
+}
+
+/**
+ * Extension `id` as the sidebar shows it: { id, file (the sidebar.json's path), title (the column's name; the
+ * id when the file does not say one), icon?, entries (a tree of { id, title, icon?, url?, children? }), count
+ * (the entries in all), notes (said(): what was left out) } or, when the file is not usable, `error`
+ * (said(): why) with no entries; `missing` for a folder with no sidebar.json: an extension with nothing to show.
+ */
+export async function readExtension(root, id) {
+  const file = path.join(layoutOf(root).extensions, id, SIDEBAR_FILE);
+  const empty = { id, file, title: id, entries: [], count: 0, notes: [] };
+  let stat;
+  try {
+    stat = await fs.stat(file);
+  } catch (error) {
+    return error.code === "ENOENT" ? { ...empty, missing: true, error: said("没有 sidebar.json") } : { ...empty, error: said("读不出这个文件：{0}", error.code ?? "error") };
+  }
+  if (!stat.isFile()) return { ...empty, error: said("sidebar.json 不是一个文件") };
+  if (stat.size > SIDEBAR_LIMITS.bytes) return { ...empty, error: said("文件超过 1MB") };
+  let text;
+  try {
+    text = await fs.readFile(file, "utf8");
+  } catch (error) {
+    return { ...empty, error: said("读不出这个文件：{0}", error.code ?? "error") };
+  }
+  const read = readSidebarText(text);
+  if (read.error) {
+    // What can still be said of a file that does not read: its name, when it has one.
+    let title = id;
+    try {
+      const named = JSON.parse(text.replace(/^/, ""))?.title;
+      if (typeof named === "string" && named.trim() && named.trim().length <= SIDEBAR_LIMITS.column) title = named.replace(/\s+/g, " ").trim();
+    } catch {}
+    return { ...empty, title, error: read.error };
+  }
+  return { ...empty, ...read.sidebar, notes: read.notes };
+}
+
+/**
+ * The extensions of workspace `root`, by id: those with a sidebar.json (the sidebar's columns), or with `all`
+ * every folder that may be one (gallery extension list). Each as readExtension says it.
+ */
+export async function listExtensions(root, { all = false } = {}) {
+  const folders = await extensionFolders(root);
+  const read = await Promise.all(folders.map(({ id }) => readExtension(root, id)));
+  return all ? read : read.filter((extension) => !extension.missing);
+}

package/browser/shared/file-table.mjs

@@ -0,0 +1,101 @@
+import { parse } from "parse5";
+import { BODY } from "./components/index.mjs";
+import { attr, elementsOf, walk } from "./html-tree.mjs";
+import { decoded, pageAddress } from "./page-address.mjs";
+import { CHART_SOURCE, cellWords, tableRows } from "./table-chart.mjs";
+
+// A table of a document's file read as the kit reads it on a page (render/kit/runtime/table-reading.js:
+// a chart drawn from a table, a view's context.table(), a package's context.rows): its header's words and
+// data-sort-type, its rows of data in the file's order, each cell's words and sort value
+// (shared/table-chart.mjs), whether a cell spans others; and, by a key (data-doc-chart-source on its
+// frame), its rows as a block reads them, { values, links }. The checks read a chart's table so
+// (render/chart-declarations.mjs), and the workspace's facts a table another document names
+// (workspace.query("table"): src/workbench/index.mjs, the plan's 5.2). Of parse5's tree; no DOM.
+
+const textOf = (node) => (node.nodeName === "#text" ? node.value : (node.childNodes ?? []).map(textOf).join(""));
+const cellsOf = (row) => elementsOf(row).filter((cell) => cell.tagName === "td" || cell.tagName === "th");
+const spans = (cell) => ["rowspan", "colspan"].some((name) => {
+  const value = Number.parseInt(attr(cell, name) ?? "1", 10);
+  return Number.isFinite(value) && value !== 1;
+});
+
+// Its groups, its header row (its head's first row, else a first row of its body all header cells; null
+// for neither) and its body's rows after that, never a <tfoot>'s.
+function tableParts(table) {
+  const groups = elementsOf(table);
+  const rowsOf = (group) => elementsOf(group).filter((row) => row.tagName === "tr");
+  const head = groups.find((group) => group.tagName === "thead");
+  let header = head ? rowsOf(head)[0] ?? null : null;
+  let rows = groups.filter((group) => group.tagName === "tbody").flatMap(rowsOf);
+  if (!header && rows.length > 0 && cellsOf(rows[0]).length > 0 && cellsOf(rows[0]).every((cell) => cell.tagName === "th")) [header, ...rows] = rows;
+  return { groups, rowsOf, header, rows };
+}
+
+/**
+ * What a table of the file holds for a chart (tableRows' `table`), as the kit reads it in the page
+ * (charts/from-table.js tableCells): its header row's words (its head's first row, else a first row
+ * of header cells alone; null for neither) and its header cells' data-sort-type, its rows of data,
+ * each cell's words and sort value (data-sort-value, or null), the first words of its <tfoot>'s rows
+ * (`foot`, which no chart reads: the readings say they were left out), and whether a cell of them
+ * spans rows or columns (a cell's words cellWords', a formula's its TeX).
+ */
+export function tableCells(table) {
+  const { groups, rowsOf, header, rows } = tableParts(table);
+  const words = (cell) => cellWords(textOf(cell));
+  return {
+    names: header ? cellsOf(header).map(words) : null,
+    types: header ? cellsOf(header).map((cell) => attr(cell, "data-sort-type") ?? null) : null,
+    rows: rows.map((row) => cellsOf(row).map((cell) => ({ words: words(cell), sort: attr(cell, "data-sort-value")?.trim() ?? null }))),
+    foot: groups.filter((group) => group.tagName === "tfoot").flatMap(rowsOf).map((row) => (cellsOf(row)[0] ? words(cellsOf(row)[0]) : "")),
+    merged: [header, ...rows].some((row) => row && cellsOf(row).some(spans)),
+  };
+}
+
+// The links a row's cells hold to documents of the workspace, as a file writes them (shared/page-address.mjs):
+// another's ../<slug>/doc.html, with #<block id> for a block, and #<block id> for one of this document (`own`).
+function linksOf(row, own) {
+  const links = [];
+  walk(row, (node) => {
+    if (node.tagName !== "a") return;
+    const href = (attr(node, "href") ?? "").trim();
+    if (!href) return;
+    const place = href.startsWith("#") && href.length > 1 ? (own ? { slug: own, block: decoded(href.slice(1)) } : null) : pageAddress(href);
+    if (place) links.push({ slug: place.slug, title: cellWords(textOf(node)), block: place.block ?? null });
+  });
+  return links;
+}
+
+/**
+ * The table of a document's `text` (its page's HTML, as its pages see it) that `key` names, the first
+ * frame carrying it as data-doc-chart-source (the one the kit and gallery check read; none a <template>
+ * holds, nor the own region of an instance), its rows as a block reads them: { columns, rows: [{ values,
+ * links, words }] }, `values` by the header's words (cellValue: a number, its words or null; of two names
+ * alike the later column's), `links` those its cells hold to documents (`own`: the document's slug, which
+ * a link within it names), `words` each column's words as written (what a filter matches); or { error }:
+ * "missing" (no table carries it) or "merged" (a cell spans others: a value has one cell).
+ */
+export function keyedTable(text, key, own = null) {
+  let table = null;
+  walk(parse(String(text)), (node) => {
+    if (table !== null || attr(node, CHART_SOURCE) !== key) return;
+    table = node.tagName === "table" ? node : elementsOf(node).find((child) => child.tagName === "table") ?? false;
+  }, { ...BODY, inTemplates: false });
+  if (!table) return { error: "missing" };
+  const cells = tableCells(table);
+  const read = tableRows(cells);
+  if (read.error) return { error: "merged" };
+  const { header, rows } = tableParts(table);
+  const dataRows = header ? rows : rows.slice(1);
+  const dataCells = cells.names ? cells.rows : cells.rows.slice(1);
+  const names = read.data.columns;
+  return {
+    columns: [...names],
+    rows: read.data.map((values, at) => {
+      const words = {};
+      names.forEach((name, column) => {
+        words[name] = dataCells[at][column]?.words ?? "";
+      });
+      return { values: { ...values }, links: linksOf(dataRows[at], own), words };
+    }),
+  };
+}