@kamishibai/sdk 0.1.1

package/src/blocks/diagram.js

@@ -0,0 +1,265 @@
+import { el } from './element.js'
+import { str } from './schema-parts.js'
+
+/** The one `kind` v1 implements. The 18-diagram-type taxonomy is later work. */
+export const DIAGRAM_KINDS = Object.freeze(['graph'])
+
+const diagramNode = Object.freeze({
+  type: 'object',
+  required: ['id', 'label'],
+  properties: { id: { ...str, minLength: 1 }, label: str },
+  additionalProperties: false,
+})
+const diagramEdge = Object.freeze({
+  type: 'object',
+  required: ['from', 'to'],
+  properties: { from: { ...str, minLength: 1 }, to: { ...str, minLength: 1 }, label: str },
+  additionalProperties: false,
+})
+
+const isNonEmptyString = (value) => typeof value === 'string' && value.length > 0
+
+/**
+ * Every problem with one diagram block, as human-readable messages.
+ * Empty array means the block is drawable.
+ *
+ * Validation happens before drawing, always: a diagram whose spec is broken
+ * (unknown kind, dangling edge, duplicate id) must fail with a `KSB_` code and
+ * a block path. Drawing "whatever survives" would produce a picture that
+ * silently disagrees with the spec it came from — the worst possible outcome
+ * for a document whose whole job is to be looked at.
+ */
+export function diagramProblems(block) {
+  if (isNonEmptyString(block?.parseError)) return [block.parseError]
+
+  const problems = []
+  if (!DIAGRAM_KINDS.includes(block?.kind)) {
+    problems.push(
+      `未知的 diagram kind ${JSON.stringify(block?.kind ?? null)}；v1 僅支援：${DIAGRAM_KINDS.join(', ')}`,
+    )
+  }
+
+  const nodes = block?.nodes
+  if (!Array.isArray(nodes) || nodes.length === 0) {
+    problems.push('diagram.nodes 必須是至少一個節點的陣列')
+    return problems
+  }
+
+  const ids = new Set()
+  for (const [index, node] of nodes.entries()) {
+    if (!isNonEmptyString(node?.id)) {
+      problems.push(`nodes[${index}].id 必須是非空字串`)
+      continue
+    }
+    if (ids.has(node.id)) {
+      problems.push(`nodes[${index}].id "${node.id}" 重複；節點 id 必須唯一`)
+      continue
+    }
+    ids.add(node.id)
+    if (typeof node.label !== 'string') {
+      problems.push(`nodes[${index}].label（id "${node.id}"）必須是字串`)
+    }
+  }
+
+  const edges = block?.edges
+  if (!Array.isArray(edges)) {
+    problems.push('diagram.edges 必須是陣列（沒有邊就給空陣列）')
+    return problems
+  }
+  for (const [index, edge] of edges.entries()) {
+    for (const end of ['from', 'to']) {
+      if (!isNonEmptyString(edge?.[end])) {
+        problems.push(`edges[${index}].${end} 必須是非空字串`)
+        continue
+      }
+      if (!ids.has(edge[end])) {
+        problems.push(
+          `edges[${index}].${end} 指向不存在的節點 "${edge[end]}"；` +
+            `已宣告的節點：${[...ids].join(', ')}`,
+        )
+      }
+    }
+    if (edge?.label !== undefined && typeof edge.label !== 'string') {
+      problems.push(`edges[${index}].label 若存在必須是字串`)
+    }
+  }
+  return problems
+}
+
+/**
+ * A `diagram` fence whose body could not be read at all.
+ *
+ * `nodes`/`edges` are deliberately absent rather than empty: the block has to
+ * be *unrenderable* by construction, so that even if the parse-error branch of
+ * validation were removed the shape check would still reject it. An empty-but-
+ * valid-looking diagram would draw a blank SVG and hide the authoring mistake.
+ */
+export const diagramParseError = (parseError) =>
+  Object.freeze({ type: 'diagram', kind: 'graph', parseError })
+
+/**
+ * `diagram` → inline SVG, drawn from a layout this module does not compute.
+ *
+ * The geometry deliberately lives outside the block: both Kami templates must
+ * draw the *same* picture from the same spec (CONTRACT D1), and a layout
+ * duplicated per template is a guarantee that they will eventually differ. It
+ * now also lives outside the *renderer* — layout needs to know the available
+ * width, which is a page-layout fact this module cannot see (wayfinder issue 13
+ * 試金石). The render layer measures and feeds `ctx.layoutOf(block)` in.
+ * What a template may still own is the paint — the classes below are styled by
+ * each stylesheet's own palette variables.
+ *
+ * The arrowhead marker id is derived from the block id, which is assigned in
+ * document order: unique within an artifact (two diagrams cannot capture each
+ * other's marker) and stable across renders (so the bytes stay identical).
+ */
+export default Object.freeze({
+  type: 'diagram',
+
+  schema: Object.freeze({
+    required: ['kind', 'nodes', 'edges'],
+    properties: {
+      kind: { enum: [...DIAGRAM_KINDS] },
+      nodes: { type: 'array', minItems: 1, items: diagramNode },
+      edges: { type: 'array', items: diagramEdge },
+    },
+  }),
+
+  example: Object.freeze({
+    block: {
+      id: 'b18',
+      type: 'diagram',
+      kind: 'graph',
+      nodes: [
+        { id: 'input', label: '來源語料' },
+        { id: 'ir', label: 'block tree' },
+        { id: 'artifact', label: '離線產物' },
+      ],
+      edges: [
+        { from: 'input', to: 'ir', label: 'parse' },
+        { from: 'ir', to: 'artifact', label: 'render' },
+        { from: 'artifact', to: 'ir', label: 'replay' },
+      ],
+    },
+  }),
+
+  styleHooks: Object.freeze([
+    'diagram',
+    'diagram-svg',
+    'diagram-arrow',
+    'diagram-edge',
+    'diagram-edge-line',
+    'diagram-edge-label',
+    'diagram-node',
+    'diagram-node-box',
+    'diagram-node-label',
+  ]),
+
+  create: ({ kind, nodes, edges }) => Object.freeze({ type: 'diagram', kind, nodes, edges }),
+
+  validate: diagramProblems,
+
+  /**
+   * How a failed `validate` is reported. Stated as plain data because this
+   * layer imports nothing — the core turns it into a `KsbError` with the block
+   * path attached. `test_f1_validate_codes_match_core` pins the code against
+   * `CODES.DIAGRAM_INVALID` so the two spellings cannot drift.
+   */
+  invalid: Object.freeze({
+    code: 'KSB_DIAGRAM_INVALID',
+    message: (problems) =>
+      `diagram block 無法繪製：${problems.join('；')}。` +
+      '規格錯了就報錯，不畫半張圖——空 SVG 會讓錯誤在視覺上消失。',
+  }),
+
+  render: (block, ctx) => {
+    const layout = ctx.layoutOf(block)
+    const arrowId = `ksb-arrow-${block.id}`
+    return el('figure', { class: 'diagram', 'data-diagram-kind': block.kind }, [
+      el(
+        'svg',
+        {
+          class: 'diagram-svg',
+          xmlns: 'http://www.w3.org/2000/svg',
+          viewBox: `0 0 ${layout.width} ${layout.height}`,
+          width: layout.width,
+          height: layout.height,
+          role: 'img',
+        },
+        [
+          el('defs', null, [
+            el(
+              'marker',
+              {
+                id: arrowId,
+                viewBox: '0 0 10 10',
+                refX: 9,
+                refY: 5,
+                markerWidth: 7,
+                markerHeight: 7,
+                orient: 'auto-start-reverse',
+              },
+              [el('path', { class: 'diagram-arrow', d: 'M 0 0 L 10 5 L 0 10 z' })],
+            ),
+          ]),
+          ...layout.edges.map((edge) =>
+            el(
+              'g',
+              {
+                class: 'diagram-edge',
+                'data-edge-from': edge.from,
+                'data-edge-to': edge.to,
+              },
+              [
+                el('path', {
+                  class: 'diagram-edge-line',
+                  d: edge.d,
+                  'marker-end': `url(#${arrowId})`,
+                }),
+                // Filtered rather than left as `null`: a null child SSRs to an
+                // empty comment node, so an unlabelled edge would differ from a
+                // labelled one by a stray `<!---->` in the bytes.
+                ...(edge.label
+                  ? [
+                      el(
+                        'text',
+                        {
+                          class: 'diagram-edge-label',
+                          x: edge.labelX,
+                          y: edge.labelY,
+                          'text-anchor': edge.labelAnchor,
+                        },
+                        [edge.label],
+                      ),
+                    ]
+                  : []),
+              ],
+            ),
+          ),
+          ...layout.nodes.map((node) =>
+            el('g', { class: 'diagram-node', 'data-node-id': node.id }, [
+              el('rect', {
+                class: 'diagram-node-box',
+                x: node.x,
+                y: node.y,
+                width: node.w,
+                height: node.h,
+                rx: 6,
+              }),
+              el(
+                'text',
+                {
+                  class: 'diagram-node-label',
+                  x: node.cx,
+                  y: node.cy + 5,
+                  'text-anchor': 'middle',
+                },
+                [node.label],
+              ),
+            ]),
+          ),
+        ],
+      ),
+    ])
+  },
+})

package/src/blocks/element.js

@@ -0,0 +1,51 @@
+/**
+ * The neutral element tree — the whole conversion contract of the SDK.
+ *
+ * A block module's `render` returns *data*, never a component. That single
+ * choice is what makes a third-party block possible at all (wayfinder issue 13):
+ * if `render` returned Vue vnodes, every plugin would hard-depend on Vue 3, a
+ * template could never be pure data, and loading a plugin would be arbitrary
+ * code execution. Returning `{tag, attrs, children}` keeps Vue an implementation
+ * detail of `src/render/**` and leaves the public contract JSON-serializable.
+ *
+ * A node is one of:
+ *
+ *  - a string          — text content, escaped by the backend
+ *  - `null`            — a deliberately empty slot (the backend emits the same
+ *                        empty comment node Vue does, so its presence or absence
+ *                        is a byte-level decision the author controls)
+ *  - `{tag, attrs?, children?}` — an element with child nodes
+ *  - `{tag, attrs?, html}`      — an element carrying raw inner HTML
+ *
+ * `children` and `html` are mutually exclusive: raw content is an island, and an
+ * island has no children the tree can reason about.
+ *
+ * Attribute values pass through verbatim, `null` included — a `null` attribute
+ * is omitted by the backend, which is how an optional attribute is expressed
+ * without a second node shape. Key order is preserved, and is part of the
+ * artifact's byte identity.
+ */
+
+/** An element with child nodes. `attrs` and `children` are both optional. */
+export function el(tag, attrs = null, children = null) {
+  const node = { tag }
+  if (attrs !== null && attrs !== undefined) node.attrs = attrs
+  if (children !== null && children !== undefined) node.children = children
+  return Object.freeze(node)
+}
+
+/**
+ * An element whose content is raw HTML — the escape hatch a `raw` island, a
+ * compiled `prose` run, or a table cell needs. The string is trusted: it has
+ * already been through the parser's inline compiler or is an explicit island.
+ */
+export function rawEl(tag, attrs, html) {
+  const node = { tag }
+  if (attrs !== null && attrs !== undefined) node.attrs = attrs
+  node.html = String(html ?? '')
+  return Object.freeze(node)
+}
+
+/** Whether a value is an element node (as opposed to text, null, or garbage). */
+export const isElement = (node) =>
+  node !== null && typeof node === 'object' && typeof node.tag === 'string'

package/src/blocks/graph.js

@@ -0,0 +1,264 @@
+import { el } from './element.js'
+import { str } from './schema-parts.js'
+
+/**
+ * `graph` — 節點邊圖 (wayfinder issue 11 P1「資料」; hover 高亮 issue 11 P5).
+ *
+ * ## The schema is the whole of 13 號票 裁決 5, verbatim
+ *
+ * A node is `{id, label}`. An edge is `{from, to, label}`. Nothing else, on
+ * either, ever: 「diagram 的語意欄位（副標／variant／群組）屬 plugin kind，
+ * 核心 `graph` 保持窄」. The battle-map vocabulary that most wants in here —
+ * 狀態色, effort, 群組, 節點型別 — is named by that ruling as the thing that
+ * belongs to a plugin kind, so `additionalProperties: false` on both shapes is
+ * the ruling made mechanical rather than a matter of restraint.
+ *
+ * That leaves `graph` narrower than `diagram`, which is the point of having
+ * both: `diagram` carries a `kind` and is the entry point for the 18-type
+ * taxonomy a plugin will grow (SPEC §3.1), while `graph` is the one shape the
+ * core promises to keep drawable forever.
+ *
+ * ## Why the SVG assembly is not shared with `diagram`
+ *
+ * It could be — the two pictures are drawn from the same layout engine. It is
+ * not, and that is a byte decision rather than a taste one: every existing
+ * `kami/long-form` artifact embeds `diagram`'s markup verbatim, and a shared
+ * helper that produced so much as one different byte would move artifacts this
+ * slice is not allowed to move (CONTRACT F6a H6, and `f2b-baseline` would say
+ * so immediately). The duplication buys the guarantee that `diagram` is not
+ * touched at all; the day both are allowed to move together, they merge.
+ *
+ * Geometry comes from `ctx.layoutOf(block)` and is never computed here, for the
+ * reason issue 13 gives as its 試金石: layout needs the width the page gives the
+ * block, which is a page-layout fact no block can see. The render layer measures
+ * and feeds it in (`measureLaidOutGraphs` in `src/render/index.js`).
+ */
+
+const graphNode = Object.freeze({
+  type: 'object',
+  required: ['id', 'label'],
+  properties: { id: { ...str, minLength: 1 }, label: str },
+  additionalProperties: false,
+})
+const graphEdge = Object.freeze({
+  type: 'object',
+  required: ['from', 'to'],
+  properties: { from: { ...str, minLength: 1 }, to: { ...str, minLength: 1 }, label: str },
+  additionalProperties: false,
+})
+
+const isNonEmptyString = (value) => typeof value === 'string' && value.length > 0
+
+/**
+ * Every problem with one graph block, as human-readable messages.
+ *
+ * A dangling edge is the failure no schema keyword can state, and drawing it
+ * anyway would crash the layout (it dereferences both endpoints) or, worse,
+ * quietly drop the edge — a dependency picture that omits a dependency is the
+ * one error a reader cannot detect by looking.
+ */
+export function graphProblems(block) {
+  const problems = []
+
+  const nodes = block?.nodes
+  if (!Array.isArray(nodes) || nodes.length === 0) {
+    problems.push('graph.nodes 必須是至少一個節點的陣列')
+    return problems
+  }
+
+  const ids = new Set()
+  for (const [index, node] of nodes.entries()) {
+    if (!isNonEmptyString(node?.id)) {
+      problems.push(`nodes[${index}].id 必須是非空字串`)
+      continue
+    }
+    if (ids.has(node.id)) {
+      problems.push(`nodes[${index}].id "${node.id}" 重複；節點 id 必須唯一`)
+      continue
+    }
+    ids.add(node.id)
+    if (typeof node.label !== 'string') {
+      problems.push(`nodes[${index}].label（id "${node.id}"）必須是字串`)
+    }
+  }
+
+  const edges = block?.edges
+  if (!Array.isArray(edges)) {
+    problems.push('graph.edges 必須是陣列（沒有邊就給空陣列）')
+    return problems
+  }
+  for (const [index, edge] of edges.entries()) {
+    for (const end of ['from', 'to']) {
+      if (!isNonEmptyString(edge?.[end])) {
+        problems.push(`edges[${index}].${end} 必須是非空字串`)
+        continue
+      }
+      if (!ids.has(edge[end])) {
+        problems.push(
+          `edges[${index}].${end} 指向不存在的節點 "${edge[end]}"；` +
+            `已宣告的節點：${[...ids].join(', ')}`,
+        )
+      }
+    }
+    if (edge?.label !== undefined && typeof edge.label !== 'string') {
+      problems.push(`edges[${index}].label 若存在必須是字串`)
+    }
+  }
+  return problems
+}
+
+export default Object.freeze({
+  type: 'graph',
+
+  schema: Object.freeze({
+    required: ['nodes', 'edges'],
+    properties: {
+      nodes: { type: 'array', minItems: 1, items: graphNode },
+      edges: { type: 'array', items: graphEdge },
+    },
+  }),
+
+  example: Object.freeze({
+    block: {
+      id: 'b25',
+      type: 'graph',
+      nodes: [
+        { id: 'blocks', label: 'block 模組' },
+        { id: 'schema', label: 'IR schema' },
+        { id: 'render', label: '渲染層' },
+        { id: 'artifact', label: '離線產物' },
+      ],
+      edges: [
+        { from: 'blocks', to: 'schema', label: '推導' },
+        { from: 'blocks', to: 'render', label: '中性樹' },
+        { from: 'schema', to: 'artifact', label: '內嵌 IR' },
+        { from: 'render', to: 'artifact', label: '組裝' },
+      ],
+    },
+  }),
+
+  styleHooks: Object.freeze([
+    'graph',
+    'graph-svg',
+    'graph-arrow',
+    'graph-edge',
+    'graph-edge-line',
+    'graph-edge-label',
+    'graph-node',
+    'graph-node-box',
+    'graph-node-label',
+  ]),
+
+  create: ({ nodes, edges }) => Object.freeze({ type: 'graph', nodes, edges }),
+
+  validate: graphProblems,
+
+  invalid: Object.freeze({
+    code: 'KSB_GRAPH_INVALID',
+    message: (problems) =>
+      `graph block 無法繪製：${problems.join('；')}。` +
+      '少畫一條邊的依賴圖，看起來與畫完的那一張一模一樣——所以規格錯了就報錯。',
+  }),
+
+  /**
+   * The hover contract, stated here because the client asset reads it:
+   * `data-graph` scopes one graph against the others on the page,
+   * `data-node-id` names a node, and `data-edge-from` / `data-edge-to` name an
+   * edge's endpoints. The script needs nothing else to know what is adjacent to
+   * what — the adjacency is already in the markup.
+   *
+   * The arrowhead marker id is derived from the block id, assigned in document
+   * order: unique within an artifact (two graphs cannot capture each other's
+   * marker) and stable across renders, so the bytes stay identical.
+   */
+  render: (block, ctx) => {
+    const layout = ctx.layoutOf(block)
+    const arrowId = `ksb-graph-arrow-${block.id}`
+    return el('figure', { class: 'graph', 'data-graph': block.id }, [
+      el(
+        'svg',
+        {
+          class: 'graph-svg',
+          xmlns: 'http://www.w3.org/2000/svg',
+          viewBox: `0 0 ${layout.width} ${layout.height}`,
+          width: layout.width,
+          height: layout.height,
+          role: 'img',
+        },
+        [
+          el('defs', null, [
+            el(
+              'marker',
+              {
+                id: arrowId,
+                viewBox: '0 0 10 10',
+                refX: 9,
+                refY: 5,
+                markerWidth: 7,
+                markerHeight: 7,
+                orient: 'auto-start-reverse',
+              },
+              [el('path', { class: 'graph-arrow', d: 'M 0 0 L 10 5 L 0 10 z' })],
+            ),
+          ]),
+          ...layout.edges.map((edge) =>
+            el(
+              'g',
+              {
+                class: 'graph-edge',
+                'data-edge-from': edge.from,
+                'data-edge-to': edge.to,
+              },
+              [
+                el('path', {
+                  class: 'graph-edge-line',
+                  d: edge.d,
+                  'marker-end': `url(#${arrowId})`,
+                }),
+                // Filtered rather than left as `null`: a null child SSRs to an
+                // empty comment node, so an unlabelled edge would differ from a
+                // labelled one by a stray comment node in the bytes.
+                ...(edge.label
+                  ? [
+                      el(
+                        'text',
+                        {
+                          class: 'graph-edge-label',
+                          x: edge.labelX,
+                          y: edge.labelY,
+                          'text-anchor': edge.labelAnchor,
+                        },
+                        [edge.label],
+                      ),
+                    ]
+                  : []),
+              ],
+            ),
+          ),
+          ...layout.nodes.map((node) =>
+            el('g', { class: 'graph-node', 'data-node-id': node.id, tabindex: '0' }, [
+              el('rect', {
+                class: 'graph-node-box',
+                x: node.x,
+                y: node.y,
+                width: node.w,
+                height: node.h,
+                rx: 6,
+              }),
+              el(
+                'text',
+                {
+                  class: 'graph-node-label',
+                  x: node.cx,
+                  y: node.cy + 5,
+                  'text-anchor': 'middle',
+                },
+                [node.label],
+              ),
+            ]),
+          ),
+        ],
+      ),
+    ])
+  },
+})