@heycys/gallery 0.0.0-stage → 0.1.1

package/skill/sdk/column-widths.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The types of the table column allocator (`DocTables.allocateColumnWidths`), kept here so that the
+ * SDK stands alone: the kit's own code takes them from this file.
+ */
+export type ColumnKind = 'compact' | 'narrative' | 'token-heavy';
+export interface ColumnInput {
+  key: string;
+  header: string;
+  cells: Array<string | number | null | undefined>;
+  kind?: ColumnKind;
+  minWidth?: number;
+  maxWidth?: number;
+  /** A column of numbers (the kit's numeric columns): its readable floor is never lowered by maxReadableFloor. */
+  numeric?: boolean;
+  /** Optional measured header width including padding/controls; supplied by the DOM adapter. */
+  headerWidth?: number;
+  /** Optional unwrapped widths including padding, aligned with cells; supplied by the DOM adapter. */
+  cellWidths?: number[];
+  /** Optional widths of the header's and each cell's longest word (WORD_BREAKS) including padding; supplied by the DOM adapter. */
+  headerWordWidth?: number;
+  cellWordWidths?: number[];
+  /** Optional widths of each cell's widest piece no line breaks in (PIECE_BREAKS, a number range) including padding; supplied by the DOM adapter. */
+  cellPieceWidths?: number[];
+}
+export interface ColumnLayout {
+  key: string;
+  kind: ColumnKind;
+  preferredWidth: number;
+  /** Readable floor: when their sum exceeds the viewport, scroll instead of compressing further. */
+  softMinWidth: number;
+  hardMinWidth: number;
+  width: number;
+  /** Relative to the allocated columns, which may exceed totalWidth at their readable floors. */
+  ratio: number;
+}
+export interface ColumnWidthOptions {
+  /** Available table width, including cell padding. */
+  totalWidth: number;
+  percentile?: number;
+  hardMinWidth?: number;
+  narrativeMinWidth?: number;
+  /**
+   * The most a column's readable floor may be, whatever its kind (a prose column's baseline and its
+   * three lines of P90 text, a path's, a short field's protected width alike), but a numeric
+   * column's; unset, no limit. On a narrow screen the kit passes a third of the table's room, so that
+   * a table of two or three columns wraps their text before it scrolls sideways.
+   */
+  maxReadableFloor?: number;
+  tokenHeavyMinWidth?: number;
+  compactMaxProtectedWidth?: number;
+  cellPadding?: number;
+  columnOverhead?: number;
+  font?: string;
+}
+/** Column widths from the cells' text: deterministic P90 + water filling, with scrolling at readable floors. */
+export type AllocateColumnWidths = (columns: ColumnInput[], options: ColumnWidthOptions) => ColumnLayout[];

package/skill/sdk/doc-charts.d.ts

@@ -0,0 +1,82 @@
+/**
+ * A cell of a table a chart is drawn from: null for an empty or missing cell, a dash or n/a; a number
+ * when it writes one number (12.5%, 3.6亿, 约 20; its data-sort-value first); else its words (a range,
+ * 3 / 4, a column whose header has data-sort-type "text" or "date"). references/writing-html.md says it in full.
+ */
+export type DocTableValue = number | string | null;
+
+/** A row of that table: each value by its column's header words. */
+export type DocTableRow = Record<string, DocTableValue>;
+
+/**
+ * The rows a chart drawn from a table (`data-doc-chart-data`) gets as `data`: its body rows in the
+ * file's order (<tfoot> left out), and its header's words in order (`columns`, as d3.csvParse gives).
+ */
+export interface DocTableRows extends Array<DocTableRow> {
+  columns: string[];
+}
+
+/** What a document's own chart type draws with (see `DocChartsApi.define`). */
+export interface DocChartDrawContext<Data = any> {
+  /** The declared chart's host, emptied before each call (its data script stays). */
+  host: HTMLElement;
+  /** The declared JSON of this chart; for a chart drawn from a table (data-doc-chart-data), its rows (DocTableRows). */
+  data: Data;
+  /** Colors of the current theme. */
+  tokens: import("./doc-tokens.js").DocTokenSnapshot;
+  /** The host's width in px. */
+  width: number;
+  /** The card's plot height in px when it sets one (`--doc-chart-height`, e.g. from the preview); otherwise null. */
+  height: number | null;
+}
+
+/** A chart of a document's own type. */
+export interface DocDrawnChartHandle<Data = any> {
+  /** Draw again, with new data if given (a chart drawn from a table takes none: it draws its table). */
+  redraw(nextData?: Data): void;
+  destroy(): void;
+}
+
+/** What a part of a document's own type is started with: the drawing context and its lifetime. */
+export interface DocChartPartContext<Data = any> extends DocChartDrawContext<Data> {
+  /** Aborted when the part is destroyed (its host left the page): give it to addEventListener. */
+  signal: AbortSignal;
+}
+
+/**
+ * A part of a document's own type: something that keeps what it needs (listeners, timers, an
+ * animation) between drawings. `mount` starts it in the emptied host; `update` is called when its
+ * width, the theme or its card's height change (or a script redraws it, or the rows of its table
+ * change), `destroy` when its host leaves the page.
+ */
+export interface DocChartPart<Data = any> {
+  mount(context: DocChartPartContext<Data>): { update?(context: DocChartPartContext<Data>): void; destroy?(): void } | void;
+}
+
+/**
+ * Charts are declared in their cards, each of a type the document's script defines:
+ * `<div data-doc-chart="slope"><script type="application/json">…its data…</script></div>`, or
+ * `<div data-doc-chart="slope" data-doc-chart-data="t1"></div>`, drawn from the rows of the table
+ * whose frame carries `data-doc-chart-source="t1"`.
+ */
+export interface DocChartsApi {
+  /**
+   * Define a chart type of the document's own, drawn from the data of each chart declared with it
+   * (its JSON, or its table's rows: DocTableRows). `type` is lowercase letters, digits and hyphens,
+   * a letter first (`interval`, `ci-plot`). `draw` is called again when a chart's width, the theme
+   * or its card's height change, and when its table's rows do; a part (`{ mount }`) keeps what it
+   * starts until its host leaves the page.
+   */
+  define<Data = any>(type: string, draw: ((context: DocChartDrawContext<Data>) => void) | DocChartPart<Data>): void;
+  /** The chart drawn in a host; null if none. */
+  get(target: string | Element): DocDrawnChartHandle | null;
+}
+
+declare global {
+  /** The rows a chart drawn from a table gets as `data`, for a document's script to type it with (JSDoc's `@type {DocTableRows}`). */
+  type DocTableRows = import("./doc-charts.js").DocTableRows;
+  /** A row of a table a chart is drawn from. */
+  type DocTableRow = import("./doc-charts.js").DocTableRow;
+  /** A cell's value of a table a chart is drawn from. */
+  type DocTableValue = import("./doc-charts.js").DocTableValue;
+}

package/skill/sdk/doc-code.d.ts

@@ -0,0 +1,28 @@
+// Code blocks are <div class="doc-code"> holding their title and a <pre><code> (highlighted on
+// their own); a diff is declared as <div class="doc-diff"> holding its title and these options as
+// JSON, its header showing the lines added and removed.
+export interface CodeViewOptions {
+  code: string;
+  /** Overrides path inference; unknown languages render as plain text. */
+  language?: string;
+  path?: string;
+  /** Default true. Copying excludes the gutter. */
+  showLineNumbers?: boolean;
+}
+export interface DiffLineData {
+  type: 'added' | 'removed' | 'unchanged';
+  content: string;
+  /** Optional positive integer; omitted numbers leave a blank gutter. */
+  lineNumber?: number;
+}
+export interface DiffViewOptions extends Omit<CodeViewOptions, 'code'> {
+  lines: DiffLineData[];
+  /** Default true. */
+  coloredLineNumbers?: boolean;
+  /** Default true. */
+  showAccentStrip?: boolean;
+}
+declare global {
+  /** gallery check's alone (no such function on the page): a declared diff's JSON (`<div class="doc-diff">`) as its options. */
+  function __declaredDiff(options: DiffViewOptions): void;
+}

package/skill/sdk/doc-dialogs.d.ts

@@ -0,0 +1,4 @@
+export interface DocDialogsApi {
+  open(target: string | HTMLDialogElement, opener?: HTMLElement | null): HTMLDialogElement;
+  close(target: string | HTMLDialogElement, returnValue?: string): HTMLDialogElement;
+}

package/skill/sdk/doc-kit.d.ts

@@ -0,0 +1,147 @@
+import type { DocState } from "./doc-state.js";
+
+/**
+ * What an instance can hear (`on`). `editable`: `context.canEdit()` has just become true, for one mounted before the page came to edit.
+ * `content`: a change inside the instance, heard only with `owns: false`, as what a component owns the
+ * kit does not watch; a change of what the file says of it is `source`, whatever it owns: of a part edited
+ * as text or data, or of the blocks a slot holds (a part edited as flow), typed, moved in or out, undone.
+ */
+export type DocComponentSignal = "source" | "resize" | "theme" | "layout" | "viewport" | "fonts" | "content" | "reveal" | "editable";
+
+/** What a component's `mount` returns, all of it optional. */
+export interface DocComponentHandle {
+  /**
+   * A signal it asked for (`on`). `detail`: the mutation records of `source` and `content`; the faces of a
+   * later `fonts`. `options.quiet`: on `content`, a change that leaves the page looking as it was.
+   */
+  update?(reason: DocComponentSignal, detail?: unknown, options?: { quiet?: boolean }): void;
+  /** The host left the page. What listens on `context.signal` goes by itself. */
+  destroy?(): void;
+}
+
+export interface DocComponentStateOptions<T extends Record<string, unknown>> {
+  /** Positive integer. A state of another version, or defaults of another shape, under this instance's name throws: see `DocStateFactory.getOrCreate`. */
+  version: number;
+  /** JSON-serializable default state. */
+  defaults: T;
+  /** Default: []; excluded from browser restoration and exported snapshots. */
+  transientKeys?: Array<keyof T & string>;
+}
+
+/** What `mount` is given for a package's instance. */
+export interface DocComponentContext {
+  /** The instance's element. */
+  readonly host: HTMLElement;
+  /** Aborts when the instance ends: give it to what the component listens to. */
+  readonly signal: AbortSignal;
+  /**
+   * Run `draw` in the frame the kit draws in, once: of what is asked before that frame, the last `draw`
+   * runs. Asked from inside a `draw` it runs in the next frame; a chain of those is an animation, which
+   * the page does not wait for to count as drawn. Nothing runs once the instance has failed.
+   */
+  frame(draw: () => void): void;
+  /** Say this instance failed: it ends there, even as `mount` runs, and shows what it holds, read-only. */
+  fail(error: unknown): void;
+  /**
+   * The first element of a part of the manifest in this instance's own markup, or null. A part edited as
+   * flow gives its slot (data-doc-slot), whose blocks are the document's, the reader's: read it (its
+   * height, its words, its headings), and never write in it, move it or take it off. A name the manifest
+   * does not have throws.
+   */
+  part(name: string): HTMLElement | null;
+  /** This instance's reading state, of no other instance of the package: the same object at every mount. */
+  state<T extends Record<string, unknown>>(options: DocComponentStateOptions<T>): DocState<T>;
+  /**
+   * Whether `edit` writes to the file now. False until the page comes to edit (the `editable` signal
+   * says when, for one that asked), and for good in an exported file and its PDF, in 演示视图, for an
+   * instance that failed and for one whose `data-doc-schema` is past its manifest's `schema`.
+   */
+  canEdit(): boolean;
+  /**
+   * Change a part edited as data, whose name its manifest gives: `change` is handed a draft of the part
+   * (its first element, off the page) and changes what it holds, at once. Returns whether that was taken:
+   * then it stands on the page, one undo step, and the file follows by itself, as for any edit. False
+   * while `canEdit()` is false, and where `change` throws, writes the part on the page instead of the
+   * draft, or leaves what a file cannot hold (a script, a handler, an element that does not read back as
+   * itself, its own tag changed): nothing has happened then, and the console says why. Undo puts the
+   * part back and `source` tells you, like any change of it. A name the manifest does not have, or a
+   * part not edited as data (a text part, a slot), throws. A list of names changes those parts in one write, one undo step (a
+   * gesture that moves a card and counts the move): `change` is handed a draft of each, by its name, and
+   * two that are one element, or one in the other, throw.
+   */
+  edit<P extends string | string[]>(part: P, change: (draft: P extends string[] ? Record<string, HTMLElement> : HTMLElement) => void): boolean;
+}
+
+/** What a package's kit.js registers. */
+export interface DocComponent {
+  /** The package's id, as its manifest writes it: <scope>/<name>. */
+  id: string;
+  /** The signals `update` is to hear. */
+  on?: DocComponentSignal[];
+  /** Default: true. The kit watches nothing the component draws in its instance, but what its parts edit as text or data. */
+  owns?: boolean;
+  /**
+   * Starts an instance, a thrown error or a promise rejected being that instance's failure alone: it
+   * shows what it holds, read-only, and the page goes on. Called again on a node an undo puts back and
+   * in an exported file: the kit takes off `dehydrate`'s and the manifest's `runtime`'s first.
+   */
+  mount(host: HTMLElement, context: DocComponentContext): DocComponentHandle | void | Promise<DocComponentHandle | void>;
+  /**
+   * Takes off of `host` what `mount` left and the manifest's `runtime` does not name. It may be given a
+   * host with none of it: an error it throws is told on the console, and `mount` goes on.
+   */
+  dehydrate?(host: HTMLElement): void;
+  /**
+   * A small edit, as a reader's gesture would make it, by `context.edit`: what `gallery component check`
+   * calls to try the way back to the file. Nothing else calls it.
+   */
+  example?(host: HTMLElement, context: DocComponentContext): void;
+}
+
+declare global {
+  /** What `mount` is given, for a package's kit.js to name it with (JSDoc's `@param {DocComponentContext} context`), with no import. */
+  type DocComponentContext = import("./doc-kit.js").DocComponentContext;
+  /** What `mount` returns. */
+  type DocComponentHandle = import("./doc-kit.js").DocComponentHandle;
+  /** A signal `update` hears. */
+  type DocComponentSignal = import("./doc-kit.js").DocComponentSignal;
+  /** What kit.js registers. */
+  type DocComponent = import("./doc-kit.js").DocComponent;
+}
+
+/** How much the kit runs now. */
+export interface DocKitStats {
+  /** Instances alive, by component. */
+  live: Record<string, number>;
+  mounted: number;
+  destroyed: number;
+  failed: number;
+  components: string[];
+}
+
+/** The kit's runtime: every component instance on the page. */
+export interface DocKitApi {
+  /** Register a component. An id registered already throws. */
+  component(definition: DocComponent): unknown;
+  /** What Gallery says of a package; generated, never written by hand. */
+  describe(description: { id: string; [field: string]: unknown }): void;
+  /** What is known of a component: where its instances are and its parts, or null. */
+  description(id: string): { id: string; [field: string]: unknown } | null;
+  /** Start what `root` holds now, as if it had been added. */
+  mount(root?: ParentNode): void;
+  /** End the instance on `host`. */
+  destroy(host: Element): void;
+  /** Run a change that leaves the page looking as it was. */
+  quietly<T>(change: () => T): T;
+  /** Take what the kit and its components left off `root`, a copy of the page. */
+  dehydrate<T extends Element>(root: T): T;
+  /** The component on `host` makes its `example` of an edit, as `gallery component check` asks it. Whether it has one. */
+  example(host: Element): boolean;
+  /** Open what hides an element, and bring it into view. */
+  reveal(element: Element): void;
+  stats(): DocKitStats;
+  /** The keys of the page's bound controls. */
+  readonly bindings: unknown;
+  /** The selectors of the elements blocks stand in. */
+  readonly flows: readonly string[];
+}

package/skill/sdk/doc-math.d.ts

@@ -0,0 +1,3 @@
+export interface DocMathApi {
+  render(root?: ParentNode): void;
+}

package/skill/sdk/doc-sheets.d.ts

@@ -0,0 +1,15 @@
+/** A Sheet area: the tab it shows. */
+export interface DocSheetsHandle {
+  get(): string;
+  set(tab: string): void;
+  destroy(): void;
+}
+
+/**
+ * Sheet areas start on their own (`<section class="doc-sheet-shell" data-doc-sheets="name">`,
+ * its tab kept under its name); a script may ask one which tab it shows, or show another.
+ */
+export interface DocSheetsApi {
+  /** The area a selector or element finds; null before it has started. */
+  get(target: string | Element): DocSheetsHandle | null;
+}

package/skill/sdk/doc-state.d.ts

@@ -0,0 +1,41 @@
+export type DocStateChange =
+  | { type: "set"; key: string }
+  | { type: "update"; keys: string[] }
+  | { type: "reset" }
+  | { type: "hydrate" };
+
+export interface DocState<T extends Record<string, unknown> = Record<string, unknown>> {
+  readonly id: string;
+  readonly version: number;
+  get<K extends keyof T>(key: K, fallback?: T[K]): T[K];
+  snapshot(): T;
+  set<K extends keyof T>(key: K, value: T[K]): void;
+  update(values: Partial<T>): void;
+  /** Restore defaults and save them, so an older embedded snapshot cannot reappear. */
+  reset(): void;
+  subscribe(listener: (snapshot: T, change: DocStateChange) => void): () => void;
+  serialize(): string;
+  hydrate(serialized: string): void;
+}
+
+export interface DocStateOptions<T extends Record<string, unknown>> {
+  /** The state's name within this document, such as "view". Storage is kept per document (its data-doc-id), so "view" and "<slug>:view" name the same state. */
+  id: string;
+  /** Positive integer checked against stored/embedded snapshots. */
+  version: number;
+  /** JSON-serializable default state; reuse one instance per id/version. */
+  defaults: T;
+  /** Overrides the browser storage key; normally left out. */
+  storageKey?: string;
+  /** Default: []; excluded from browser restoration and exported snapshots. */
+  transientKeys?: Array<keyof T & string>;
+}
+
+export interface DocStateFactory {
+  readonly schemaVersion: 1;
+  /** Throws when the state exists already: one id and version is one state. */
+  create<T extends Record<string, unknown>>(options: DocStateOptions<T>): DocState<T>;
+  /** The state of this id: the one made already when its version and the shape of its defaults are these, a new one when there is none, and an error otherwise. */
+  getOrCreate<T extends Record<string, unknown>>(options: DocStateOptions<T>): DocState<T>;
+  serializeAll(): string;
+}

package/skill/sdk/doc-tables.d.ts

@@ -0,0 +1,24 @@
+import type { AllocateColumnWidths, ColumnLayout } from "./column-widths.js";
+export type { AllocateColumnWidths, ColumnInput, ColumnKind, ColumnLayout, ColumnWidthOptions } from "./column-widths.js";
+export type DocSortDirection = "asc" | "desc";
+export type DocSortType = "number" | "text" | "date";
+
+export interface DocTableSortDetail {
+  column: number;
+  key: string | null;
+  direction: DocSortDirection;
+}
+
+export interface DocTableState {
+  /** null restores original row order. */
+  sort: { column: number; direction: DocSortDirection; key?: string | null } | null;
+}
+
+export interface DocTablesApi {
+  allocateColumnWidths: AllocateColumnWidths;
+  /** Remeasure a table now. Hidden tables wait until visible; returns the last layout or []. */
+  layout(target: string | HTMLTableElement): ColumnLayout[];
+  getState(target: string | HTMLTableElement): DocTableState;
+  setState(target: string | HTMLTableElement, state: DocTableState): void;
+  subscribe(target: string | HTMLTableElement, listener: (state: DocTableState) => void): () => void;
+}

package/skill/sdk/doc-tokens.d.ts

@@ -0,0 +1,22 @@
+export interface DocTokenSnapshot {
+  readonly tone: (name: "success" | "danger" | "warning" | "info" | "neutral" | "accent" | "muted" | "text" | "border") => string;
+  readonly css: (name: string, fallback?: string) => string;
+  readonly bg: string;
+  readonly surface: string;
+  readonly text: string;
+  readonly muted: string;
+  readonly border: string;
+  readonly grid: string;
+  readonly accent: string;
+  readonly accentSoft: string;
+  readonly success: string;
+  readonly warning: string;
+  readonly danger: string;
+  readonly series: readonly string[];
+}
+
+export interface DocTokensApi {
+  readonly read: (element?: Element) => DocTokenSnapshot;
+  readonly seriesNames: readonly string[];
+}
+

package/skill/sdk/index.d.ts

@@ -0,0 +1,30 @@
+import type { DocChartsApi } from "./doc-charts.js";
+import type { DocDialogsApi } from "./doc-dialogs.js";
+import type { DocKitApi } from "./doc-kit.js";
+import type { DocMathApi } from "./doc-math.js";
+import type { DocStateFactory } from "./doc-state.js";
+import type { DocSheetsApi } from "./doc-sheets.js";
+import type { DocTablesApi } from "./doc-tables.js";
+import type { DocTokensApi } from "./doc-tokens.js";
+
+declare global {
+  var DocCharts: DocChartsApi;
+  var DocDialogs: DocDialogsApi;
+  var DocKit: DocKitApi;
+  var DocMath: DocMathApi;
+  var DocState: DocStateFactory;
+  var DocSheets: DocSheetsApi;
+  var DocTables: DocTablesApi;
+  var DocTokens: DocTokensApi;
+}
+
+export * from "./doc-charts.js";
+export * from "./doc-dialogs.js";
+export * from "./doc-kit.js";
+export * from "./doc-math.js";
+export * from "./doc-state.js";
+export * from "./doc-sheets.js";
+export * from "./doc-tables.js";
+export * from "./doc-tokens.js";
+
+export * from "./doc-code.js";

package/starter/doc.html

@@ -0,0 +1,21 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>__REPORT_TITLE__</title>
+</head>
+<body>
+  <main class="doc-page" data-doc-id="__REPORT_SLUG__">
+    <header class="doc-header">
+      <h1 class="doc-title">__REPORT_TITLE__</h1>
+    </header>
+
+    <!-- Starter content: replace this whole section; gallery check fails until it is gone. -->
+    <section class="doc-section" aria-labelledby="content-title" data-doc-placeholder>
+      <h2 id="content-title">文档正文</h2>
+      <p>用文档内容替换这一节：转换已定稿的文档时沿用它的大纲；整理项目笔记、会议记录或原始实验记录时，按写作偏好重新组织大纲。保留原始单位、口径与证据位置。</p>
+    </section>
+  </main>
+</body>
+</html>

package/starter/doc.json

@@ -0,0 +1,5 @@
+{
+  "title": "__REPORT_TITLE__",
+  "description": "__REPORT_DESCRIPTION__",
+  "type": "report"
+}