@onioneko/boardkit-blocks 0.1.0

package/dist/status.js

@@ -0,0 +1,82 @@
+export const statusBlock = {
+    type: "status",
+    schema: {
+        type: "object",
+        required: ["id", "states", "value"],
+        properties: {
+            id: { type: "string" },
+            title: { type: "string" },
+            states: { type: "array", items: { type: "string" }, minItems: 1 },
+            value: { type: "string" },
+            note: { type: "string" },
+        },
+        additionalProperties: false,
+    },
+    // Declared `attrs: unknown` on purpose, wider than `Readonly<StatusAttrs>`
+    // (a function accepting `unknown` is assignable wherever a narrower-param
+    // function is expected, so this still satisfies `BlockType<StatusAttrs>`).
+    // `validate` is called directly by hosts and tests with arbitrary/possibly
+    // malformed data (its own doc contract says "never throws" — see
+    // BlockType.validate in core), so the null/non-object case is guarded
+    // before any property access, not just trusted from the generic.
+    validate: (attrs) => {
+        if (typeof attrs !== "object" || attrs === null)
+            return [];
+        const { value, states } = attrs;
+        if (Array.isArray(states) && typeof value === "string" && !states.includes(value)) {
+            return [{ code: "E_STATUS_VALUE", message: `value "${value}" is not in states` }];
+        }
+        return [];
+    },
+    transitions: [{ attr: "value", event: "status.changed" }],
+    affordances: [
+        {
+            name: "transition",
+            params: {
+                type: "object",
+                required: ["to"],
+                properties: { to: { type: "string" } },
+                additionalProperties: false,
+            },
+            patch: (_attrs, params) => ({ value: params.to }),
+        },
+    ],
+    project: {
+        text: (attrs) => {
+            const value = String(attrs.value);
+            const title = String(attrs.title ?? "").trim();
+            return title === "" ? `**STATUS**: ${value}` : `**STATUS**: ${value} — ${title}`;
+        },
+        html: (attrs) => {
+            const states = attrs.states;
+            const value = String(attrs.value);
+            const buttons = states
+                .filter((state) => state !== value)
+                .map((state) => ({
+                type: "element",
+                tagName: "button",
+                properties: {
+                    "data-intent": JSON.stringify({ affordance: "transition", params: { to: state } }),
+                },
+                children: [{ type: "text", value: state }],
+            }));
+            return {
+                type: "element",
+                tagName: "div",
+                // The state is data, not styling: one attribute holds it whatever it
+                // contains, and the class list stays fixed.
+                properties: { className: ["status"], "data-state": value },
+                children: [
+                    {
+                        type: "element",
+                        tagName: "span",
+                        properties: { className: ["badge"] },
+                        children: [{ type: "text", value }],
+                    },
+                    ...buttons,
+                ],
+            };
+        },
+    },
+};
+//# sourceMappingURL=status.js.map

package/dist/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@onioneko/boardkit-blocks",
+  "version": "0.1.0",
+  "description": "BoardKit's reference block pack: checklist, status, metric, chart, form and rule block types for the BoardKit engine.",
+  "keywords": [
+    "markdown",
+    "board",
+    "blocks",
+    "checklist",
+    "agents",
+    "boardkit"
+  ],
+  "homepage": "https://github.com/onioneko/boardkit/tree/main/packages/blocks#readme",
+  "bugs": {
+    "url": "https://github.com/onioneko/boardkit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/onioneko/boardkit.git",
+    "directory": "packages/blocks"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "onioneko",
+    "url": "https://github.com/onioneko"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/__fixtures__"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@onioneko/boardkit-core": ">=0.1.0 <1.0.0"
+  },
+  "devDependencies": {
+    "@types/hast": "^3.0.0",
+    "hast-util-from-html": "^2.0.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0",
+    "@onioneko/boardkit-core": "^0.1.0",
+    "@onioneko/boardkit-html": "^0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/chart.ts

@@ -0,0 +1,43 @@
+import type { BlockType } from "@onioneko/boardkit-core";
+
+/**
+ * starter block: chart — an opaque chart source. The text hook emits the spec
+ * verbatim (machine-readable); the html hook falls back to a `<pre>` because
+ * the library does not know chart libraries — hosts register their own block
+ * type (or renderer) to replace this fallback.
+ *
+ * Usage: a chart body carries `{ id, type, source, spec }`; `spec` is the
+ * chart's own DSL and is rendered untouched.
+ */
+
+/** Attrs for the `chart` block, mirroring its JSON Schema. */
+export type ChartAttrs = {
+  readonly id: string;
+  readonly type: string;
+  readonly source: string;
+  readonly spec: string;
+};
+
+export const chartBlock: BlockType<ChartAttrs> = {
+  type: "chart",
+  schema: {
+    type: "object",
+    required: ["id", "type", "source", "spec"],
+    properties: {
+      id: { type: "string" },
+      type: { type: "string" },
+      source: { type: "string" },
+      spec: { type: "string" },
+    },
+    additionalProperties: false,
+  },
+  project: {
+    text: (attrs) => String(attrs.spec),
+    html: (attrs): import("hast").Nodes => ({
+      type: "element",
+      tagName: "pre",
+      properties: { className: ["chart"], "data-source": String(attrs.source) },
+      children: [{ type: "text", value: String(attrs.spec) }],
+    }),
+  },
+};

package/src/checklist.ts

@@ -0,0 +1,123 @@
+import type { BlockType } from "@onioneko/boardkit-core";
+
+/**
+ * starter block: checklist — a list of labeled checkbox items. Each item is
+ * `{ id, label, done }`; the `toggle` affordance flips one item's `done` flag.
+ *
+ * The item-toggle transition names events by direction: checking a box emits
+ * `checklist.item.done` (false→true), unchecking it emits
+ * `checklist.item.undone` (true→false); both carry the `from`/`to` booleans.
+ *
+ * Usage: include in `createEngine({ blocks })` and add `"checklist"` to the
+ * parse options' `blockTypes` set so checklist fences are parsed as blocks.
+ */
+
+/** Attrs for the `checklist` block, mirroring its JSON Schema. */
+export type ChecklistAttrs = {
+  readonly id: string;
+  readonly title?: string;
+  readonly items: readonly {
+    readonly id: string;
+    readonly label: string;
+    readonly done: boolean;
+  }[];
+};
+
+export const checklistBlock: BlockType<ChecklistAttrs> = {
+  type: "checklist",
+  schema: {
+    type: "object",
+    required: ["id", "items"],
+    properties: {
+      id: { type: "string" },
+      title: { type: "string" },
+      items: {
+        type: "array",
+        items: {
+          type: "object",
+          required: ["id", "label", "done"],
+          properties: {
+            id: { type: "string" },
+            label: { type: "string" },
+            done: { type: "boolean" },
+          },
+          additionalProperties: false,
+        },
+      },
+    },
+    additionalProperties: false,
+  },
+  transitions: [
+    {
+      attr: "items[].done",
+      events: {
+        "false→true": "checklist.item.done",
+        "true→false": "checklist.item.undone",
+      },
+    },
+  ],
+  affordances: [
+    {
+      name: "toggle",
+      params: {
+        type: "object",
+        required: ["itemId"],
+        properties: { itemId: { type: "string" } },
+        additionalProperties: false,
+      },
+      patch: (attrs, params) => {
+        const itemId = (params as { itemId: string }).itemId;
+        const items = attrs.items.map((item) =>
+          item.id === itemId ? { ...item, done: !item.done } : item,
+        );
+        return { items };
+      },
+    },
+  ],
+  project: {
+    text: (attrs) => {
+      const items = attrs.items;
+      return items.map((item) => `- [${item.done ? "x" : " "}] ${item.label}`).join("\n");
+    },
+    html: (attrs): import("hast").Nodes => {
+      const items = attrs.items;
+      return {
+        type: "element",
+        tagName: "ul",
+        properties: { className: ["checklist"] },
+        // Each item's input and label text are wrapped in a `<label>` so a
+        // click anywhere on the item — not just the tiny box — toggles it
+        // natively; `data-intent` stays on the `<input>` itself (the existing
+        // contract the page's `closest('[data-intent]')` handler reads).
+        children: items.map((item) => ({
+          type: "element",
+          tagName: "li",
+          properties: {},
+          children: [
+            {
+              type: "element",
+              tagName: "label",
+              properties: {},
+              children: [
+                {
+                  type: "element",
+                  tagName: "input",
+                  properties: {
+                    type: "checkbox",
+                    ...(item.done ? { checked: true } : {}),
+                    "data-intent": JSON.stringify({
+                      affordance: "toggle",
+                      params: { itemId: item.id },
+                    }),
+                  },
+                  children: [],
+                },
+                { type: "text", value: item.label },
+              ],
+            },
+          ],
+        })),
+      };
+    },
+  },
+};

package/src/form.ts

@@ -0,0 +1,101 @@
+import type { BlockType } from "@onioneko/boardkit-core";
+
+/**
+ * starter block: form — a question with typed fields. Answering is the `answer`
+ * affordance; the view adapter assembles entered values into the intent params
+ * at interaction time (outside the block's concern).
+ *
+ * Usage: a form has `fields` (each with `id`, `label`, `type`, and optional
+ * `options`) and a `status` of `open` or `answered`. The `answer` affordance
+ * stores the assembled values in `answer`, flips `status` to `answered`, and
+ * emits `form.answered`.
+ */
+
+/** Attrs for the `form` block, mirroring its JSON Schema. */
+export type FormAttrs = {
+  readonly id: string;
+  readonly title?: string;
+  readonly fields: readonly {
+    readonly id: string;
+    readonly label: string;
+    readonly type: "text" | "select" | "number";
+    readonly options?: readonly string[];
+  }[];
+  readonly status: "open" | "answered";
+  readonly answer?: Record<string, unknown>;
+};
+
+export const formBlock: BlockType<FormAttrs> = {
+  type: "form",
+  schema: {
+    type: "object",
+    required: ["id", "fields", "status"],
+    properties: {
+      id: { type: "string" },
+      title: { type: "string" },
+      fields: {
+        type: "array",
+        items: {
+          type: "object",
+          required: ["id", "label", "type"],
+          properties: {
+            id: { type: "string" },
+            label: { type: "string" },
+            type: { enum: ["text", "select", "number"] },
+            options: { type: "array", items: { type: "string" } },
+          },
+          additionalProperties: false,
+        },
+      },
+      status: { enum: ["open", "answered"] },
+      answer: { type: "object" },
+    },
+    additionalProperties: false,
+  },
+  transitions: [{ attr: "status", event: "form.answered" }],
+  affordances: [
+    {
+      name: "answer",
+      params: { type: "object" },
+      patch: (_attrs, params) => ({
+        answer: params as Record<string, unknown>,
+        status: "answered",
+      }),
+    },
+  ],
+  project: {
+    text: (attrs) => {
+      const fields = attrs.fields;
+      const lines = fields.map((field) => {
+        const suffix =
+          field.options !== undefined && field.options.length > 0
+            ? ` (${field.options.join("/")})`
+            : "";
+        return `- ${field.label}${suffix}`;
+      });
+      return lines.join("\n");
+    },
+    html: (attrs): import("hast").Nodes => {
+      const fields = attrs.fields;
+      return {
+        type: "element",
+        tagName: "div",
+        properties: { className: ["form"] },
+        children: fields.map((field) => ({
+          type: "element",
+          tagName: "label",
+          properties: {},
+          children: [
+            { type: "text", value: field.label },
+            {
+              type: "element",
+              tagName: "input",
+              properties: { type: field.type === "number" ? "number" : "text", name: field.id },
+              children: [],
+            },
+          ],
+        })),
+      };
+    },
+  },
+};

package/src/index.ts

@@ -0,0 +1,45 @@
+/**
+ * The starter block pack: six ready-made block types, exported together for
+ * convenience. Hosts that do not want every block may build their own array
+ * from the individual exports.
+ */
+
+export type { ChartAttrs } from "./chart.js";
+export { chartBlock } from "./chart.js";
+export type { ChecklistAttrs } from "./checklist.js";
+export { checklistBlock } from "./checklist.js";
+export type { FormAttrs } from "./form.js";
+export { formBlock } from "./form.js";
+export type { MetricAttrs } from "./metric.js";
+export { metricBlock } from "./metric.js";
+export type { RuleAttrs } from "./rule.js";
+export { ruleBlock } from "./rule.js";
+export type { StatusAttrs } from "./status.js";
+export { statusBlock } from "./status.js";
+
+import type { AnyBlockType } from "@onioneko/boardkit-core";
+import { chartBlock } from "./chart.js";
+import { checklistBlock } from "./checklist.js";
+import { formBlock } from "./form.js";
+import { metricBlock } from "./metric.js";
+import { ruleBlock } from "./rule.js";
+import { statusBlock } from "./status.js";
+
+/**
+ * All six starter blocks, ready to pass to `createEngine({ blocks })`.
+ * @example
+ * ```ts
+ * const engine = createEngine({
+ *   storage: createMemStorage(),
+ *   blocks: starterBlocks,
+ * });
+ * ```
+ */
+export const starterBlocks: readonly AnyBlockType[] = [
+  checklistBlock,
+  statusBlock,
+  metricBlock,
+  chartBlock,
+  formBlock,
+  ruleBlock,
+];

package/src/metric.ts

@@ -0,0 +1,58 @@
+import type { BlockType } from "@onioneko/boardkit-core";
+
+/**
+ * starter block: metric — a labeled live value backed by a source. Hooks
+ * receive resolved values keyed by source id, so the metric's value is injected
+ * at projection time and never persisted.
+ *
+ * Usage: a metric's `source` field names a source id; the block declares it
+ * through `sources`, so the value is resolved from the block alone — the
+ * document needs no `{{source:…}}` prose ref. The resolved value (optionally
+ * annotated by `view`/`thresholds`) is rendered next to its `label`; an
+ * unresolved (absent or stale) value falls back to the source id.
+ */
+
+/** Attrs for the `metric` block, mirroring its JSON Schema. */
+export type MetricAttrs = {
+  readonly id: string;
+  readonly label: string;
+  readonly source: string;
+  readonly view?: "value" | "sparkline" | "chart";
+  readonly thresholds?: readonly number[];
+};
+
+export const metricBlock: BlockType<MetricAttrs> = {
+  type: "metric",
+  schema: {
+    type: "object",
+    required: ["id", "label", "source"],
+    properties: {
+      id: { type: "string" },
+      label: { type: "string" },
+      source: { type: "string" },
+      view: { enum: ["value", "sparkline", "chart"] },
+      thresholds: { type: "array", items: { type: "number" } },
+    },
+    additionalProperties: false,
+  },
+  sources: (attrs) =>
+    typeof attrs.source === "string" ? [{ kind: "source", source: attrs.source, params: {} }] : [],
+  project: {
+    text: (attrs, values) =>
+      `${String(attrs.label)}: ${values[String(attrs.source)] ?? String(attrs.source)}`,
+    html: (attrs, values): import("hast").Nodes => ({
+      type: "element",
+      tagName: "span",
+      properties: { className: ["metric"] },
+      children: [
+        {
+          type: "element",
+          tagName: "strong",
+          properties: {},
+          children: [{ type: "text", value: String(attrs.label) }],
+        },
+        { type: "text", value: ` ${values[String(attrs.source)] ?? String(attrs.source)}` },
+      ],
+    }),
+  },
+};

package/src/rule.ts

@@ -0,0 +1,64 @@
+import type { BlockType } from "@onioneko/boardkit-core";
+
+/**
+ * starter block: rule — an opaque when/do automation with an enabled switch.
+ * The library validates only presence and type; the semantics of `when`/`do`
+ * belong to the host.
+ *
+ * Usage: the `toggle` affordance flips `enabled`, emitting `rule.enabled`; the
+ * host observes that event (or reads the block) to execute the rule.
+ */
+
+/** Attrs for the `rule` block, mirroring its JSON Schema. */
+export type RuleAttrs = {
+  readonly id: string;
+  readonly title?: string;
+  readonly when: string;
+  readonly do: string;
+  readonly enabled: boolean;
+};
+
+export const ruleBlock: BlockType<RuleAttrs> = {
+  type: "rule",
+  schema: {
+    type: "object",
+    required: ["id", "when", "do", "enabled"],
+    properties: {
+      id: { type: "string" },
+      title: { type: "string" },
+      when: { type: "string" },
+      do: { type: "string" },
+      enabled: { type: "boolean" },
+    },
+    additionalProperties: false,
+  },
+  transitions: [{ attr: "enabled", event: "rule.enabled" }],
+  affordances: [
+    {
+      name: "toggle",
+      patch: (attrs) => ({ enabled: !attrs.enabled }),
+    },
+  ],
+  project: {
+    text: (attrs) =>
+      `- rule ${attrs.enabled === true ? "(enabled)" : "(disabled)"}: when ${String(attrs.when)} do ${String(attrs.do)}`,
+    html: (attrs): import("hast").Nodes => ({
+      type: "element",
+      tagName: "div",
+      properties: { className: ["rule"] },
+      children: [
+        {
+          type: "element",
+          tagName: "input",
+          properties: {
+            type: "checkbox",
+            ...(attrs.enabled === true ? { checked: "" } : {}),
+            "data-intent": JSON.stringify({ affordance: "toggle" }),
+          },
+          children: [],
+        },
+        { type: "text", value: ` when ${String(attrs.when)} do ${String(attrs.do)}` },
+      ],
+    }),
+  },
+};