Blocks

Blocks are the fundamental building elements that compose a slide in Pathway. Each block represents a piece of content or an interactive element that learners see and interact with.

Core Concepts

• Blocks are defined as an ordered array within each slide
• Each block has a unique id within its slide and a kind property that determines its type ("heading", "text", "button", etc.)
• Block definitions are validated with Zod schemas, with discriminated unions based on the kind property

Events

Any block can have events attached to it (e.g., a button click). Events reference actions by their unique ID and can include optional parameters.

Currently, only the click event is supported:

{
  "id": "link-btn",
  "kind": "button",
  "text": "Open Google",
  "click": [
    {
      "action": "core.link",
      "params": {
        "href": "https://www.google.com"
      }
    }
  ]
}

Common Block Types

Heading

Displays a heading or title text on the slide.

Text

Displays body text or paragraph content on the slide.

Button

An interactive button mainly used to trigger actions on click.

Media Block Types

Image

Displays an image with automatic optimization on export.

Planned Media Block Types

Audio

Embeds an audio player on the slide.

Planned properties:

• src (string): Path to the audio file
• autoplay (boolean, optional)
• controls (boolean, optional)

Video

Embeds a video player on the slide.

Planned properties:

• src (string): Path to the video file or external URL
• autoplay (boolean, optional)
• controls (boolean, optional)

Containers

Stack

A container that arranges its child blocks in a vertical or horizontal stack.

Grid

A container that arranges its child blocks in a grid with configurable rows and columns.

Layer

An overlay container positioned outside the normal flow and anchored to the slide or parent.

Advanced Planned Blocks

Quiz (Single/Multiple Choice)

Interactive quiz question with answer validation.

Planned properties:

• question (string): The quiz question text
• type ("single" | "multiple"): Single or multiple choice
• options (array): Answer options with correct/incorrect flags
• feedback (object, optional): Feedback messages for correct/incorrect answers

Character/Dialogue

Displays character dialogue for conversations.

Planned properties:

• character (string): Character name or ID
• text (string): Dialogue text
• avatar (string, optional): Path to character image
• choices (array, optional): Branching dialogue options

Drag-and-Drop

Interactive drag-and-drop activity.

Planned properties:

• draggables (array): Items that can be dragged
• targets (array): Drop zones with validation rules
• feedback (object, optional): Success/failure feedback

Tooltip/Modal

Overlay content that appears on demand.

Planned properties:

• id (string)
• kind (literal "tooltip" | "modal")
• trigger (string): ID of the block that triggers display
• children (Block[]): Content to display in overlay
• position (string, optional): Position relative to trigger

Design Principles

1. Composability: Blocks can be nested within container blocks for flexible layouts
2. Type Safety: All blocks use discriminated unions for compile-time validation
3. Accessibility: Each block type considers ARIA attributes and semantic HTML
4. Responsive by Default: Blocks adapt to different screen sizes through CSS and container queries
5. Framework-Agnostic: Block schemas live in packages/engine/ and can be rendered by any framework
6. Human and AI Editable: JSON representation is readable and easy to generate/modify