@duckpic/content-spec 0.2.2 → 0.2.3

package/dist/components/ComponentSpec.d.ts

@@ -1,4 +1,23 @@
-import type { ZodType } from "zod";
+import type { ZodType, ZodTypeAny } from "zod";
+export interface ComponentIoChannelSpec {
+    /**
+     * Optional Zod schema to describe the runtime value shape for this channel.
+     * This is metadata for wiring / tooling; not validated at authoring time.
+     */
+    schema?: ZodTypeAny;
+    /**
+     * Human-friendly type name (e.g. "VocabId[]") the editor can display.
+     */
+    valueType?: string;
+    /**
+     * Optional description to surface in UI hints.
+     */
+    description?: string;
+}
+export interface ComponentIoSpec {
+    inputs?: Record<string, ComponentIoChannelSpec>;
+    outputs?: Record<string, ComponentIoChannelSpec>;
+}
 export interface ComponentUiMetadata {
     /**
      * Human-friendly label for menus and UI surfaces.
@@ -21,5 +40,9 @@ export interface ComponentSpec {
     type: string;
     propsSchema: ZodType<any>;
     slots: string[];
+    /**
+     * Optional runtime input/output channels for dynamic data wiring.
+     */
+    io?: ComponentIoSpec;
     ui?: ComponentUiMetadata;
 }

package/dist/components/VocabularyList.d.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+import type { ComponentSpec } from "./ComponentSpec";
+export declare const VocabularyListPropsSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    staticVocabIds: z.ZodArray<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const VocabularyListComponentSpec: ComponentSpec;

package/dist/components/VocabularyList.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+export const VocabularyListPropsSchema = z.object({
+    title: z.string().optional(),
+    staticVocabIds: z.array(z.number()).min(1)
+});
+export const VocabularyListComponentSpec = {
+    type: "VocabularyList",
+    propsSchema: VocabularyListPropsSchema,
+    slots: [],
+    io: {
+        inputs: {
+            extraVocabIds: {
+                schema: z.array(z.number()),
+                valueType: "VocabId[]",
+                description: "Additional vocab ids injected at runtime (e.g. incorrect answers)."
+            }
+        },
+        outputs: {
+            selectedVocabIds: {
+                schema: z.array(z.number()),
+                valueType: "VocabId[]",
+                description: "Ids the student marked or selected in this list."
+            }
+        }
+    },
+    ui: {
+        label: "Vocabulary list",
+        insertable: true,
+        insertMenuOrder: 50,
+    }
+};

package/dist/index.d.ts

@@ -4,8 +4,9 @@ export * from "./components/Layout";
 export * from "./components/Page";
 export * from "./components/Multipage";
 export * from "./components/Video";
+export * from "./components/VocabularyList";
 export * from "./schema/PageTree";
-import type { ComponentSpec, ComponentUiMetadata } from "./components/ComponentSpec.ts";
+import type { ComponentSpec } from "./components/ComponentSpec.ts";
 export declare const ComponentRegistry: {
     Text: ComponentSpec;
     Quiz: ComponentSpec;
@@ -13,9 +14,10 @@ export declare const ComponentRegistry: {
     Page: ComponentSpec;
     Multipage: ComponentSpec;
     Video: ComponentSpec;
+    VocabularyList: ComponentSpec;
 };
 export type ComponentType = keyof typeof ComponentRegistry;
 export declare function getPropsSchema(type: ComponentType): import("zod").ZodType<any, unknown, import("zod/v4/core").$ZodTypeInternals<any, unknown>>;
 export declare function getInsertableComponentEntries(): Array<[ComponentType, ComponentSpec]>;
 export declare function getInsertableComponentTypes(): ComponentType[];
-export type { ComponentSpec, ComponentUiMetadata };
+export type { ComponentSpec, ComponentUiMetadata, ComponentIoSpec, ComponentIoChannelSpec } from "./components/ComponentSpec";

package/dist/index.js

@@ -4,6 +4,7 @@ export * from "./components/Layout";
 export * from "./components/Page";
 export * from "./components/Multipage";
 export * from "./components/Video";
+export * from "./components/VocabularyList";
 export * from "./schema/PageTree";
 import { TextComponentSpec } from "./components/Text";
 import { QuizComponentSpec } from "./components/Quiz";
@@ -11,6 +12,7 @@ import { LayoutComponentSpec } from "./components/Layout";
 import { PageComponentSpec } from "./components/Page";
 import { MultipageComponentSpec } from "./components/Multipage";
 import { VideoComponentSpec } from "./components/Video";
+import { VocabularyListComponentSpec } from "./components/VocabularyList";
 export const ComponentRegistry = {
     Text: TextComponentSpec,
     Quiz: QuizComponentSpec,
@@ -18,6 +20,7 @@ export const ComponentRegistry = {
     Page: PageComponentSpec,
     Multipage: MultipageComponentSpec,
     Video: VideoComponentSpec,
+    VocabularyList: VocabularyListComponentSpec,
 };
 // Helper to get a schema by type
 export function getPropsSchema(type) {

package/dist/schema/PageTree.d.ts

@@ -1,12 +1,35 @@
 import { z } from "zod";
 export declare const NodeIdSchema: z.ZodString;
+export declare const RuntimeVariableSchema: z.ZodString;
+export declare const RuntimeBindingSchema: z.ZodObject<{
+    var: z.ZodString;
+}, z.core.$strip>;
+export declare const NodeBindingsSchema: z.ZodObject<{
+    inputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        var: z.ZodString;
+    }, z.core.$strip>>>;
+    outputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        var: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
 export declare const ContentNodeSchema: z.ZodObject<{
     id: z.ZodString;
     type: z.ZodString;
     props: z.ZodRecord<z.ZodString, z.ZodAny>;
     slots: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
+    bindings: z.ZodOptional<z.ZodObject<{
+        inputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            var: z.ZodString;
+        }, z.core.$strip>>>;
+        outputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            var: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ContentNode = z.infer<typeof ContentNodeSchema>;
+export type RuntimeVariable = z.infer<typeof RuntimeVariableSchema>;
+export type RuntimeBinding = z.infer<typeof RuntimeBindingSchema>;
+export type NodeBindings = z.infer<typeof NodeBindingsSchema>;
 export declare const PageTreeSchema: z.ZodObject<{
     version: z.ZodString;
     root: z.ZodString;
@@ -15,6 +38,14 @@ export declare const PageTreeSchema: z.ZodObject<{
         type: z.ZodString;
         props: z.ZodRecord<z.ZodString, z.ZodAny>;
         slots: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
+        bindings: z.ZodOptional<z.ZodObject<{
+            inputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                var: z.ZodString;
+            }, z.core.$strip>>>;
+            outputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                var: z.ZodString;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type PageTree = z.infer<typeof PageTreeSchema>;

package/dist/schema/PageTree.js

@@ -1,11 +1,20 @@
 import { z } from "zod";
 export const NodeIdSchema = z.string().min(1);
 // You can switch to stricter UUID validation later.
+export const RuntimeVariableSchema = z.string().min(1);
+export const RuntimeBindingSchema = z.object({
+    var: RuntimeVariableSchema
+});
+export const NodeBindingsSchema = z.object({
+    inputs: z.record(z.string().min(1), RuntimeBindingSchema).optional(),
+    outputs: z.record(z.string().min(1), RuntimeBindingSchema).optional(),
+});
 export const ContentNodeSchema = z.object({
     id: NodeIdSchema,
     type: z.string(), // we'll refine typing later
     props: z.record(z.string(), z.any()), // key: string, value: any
-    slots: z.record(z.string(), z.array(NodeIdSchema))
+    slots: z.record(z.string(), z.array(NodeIdSchema)),
+    bindings: NodeBindingsSchema.optional()
 });
 export const PageTreeSchema = z.object({
     version: z.string(),

package/dist/validators/validateNode.js

@@ -14,4 +14,26 @@ export function validateNode(node) {
             throw new Error(`Invalid slot '${slotName}' for component type ${node.type}`);
         }
     }
+    // 3) Validate runtime bindings
+    if (node.bindings) {
+        if (!spec.io) {
+            throw new Error(`Component type ${node.type} does not support runtime bindings`);
+        }
+        if (node.bindings.inputs) {
+            const allowedInputs = spec.io.inputs ?? {};
+            for (const inputName of Object.keys(node.bindings.inputs)) {
+                if (!allowedInputs[inputName]) {
+                    throw new Error(`Invalid input binding '${inputName}' for component type ${node.type}`);
+                }
+            }
+        }
+        if (node.bindings.outputs) {
+            const allowedOutputs = spec.io.outputs ?? {};
+            for (const outputName of Object.keys(node.bindings.outputs)) {
+                if (!allowedOutputs[outputName]) {
+                    throw new Error(`Invalid output binding '${outputName}' for component type ${node.type}`);
+                }
+            }
+        }
+    }
 }

package/dist/validators/validatePageTree.d.ts

@@ -6,5 +6,13 @@ export declare function validatePageTree(tree: unknown): {
         type: string;
         props: Record<string, any>;
         slots: Record<string, string[]>;
+        bindings?: {
+            inputs?: Record<string, {
+                var: string;
+            }> | undefined;
+            outputs?: Record<string, {
+                var: string;
+            }> | undefined;
+        } | undefined;
     }>;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duckpic/content-spec",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",

package/src/components/ComponentSpec.ts

@@ -1,4 +1,25 @@
-import type { ZodType } from "zod";
+import type { ZodType, ZodTypeAny } from "zod";
+
+export interface ComponentIoChannelSpec {
+  /**
+   * Optional Zod schema to describe the runtime value shape for this channel.
+   * This is metadata for wiring / tooling; not validated at authoring time.
+   */
+  schema?: ZodTypeAny;
+  /**
+   * Human-friendly type name (e.g. "VocabId[]") the editor can display.
+   */
+  valueType?: string;
+  /**
+   * Optional description to surface in UI hints.
+   */
+  description?: string;
+}
+
+export interface ComponentIoSpec {
+  inputs?: Record<string, ComponentIoChannelSpec>;
+  outputs?: Record<string, ComponentIoChannelSpec>;
+}
 
 export interface ComponentUiMetadata {
   /**
@@ -23,5 +44,9 @@ export interface ComponentSpec {
   type: string;
   propsSchema: ZodType<any>;
   slots: string[];
+  /**
+   * Optional runtime input/output channels for dynamic data wiring.
+   */
+  io?: ComponentIoSpec;
   ui?: ComponentUiMetadata;
 }

package/src/components/VocabularyList.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import type { ComponentSpec } from "./ComponentSpec";
+
+export const VocabularyListPropsSchema = z.object({
+  title: z.string().optional(),
+  staticVocabIds: z.array(z.number()).min(1)
+});
+
+export const VocabularyListComponentSpec: ComponentSpec = {
+  type: "VocabularyList",
+  propsSchema: VocabularyListPropsSchema,
+  slots: [],
+  io: {
+    inputs: {
+      extraVocabIds: {
+        schema: z.array(z.number()),
+        valueType: "VocabId[]",
+        description: "Additional vocab ids injected at runtime (e.g. incorrect answers)."
+      }
+    },
+    outputs: {
+      selectedVocabIds: {
+        schema: z.array(z.number()),
+        valueType: "VocabId[]",
+        description: "Ids the student marked or selected in this list."
+      }
+    }
+  },
+  ui: {
+    label: "Vocabulary list",
+    insertable: true,
+    insertMenuOrder: 50,
+  }
+};

package/src/index.ts

@@ -4,6 +4,7 @@ export * from "./components/Layout";
 export * from "./components/Page";
 export * from "./components/Multipage";
 export * from "./components/Video";
+export * from "./components/VocabularyList";
 export * from "./schema/PageTree";
 
 
@@ -13,6 +14,7 @@ import { LayoutComponentSpec } from "./components/Layout";
 import { PageComponentSpec } from "./components/Page";
 import { MultipageComponentSpec } from "./components/Multipage";
 import { VideoComponentSpec } from "./components/Video";
+import { VocabularyListComponentSpec } from "./components/VocabularyList";
 import type { ComponentSpec, ComponentUiMetadata } from "./components/ComponentSpec.ts";
 
 export const ComponentRegistry = {
@@ -22,6 +24,7 @@ export const ComponentRegistry = {
   Page: PageComponentSpec,
   Multipage: MultipageComponentSpec,
   Video: VideoComponentSpec,
+  VocabularyList: VocabularyListComponentSpec,
 };
 
 export type ComponentType = keyof typeof ComponentRegistry;
@@ -60,4 +63,9 @@ export function getInsertableComponentTypes(): ComponentType[] {
   return getInsertableComponentEntries().map(([type]) => type);
 }
 
-export type { ComponentSpec, ComponentUiMetadata };
+export type {
+  ComponentSpec,
+  ComponentUiMetadata,
+  ComponentIoSpec,
+  ComponentIoChannelSpec
+} from "./components/ComponentSpec";

package/src/schema/PageTree.ts

@@ -3,14 +3,29 @@ import { z } from "zod";
 export const NodeIdSchema = z.string().min(1); 
 // You can switch to stricter UUID validation later.
 
+export const RuntimeVariableSchema = z.string().min(1);
+
+export const RuntimeBindingSchema = z.object({
+  var: RuntimeVariableSchema
+});
+
+export const NodeBindingsSchema = z.object({
+  inputs: z.record(z.string().min(1), RuntimeBindingSchema).optional(),
+  outputs: z.record(z.string().min(1), RuntimeBindingSchema).optional(),
+});
+
 export const ContentNodeSchema = z.object({
   id: NodeIdSchema,
   type: z.string(),                           // we'll refine typing later
   props: z.record(z.string(), z.any()),       // key: string, value: any
-  slots: z.record(z.string(), z.array(NodeIdSchema))
+  slots: z.record(z.string(), z.array(NodeIdSchema)),
+  bindings: NodeBindingsSchema.optional()
 });
 
 export type ContentNode = z.infer<typeof ContentNodeSchema>;
+export type RuntimeVariable = z.infer<typeof RuntimeVariableSchema>;
+export type RuntimeBinding = z.infer<typeof RuntimeBindingSchema>;
+export type NodeBindings = z.infer<typeof NodeBindingsSchema>;
 
 export const PageTreeSchema = z.object({
   version: z.string(),

package/src/validators/validateNode.ts

@@ -20,4 +20,35 @@ export function validateNode(node: ContentNode) {
       );
     }
   }
+
+  // 3) Validate runtime bindings
+  if (node.bindings) {
+    if (!spec.io) {
+      throw new Error(
+        `Component type ${node.type} does not support runtime bindings`
+      );
+    }
+
+    if (node.bindings.inputs) {
+      const allowedInputs = spec.io.inputs ?? {};
+      for (const inputName of Object.keys(node.bindings.inputs)) {
+        if (!allowedInputs[inputName]) {
+          throw new Error(
+            `Invalid input binding '${inputName}' for component type ${node.type}`
+          );
+        }
+      }
+    }
+
+    if (node.bindings.outputs) {
+      const allowedOutputs = spec.io.outputs ?? {};
+      for (const outputName of Object.keys(node.bindings.outputs)) {
+        if (!allowedOutputs[outputName]) {
+          throw new Error(
+            `Invalid output binding '${outputName}' for component type ${node.type}`
+          );
+        }
+      }
+    }
+  }
 }