Skip to content

Frontmatter fields

A file's frontmatter as one labeled box per key, with the raw text one disclosure away.

<div data-mount="typed"></div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/frontmatter-fields.css";
import { shapeOf, labelOf, readBox } from "capsomer/behavior/frontmatter-fields";

Usage

<fieldset class="cap-fm">
  <legend class="cap-fm-legend">Post details</legend>
  <div class="cap-fields cap-fm-grid">
    <div class="cap-fm-field">
      <div class="cap-field">
        <label class="cap-field-label" for="fm-title">Title</label>
        <input class="cap-input" id="fm-title" value="Spring update" />
      </div>
    </div>
    <div class="cap-fm-field">
      <div class="cap-field">
        <label class="cap-field-label" for="fm-tags">Tags</label>
        <p class="cap-field-help" id="fm-tags-h">Separated by commas.</p>
        <input class="cap-input" id="fm-tags" aria-describedby="fm-tags-h" value="release notes, field notes" />
      </div>
    </div>
    <div class="cap-fm-field" data-wide>
      <div class="cap-field" data-orientation="horizontal">
        <label class="cap-check"><input type="checkbox" aria-describedby="fm-banner-h" /> Draft banner</label>
        <p class="cap-field-help" id="fm-banner-h">Shows the word "Draft" on the page.</p>
      </div>
    </div>
  </div>
  <details class="cap-disclosure cap-fm-raw">
    <summary>Edit as text</summary>
    <div class="cap-disclosure-body cap-field">
      <label class="cap-field-label" for="fm-raw">The frontmatter as text</label>
      <p class="cap-field-help" id="fm-raw-h">Only here: summary.</p>
      <textarea class="cap-input cap-fm-raw-text" id="fm-raw" aria-describedby="fm-raw-h" spellcheck="false">title: Spring update</textarea>
    </div>
  </details>
</fieldset>
import { FrontmatterFields, type FieldSpec } from "capsomer/react/frontmatter-fields";

const fields: FieldSpec[] = [
  { key: "title", label: "Title" },
  { key: "description", label: "Description", box: "text" },
  { key: "tags", label: "Tags", box: "list" },
  { key: "banner", label: "Draft banner", box: "flag", flag: { on: "Draft", off: null } },
];

<FrontmatterFields source={source} onChange={setSource} fields={fields} extra="text" legend="Post details">
  {/* the app's own controls, in the grid after the boxes */}
</FrontmatterFields>;

Examples

With the app's labels, help and flag word

<div data-mount="specs"></div>

Read-only, empty boxes hidden

<div data-mount="readonly"></div>

Keys the app does not type: the text alone, open

<div data-mount="text"></div>

A file with no frontmatter

<div data-mount="none"></div>

API reference

FrontmatterFields

PropTypeRequiredDoes
sourcestringYesThe whole file: frontmatter fences, frontmatter and body.
onChange(next: string) => voidThe whole file again, with the change made. Left out, every box is read-only.
readOnlyboolean
fieldsreadonly FieldSpec[]What the app knows about its keys: labels, boxes, help, flag words, order.
extra"fields" | "text"A key with no spec: a box of its own ("fields", the default) or the raw text only ("text").
legendReactNode
hideEmptybooleanHide boxes whose key is absent and empty; on by default when read-only.
rawbooleanThe raw text disclosure: shown by default.
rawSummaryReactNode
emptyReactNodeShown in place of the fields when the file has no frontmatter.
childrenReactNodeAfter the boxes: the app's own controls for this item.

Functions

FunctionSignatureDoes
useTyped(stored: string): TypedBox
shapeOf(lines: readonly string[]): BoxKind | nullThe box a block's shape allows, or null when no box can say it. A block list or flow list whose items hold a comma is "lines", since "a, b" could not give them back.
labelOf(key: string): string"pov" reads as "POV", "first_line" as "First line": the key itself is in the raw text.
readBox(front: string | null, key: string, box: BoxKind, flag?: FlagWords | undefined): stringWhat a box shows for a key.
scalarRaw(value: string, style?: ScalarStyle): stringA scalar as YAML reads it back as the same string: quoted only when it would otherwise be read as syntax, a number, a boolean or null. An ISO date stays bare, as sites write it.
writeBox(key: string, box: BoxKind, value: string, options?: { flag?: FlagWords | undefined; style?: ScalarStyle | undefined; keep?: boolean | undefined; }): string[]The block a box writes for a value: [] when it is emptied (the key is removed).
setBox(front: string, key: string, box: BoxKind, value: string, flag?: FlagWords | undefined, keep?: boolean): stringThe frontmatter with one box's value set. A box that already shows the value leaves the text as it was; an emptied box removes its key (or, with keep, writes it empty); a key the frontmatter lacks is added at the end. The blank lines that followed the block are kept.
typeFront(front: string | null, specs?: readonly FieldSpec[], options?: TypeOptions): TypedFrontEach box the frontmatter gets: the app's specs first, in their order, then the keys it has no spec for, in file order. A key whose shape no box can say is raw only, whatever its spec says.

CSS variables

VariableDefault
--fields-gapvar(--gap)
--fields-min14rem

Parts and data attributes

ClassIs
.cap-fmthe root
.cap-fm-fielda part
.cap-fm-grida part
.cap-fm-legenda part
.cap-fm-raw-texta part
AttributeValues
data-widepresent or absent
StateRead from
:emptythe platform

Accessibility

KeyDoes
Tab, Shift+TabMoves between the boxes, then the "Edit as text" summary and the raw text
Space (checkbox)Turns a flag on or off
Enter or Space (summary)Opens or closes the raw text
  • The boxes are in a fieldset named by its legend; each box is a Field, its label above it and its help as its description. A flag is a .cap-check checkbox, its help as its description.
  • The raw text is a labeled textarea ("The frontmatter as text"), described by the line that names the keys only it holds.
  • Read-only boxes are readonly, so they keep focus and can be read and copied; a read-only flag is disabled.
  • Hit areas are Field's and the disclosure's, at least --target.
  • Forced colors: the fieldset's edge is a border, so it stays.