Craft

The layout spec

A layout is JSON: a flat map of elements and the key of the one at the root.

{
  "root": "page",
  "elements": {
    "page": {
      "type": "Stack",
      "props": { "direction": "vertical", "gap": "md" },
      "children": ["hero", "stats"]
    },
    "hero": {
      "type": "ImageHeader",
      "props": { "src": { "$state": "/image" }, "title": { "$state": "/name" } },
      "children": []
    },
    "stats": {
      "type": "StatGrid",
      "props": {
        "items": [
          ["Strength", { "$state": "/strength" }],
          ["Dexterity", { "$state": "/dexterity" }]
        ],
        "cols": 2
      },
      "children": []
    }
  }
}

Elements

Key What it is
root The key of the element at the top.
elements Every element, by key. There is no nesting: the tree is made only by children.
type The component's name, exactly as the component reference writes it.
props The component's props. Required on every element, even when empty: "props": {}.
children The keys of the elements inside it, in order. Every key must exist in elements, or that part is missing.
visible Optional. A condition that hides the element when false.
repeat Optional. Renders the children once per item of an array.
sections Top level, optional. Named fragments mounted by Include or SectionSwitch.

Keep element keys readable: hero-image, stats-section, backstory-text.

Data binding

A file's content is the layout's state. Bind a prop to a field with { "$state": "/fieldName" }:

{ "text": { "$state": "/name" } }
{ "value": { "$state": "/stats/strength" } }

A nested field is a path: /stats/strength reads stats.strength. The paths you can bind are the type's schema fields, plus these:

Path What it holds
/title The file's name (the same as /name).
/description The file's description.
/image The file's main picture. Image components read its URL, focal point and generation state themselves.
/createdAt, /updatedAt When the file was made and last changed.
/_<field>Entries For each object field, its [key, value] pairs: useful for a stat grid or table when the keys aren't fixed.

Computed fields are worked out into the state too, and bind like any other field. They show read-only.

Visibility

visible hides an element when its condition is false. A "has a value" condition on a field the element or anything inside it shows ("visible": {"$state": "/patronus"} on the Patronus row, or on a Card holding a Markdown of /notes) is ignored: an empty field stays on the sheet so players can fill it in. Gate on another field (a toggle, a class) instead.

{
  "type": "Image",
  "props": { "src": { "$state": "/portrait" }, "alt": "Portrait" },
  "visible": { "$state": "/showPortrait" },
  "children": []
}
Condition Form
Has a value { "$state": "/field" }
Equal, not equal { "$state": "/field", "eq": "value" }, "neq"
Compare { "$state": "/level", "gte": 3 }, also gt, lt, lte. The value may be a number or { "$state": "/otherField" }.
Not add "not": true to any condition
All { "$and": [a, b] }, or a plain array [a, b]
Any { "$or": [a, b] }

Use one comparison per condition. eq and neq compare exactly: a number stored as text doesn't equal a number.

When the "has a value" form tests a field the element or anything inside it shows (like the image above), the editor keeps the element on the page so the empty field can still be filled in. Every other condition hides the element everywhere, so use a different field (a toggle such as /offersGear) for a section that should really disappear.

ImageHeader needs no condition: with no picture it shows a gradient.

Repeats

Any element can render its children once per item of an array:

{
  "trackers-list": {
    "type": "Stack",
    "props": { "direction": "vertical", "gap": "sm" },
    "repeat": { "statePath": "/trackers", "key": "key" },
    "children": ["tracker-row"]
  },
  "tracker-row": {
    "type": "Dots",
    "props": {
      "label": { "$item": "label" },
      "value": { "$item": "current" },
      "max": { "$item": "max" }
    },
    "visible": [{ "$item": "style", "eq": "dots" }],
    "children": []
  }
}
  • Inside the repeat, { "$item": "field" } reads a field of the current item and { "$item": "" } the whole item. Conditions can use $item and { "$index": true }, for example to show a row from a level up: { "$item": "minLevel", "lte": { "$state": "/level" } }.
  • key names an item field whose value is unique and stable.
  • statePath is a full path. Repeats don't nest: to group (spells by level), repeat over the groups and use a component that lists its own items, such as Checklist or BadgeList.
  • Editing an $item value saves it to that item.

Prefer one array with a field that tells items apart (a spells array with a level) over numbered fields (spells1 … spells9).

Edit paths

A value worked out by a computed field can't be edited, so a control that repeats over a computed list can't save to its rows. editPath sends the edit somewhere else: the control still shows the computed value, and an edit saves to the stored path you name.

This is the pattern for class resources (rage, ki, spell slots): the maximums live on the class file, the current values in a stored map on this file, and a computed resources list joins them.

{
  "resource-list": {
    "type": "Stack",
    "props": { "direction": "vertical", "gap": "sm" },
    "repeat": { "statePath": "/resources", "key": "key" },
    "children": ["resource-row"]
  },
  "resource-row": {
    "type": "Dots",
    "props": {
      "label": { "$item": "name" },
      "value": { "$item": "current" },
      "max": { "$item": "maximum" },
      "editPath": { "value": "/resourceState/{key}/current" }
    },
    "children": []
  }
}
  • editPath maps an editable prop to a full state path. {key} reads that field of the current item, so each row needs a stable slug matching the stored map's keys. The map is keyed by slug, never by row number or display name.
  • A path with {placeholders} works only inside a repeat. A path without them works anywhere. When a placeholder can't be filled, the control shows read-only instead of saving somewhere wrong.
  • The path must end at a stored field. A path on or under a computed field is refused, and the control stays read-only.
  • The path doesn't need to exist yet. The first edit creates it.
  • Dots, Stepper, Progress, TrackBoxes, Clock, Toggle and Text take an edit path.
  • The display must read the written value back. The computed list has to read the same stored path (current: $self.resourceState?.[r.key]?.current ?? 0), or the edit saves and the sheet never shows it.
  • A key made only of digits is an array index: /resourceState/3/current writes into an array. Use keys like rage or slots-1.

Outside a repeat, one known resource needs no edit path: bind value to the stored path (/resourceState/rage/current) and max to a computed field.

Sections

Blocks that only some files need, such as a subclass's features, go in named sections. Each section is a small layout of its own, with its own root and elements, reading the same state:

{
  "root": "page",
  "elements": {
    "page": { "type": "Stack", "props": {}, "children": ["subclass-features"] },
    "subclass-features": {
      "type": "SectionSwitch",
      "props": {
        "statePath": "/subclassName",
        "cases": [
          { "equals": "The Fiend", "section": "warlock-the-fiend" },
          { "equals": "The Archfey", "section": "warlock-the-archfey" }
        ],
        "default": null
      },
      "children": []
    }
  },
  "sections": {
    "warlock-the-fiend": {
      "name": "The Fiend",
      "root": "card",
      "elements": {
        "card": { "type": "Card", "props": { "title": "The Fiend" }, "children": [] }
      }
    },
    "warlock-the-archfey": {
      "name": "The Archfey",
      "root": "card",
      "elements": {
        "card": { "type": "Card", "props": { "title": "The Archfey" }, "children": [] }
      }
    }
  }
}
  • SectionSwitch mounts the section of the first case whose value equals the one at statePath, or default when none does.
  • Include ({ "section": "<id>" }) always mounts one section. Give it a visible condition for a single optional block.
  • Sections can't mount other sections. Every section named must exist.
  • Adding a subclass means one new section and one new case.

References to other files

Declare a reference in the schema first. The field that holds it names the type it points to:

{
  "armor": { "type": "string", "referencedFileTypeSlug": "armor" },
  "inventory": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "item": { "type": "string", "referencedFileTypeSlug": "item" },
        "quantity": { "type": "number" }
      }
    }
  }
}

In content, write the file's slug ("armor": "leather-armor"). Craft stores the reference itself. Never make up reference ids.

To show Use
One reference Select with fileTypeSlug
A list of references FileReferenceGrid with fileTypeSlug, and referenceField when the items are objects
A short list of references BadgeList with fileTypeSlug
One reference's value, read-only ReferenceValue
Fields of each file in a list (each teammate's level) a computed list, $self.team.map(c => ({ name: load(c)?.$name, level: load(c)?.level })), shown in a DataTable
{
  "type": "FileReferenceGrid",
  "props": {
    "items": { "$state": "/inventory" },
    "fileTypeSlug": "item",
    "referenceField": "item",
    "columns": 4,
    "label": "Inventory"
  },
  "children": []
}
  • In a list of objects, the other fields (quantity, equipped) show as badges on each card.
  • A single slot can use the grid too: "items": [{ "$state": "/mainHand" }] with "referenceField": null.
  • A field that may point to several types lists them all in fileTypeSlugs (["weapon", "item"]). Picked values are saved as "type/slug".
  • These components add and remove references themselves. Don't build your own controls for it. showAddNew: false hides adding, and showAddNewOnHover: false keeps the add button visible on desktop.