@heycys/gallery 0.1.1 → 0.2.0

package/browser/shared/component-source.mjs

@@ -0,0 +1,39 @@
+// What a component that hears `source` hears of attributes (src/render/kit/runtime/kernel.js;
+// docs/render.md "A custom block on a page"): a change of an attribute in a part or a slot that says
+// something of the file, and of a class only where a look class changes, so that what the kit and the
+// editor toggle as they lay the page out is no change of the file's.
+
+import { COLOR_NAMES } from "./colors.mjs";
+
+/**
+ * The attributes that say something of the file in a part or a slot, which a component hearing
+ * `source` hears change (runtime/kernel.js): a to-do item checked, a cell's spans, what a table's
+ * header and cells say of its sort (the table description's data-sort-*, listed one by one, as an
+ * observer takes them). A class is one only where a look class changes (lookChanged); `hidden` and
+ * `open` are the reader's, which `reveal` tells.
+ */
+export const SOURCE_ATTRIBUTES = ["data-checked", "rowspan", "colspan", "data-sort-status", "data-sort-type", "data-sort-key", "data-sort-default", "data-sort-ignore", "data-sort-value", "data-sort-rank"];
+
+/**
+ * The classes that are a block's or a cell's look, which a reader sets and the file keeps: a text color
+ * or a fill (doc-text-<color>, doc-highlight-<color>), a text block's alignment and indent (a table's frame's alignment is the same two classes), a cell's alignments and its bold (table.mjs's
+ * CELL_ALIGN_CLASSES, CELL_VALIGN_CLASSES, CELL_BOLD_CLASS, the editor's CELL_LOOKS). What the kit and
+ * the editor toggle as they lay a page out (a table's number and doc-table--auto, a code block's
+ * folds) is none, so that no component hears its own layout as a change of the file, and draws again
+ * for ever.
+ */
+export const LOOK_CLASSES = new Set([
+  ...COLOR_NAMES.flatMap((name) => [`doc-text-${name}`, `doc-highlight-${name}`]),
+  // table.mjs's CELL_ALIGN_CLASSES, CELL_VALIGN_CLASSES and CELL_BOLD_CLASS, written out: an import of that
+  // file would bring its description, prose and all, into the kit's runtime (tests/unit/installed.mjs
+  // holds the two lists together).
+  "doc-align-left", "doc-align-center", "doc-align-right", "doc-valign-top", "doc-valign-middle", "doc-valign-bottom", "doc-bold",
+  // A paragraph's or a heading's indent (the editor's components/align.mjs INDENTS; its alignment is a cell's classes above).
+  ...Array.from({ length: 8 }, (_, index) => `doc-indent-${index + 1}`),
+]);
+
+/** Whether a class attribute's look classes (LOOK_CLASSES) differ from `before` to `after`, either null for none. */
+export function lookChanged(before, after) {
+  const looks = (value) => [...new Set(String(value ?? "").split(/\s+/).filter((name) => LOOK_CLASSES.has(name)))].sort().join(" ");
+  return looks(before) !== looks(after);
+}

package/browser/shared/components/heading.mjs

@@ -1,4 +1,5 @@
-// A heading, levels 1 to 4 (the fourth body-sized): a basic block.
+// A heading, levels 1 to 4 (the fourth body-sized): a basic block. Aligned and indented as a paragraph
+// is (paragraph.mjs TEXT_ALIGN_CLASSES, described there and by the table).
 export default {
   id: "heading",
   category: "block",

package/browser/shared/components/index.mjs

@@ -137,9 +137,16 @@ export const EVENTS = {
   "doc-theme-request": "a workbench asks for a theme (ui.js listens)",
   "doc-look-request": "the document's look is asked of the page (字体与布局: the page's session for the workbench, the preview's live reload for doc.json written again; ui.js puts it on <html>, src/shared/document-look.mjs)",
   "doc-look-change": "the look the page shows changed (ui.js): the page editor's session tells the workbench",
-  "doc-layout-change": "a card's size changed where widths do not tell (the editor), or the document's look changed (ui.js)",
+  "doc-layout-change": "a card's size changed where widths do not tell (the editor, a custom page's canvas), or the document's look changed (ui.js)",
+  "doc-workspace-change": "what the workspace holds changed, the kind its detail (the page's live script, as the server's \"data <kind>\" says it): the kit tells the instances that hear data and read that kind",
+  "doc-todo-set": "a block's context.workspace.setTodo asks whoever shows the page to check a to-do of a document (cancelable: a custom page's board or a document's editor cancels it and answers from the workspace's service)",
+  "doc-open-request": "a block's context.workspace.open asks to open a document or a custom page (cancelable: the page's session for the workbench answers it, else the kit goes there)",
   "doc-editable": "the page takes what a component writes from now on (the editor)",
   "doc-component-edit": "a component's context.edit asks to write a part: the editor cancels it to say it took the edit, the kit writing no file (on the instance)",
+  "doc-table-intent": "a view's context.table() asks to change the table it reads (set a cell, move, add or take out a row), or whether it would take such a change now (canEdit, op check): the editor cancels it to say it made the change (or would), one undo step, the kit writing nothing (on the instance)",
+  "doc-settings-changed": "what gallery.json says of the components changed (the page's event stream, its settings line: hidden, disabled, shown, the consents to the net, unlisted and the packs off): the editor's menus follow it, and the kit starts again an instance whose block's consent changed (runtime/net.js)",
+  "doc-net-fetch": "a block's context.fetch asks whoever serves the page to fetch for it (runtime/net.js sends it; the server's live script cancels it and answers from its net route)",
+  "doc-net-consent": "a block's 允许访问 asks the reader to let it online (runtime/net.js sends it; the page's session cancels it and the workbench opens its consent dialog)",
   "doc-export-copy-done": "导出当前视图副本 finished (ui.js)",
   "doc-table-sort": "a table's sort changed (tables/, on the table)",
   "doc-jump-request": "演示视图 asks the kit to go to a block of its own page, a step of the history (runtime/reveal.js listens, editor/page/present-links.mjs sends)",
@@ -171,9 +178,11 @@ export const FLOW_BLOCKS = `${FLOWS.join(", ")}, :is(${GROUPING_FLOWS.join(", ")
  * What the kit's runtime reads of the descriptions (runtime/kernel.js): where each component's
  * instances are (`match`) and what it leaves on the page (`runtime`), of the components that say
  * either. /kit/runtime.js carries these alone (assets.mjs, `define`), so an export holds no prose.
- * A field the kernel starts reading is added to RUNTIME_FIELDS (tests/unit/runtime.mjs checks it).
+ * A field the kernel starts reading is added to RUNTIME_FIELDS (tests/unit/runtime.mjs checks it):
+ * `needs`, what a custom block uses (its context.workspace), which only a package describes (no
+ * component of the kit has it, so the runtime carries none).
  */
-export const RUNTIME_FIELDS = ["match", "runtime", "schema"];
+export const RUNTIME_FIELDS = ["match", "runtime", "schema", "needs"];
 export const runtimeDescriptions = (components = COMPONENTS) => components
   .filter((component) => RUNTIME_FIELDS.some((field) => component[field] !== undefined))
   .map((component) => Object.fromEntries([["id", component.id], ...RUNTIME_FIELDS.filter((field) => component[field] !== undefined).map((field) => [field, component[field]])]));

package/browser/shared/components/installed.mjs

@@ -50,6 +50,19 @@ export function heldBy(node) {
   return owner !== null && edgeAround(edge) === owner ? null : owner;
 }
 
+/**
+ * The region what an element holds stands in (its children, its words): the instance itself for an
+ * instance, the document's (null) inside a slot that opens it again, and otherwise the region the
+ * element stands in, as heldBy says it. heldBy for a child the element does not have yet, or has lost:
+ * where a change of what it holds happened.
+ */
+export function heldWithin(element) {
+  if (!element.matches(REGION)) return heldBy(element);
+  const owner = heldBy(element);
+  if (element.matches(INSTANCE)) return owner ?? element;
+  return owner !== null && edgeAround(element) === owner ? null : owner;
+}
+
 /** Whether an element is a slot that opens the document's region again: one of an instance that stands in the document's. */
 const opensDocument = (node) => node.matches(SLOT_PART) && heldBy(node) !== null && edgeAround(node) === heldBy(node);
 
@@ -110,8 +123,24 @@ export const PACKAGE_MARK = "data-doc-package";
  */
 export const ARRIVING = "data-ge-arriving";
 
-/** What gallery.json's lists make of a package that loads: "disabled", "hidden" or "normal". */
-export const settingState = (id, { hidden, disabled }) => (disabled.includes(id) ? "disabled" : hidden.includes(id) ? "hidden" : "normal");
+/**
+ * Whether the document's insert entries ("/", 在下方新建, the handle's grid) offer the
+ * block `id` whose manifest's `places` are those (left out: ["document"]), by gallery.json's lists
+ * (`settings`: hidden, shown, disabled, unlisted, packsOff, each left out for none): one that says it stands in a
+ * document is offered unless hidden; one that does not, only where shown; one disabled never, as it does
+ * not load, nor one unlisted (设置 › 组件列表's master switch off: no menu and no library offers it, what
+ * is written of it shows as ever), nor one of a pack switched off (packsOff, the ids of the packs off: the
+ * scope of its id; the same as unlisted, for a whole pack). The one rule, which the server and the page
+ * both run (notes/plans/custom-blocks-spec-2026-11-07.md section 2, block-packs-plan-2026-11-09.md §1).
+ */
+export function inDocumentMenus(places, settings, id) {
+  const { hidden = [], shown = [], disabled = [], unlisted = [], packsOff = [] } = settings ?? {};
+  if (disabled.includes(id) || unlisted.includes(id) || packsOff.includes(String(id).split("/")[0])) return false;
+  return (places ?? ["document"]).includes("document") ? !hidden.includes(id) : shown.includes(id);
+}
+
+/** What gallery.json's lists make of a package that loads, its manifest's `places` with them: "disabled", "hidden" (no document's menu offers it: inDocumentMenus, which a block unlisted is too) or "normal". */
+export const settingState = (id, settings, places) => (settings.disabled.includes(id) ? "disabled" : inDocumentMenus(places, settings, id) ? "normal" : "hidden");
 
 /** The class of the kit's note in such an instance, in a preview alone. */
 export const NOTE = "doc-component-note";
@@ -223,10 +252,13 @@ export default {
     "data-doc-component": "the package an instance is of: <scope>/<name>, on a block-level div or section",
     "data-doc-schema": "the shape an instance holds its content in: a whole number its component chooses, read-only past its manifest's schema",
     "data-doc-slot": "a slot of an instance: the part of its manifest edited as flow, by name, on a block-level div or section in the instance's own region; what it holds is the document's blocks",
+    "data-doc-from": "on an instance of a custom block whose needs hold tables: the key of the table it is a view of, which the table's frame carries as data-doc-chart-source",
   },
   runtime: {
     generated: [".doc-component-note", ".doc-component-data"],
     attrs: { "[data-doc-fallback]": ["data-doc-fallback"], "[data-doc-fallback-control]": ["data-doc-fallback-control", "inert"] },
-    internal: [PACKAGE_MARK, "doc-component-more", DATA_ONE, DATA_LINE, DATA_SHORT], // of what the kit drew of a script of data: a line saying what it left out, and its marks
+    // Of what the kit drew of a script of data: a line saying what it left out, and its marks; and the mark
+    // DocKit.drag (runtime/gestures.js) puts on what a component draws while it is dragged, a class.
+    internal: [PACKAGE_MARK, "doc-component-more", DATA_ONE, DATA_LINE, DATA_SHORT, "doc-dragging"],
   },
 };

package/browser/shared/components/page.mjs

@@ -15,10 +15,12 @@ export function pageLanguage(html) {
 
 /**
  * A document's look on its <html> (字体与布局: its doc.json's look, which the render puts on and the kit's
- * tokens read; src/shared/document-look.mjs), the attribute of each choice. The width's is
- * data-doc-measure (a column's measure, its line length): data-doc-width is the reader's own 全宽.
+ * tokens read; src/shared/document-look.mjs), the attribute of each choice. The 正文宽度's is
+ * data-doc-measure (a column's measure, its line length); 全宽 (the top bar's 更多, under 目录) is
+ * data-doc-width="full", the one attribute the kit's page, the editor's room and the display menu's
+ * 全宽显示 (the reader's own switch in an export) all read: one way to be wide, not two.
  */
-export const LOOK_ATTRIBUTES = Object.freeze({ font: "data-doc-font", size: "data-doc-size", spacing: "data-doc-spacing", width: "data-doc-measure" });
+export const LOOK_ATTRIBUTES = Object.freeze({ font: "data-doc-font", size: "data-doc-size", spacing: "data-doc-spacing", width: "data-doc-measure", full: "data-doc-width" });
 
 export default {
   id: "page",
@@ -37,10 +39,20 @@ export default {
   classes: ["doc-page", "doc-header", "doc-kicker", "doc-title", "doc-button"],
   runtime: {
     generated: [".doc-display", "script[data-doc-state]"],
-    root: { attrs: ["data-doc-ready", "data-doc-drawn", "data-doc-controls"] },
-    // The reader's theme and width (ui.js), and the document's look (字体与布局: its doc.json's, put on by
-    // the render, src/shared/document-look.mjs), which a copy of the view keeps; never written in doc.html.
-    state: { html: ["data-doc-theme", "data-doc-width", ...Object.values(LOOK_ATTRIBUTES)] },
-    internal: ["doc-display*", "data-doc-export-copy", "data-theme", "doc-export-id", "doc-reveal", "doc-kit-error"],
+    // data-doc-effective-theme: the theme the page shows now (ui.js), "light" or "dark", which a custom page's own colors go by.
+    // data-doc-platform: "mac" on an Apple platform (runtime/index.js sets it as the page opens), the text's color and smoothing go by it; a copy of the view lets it go, its reader's machine judges anew.
+    root: { attrs: ["data-doc-ready", "data-doc-drawn", "data-doc-controls", "data-doc-effective-theme", "data-doc-platform"] },
+    // The reader's theme (ui.js) and the document's look (字体与布局 and 全宽: its doc.json's, put on by
+    // the render, src/shared/document-look.mjs; the reader's own 全宽显示 is the same data-doc-width), which
+    // a copy of the view keeps; never written in doc.html.
+    state: { html: ["data-doc-theme", ...Object.values(LOOK_ATTRIBUTES)] },
+    internal: ["doc-display*", "data-doc-export-copy", "data-theme", "doc-export-id", "doc-reveal", "doc-kit-error", "doc-net-consent*", "data-doc-snapshot",
+      // A consent bar on a card under 240px of content (runtime/net.js), its line over its button.
+      "data-doc-net-narrow",
+      // The time an export's snapshot was made (its data-doc-snapshot tag's: render/net-snapshot.mjs), which context.workspace.query answers as `at`.
+      "data-at",
+      // A custom page's (no document's: src/render/page-html.mjs, the kit's board/): its cards' cells, the Agent's
+      // (data-x, data-y, data-w, data-h), and its boards' columns now (data-columns, board.js's).
+      "data-x", "data-y", "data-w", "data-h", "data-columns"],
   },
 };

package/browser/shared/components/paragraph.mjs

@@ -1,9 +1,16 @@
 // A paragraph (文本), or small text (小字, p.doc-note): a basic block. Small text may end in a part at
 // the line's right end (span.doc-tab: the page editor's Tab).
+
+/**
+ * A paragraph's or a heading's alignment and indent (the page editor's 对齐与缩进): centred or at the
+ * right (left is neither), moved in by levels of two body characters (styles/flow.css).
+ */
+export const TEXT_ALIGN_CLASSES = ["doc-align-center", "doc-align-right", ...Array.from({ length: 8 }, (_, index) => `doc-indent-${index + 1}`)];
+
 export default {
   id: "paragraph",
   category: "block",
   match: "p",
   tail: ".doc-tab", // small text's end part, a span at the line's right end
-  classes: ["doc-note", "doc-tab"],
+  classes: ["doc-note", "doc-tab", ...TEXT_ALIGN_CLASSES.filter((name) => name.startsWith("doc-indent-"))], // the alignments are the table's (a cell's), the same classes
 };

package/browser/shared/components/state.mjs

@@ -2,7 +2,9 @@
 // a key (data-doc-bind), elements shown for a key's value (data-doc-show),
 // keys forgotten when the page is left (data-doc-transient); and the kit's styles of such
 // controls (styles/state.css). A filter (.doc-filter) is one block: its row of buttons and what
-// they filter below it (a list, say), together.
+// they filter below it (a list, say), together. A <select> of any control or block, bound or not, opens
+// the kit's menu of choices (runtime/choice.js, styles/choice.css), never the browser's popup: a card at
+// the end of <body> while it is open, nothing an author writes, which an export of the view leaves out.
 export default {
   id: "state",
   match: "[data-doc-bind], [data-doc-show]",
@@ -14,7 +16,9 @@ export default {
   classes: ["doc-state-fields", "doc-state-field", "doc-state-actions", "doc-filter", "doc-filter-row", "doc-filter-button", "doc-state-list"],
   wholes: ["doc-filter", "doc-filter-row", "doc-state-fields", "doc-state-list"], // the classes above that are a whole block of their own (the others are parts inside one)
   runtime: {
+    generated: [".doc-choice"],
     attrs: { "[data-doc-show]": ["hidden"] },
     state: { "button[data-doc-bind]": ["aria-pressed"] },
+    internal: ["doc-choice-*"], // the menu's rows, their words, the check and the group headings
   },
 };

package/browser/shared/components/table.mjs

@@ -30,6 +30,7 @@ export default {
     "data-number-columns": "off: no column read as numbers (none centered, none sortable by number), on the table or its frame",
     "data-doc-chart-source": "on its frame: the key a chart drawn from it reads it by (data-doc-chart-data on the chart's host)",
   },
+  // The frame may be placed centred or at the right (doc-align-center, doc-align-right, a text block's: the page editor's 对齐 ›).
   // A cell may also be given a text color or a fill (doc-text-*, doc-highlight-*: text.mjs), an alignment, a vertical one and bold
   // (doc-bold); a header row's cell's look is doc-bold doc-highlight-gray, as the page editor gives it (a header column's th scope="row" none).
   classes: ["doc-table", "doc-table-wrap", "doc-table-meta", "doc-table--sticky-first", ...CELL_ALIGN_CLASSES, ...CELL_VALIGN_CLASSES, CELL_BOLD_CLASS],

package/browser/shared/document-look.mjs

@@ -1,13 +1,15 @@
-// A document's look (字体与布局, under the workbench's 更多: Notion's page format, notion-lite's
-// view/frame/page-format.js): its font, the size of its text, the spacing of its lines and blocks and
-// the width of its reading column. The document's own, as Notion keeps it on the page: `look` in its
+// A document's look (字体与布局 and 全宽, under the workbench's 更多: Notion's page format, notion-lite's
+// view/frame/page-format.js, whose page_full_width is a field of the page as ours is of the document):
+// its font, the size of its text, the spacing of its lines and blocks, the width of its reading column
+// and whether it is shown at the full width of the page whatever that is (全宽). The document's own, as
+// Notion keeps it on the page: `look` in its
 // doc.json (report.json in a document made before Gallery 0.1), over the workspace's default look,
 // `look` in its gallery.json (which the card's 应用到全部文档 writes, every document's own taken away:
 // ./workspace-look.mjs), choice by choice (effectiveLook). The workspace's keeps each choice that is
 // not the default, the field gone when none is; a doc.json each choice that is not the workspace's,
 // the field gone when none is:
 //
-//   "look": { "font": "serif" | "mixed", "size": "small" | "large", "spacing": "compact" | "loose", "width": "narrow" | "wide" }
+//   "look": { "font": "serif" | "mixed", "size": "small" | "large", "spacing": "compact" | "loose", "width": "narrow" | "wide", "full": "full" }
 //
 // A doc.json may say a default too ("font": "sans", "size": "default"…): 默认 chosen on a page while
 // the workspace's default says otherwise. The look a document shows is never written in doc.html: the
@@ -26,6 +28,9 @@ export const LOOK = Object.freeze({
   size: Object.freeze(["default", "small", "large"]), // 字体大小: 小号, 默认, 大号
   spacing: Object.freeze(["default", "compact", "loose"]), // 正文间距: 紧凑, 默认, 宽松
   width: Object.freeze(["default", "narrow", "wide"]), // 正文宽度: 偏窄, 默认, 偏宽
+  // 全宽 (the 更多 menu's switch under 目录): the page at the full width of its area, whatever its 正文宽度 is; its attribute is
+  // the kit's own data-doc-width="full", the reader's display menu's 全宽显示 too (components/page.mjs LOOK_ATTRIBUTES)
+  full: Object.freeze(["default", "full"]),
 });
 
 /** The attribute each choice is on <html> by: the page's description says them (components/page.mjs). */
@@ -80,7 +85,7 @@ export function lookOf(value) {
   return look;
 }
 
-/** Each choice of a look, the default where it makes none: { font, size, spacing, width }. */
+/** Each choice of a look, the default where it makes none: { font, size, spacing, width, full }. */
 export const fullLook = (value) => ({ ...Object.fromEntries(Object.entries(LOOK).map(([key, [first]]) => [key, first])), ...lookOf(value) });
 
 /** Whether two looks are the same. */