@kamishibai/sdk 0.1.1

package/src/blocks/grid.js

@@ -0,0 +1,156 @@
+import { el } from './element.js'
+import { children } from './schema-parts.js'
+import {
+  GRID_COLUMNS,
+  PLACEMENT_KEYS,
+  hasPlacement,
+  placementProblems,
+  placementStyle,
+} from './placement.js'
+
+/**
+ * `grid` — 「像在外面包一層 `display:grid` 的 div」(wayfinder issue 14 裁決 2).
+ *
+ * The twelfth core type, and the first one added through the F1 registry rather
+ * than by editing the SDK: everything a grid *is* — its schema branch, its
+ * example, its Markdown-superset syntax, its refusal wording, its markup — is
+ * in this file, and `src/blocks/index.js` gains one line.
+ *
+ * It is a container and nothing more. It has no columns option (24 is
+ * vocabulary, not configuration), no gap, no alignment: appearance never enters
+ * the IR. Content that is *not* wrapped in one stays flow content exactly as
+ * before, which is what makes the whole type opt-in — 「不包＝預設流式」.
+ */
+
+/** Verbatim — the `:::` fence names this module claims in the Markdown superset. */
+const GRID_FENCE = 'grid'
+const PLACE_FENCE = 'place'
+
+const INTEGER_LITERAL = /^-?\d+$/
+
+/**
+ * `col=1 colSpan=12` → `{col: 1, colSpan: 12}`.
+ *
+ * A key nobody recognises is kept rather than dropped, and an unparseable value
+ * is kept as the string it was. Both survive into the block, where
+ * `unevaluatedProperties: false` and the placement bounds refuse them with a
+ * block path — because the failure mode that matters here is the *typo*
+ * (`colspan=8`), and a parser that quietly discards a typo produces a document
+ * whose layout is silently not the one the author wrote (seal F7 的同一條).
+ */
+export function parsePlacementParams(params) {
+  const out = {}
+  for (const token of String(params ?? '').trim().split(/\s+/)) {
+    if (token.length === 0) continue
+    const at = token.indexOf('=')
+    if (at <= 0) continue
+    const key = token.slice(0, at)
+    const raw = token.slice(at + 1)
+    out[key] = INTEGER_LITERAL.test(raw) ? Number(raw) : raw
+  }
+  return out
+}
+
+/** Attach one placement to every block a `:::place` fence contained. */
+const place = (params, kids) => {
+  const placement = parsePlacementParams(params)
+  return kids.map((kid) => ({ ...kid, ...placement }))
+}
+
+/**
+ * Every relational placement problem among a grid's direct children.
+ *
+ * Bounds are the schema's job; what no schema keyword can say is that a span
+ * has to *end* inside the 24 columns. Reporting it here — from the module, as
+ * plain data — is what keeps a third-party container able to refuse its own
+ * broken geometry instead of drawing something the author did not write.
+ */
+export function gridProblems(block) {
+  const kids = Array.isArray(block?.children) ? block.children : []
+  return kids.flatMap((kid, index) => placementProblems(`children[${index}]`, kid))
+}
+
+export default Object.freeze({
+  type: 'grid',
+
+  schema: Object.freeze({ required: ['children'], properties: { children } }),
+
+  example: Object.freeze({
+    block: {
+      id: 'b19',
+      type: 'grid',
+      children: [
+        { id: 'b20', type: 'prose', html: '主欄：占 24 格中的 16 格。', col: 1, colSpan: 16 },
+        { id: 'b21', type: 'prose', html: '側欄：占 24 格中的 8 格。', col: 17, colSpan: 8 },
+      ],
+    },
+  }),
+
+  nesting: Object.freeze({ arrays: Object.freeze(['children']) }),
+
+  /**
+   * The Markdown superset, declared rather than wired into the parser.
+   *
+   * ````
+   * ::::grid
+   * :::place col=1 colSpan=16
+   * 主欄。
+   * :::
+   * :::place col=17 colSpan=8
+   * 側欄。
+   * :::
+   * ::::
+   * ````
+   *
+   * The outer fence wears one more colon than the inner ones, the same rule
+   * markdown-it-container uses for nesting. `place` builds no block of its own:
+   * placement belongs to the *child*, exactly as `grid-column` does in CSS, so
+   * the fence hands its coordinates to whatever blocks it contained and leaves.
+   */
+  syntax: Object.freeze({
+    containers: Object.freeze([GRID_FENCE, PLACE_FENCE]),
+    build: ({ name, params, children: kids }) =>
+      name === GRID_FENCE ? { type: GRID_FENCE, children: kids } : place(params, kids),
+  }),
+
+  styleHooks: Object.freeze(['grid', 'grid-cell']),
+
+  create: ({ children: kids }) => Object.freeze({ type: GRID_FENCE, children: kids }),
+
+  validate: gridProblems,
+
+  invalid: Object.freeze({
+    code: 'KSB_PLACEMENT_INVALID',
+    message: (problems) =>
+      `grid 子項擺位非法：${problems.join('；')}。` +
+      `${GRID_COLUMNS} 格座標是整數詞彙，越界即報錯——` +
+      '靜默夾持會讓版面悄悄不是作者寫的那一個。',
+  }),
+
+  /**
+   * The 24 columns are declared inline, on the container itself.
+   *
+   * A stylesheet could carry them, but then a grid would only work in templates
+   * that had heard of grids — and every existing template would have to ship a
+   * new rule, which is a byte change to every artifact those templates ever
+   * drew. Geometry is what a grid *is*; the paint (gaps, rules, colour) stays
+   * the template's, through the two hooks above.
+   */
+  render: (block, ctx) => {
+    const kids = ctx.drawableChildren(block.children)
+    return el(
+      'div',
+      {
+        class: 'grid',
+        style: `display: grid; grid-template-columns: repeat(${GRID_COLUMNS}, minmax(0, 1fr))`,
+      },
+      kids.map((kid, index) =>
+        el('div', { class: 'grid-cell', style: placementStyle(kid) }, [
+          ctx.renderBlock(kid, { index, total: kids.length }),
+        ]),
+      ),
+    )
+  },
+})
+
+export { GRID_COLUMNS, PLACEMENT_KEYS, hasPlacement }

package/src/blocks/index.js

@@ -0,0 +1,106 @@
+import { blockModules, registerBlockModule, sealCoreRegistry } from './registry.js'
+
+import section from './section.js'
+import prose from './prose.js'
+import quote from './quote.js'
+import callout from './callout.js'
+import code from './code.js'
+import table from './table.js'
+import raw from './raw.js'
+import list from './list.js'
+import deck from './deck.js'
+import slide from './slide.js'
+import diagram from './diagram.js'
+import grid from './grid.js'
+import stat from './stat.js'
+import timeline from './timeline.js'
+import board from './board.js'
+import graph from './graph.js'
+
+/**
+ * The core block vocabulary (SPEC §3), in canonical order.
+ *
+ * Order is load-bearing: it is the order of the `type` enum and of the branch
+ * list in the generated JSON Schema, and therefore of the bytes `kamishibai
+ * schema` prints. It is also the only place the core types are listed —
+ * every other list in the SDK (schema, examples, the renderer table, the
+ * template admission rule) is derived from the registry rather than repeated.
+ *
+ * A *seventeenth* type does not belong here: a plugin calls `registerBlockModule`
+ * from outside and needs no edit to any file inside `src/` (CONTRACT A4).
+ *
+ * `grid` is appended rather than slotted in beside the other containers, and
+ * that is a byte decision, not a taste one: this order is the order of the
+ * `type` enum and of the schema's branch list, so inserting anywhere but the
+ * end would move bytes the F2a slice is not allowed to move (CONTRACT C5).
+ *
+ * The four data types F6a landed (`stat`, `timeline`, `board`, `graph` —
+ * wayfinder issue 11 P1「資料」) are appended after `grid` for the same reason,
+ * and among themselves they sit in the order that ticket lists them. Anywhere
+ * else in this array is a moved byte in `kamishibai schema --json` for a type
+ * that has nothing to do with this slice.
+ */
+const CORE_MODULES = Object.freeze([
+  section,
+  prose,
+  quote,
+  callout,
+  code,
+  table,
+  raw,
+  list,
+  deck,
+  slide,
+  diagram,
+  grid,
+  stat,
+  timeline,
+  board,
+  graph,
+])
+
+for (const mod of CORE_MODULES) registerBlockModule(mod)
+sealCoreRegistry()
+
+export {
+  BLOCK_MODULE_FIELDS,
+  PLUGIN_TYPE_PREFIX,
+  PLUGIN_TYPE_WILDCARD,
+  blockModule,
+  blockModules,
+  blockTypes,
+  pluginBlockTypes,
+  registerBlockModule,
+  registryVersion,
+  resetBlockRegistry,
+} from './registry.js'
+
+export { el, rawEl, isElement } from './element.js'
+
+export {
+  GRID_COLUMNS,
+  PLACEMENT_KEYS,
+  PLACEMENT_PROPERTIES,
+  ROW_KEYS,
+  hasPlacement,
+  hasRowVocabulary,
+  placedWidth,
+  placementProblems,
+  placementStyle,
+} from './placement.js'
+
+/**
+ * The `:::` fence names the registered vocabulary claims, name → module.
+ *
+ * The parser used to hold this list itself (`CALLOUT_VARIANTS`, hard-coded in
+ * `parser/container.js`), which meant a new container type was a parser edit —
+ * the eleven-file problem in its last hiding place. Now a module declares
+ * `syntax.containers` and the parser asks.
+ */
+export function containerSyntax() {
+  const table = new Map()
+  for (const mod of blockModules()) {
+    for (const name of mod.syntax?.containers ?? []) table.set(name, mod)
+  }
+  return table
+}

package/src/blocks/list.js

@@ -0,0 +1,50 @@
+import { el } from './element.js'
+import { itemGroups } from './schema-parts.js'
+
+/**
+ * `list` — keeps its own frame and hands each item's blocks straight back to
+ * the renderer, so a callout inside a list item is the very same callout module
+ * as one at document level (CONTRACT C1).
+ */
+export default Object.freeze({
+  type: 'list',
+
+  schema: Object.freeze({
+    required: ['ordered', 'items'],
+    properties: { ordered: { type: 'boolean' }, items: itemGroups },
+  }),
+
+  example: Object.freeze({
+    block: {
+      id: 'b11',
+      type: 'list',
+      ordered: false,
+      items: [
+        [{ id: 'b12', type: 'prose', html: '項目一：每個項目是一組 block。' }],
+        [
+          { id: 'b13', type: 'prose', html: '項目二：所以項目內可以放別的 block。' },
+          {
+            id: 'b14',
+            type: 'callout',
+            variant: 'note',
+            children: [{ id: 'b15', type: 'prose', html: '像這個 callout。' }],
+          },
+        ],
+      ],
+    },
+  }),
+
+  /** `items` is an array *of arrays* — the only matrix shape in the vocabulary. */
+  nesting: Object.freeze({ matrices: Object.freeze(['items']) }),
+
+  styleHooks: Object.freeze(['list']),
+
+  create: ({ ordered, items }) => Object.freeze({ type: 'list', ordered, items }),
+
+  render: (block, ctx) =>
+    el(
+      block.ordered ? 'ol' : 'ul',
+      { class: 'list' },
+      (block.items ?? []).map((item) => el('li', null, ctx.renderChildren(item))),
+    ),
+})

package/src/blocks/placement.js

@@ -0,0 +1,119 @@
+/**
+ * The 24-column placement vocabulary — the *only* coordinates the IR carries.
+ *
+ * It lives beside `element.js` rather than inside `grid.js` or inside a layout
+ * because three different layers have to agree on it and none of them may own
+ * it (wayfinder issue 14 裁決 2):
+ *
+ *  - the `grid` block module validates its children against it,
+ *  - `core/schema.js` widens `$defs.block` with it, so *any* block may carry a
+ *    placement without every block module having to declare four fields,
+ *  - the render layer divides the available width by it before a diagram is
+ *    measured (issue 14 裁決 3「diagram 一律收實際可用寬」).
+ *
+ * Four integers and nothing else. No units, no gaps, no alignment: appearance
+ * never enters the IR (issue 13 裁決 5), so what an author writes is *which
+ * cells this block occupies*, and what that looks like stays a template's
+ * business. A block with no placement is flow content, exactly as before —
+ * 「不包＝預設流式」.
+ */
+
+/** Verbatim — the grid is 24 columns wide. Never configurable: it is vocabulary. */
+export const GRID_COLUMNS = 24
+
+/** Verbatim — the four placement field names, in declaration order. */
+export const PLACEMENT_KEYS = Object.freeze(['col', 'row', 'colSpan', 'rowSpan'])
+
+/** The two field names that only mean something where rows are fixed. */
+export const ROW_KEYS = Object.freeze(['row', 'rowSpan'])
+
+const gridInteger = Object.freeze({ type: 'integer', minimum: 1, maximum: GRID_COLUMNS })
+
+/**
+ * The placement fields as JSON Schema, for merging into `$defs.block`.
+ *
+ * Bounds are expressible here, so they are checked here — that is what puts a
+ * bad `col` in front of `lint` with a block path attached, without the document
+ * ever reaching a renderer. What a schema keyword *cannot* say is that
+ * `col + colSpan - 1` must still land inside 24 columns; that relational rule
+ * belongs to the `grid` module's own `validate`.
+ */
+export const PLACEMENT_PROPERTIES = Object.freeze(
+  Object.fromEntries(PLACEMENT_KEYS.map((key) => [key, gridInteger])),
+)
+
+/** Whether a block carries any placement at all (absence means flow content). */
+export const hasPlacement = (block) =>
+  PLACEMENT_KEYS.some((key) => block?.[key] !== undefined && block[key] !== null)
+
+/** Whether a block carries row vocabulary (legal only where rows are fixed). */
+export const hasRowVocabulary = (block) =>
+  ROW_KEYS.some((key) => block?.[key] !== undefined && block[key] !== null)
+
+const isGridInteger = (value) =>
+  Number.isInteger(value) && value >= 1 && value <= GRID_COLUMNS
+
+/**
+ * The span rule for one axis, as human-readable problems.
+ *
+ * Out-of-range values are *not* re-reported here: the schema already refuses
+ * them, and saying it twice in two wordings would give an author two different
+ * sentences for one mistake. What is reported is only the relation the schema
+ * cannot express — a span whose far edge falls outside the 24 columns.
+ */
+const axisProblems = (where, block, startKey, spanKey, edgeWord) => {
+  const start = block?.[startKey]
+  const span = block?.[spanKey]
+  if (!isGridInteger(start) || !isGridInteger(span)) return []
+  const edge = start + span - 1
+  if (edge <= GRID_COLUMNS) return []
+  return [
+    `${where} 的 ${startKey} ${start} ＋ ${spanKey} ${span} 讓${edgeWord}落在第 ${edge} 格，` +
+      `超出 ${GRID_COLUMNS} 格`,
+  ]
+}
+
+/**
+ * Every relational placement problem of one block, as human-readable messages.
+ * Empty array means the block's placement is expressible on a 24-column grid.
+ *
+ * @param {string} where how to name this block in a message (e.g. `children[2]`)
+ *
+ * The edge word is per axis. It used to be 「右緣」 for both, so a `row 20 ＋
+ * rowSpan 8` was reported as a *right* edge falling outside — a sentence that
+ * sends the reader to look at the wrong axis of their own layout. Nobody hit it
+ * before F2f because rows were only legal inside an explicit grid; the
+ * grid-addressed page made row coordinates ordinary, so the wording had to
+ * become true.
+ */
+export const placementProblems = (where, block) => [
+  ...axisProblems(where, block, 'col', 'colSpan', '右緣'),
+  ...axisProblems(where, block, 'row', 'rowSpan', '下緣'),
+]
+
+/**
+ * The CSS a placement means, as an inline `style` value — or `null` for none.
+ *
+ * Geometry is inline rather than in a stylesheet because it is a property of
+ * *what a grid is*, not of who painted it: a template that never heard of grids
+ * must still draw one correctly, and a template that has opinions still owns
+ * every colour, gap and border through the `grid`/`grid-cell` hooks. The same
+ * reasoning that makes deck playback a skeleton asset makes this one inline.
+ */
+export function placementStyle(block) {
+  const span = isGridInteger(block?.colSpan) ? block.colSpan : GRID_COLUMNS
+  const col = isGridInteger(block?.col) ? block.col : 'auto'
+  const parts = [`grid-column: ${col} / span ${span}`]
+  if (hasRowVocabulary(block)) {
+    const rowSpan = isGridInteger(block?.rowSpan) ? block.rowSpan : 1
+    const row = isGridInteger(block?.row) ? block.row : 'auto'
+    parts.push(`grid-row: ${row} / span ${rowSpan}`)
+  }
+  return parts.join('; ')
+}
+
+/** How much of `available` px a block occupies, given its column span. */
+export const placedWidth = (available, block) => {
+  const span = isGridInteger(block?.colSpan) ? block.colSpan : GRID_COLUMNS
+  return Math.floor((available * span) / GRID_COLUMNS)
+}

package/src/blocks/prose.js

@@ -0,0 +1,28 @@
+import { rawEl } from './element.js'
+import { str } from './schema-parts.js'
+
+/**
+ * Block-level flow content that `<p>` may not contain. A `<p>` wrapping a
+ * `<ul>` is invalid HTML: the parser implicitly closes the paragraph, so the
+ * real DOM becomes an empty `<p>`, a list that has escaped the `.prose`
+ * styling scope, and another empty `<p>`. Pick the container to match.
+ */
+const BLOCK_LEVEL_CONTENT = /<(?:ul|ol|div|pre|table|blockquote|figure|hr|h[1-6])\b/i
+
+/** `prose` — one run of inline Markdown, already compiled to HTML by the parser. */
+export default Object.freeze({
+  type: 'prose',
+
+  schema: Object.freeze({ required: ['html'], properties: { html: str } }),
+
+  example: Object.freeze({
+    block: { id: 'b3', type: 'prose', html: '散文段落，行內 Markdown 已編譯為 HTML。' },
+  }),
+
+  styleHooks: Object.freeze(['prose']),
+
+  create: (html) => Object.freeze({ type: 'prose', html }),
+
+  render: (block) =>
+    rawEl(BLOCK_LEVEL_CONTENT.test(block.html) ? 'div' : 'p', { class: 'prose' }, block.html),
+})

package/src/blocks/quote.js

@@ -0,0 +1,25 @@
+import { el } from './element.js'
+import { children } from './schema-parts.js'
+
+/** `quote` — a block quotation whose contents are ordinary child blocks. */
+export default Object.freeze({
+  type: 'quote',
+
+  schema: Object.freeze({ required: ['children'], properties: { children } }),
+
+  example: Object.freeze({
+    block: {
+      id: 'b4',
+      type: 'quote',
+      children: [{ id: 'b5', type: 'prose', html: '被引用的一段話。' }],
+    },
+  }),
+
+  nesting: Object.freeze({ arrays: Object.freeze(['children']) }),
+
+  styleHooks: Object.freeze(['quote']),
+
+  create: (kids) => Object.freeze({ type: 'quote', children: kids }),
+
+  render: (block, ctx) => el('blockquote', { class: 'quote' }, ctx.renderChildren(block.children)),
+})

package/src/blocks/raw.js

@@ -0,0 +1,47 @@
+import { rawEl } from './element.js'
+import { str } from './schema-parts.js'
+
+/** The two island flavours: arbitrary markup, or a drawing. */
+export const RAW_SUBTYPES = Object.freeze(['html', 'svg'])
+
+/**
+ * `raw` — the escape hatch (SPEC §11 島嶼).
+ *
+ * `intent` is required and non-empty on purpose: an island is a confession that
+ * the vocabulary could not say something, and the confession has to record
+ * *what*. That record is what later promotes a recurring island into a real
+ * plugin block instead of leaving hand-written HTML to accumulate forever.
+ */
+export default Object.freeze({
+  type: 'raw',
+
+  schema: Object.freeze({
+    required: ['subtype', 'intent', 'html'],
+    properties: {
+      subtype: { enum: [...RAW_SUBTYPES] },
+      intent: { ...str, minLength: 1 },
+      html: str,
+    },
+  }),
+
+  example: Object.freeze({
+    block: {
+      id: 'b10',
+      type: 'raw',
+      subtype: 'html',
+      intent: '為何需要手寫這塊',
+      html: '<div class="island">手寫內容</div>',
+    },
+  }),
+
+  styleHooks: Object.freeze(['island']),
+
+  create: ({ subtype, intent, html }) => Object.freeze({ type: 'raw', subtype, intent, html }),
+
+  render: (block) =>
+    rawEl(
+      block.subtype === 'svg' ? 'figure' : 'div',
+      { class: 'island', 'data-intent': block.intent },
+      block.html,
+    ),
+})