//! moss component contract — Source 2 of the federated contract.
//!
//! Single source of truth for every `moss-*` class moss currently emits.
//! Each entry declares: the class name, its kind (container/instance/standalone/chrome),
//! accepted `data-*` attributes with value spaces, example HTML, example markdown.
//!
//! ## Adding a new emitter class
//!
//! 1. Emit the class from your renderer module (`build/markdown/*`, `build/components/*`).
//! 2. Add a `ComponentEntry` to [`COMPONENTS`] here.
//! 3. Run `cargo test --test components_sync_test` from src-tauri/ — the
//! scanner test will fail if you forget.
//! 4. Run `cargo run --bin generate-contract-docs --features dev-tools` to
//! refresh `docs/contract/reference.md`.
//!
//! ## Why a const table, not a derive macro?
//!
//! Mirrors the BUILTIN_FIELDS precedent in `schema_fields.rs`. The synchronization
//! is enforced by a sync test (`emitter_classes_match_components_table`) that
//! scans emitter Rust source for `class="moss-..."` literals. This is a
//! best-effort scanner (won't catch classes assembled via `format!()`), not a
//! type-checked guarantee like BUILTIN_FIELDS' compile-time mirror. The
//! limitation is documented in the spec § Source 2.
/// Status of a component entry.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Status {
/// In active use; theme authors can rely on it.
Confirmed,
/// Emerging convention; may evolve.
Emerging,
/// Scheduled for removal; theme authors should migrate.
Retired,
}
/// A declared `data-*` attribute on a component.
pub struct DataAttr {
/// Attribute name including `data-` prefix (e.g. `"data-layout"`).
pub name: &'static str,
/// Allowed values (e.g. `&["grid", "list", "minimal"]`). Empty means free-form.
pub values: &'static [&'static str],
/// Default value (first in `values`, or `""` for free-form).
pub default: &'static str,
/// Short description shown in reference.md.
pub description: &'static str,
}
/// A single component contract entry.
pub struct ComponentEntry {
/// Class name without leading `.` (e.g. `"moss-cards"`).
pub class: &'static str,
/// Container / Instance / Standalone / Chrome.
pub kind: &'static str,
/// For Instance kinds, the parent container's class (or `""`).
pub parent: &'static str,
/// Declared `data-*` attributes on the element with this class.
pub data_attrs: &'static [DataAttr],
/// Example HTML snippet showing the class in context. Multi-line allowed.
pub example_html: &'static str,
/// Example markdown that produces this HTML. Empty for HTML-only chrome.
pub example_markdown: &'static str,
/// Status: confirmed / emerging / retired.
pub status: Status,
/// Contract version this entry was introduced in.
pub since: &'static str,
/// Optional human-readable description.
pub description: &'static str,
}
/// The full contract surface — every `moss-*` class moss currently emits.
///
/// Phase 0b seeds this with the CURRENT emitted vocabulary (not the
/// v1-collapsed shape). Phase 1c rewrites to the collapsed form.
pub const COMPONENTS: &[ComponentEntry] = &[
ComponentEntry {
class: "moss-cards",
kind: "container",
parent: "",
data_attrs: &[
DataAttr {
name: "data-layout",
values: &["grid", "list", "minimal"],
default: "grid",
description: "Card layout density. Grid: 2-3 cols with covers. List: single column with side covers. Minimal: text-only with year groupings.",
},
DataAttr {
name: "data-density",
values: &["default", "compact"],
default: "default",
description: "Vertical spacing density.",
},
DataAttr {
name: "data-list-axis",
values: &["date", "weight", "title"],
default: "title",
description: "Sort axis for the listing (mirrors the folder's `sort:` frontmatter). Drives `--moss-card-min` density tuning and decides whether each `.moss-card-meta` slot is filled (date axis) or omitted (weight/title axes).",
},
DataAttr {
name: "data-list-has-covers",
values: &[""],
default: "",
description: "Boolean presence flag: emitted iff any child card has a cover. Combines with `data-list-axis` to widen `--moss-card-min` for cover-led layouts. Use `[data-list-has-covers]` in CSS to target it.",
},
],
example_html: r#"<div class="moss-cards-container">
<div class="moss-cards" data-layout="grid" data-list-axis="date" data-list-has-covers>
<a class="moss-card" href="...">...</a>
<a class="moss-card" href="...">...</a>
</div>
</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Auto-generated listing of child pages. The single canonical container; layout density on `data-layout` (`grid` for cover-led tiles, `list` for cover+excerpt rows, `minimal` for text-only year-grouped indexes). Wrapped in `.moss-cards-container` to scope CSS container queries.",
},
ComponentEntry {
class: "moss-cards-container",
kind: "container",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-cards-container">
<div class="moss-cards" data-layout="grid">...</div>
</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Outer wrapper around `.moss-cards` that carries `container-type: inline-size` so the grid can use `@container` queries instead of viewport `@media` queries. Layout-agnostic — wraps any `data-layout` variant.",
},
ComponentEntry {
class: "moss-summary-layout",
kind: "container",
parent: "moss-cards",
data_attrs: &[],
example_html: r#"<div class="moss-cards" data-layout="list">...</div>"#,
example_markdown: "",
status: Status::Retired,
since: "1",
description: "Retired: the additional co-class on `.moss-cards[data-layout=\"list\"]` had no matching rules in the default CSS once `children_style: summary` collapsed into the list-layout block, and its lingering emission broke themes that hid the class (e.g. SoCiviC's `.moss/theme/style.css` keyed `display: none` on it, erasing folder-embed listings). Theme authors targeting summary listings should use `.moss-cards[data-layout=\"list\"]` directly.",
},
// -------------------------------------------------------------------
// Cards family — current emitted vocabulary (pre-Phase 1c collapsing).
// Three parallel layouts: grid, list, minimal. Each has its own
// container + instance + sub-classes.
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-cards-grid",
kind: "container",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-cards-grid">
<a class="moss-card-grid" href="...">...</a>
</div>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-cards[data-layout=grid]`.",
},
ComponentEntry {
class: "moss-cards-list",
kind: "container",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-cards-list">
<a class="moss-card-list" href="...">...</a>
</div>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-cards[data-layout=list]`.",
},
ComponentEntry {
class: "moss-cards-minimal-year-group",
kind: "container",
parent: "",
data_attrs: &[],
example_html: r#"<section class="moss-cards-minimal-year-group">
<h3>2024</h3>
<div class="moss-card-minimal">...</div>
</section>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Year-grouped section in minimal card layout (e.g. blog index). Modifier `--summary` collapses past years.",
},
ComponentEntry {
class: "moss-cards-minimal-year-group--summary",
kind: "container",
parent: "moss-cards-minimal-year-group",
data_attrs: &[],
example_html: r#"<section class="moss-cards-minimal-year-group moss-cards-minimal-year-group--summary">...</section>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "BEM modifier on `.moss-cards-minimal-year-group`. Applied to year groups that should render in collapsed summary form (e.g. past years on a blog index).",
},
ComponentEntry {
class: "moss-card",
kind: "instance",
parent: "moss-cards",
data_attrs: &[
DataAttr {
name: "data-linkblog",
values: &[],
default: "",
description: "Presence flag: emitted IFF the card's source page has an `external_url:` frontmatter (linkblog pattern). When set, the element is a `<div>` rather than `<a>` so the kicker can host a nested `<a>★</a>` archive link; title, cover, and description carry their own inner anchors to the canonical URL. Absent on ordinary cards (single whole-card `<a>`).",
},
],
example_html: r#"<a class="moss-card" href="...">...</a>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "v1 collapsed shape — single canonical instance class inside `.moss-cards`. Layout-specific styling targets `.moss-cards[data-layout=X] .moss-card`. Tag is `<a>` for ordinary cards and `<div>` for linkblog cards (`[data-linkblog]`).",
},
ComponentEntry {
class: "moss-card-cover",
kind: "instance",
parent: "moss-card",
data_attrs: &[],
example_html: r#"<div class="moss-card-cover"><img src="..." /></div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Cover media slot inside `.moss-card`. Gets `.moss-card-no-cover` modifier when no image is present.",
},
ComponentEntry {
class: "moss-card-no-cover",
kind: "instance",
parent: "moss-card",
data_attrs: &[],
example_html: r#"<div class="moss-card-cover moss-card-no-cover"></div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Modifier applied to `.moss-card-cover` when no cover media is available.",
},
ComponentEntry {
class: "moss-card-content",
kind: "instance",
parent: "moss-card",
data_attrs: &[],
example_html: r#"<div class="moss-card-content">...</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Text content slot inside a grid-layout `.moss-card` (kicker + title + meta).",
},
ComponentEntry {
class: "moss-card-row",
kind: "instance",
parent: "moss-card",
data_attrs: &[],
example_html: r#"<div class="moss-card-row">...</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Row wrapper inside a list-layout `.moss-card` holding body + cover side-by-side.",
},
ComponentEntry {
class: "moss-card-body",
kind: "instance",
parent: "moss-card",
data_attrs: &[],
example_html: r#"<div class="moss-card-body">...</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Text body slot of a list-layout `.moss-card`.",
},
ComponentEntry {
class: "moss-card-head",
kind: "instance",
parent: "moss-card",
data_attrs: &[],
example_html: r#"<div class="moss-card-head">...</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Header row of a `.moss-card-body` (title + kicker + meta).",
},
ComponentEntry {
class: "moss-card-title",
kind: "instance",
parent: "moss-card",
data_attrs: &[],
example_html: r#"<h3 class="moss-card-title">Page title</h3>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Title inside `.moss-card`.",
},
ComponentEntry {
class: "moss-card-meta",
kind: "instance",
parent: "moss-card",
data_attrs: &[],
example_html: r#"<div class="moss-card-meta">2024-01-15</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Type-aware metadata slot (date for articles, count for folders, domain for links). Renders ABOVE the title in horizontal mode — filling the kicker position when the explicit `kicker` slot is unset, per `docs/design-system/preview-cards.md:22-30`. To the right of the title in vertical CJK mode (the horizontal kicker position transposed). Meta IS the visual kicker, with the same uppercase overline treatment.",
},
ComponentEntry {
class: "moss-card-kicker",
kind: "instance",
parent: "moss-card",
data_attrs: &[],
example_html: r#"<span class="moss-card-kicker">Category</span>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Eyebrow / overline above the title inside `.moss-card`.",
},
ComponentEntry {
class: "moss-card-permalink",
kind: "instance",
parent: "moss-card-kicker",
data_attrs: &[],
example_html: r#"<a class="moss-card-permalink" href="/posts/foo/" title="Permalink to 'Title'">★</a>"#,
example_markdown: "",
status: Status::Emerging,
since: "1",
description: "Author's-archive link mark (★, U+2605) emitted INSIDE `.moss-card-kicker` for linkblog cards (those whose child page has `external_url:`). The card title links to the external canonical (publisher); the `★` links to the local archival copy at the page's slug. Reads as part of the kicker line — \"Publisher · Year ★\". Semantically distinct from Daring-Fireball's linkblog ★ (which marks discussion permalink alongside commentary) — here the local copy is the same content preserved for resilience and stable bylines, not added commentary. Putting `<a>★</a>` inside the kicker is valid because linkblog cards emit `<div class=\"moss-card\" data-linkblog>` (not `<a>`) as the outer element — see the `data-linkblog` attribute described on `.moss-card`.",
},
ComponentEntry {
class: "moss-card-title-link",
kind: "instance",
parent: "moss-card-head",
data_attrs: &[],
example_html: r#"<a class="moss-card-title-link" href="https://outlet.example/article"><h3 class="moss-card-title">Article Title</h3></a>"#,
example_markdown: "",
status: Status::Emerging,
since: "1",
description: "Anchor wrapping the `.moss-card-title` `<h3>` on linkblog cards. Ordinary cards have the whole-card `<a class=\"moss-card\">` as the link target — but linkblog cards switch the outer to `<div>` so the kicker can host a nested `★` anchor, which means the title needs its own anchor to stay clickable. Same canonical-URL target as the other inner anchors (`moss-card-cover-link`, `moss-card-description-link`).",
},
ComponentEntry {
class: "moss-card-cover-link",
kind: "instance",
parent: "moss-card-row",
data_attrs: &[],
example_html: r#"<a class="moss-card-cover-link" href="https://outlet.example/article"><div class="moss-card-cover">...</div></a>"#,
example_markdown: "",
status: Status::Emerging,
since: "1",
description: "Anchor wrapping the `.moss-card-cover` on linkblog cards — same role as `.moss-card-title-link` but for the cover image / media. Targets the canonical (external) URL.",
},
ComponentEntry {
class: "moss-card-description-link",
kind: "instance",
parent: "moss-card-body",
data_attrs: &[],
example_html: r#"<a class="moss-card-description-link" href="https://outlet.example/article"><p class="moss-card-description">…</p></a>"#,
example_markdown: "",
status: Status::Emerging,
since: "1",
description: "Anchor wrapping the `.moss-card-description` on linkblog cards — same role as `.moss-card-title-link` but for the description excerpt. Targets the canonical (external) URL.",
},
ComponentEntry {
class: "moss-card-description",
kind: "instance",
parent: "moss-card",
data_attrs: &[],
example_html: r#"<p class="moss-card-description">Excerpt...</p>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Excerpt / description paragraph inside a `.moss-card` — below the title in both grid- and list-layout cards.",
},
ComponentEntry {
class: "moss-card-count",
kind: "instance",
parent: "moss-card",
data_attrs: &[],
example_html: r#"<div class="moss-card-count">4 articles</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Tertiary subtitle line showing `N articles` for a folder card. Renders only on non-date listings when the folder card has no `description` to display.",
},
ComponentEntry {
class: "moss-embed-more",
kind: "instance",
parent: "moss-cards-container",
data_attrs: &[],
example_html: r#"<p class="moss-embed-more"><a href="/news/">More →</a></p>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Trailing \"More →\" link on a truncated children listing (emitted when `children_limit` caps the embed); links to the folder's full index. Rendered as a sibling immediately after `.moss-cards-container`, so it sits outside the listing's flex `gap` and binds to the list via its own `margin-top` (see docs/architecture/ui-design/spacing.md).",
},
ComponentEntry {
class: "moss-card-grid",
kind: "instance",
parent: "moss-cards-grid",
data_attrs: &[],
example_html: r#"<a class="moss-card-grid" href="...">...</a>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card` (with parent `.moss-cards[data-layout=grid]`).",
},
ComponentEntry {
class: "moss-card-grid-cover",
kind: "instance",
parent: "moss-card-grid",
data_attrs: &[],
example_html: r#"<div class="moss-card-grid-cover"><img src="..." /></div>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-cover`.",
},
ComponentEntry {
class: "moss-card-grid-no-cover",
kind: "instance",
parent: "moss-card-grid",
data_attrs: &[],
example_html: r#"<div class="moss-card-grid-cover moss-card-grid-no-cover"></div>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-no-cover`.",
},
ComponentEntry {
class: "moss-card-grid-content",
kind: "instance",
parent: "moss-card-grid",
data_attrs: &[],
example_html: r#"<div class="moss-card-grid-content">...</div>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-content`.",
},
ComponentEntry {
class: "moss-card-grid-kicker",
kind: "instance",
parent: "moss-card-grid",
data_attrs: &[],
example_html: r#"<span class="moss-card-grid-kicker">Category</span>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-kicker`.",
},
ComponentEntry {
class: "moss-card-grid-title",
kind: "instance",
parent: "moss-card-grid",
data_attrs: &[],
example_html: r#"<h3 class="moss-card-grid-title">Page title</h3>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-title`.",
},
ComponentEntry {
class: "moss-card-grid-meta",
kind: "instance",
parent: "moss-card-grid",
data_attrs: &[],
example_html: r#"<div class="moss-card-grid-meta">2024-01-15</div>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-meta`.",
},
ComponentEntry {
class: "moss-card-list",
kind: "instance",
parent: "moss-cards-list",
data_attrs: &[],
example_html: r#"<a class="moss-card-list" href="...">...</a>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card` (with parent `.moss-cards[data-layout=list]`).",
},
ComponentEntry {
class: "moss-card-list-row",
kind: "instance",
parent: "moss-card-list",
data_attrs: &[],
example_html: r#"<div class="moss-card-list-row">...</div>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-row`.",
},
ComponentEntry {
class: "moss-card-list-cover",
kind: "instance",
parent: "moss-card-list",
data_attrs: &[],
example_html: r#"<div class="moss-card-list-cover"><img src="..." /></div>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-cover`.",
},
ComponentEntry {
class: "moss-card-list-body",
kind: "instance",
parent: "moss-card-list",
data_attrs: &[],
example_html: r#"<div class="moss-card-list-body">...</div>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-body`.",
},
ComponentEntry {
class: "moss-card-list-head",
kind: "instance",
parent: "moss-card-list",
data_attrs: &[],
example_html: r#"<div class="moss-card-list-head">...</div>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-head`.",
},
ComponentEntry {
class: "moss-card-list-kicker",
kind: "instance",
parent: "moss-card-list",
data_attrs: &[],
example_html: r#"<span class="moss-card-list-kicker">Category</span>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-kicker`.",
},
ComponentEntry {
class: "moss-card-list-title",
kind: "instance",
parent: "moss-card-list",
data_attrs: &[],
example_html: r#"<h3 class="moss-card-list-title">Page title</h3>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-title`.",
},
ComponentEntry {
class: "moss-card-list-meta",
kind: "instance",
parent: "moss-card-list",
data_attrs: &[],
example_html: r#"<div class="moss-card-list-meta">2024-01-15</div>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-meta`.",
},
ComponentEntry {
class: "moss-card-list-description",
kind: "instance",
parent: "moss-card-list",
data_attrs: &[],
example_html: r#"<p class="moss-card-list-description">Excerpt...</p>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card-description`.",
},
ComponentEntry {
class: "moss-card-minimal",
kind: "instance",
parent: "moss-cards-minimal-year-group",
data_attrs: &[],
example_html: r#"<div class="moss-card-minimal">
<a class="moss-prefix-link" href="...">...</a>
</div>"#,
example_markdown: "",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed into `.moss-card` (with parent `.moss-cards[data-layout=minimal]`).",
},
ComponentEntry {
class: "moss-folder-item",
kind: "instance",
parent: "moss-cards-minimal-year-group",
data_attrs: &[],
example_html: r#"<div class="moss-card-minimal moss-folder-item">
<a class="moss-prefix-link moss-folder-link" href="...">...</a>
<p class="moss-folder-description">...</p>
</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Modifier on `.moss-card-minimal` for folder-type entries in minimal listings.",
},
ComponentEntry {
class: "moss-folder-title",
kind: "instance",
parent: "moss-folder-item",
data_attrs: &[],
example_html: r#"<span class="moss-folder-title">Folder name</span>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Title text of a folder entry in minimal listings.",
},
ComponentEntry {
class: "moss-folder-description",
kind: "instance",
parent: "moss-folder-item",
data_attrs: &[],
example_html: r#"<p class="moss-folder-description">Description...</p>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Description paragraph of a folder entry in minimal listings.",
},
ComponentEntry {
class: "moss-folder-link",
kind: "instance",
parent: "moss-folder-item",
data_attrs: &[],
example_html: r#"<a class="moss-prefix-link moss-folder-link" href="...">...</a>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Modifier on `.moss-prefix-link` for folder-type links in minimal listings.",
},
// -------------------------------------------------------------------
// Prefix-link primitive — used by minimal cards and other listings.
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-prefix-link",
kind: "instance",
parent: "moss-card-minimal",
data_attrs: &[],
example_html: r#"<a class="moss-prefix-link" href="...">
<span class="moss-prefix-link-prefix">2024-01-15</span>
<span class="moss-prefix-link-title">Page title</span>
</a>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Link with a prefix span (date or icon) and a title span. Used inside minimal cards.",
},
ComponentEntry {
class: "moss-prefix-link-prefix",
kind: "instance",
parent: "moss-prefix-link",
data_attrs: &[],
example_html: r#"<span class="moss-prefix-link-prefix">2024-01-15</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Prefix slot of a prefix-link (typically a date).",
},
ComponentEntry {
class: "moss-prefix-link-title",
kind: "instance",
parent: "moss-prefix-link",
data_attrs: &[],
example_html: r#"<span class="moss-prefix-link-title">Page title</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Title slot of a prefix-link.",
},
ComponentEntry {
class: "moss-prefix-link-suffix",
kind: "instance",
parent: "moss-prefix-link",
data_attrs: &[],
example_html: r#"<span class="moss-prefix-link-suffix">→</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Optional trailing slot of a prefix-link.",
},
// -------------------------------------------------------------------
// Callouts — Obsidian-style admonitions. Type variant goes on the
// container as `.callout-<type>`. Phase 1c may collapse into
// `.moss-callout[data-type]`.
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-callout",
kind: "standalone",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-callout callout" data-type="note">
<div class="callout-title">Note</div>
<div class="callout-content">Body...</div>
</div>"#,
example_markdown: "> [!note]\n> Body...",
status: Status::Confirmed,
since: "0",
description: "Obsidian-style callout. The Obsidian-compat `.callout` class is co-emitted; type lives on `data-type` (v1).",
},
ComponentEntry {
class: "callout",
kind: "standalone",
parent: "",
data_attrs: &[
DataAttr {
name: "data-type",
values: &["note", "info", "tip", "warning", "pending"],
default: "note",
description: "v1 callout type. Theme authors target `.callout[data-type=...]` to style by variant.",
},
],
example_html: r#"<div class="moss-callout callout" data-type="note">...</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Obsidian-compat class co-emitted on every callout for theme parity. Type lives on `data-type` (v1).",
},
ComponentEntry {
class: "callout-title",
kind: "instance",
parent: "moss-callout",
data_attrs: &[],
example_html: r#"<div class="callout-title">Note</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Title row of a callout.",
},
ComponentEntry {
class: "callout-content",
kind: "instance",
parent: "moss-callout",
data_attrs: &[],
example_html: r#"<div class="callout-content">Body...</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Body container of a callout.",
},
ComponentEntry {
class: "callout-note",
kind: "instance",
parent: "moss-callout",
data_attrs: &[],
example_html: r#"<div class="moss-callout callout callout-note">...</div>"#,
example_markdown: "> [!note]\n> Body",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — type lives on `.callout[data-type=note]`.",
},
ComponentEntry {
class: "callout-info",
kind: "instance",
parent: "moss-callout",
data_attrs: &[],
example_html: r#"<div class="moss-callout callout callout-info">...</div>"#,
example_markdown: "> [!info]\n> Body",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — type lives on `.callout[data-type=info]`.",
},
ComponentEntry {
class: "callout-tip",
kind: "instance",
parent: "moss-callout",
data_attrs: &[],
example_html: r#"<div class="moss-callout callout callout-tip">...</div>"#,
example_markdown: "> [!tip]\n> Body",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — type lives on `.callout[data-type=tip]`.",
},
ComponentEntry {
class: "callout-warning",
kind: "instance",
parent: "moss-callout",
data_attrs: &[],
example_html: r#"<div class="moss-callout callout callout-warning">...</div>"#,
example_markdown: "> [!warning]\n> Body",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — type lives on `.callout[data-type=warning]`.",
},
ComponentEntry {
class: "callout-pending",
kind: "instance",
parent: "moss-callout",
data_attrs: &[],
example_html: r#"<div class="moss-callout callout callout-pending">...</div>"#,
example_markdown: "> [!pending]\n> Body",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — type lives on `.callout[data-type=pending]`.",
},
// -------------------------------------------------------------------
// Embeds — `![[file.ext]]` shortcode renderers (audio, video, pdf,
// notebook, table, 3d, iframe).
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-embed",
kind: "standalone",
parent: "",
data_attrs: &[
DataAttr {
name: "data-type",
values: &["audio", "video", "pdf", "notebook", "table", "iframe", "3d"],
default: "",
description: "v1 embed kind. Set on the embed element. Theme authors target `.moss-embed[data-type=...]`.",
},
DataAttr {
name: "data-loop",
values: &[],
default: "",
description: "Ambient background video: autoplay + muted + loop + playsinline, controls off. Authored as `![[clip.mp4|loop]]`. Boolean presence flag (value is empty). JS reads it to apply the reduced-motion guard and mount the pause/play toggle.",
},
DataAttr {
name: "data-width",
values: &["body", "wide", "page", "screen"],
default: "body",
description: "Display width — text-column (body), wider than text (wide), page-width (page), or viewport-width (screen). See spec § P9.",
},
DataAttr {
name: "data-provider",
values: &["youtube", "vimeo", "codepen"],
default: "",
description: "Identifies the embed provider for external URL embeds. Absent for generic iframes and local HTML embeds.",
},
],
example_html: r#"<video class="moss-embed moss-embed-video" data-type="video" data-loop src="clip.mp4" autoplay muted loop playsinline preload="metadata"></video>"#,
example_markdown: "![[clip.mp4|loop]]",
status: Status::Confirmed,
since: "0",
description: "Base class on every typed embed. Kind on `data-type` (v1). Ambient video: add `data-loop` via `![[clip.mp4|loop]]`. `.moss-embed-audio` / `-video` / `-pdf` / `-notebook` / `-table` / `-iframe` / `-3d` retired in Phase 1c.",
},
ComponentEntry {
class: "moss-embed-audio",
kind: "instance",
parent: "moss-embed",
data_attrs: &[],
example_html: r#"<div class="moss-embed moss-embed-audio"><audio controls src="..."></audio></div>"#,
example_markdown: "![[track.mp3]]",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed to `.moss-embed[data-type=audio]`.",
},
ComponentEntry {
class: "moss-embed-video",
kind: "instance",
parent: "moss-embed",
data_attrs: &[],
example_html: r#"<div class="moss-embed moss-embed-video"><video controls src="..."></video></div>"#,
example_markdown: "![[clip.mp4]]",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed to `.moss-embed[data-type=video]`.",
},
ComponentEntry {
class: "moss-embed-pdf",
kind: "instance",
parent: "moss-embed",
data_attrs: &[],
example_html: r#"<div class="moss-embed moss-embed-pdf"><iframe src="..."></iframe></div>"#,
example_markdown: "![[paper.pdf]]",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed to `.moss-embed[data-type=pdf]`.",
},
ComponentEntry {
class: "moss-embed-iframe",
kind: "instance",
parent: "moss-embed",
data_attrs: &[],
example_html: r#"<div class="moss-embed moss-embed-iframe"><iframe src="..."></iframe></div>"#,
example_markdown: "![[page.html]]",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed to `.moss-embed[data-type=iframe]`.",
},
ComponentEntry {
class: "moss-embed-notebook",
kind: "instance",
parent: "moss-embed",
data_attrs: &[],
example_html: r#"<div class="moss-embed moss-embed-notebook">...</div>"#,
example_markdown: "![[analysis.ipynb]]",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed to `.moss-embed[data-type=notebook]`.",
},
ComponentEntry {
class: "moss-embed-ipynb",
kind: "instance",
parent: "moss-embed",
data_attrs: &[],
example_html: r#"<div class="moss-embed moss-embed-ipynb">...</div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Alias of `.moss-embed-notebook`; consolidation pending.",
},
ComponentEntry {
class: "moss-embed-table",
kind: "instance",
parent: "moss-embed",
data_attrs: &[],
example_html: r#"<div class="moss-embed moss-embed-table"><table>...</table></div>"#,
example_markdown: "![[data.csv]]",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed to `.moss-embed[data-type=table]`.",
},
ComponentEntry {
class: "moss-embed-3d",
kind: "instance",
parent: "moss-embed",
data_attrs: &[],
example_html: r#"<div class="moss-embed moss-embed-3d">...</div>"#,
example_markdown: "![[model.glb]]",
status: Status::Retired,
since: "0",
description: "Retired in Phase 1c — collapsed to `.moss-embed[data-type=3d]`.",
},
ComponentEntry {
class: "moss-embed-error",
kind: "instance",
parent: "moss-embed",
data_attrs: &[],
example_html: r#"<div class="moss-embed moss-embed-error">File not found: ...</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Error state for embeds whose target cannot be resolved.",
},
ComponentEntry {
class: "moss-embed-missing",
kind: "instance",
parent: "moss-embed",
data_attrs: &[],
example_html: r#"<div class="moss-embed-missing">Folder not found: journal</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "1",
description: "Fallback rendered when a folder-list embed (`![[journal/]]`) targets a folder that does not exist or cannot be resolved. Distinct from `.moss-embed-error` (file/wikilink resolution failure) — this one is specifically the folder-listing path.",
},
// -------------------------------------------------------------------
// Hero, image, visual primitives.
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-hero",
kind: "standalone",
parent: "",
data_attrs: &[
DataAttr {
name: "data-width",
values: &["body", "wide", "page", "screen"],
default: "body",
description: "Display width — text-column (body), wider than text (wide), page-width (page), or viewport-width (screen). See spec § P9. Phase 1c will emit this from authoring shortcode (e.g. `:::hero {full}` -> `data-width=\"screen\"`).",
},
],
example_html: r#"<section class="moss-hero" data-width="page">
<div class="moss-hero-content">...</div>
</section>"#,
example_markdown: ":::hero {image=cover.jpg}\n:::\n",
status: Status::Confirmed,
since: "0",
description: "Hero banner section at the top of a page (cover image + title). v1 adds `data-width` for author-controlled sizing.",
},
ComponentEntry {
class: "moss-hero-content",
kind: "instance",
parent: "moss-hero",
data_attrs: &[],
example_html: r#"<div class="moss-hero-content">...</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Text content slot inside `.moss-hero`.",
},
ComponentEntry {
class: "moss-image",
kind: "standalone",
parent: "",
data_attrs: &[
DataAttr {
name: "data-aspect",
values: &["portrait", "square", "auto"],
default: "auto",
description: "v1 image aspect-ratio hint. Theme authors target `.moss-image[data-aspect=...]`. Emitter wiring lands in a follow-up.",
},
DataAttr {
name: "data-width",
values: &["body", "wide", "page", "screen"],
default: "body",
description: "Display width — text-column (body), wider than text (wide), page-width (page), or viewport-width (screen). See spec § P9.",
},
],
example_html: r#"<figure class="moss-image" style="width:55%"><img src="..." alt="..." /></figure>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Wrapper around an inline `<img>` for sizing and figure semantics. `data-width` carries a named width token (body|wide|page|screen); a content-relative width is instead emitted as inline `style=\"width:NN%\"` (set by the editor drag-resize), which also forces the inner image to fill that percent box. Images narrower than the content column center horizontally.",
},
ComponentEntry {
class: "moss-align-left",
kind: "standalone",
parent: "",
data_attrs: &[],
example_html: r#"<img src="..." alt="..." class="moss-align-left" />"#,
example_markdown: "![[photo.jpg|align-left]]",
status: Status::Confirmed,
since: "0",
description: "Floats an image to the left of body text (editorial runaround). Defaults max-width to 50% on desktop, collapses to full-width below 48rem. CSS `:has()` escalates the float to a wrapping `<figure class=\"moss-image\">` or `<picture>` when present. Mirrors WordPress's `alignleft` convention.",
},
ComponentEntry {
class: "moss-align-right",
kind: "standalone",
parent: "",
data_attrs: &[],
example_html: r#"<img src="..." alt="..." class="moss-align-right" />"#,
example_markdown: "![[photo.jpg|align-right]]",
status: Status::Confirmed,
since: "0",
description: "Floats an image to the right of body text (editorial runaround). Symmetric counterpart to `.moss-align-left`. Mirrors WordPress's `alignright` convention.",
},
ComponentEntry {
class: "moss-article-title",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<h1 class="moss-article-title">Title</h1>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Article-page H1 title emitted from frontmatter.",
},
ComponentEntry {
class: "moss-heading-anchor",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r##"<h2 id="setup">Setup<a class="moss-heading-anchor" href="#setup" aria-label="Permalink to this section"><span aria-hidden="true">#</span></a></h2>"##,
example_markdown: "## Setup",
status: Status::Emerging,
since: "1",
description: "Clickable permalink appended inside every author-written body heading that carries a slug id; links to the heading's `#`-fragment. The auto-injected `moss-article-title` H1 is emitted separately and gets no anchor.",
},
// -------------------------------------------------------------------
// Grid + gallery + buttons containers (free-form layouts).
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-grid",
kind: "container",
parent: "",
data_attrs: &[
DataAttr {
name: "data-width",
values: &["body", "wide", "page", "screen"],
default: "body",
description: "Display width — text-column (body), wider than text (wide), page-width (page), or viewport-width (screen). See spec § P9.",
},
],
example_html: r#"<div class="moss-grid" data-width="wide">
<div class="moss-grid-card">...</div>
</div>"#,
example_markdown: ":::grid {cols=2}\nLeft cell\n+++\nRight cell\n:::\n",
status: Status::Confirmed,
since: "0",
description: "Generic grid container (used by profiles, link previews, etc.). Modifier classes: `profiles`, `featured`, `no-cards`. v1 adds `data-width` (P9).",
},
ComponentEntry {
class: "moss-grid-card",
kind: "instance",
parent: "moss-grid",
data_attrs: &[
DataAttr {
name: "data-kind",
values: &["link", "friend", "card"],
default: "card",
description: "v1 grid-card variant. Today expressed via co-emitted classes (`.link-card`, `.friend-card`, `.no-cards`); Phase 1c collapses to this `data-kind` attribute.",
},
],
example_html: r#"<a class="moss-grid-card" data-kind="link" href="...">...</a>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Card instance inside `.moss-grid`. Today emits sibling classes `link-card` / `friend-card` / `no-cards`; v1 collapses to `data-kind`.",
},
ComponentEntry {
class: "moss-gallery",
kind: "container",
parent: "",
data_attrs: &[
DataAttr {
name: "data-width",
values: &["body", "wide", "page", "screen"],
default: "body",
description: "Display width — text-column (body), wider than text (wide), page-width (page), or viewport-width (screen). See spec § P9.",
},
],
example_html: r#"<div class="moss-gallery" data-width="page">
<figure class="moss-gallery-item">...</figure>
</div>"#,
example_markdown: ":::gallery\nphoto.jpg\n:::\n",
status: Status::Confirmed,
since: "0",
description: "Image gallery container. v1 adds `data-width` (P9).",
},
ComponentEntry {
class: "moss-gallery-item",
kind: "instance",
parent: "moss-gallery",
data_attrs: &[],
example_html: r#"<figure class="moss-gallery-item"><img src="..." /></figure>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Single image entry inside `.moss-gallery`.",
},
ComponentEntry {
class: "moss-buttons",
kind: "container",
parent: "",
data_attrs: &[
DataAttr {
name: "data-style",
values: &["default", "inverted"],
default: "default",
description: "v1 button-row style. Theme authors target `.moss-buttons[data-style=...]`.",
},
],
example_html: r#"<div class="moss-buttons" data-style="inverted">
<a class="moss-btn" href="...">Click</a>
</div>"#,
example_markdown: ":::buttons\n[Get started](https://example.com)\n:::\n",
status: Status::Confirmed,
since: "0",
description: "Container for a row of `.moss-btn` buttons. v1: the inverted variant is on `data-style=\"inverted\"`.",
},
// -------------------------------------------------------------------
// Button primitive (used by subscribe + general CTAs).
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-btn",
kind: "standalone",
parent: "",
data_attrs: &[
DataAttr {
name: "data-role",
values: &["default", "primary", "secondary"],
default: "default",
description: "v1 button role. Theme authors target `.moss-btn[data-role=...]`.",
},
],
example_html: r#"<button class="moss-btn" data-role="primary">
<span class="moss-btn__label">Submit</span>
</button>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Generic button primitive. Role on `data-role` (v1).",
},
ComponentEntry {
class: "moss-btn__label",
kind: "instance",
parent: "moss-btn",
data_attrs: &[],
example_html: r#"<span class="moss-btn__label">Submit</span>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Label span inside `.moss-btn`.",
},
ComponentEntry {
class: "moss-btn__check",
kind: "instance",
parent: "moss-btn",
data_attrs: &[],
example_html: r#"<span class="moss-btn__check">✓</span>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Success checkmark slot inside `.moss-btn`.",
},
ComponentEntry {
class: "moss-btn__spinner",
kind: "instance",
parent: "moss-btn",
data_attrs: &[],
example_html: r#"<span class="moss-btn__spinner"></span>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Loading spinner slot inside `.moss-btn`.",
},
// -------------------------------------------------------------------
// Subscribe form (newsletter / Buttondown / seta).
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-subscribe",
kind: "standalone",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-subscribe">
<form class="moss-subscribe-form">...</form>
</div>"#,
example_markdown: ":::subscribe\n:::\n",
status: Status::Confirmed,
since: "0",
description: "Newsletter subscribe block (auto-injected into footer when email channel configured).",
},
ComponentEntry {
class: "moss-subscribe-form",
kind: "instance",
parent: "moss-subscribe",
data_attrs: &[
DataAttr {
name: "data-position",
values: &["inline", "apply"],
default: "inline",
description: "Placement/behavior variant. All moss-hosted subscribe forms are `inline` (the auto-injected footer form and the `:::subscribe` shortcode emit identical HTML — footer vs in-page styling keys on the `footer` ancestor in CSS, not this attribute). `apply` marks the `:::apply` form (terminal success, FormData body).",
},
DataAttr {
name: "data-button-override",
values: &["true"],
default: "true",
description: "Emitted only when the author overrides the button label (`:::subscribe{button=\"...\"}`). Signals subscribe.ts to leave the button label AND placeholder as authored instead of overwriting them with the language-default copy.",
},
DataAttr {
name: "data-moss-hosted",
values: &["true"],
default: "true",
description: "Marks moss-hosted (seta) forms hydrated by subscribe.ts. Absent on 3rd-party provider forms.",
},
DataAttr {
name: "data-state",
values: &["idle", "loading", "success", "error"],
default: "idle",
description: "Runtime submit state machine, driven by subscribe.ts. Emitted as `idle`; theme authors target `.moss-subscribe-form[data-state=...]`.",
},
DataAttr {
name: "data-moss-pending-site",
values: &["true"],
default: "true",
description: "Pre-first-publish pending wiring (`action=\"#\"`, no site_id yet). Hidden on published pages (body without `data-moss-preview`) via the email.css defense rule so a pending form never faces real readers.",
},
],
example_html: r#"<form class="moss-subscribe-form">...</form>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Form element inside `.moss-subscribe`.",
},
ComponentEntry {
class: "moss-btn-slot",
kind: "instance",
parent: "moss-subscribe",
data_attrs: &[],
example_html: r#"<div class="moss-btn-slot"><button class="moss-btn">...</button></div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Fixed-width slot wrapping a form's submit button; used by both the subscribe and comment forms to prevent layout shift across idle/loading/success states.",
},
ComponentEntry {
class: "moss-subscribe-status",
kind: "instance",
parent: "moss-subscribe",
data_attrs: &[],
example_html: r#"<div class="moss-subscribe-status">
<span class="moss-subscribe-status__icon"></span>
Subscribed!
</div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Status message shown after submit (success/error).",
},
ComponentEntry {
class: "moss-subscribe-status__icon",
kind: "instance",
parent: "moss-subscribe-status",
data_attrs: &[],
example_html: r#"<span class="moss-subscribe-status__icon"></span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Icon slot inside `.moss-subscribe-status`.",
},
ComponentEntry {
class: "moss-subscribe-landing",
kind: "standalone",
parent: "",
data_attrs: &[],
example_html: r#"<section class="moss-subscribe-landing">...</section>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Standalone subscribe landing page surface (larger variant).",
},
// -------------------------------------------------------------------
// Apply form (membership / contributor application).
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-apply",
kind: "standalone",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-apply" data-state="idle">
<form class="moss-subscribe-form moss-apply-form">...</form>
</div>"#,
example_markdown: ":::apply\n:::\n",
status: Status::Emerging,
since: "0",
description: "Apply / membership-request form block (:::apply shortcode).",
},
ComponentEntry {
class: "moss-apply-form",
kind: "instance",
parent: "moss-apply",
data_attrs: &[
DataAttr {
name: "data-position",
values: &["apply"],
default: "apply",
description: "Position variant; always `apply` for this form. Drives CSS layout in email.css.",
},
DataAttr {
name: "data-revert",
values: &["false"],
default: "false",
description: "When `false`, success is terminal (no auto-revert). subscribe.ts reads this.",
},
],
example_html: r#"<form class="moss-subscribe-form moss-apply-form" data-position="apply" data-revert="false">...</form>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Form element inside `.moss-apply`. Also carries `.moss-subscribe-form` so subscribe.ts hydrates it.",
},
ComponentEntry {
class: "moss-apply-matters",
kind: "instance",
parent: "moss-apply",
data_attrs: &[],
example_html: r#"<input type="text" name="matters" class="moss-input moss-apply-matters">"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Second apply-form input inside `.moss-apply-form` — a Matters username OR a one-line pitch (placeholder-only, no visible label).",
},
ComponentEntry {
class: "moss-apply-hp",
kind: "instance",
parent: "moss-apply",
data_attrs: &[],
example_html: r#"<input type="text" name="website" class="moss-apply-hp" tabindex="-1" aria-hidden="true">"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Honeypot field (off-screen) inside `.moss-apply-form`. Bots fill it; humans don't.",
},
ComponentEntry {
class: "moss-apply-status",
kind: "instance",
parent: "moss-apply",
data_attrs: &[],
example_html: r#"<div class="moss-subscribe-status moss-apply-status" aria-live="polite">...</div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Status region inside `.moss-apply-form` (also carries `.moss-subscribe-status`).",
},
ComponentEntry {
class: "moss-apply-helper",
kind: "instance",
parent: "moss-apply",
data_attrs: &[],
example_html: r#"<p class="moss-apply-helper" id="moss-apply-email-help">用于获取邀请及免费托管服务</p>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Helper text line beneath each field in `.moss-apply-form` (referenced by the field's aria-describedby). Internal — not part of the public component contract.",
},
// -------------------------------------------------------------------
// Series navigation (prev/next + collection links).
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-series-nav",
kind: "standalone",
parent: "",
data_attrs: &[],
example_html: r#"<nav class="moss-series-nav">
<div class="moss-series-nav-links">...</div>
</nav>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Series navigation bar (prev/next/collection) on series pages.",
},
ComponentEntry {
class: "moss-series-nav-links",
kind: "instance",
parent: "moss-series-nav",
data_attrs: &[],
example_html: r#"<div class="moss-series-nav-links">...</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Row holding prev/next links in series nav.",
},
ComponentEntry {
class: "moss-series-nav-link",
kind: "instance",
parent: "moss-series-nav",
data_attrs: &[],
example_html: r#"<a class="moss-series-nav-link moss-series-nav-prev" href="...">...</a>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Individual link inside series nav. Modifiers: `moss-series-nav-prev`, `moss-series-nav-next`, `empty` (placeholder).",
},
ComponentEntry {
class: "moss-series-nav-prev",
kind: "instance",
parent: "moss-series-nav",
data_attrs: &[],
example_html: r#"<a class="moss-series-nav-link moss-series-nav-prev" href="...">...</a>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Previous-page modifier on a series nav link.",
},
ComponentEntry {
class: "moss-series-nav-next",
kind: "instance",
parent: "moss-series-nav",
data_attrs: &[],
example_html: r#"<a class="moss-series-nav-link moss-series-nav-next" href="...">...</a>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Next-page modifier on a series nav link.",
},
ComponentEntry {
class: "moss-series-nav-arrow",
kind: "instance",
parent: "moss-series-nav",
data_attrs: &[],
example_html: r#"<span class="moss-series-nav-arrow">→</span>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Arrow glyph inside a series-nav link.",
},
ComponentEntry {
class: "moss-series-nav-title",
kind: "instance",
parent: "moss-series-nav",
data_attrs: &[],
example_html: r#"<span class="moss-series-nav-title">Next page title</span>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Title text of the destination page in a series-nav link.",
},
ComponentEntry {
class: "moss-series-nav-collection",
kind: "instance",
parent: "moss-series-nav",
data_attrs: &[],
example_html: r#"<div class="moss-series-nav-collection">...</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Collection-listing slot in series nav (sibling pages).",
},
ComponentEntry {
class: "moss-series-nav-collection-row",
kind: "instance",
parent: "moss-series-nav-collection",
data_attrs: &[],
example_html: r#"<div class="moss-series-nav-collection-row">...</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Row inside the collection listing of series nav.",
},
// -------------------------------------------------------------------
// Collection cover (collection landing pages).
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-collection-cover",
kind: "standalone",
parent: "",
data_attrs: &[],
example_html: r#"<section class="moss-collection-cover">
<div class="moss-collection-cover-row">...</div>
</section>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Header surface on a collection landing page.",
},
ComponentEntry {
class: "moss-collection-cover-row",
kind: "instance",
parent: "moss-collection-cover",
data_attrs: &[],
example_html: r#"<div class="moss-collection-cover-row">...</div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Row inside `.moss-collection-cover`.",
},
ComponentEntry {
class: "moss-collection-cover-body",
kind: "instance",
parent: "moss-collection-cover",
data_attrs: &[],
example_html: r#"<div class="moss-collection-cover-body">...</div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Body content slot inside `.moss-collection-cover`.",
},
// -------------------------------------------------------------------
// Form primitives (input, label, field, link).
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-input",
kind: "standalone",
parent: "",
data_attrs: &[],
example_html: r#"<input class="moss-input" type="email" />"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Generic form input primitive.",
},
ComponentEntry {
class: "moss-field",
kind: "container",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-field">
<label class="moss-label">Email</label>
<input class="moss-input" />
</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Form field group (label + input). Modifier `--inline` for horizontal layout.",
},
ComponentEntry {
class: "moss-label",
kind: "instance",
parent: "moss-field",
data_attrs: &[],
example_html: r#"<label class="moss-label">Email</label>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Label primitive for `.moss-field`. Modifier `--small` for compact form.",
},
ComponentEntry {
class: "moss-link",
kind: "standalone",
parent: "",
data_attrs: &[],
example_html: r#"<a class="moss-link" href="...">Click me</a>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Inline-link primitive (resets `<button>` chrome too). Use `--subtle` for muted variant.",
},
ComponentEntry {
class: "moss-field--inline",
kind: "instance",
parent: "moss-field",
data_attrs: &[],
example_html: r#"<div class="moss-field moss-field--inline">
<label class="moss-label">Email</label>
<input class="moss-input" />
</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "BEM modifier on `.moss-field` for horizontal label+input layout (used by settings UI primitives).",
},
ComponentEntry {
class: "moss-label--small",
kind: "instance",
parent: "moss-label",
data_attrs: &[],
example_html: r#"<label class="moss-label moss-label--small">Compact label</label>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "BEM modifier on `.moss-label` for compact form (used by services settings rows).",
},
ComponentEntry {
class: "moss-info-grid",
kind: "container",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-info-grid">
<div class="moss-field moss-field--inline">...</div>
<div class="moss-field moss-field--inline">...</div>
</div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Two-column aligned label+value rows (CSS grid with `display: contents` children). Used by the deployment settings panel; ships in the default theme so authors can reuse the layout.",
},
ComponentEntry {
class: "moss-row",
kind: "container",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-row">
<div class="moss-field">...</div>
<div class="moss-field">...</div>
</div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Horizontal flex row of equal-flex `.moss-field` children. Form-row layout helper shipped in the default theme.",
},
ComponentEntry {
class: "moss-input-feedback",
kind: "instance",
parent: "moss-field",
data_attrs: &[],
example_html: r#"<span class="moss-input-feedback">Saving…</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Auto-save status hint slot under `.moss-field`. Three state modifiers: `--success`, `--error`, `--fade-out`.",
},
ComponentEntry {
class: "moss-input-feedback--success",
kind: "instance",
parent: "moss-input-feedback",
data_attrs: &[],
example_html: r#"<span class="moss-input-feedback moss-input-feedback--success">Saved</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Success state modifier on `.moss-input-feedback`.",
},
ComponentEntry {
class: "moss-input-feedback--error",
kind: "instance",
parent: "moss-input-feedback",
data_attrs: &[],
example_html: r#"<span class="moss-input-feedback moss-input-feedback--error">Failed to save</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Error state modifier on `.moss-input-feedback`.",
},
ComponentEntry {
class: "moss-input-feedback--fade-out",
kind: "instance",
parent: "moss-input-feedback",
data_attrs: &[],
example_html: r#"<span class="moss-input-feedback moss-input-feedback--success moss-input-feedback--fade-out">Saved</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Transient fade-out modifier on `.moss-input-feedback` (applied after a success message to dismiss it).",
},
// -------------------------------------------------------------------
// Other emit surfaces (comments, colophon, shell frame, misc).
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-comments",
kind: "standalone",
parent: "",
data_attrs: &[],
example_html: r#"<section class="moss-comments">...</section>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Comments surface (per-site SQLite backend or Artalk legacy).",
},
ComponentEntry {
class: "moss-service-inactive",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<section class="moss-comments moss-service-inactive">...</section>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Co-class applied to `.moss-comments` and `.moss-subscribe-form` when the backing service is not configured. Hidden by default in published sites and revealed inside the preview chrome so authors can see the inactive surface during editing.",
},
// -------------------------------------------------------------------
// Preview link popover — emitted by `assets/js/preview.js` runtime.
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-preview-popup",
kind: "chrome",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-preview-popup" role="tooltip" aria-live="polite">
<strong class="moss-preview-title">...</strong>
<p class="moss-preview-desc">...</p>
<p class="moss-preview-text">...</p>
</div>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Floating link-preview popover injected at `document.body` level by the runtime `preview.js`. Fetches `/_moss/previews.json` and renders a hover card with title, description, and excerpt for internal links.",
},
ComponentEntry {
class: "moss-preview-title",
kind: "instance",
parent: "moss-preview-popup",
data_attrs: &[],
example_html: r#"<strong class="moss-preview-title">Article title</strong>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Title slot inside `.moss-preview-popup`.",
},
ComponentEntry {
class: "moss-preview-desc",
kind: "instance",
parent: "moss-preview-popup",
data_attrs: &[],
example_html: r#"<p class="moss-preview-desc">Short description</p>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Description slot inside `.moss-preview-popup` (from frontmatter `description`).",
},
ComponentEntry {
class: "moss-preview-text",
kind: "instance",
parent: "moss-preview-popup",
data_attrs: &[],
example_html: r#"<p class="moss-preview-text">Excerpt of the linked article…</p>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Excerpt slot inside `.moss-preview-popup` (auto-extracted from the linked article body).",
},
// -------------------------------------------------------------------
// Missing-image fallback marker — added by the inline
// `#moss-img-fallback` script in shell.html at runtime, when an <img>
// fails to load.
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-img-fallback",
kind: "chrome",
parent: "",
data_attrs: &[],
example_html: r#"<img class="site-logo moss-img-fallback" src="data:image/svg+xml,..." alt="" aria-hidden="true">"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Marker class a capture-phase `error` listener (inlined in shell.html, not a separate hashed asset) adds to any <img> whose load fails (deleted/renamed/typo'd source — never enters moss's AssetRegistry, so nothing server-side can placeholder it). The browser's native broken-image icon never appears: the script swaps the <img>'s OWN `src` in place to a self-contained blueprint-grid-pattern SVG data URI (same blueprint-blue as the animated frontend/app/components/blueprint-grid.ts canvas, without the per-instance canvas/RAF cost) and strips any enclosing <picture>'s <source> children — it does NOT replace the element, so every context-specific sizing/fit rule (.moss-card-cover > img, .moss-hero img, .site-logo, …) keeps applying because the <img>'s tag, class list, and other attributes are untouched.",
},
ComponentEntry {
class: "moss-colophon",
kind: "chrome",
parent: "",
data_attrs: &[],
example_html: r#"<footer class="moss-colophon">
<span class="moss-colophon-icon"></span>
Built with moss
</footer>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Footer colophon credit appended by moss.",
},
ComponentEntry {
class: "moss-colophon-icon",
kind: "instance",
parent: "moss-colophon",
data_attrs: &[],
example_html: r#"<span class="moss-colophon-icon"></span>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Icon slot inside `.moss-colophon`.",
},
ComponentEntry {
class: "moss-shell-frame",
kind: "chrome",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-shell-frame">...</div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "App-shell frame surface (preview chrome).",
},
ComponentEntry {
class: "moss-mobile-frame",
kind: "chrome",
parent: "moss-shell-frame",
data_attrs: &[],
example_html: r#"<html class="moss-shell-frame moss-mobile-frame">...</html>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Runtime marker the preview bridge adds to `<html>` when the shell is in mobile device-preview mode; drops the titlebar-clearance padding (the phone frame sits below the titlebar).",
},
ComponentEntry {
class: "main-nav",
kind: "chrome",
parent: "",
data_attrs: &[],
example_html: r#"<nav class="main-nav container">...</nav>"#,
example_markdown: "",
status: Status::Confirmed,
since: "0",
description: "Top site navigation bar. Legacy non-`moss-` prefix kept for theme parity.",
},
ComponentEntry {
class: "moss-child-section-divider",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<hr class="moss-child-section-divider" />"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Divider rule between auto-generated child sections.",
},
ComponentEntry {
class: "moss-unknown-shortcode",
kind: "standalone",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-unknown-shortcode">Unknown shortcode: foo</div>"#,
example_markdown: "{{< foo >}}",
status: Status::Confirmed,
since: "0",
description: "Fallback emitted when a shortcode tag is not recognised by any plugin.",
},
// -------------------------------------------------------------------
// Syntax highlight tokens (emitted by syntect inside <code>).
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-hl-keyword",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-keyword">if</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight token: keyword.",
},
ComponentEntry {
class: "moss-hl-string",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-string">"hi"</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight token: string literal.",
},
ComponentEntry {
class: "moss-hl-comment",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-comment">// note</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight token: comment.",
},
ComponentEntry {
class: "moss-hl-function",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-function">render</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight token: function name.",
},
ComponentEntry {
class: "moss-hl-type",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-type">String</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight token: type name.",
},
ComponentEntry {
class: "moss-hl-number",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-number">42</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight token: numeric literal.",
},
ComponentEntry {
class: "moss-hl-operator",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-operator">+</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight token: operator.",
},
ComponentEntry {
class: "moss-hl-builtin",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-builtin">print</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight token: builtin identifier.",
},
ComponentEntry {
class: "moss-hl-tag",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-tag">div</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight token: markup tag name.",
},
ComponentEntry {
class: "moss-hl-attr",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-attr">class</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight token: attribute name.",
},
ComponentEntry {
class: "moss-hl-meta",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-meta">@derive</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight token: meta/annotation.",
},
ComponentEntry {
class: "moss-hl-addition-bg",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-addition-bg">+ added line</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight diff token: added-line background.",
},
ComponentEntry {
class: "moss-hl-deletion",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-deletion">- removed line</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight diff token: removed-line text.",
},
ComponentEntry {
class: "moss-hl-deletion-bg",
kind: "instance",
parent: "",
data_attrs: &[],
example_html: r#"<span class="moss-hl-deletion-bg">- removed line</span>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Syntax-highlight diff token: removed-line background.",
},
ComponentEntry {
class: "moss-recent",
kind: "container",
parent: "",
data_attrs: &[],
example_html: r#"<ul class="moss-recent">
<li><a href="/posts/spring-notes/">Spring notes</a><div class="moss-recent__date">2026-04-12</div><div class="moss-recent__desc">A walk through the garden.</div></li>
</ul>"#,
example_markdown: ":::recent {count=5 since=\"2026-01-01\"}\n:::\n",
status: Status::Emerging,
since: "0",
description: "Auto-generated list of recent posts emitted by the `:::recent` shortcode. Sorted newest-first; date and description slots are filled per child. No default CSS in the bundled theme — theme authors style it freely.",
},
ComponentEntry {
class: "moss-recent__date",
kind: "instance",
parent: "moss-recent",
data_attrs: &[],
example_html: r#"<div class="moss-recent__date">2026-04-12</div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Per-entry date slot inside `.moss-recent` (BEM child). Format is `YYYY-MM-DD`, derived from frontmatter `date`. Empty string when the post lacks a parseable date.",
},
ComponentEntry {
class: "moss-recent__desc",
kind: "instance",
parent: "moss-recent",
data_attrs: &[],
example_html: r#"<div class="moss-recent__desc">A walk through the garden.</div>"#,
example_markdown: "",
status: Status::Emerging,
since: "0",
description: "Per-entry description slot inside `.moss-recent` (BEM child). Sourced from frontmatter `description`; empty when unset.",
},
// -------------------------------------------------------------------
// Ambient loop video — JS-injected wrapper + toggle (§3.5).
// The <video data-loop> synthesizer emits `data-loop` on the <video>;
// ambient-video.ts wraps it at init time.
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-ambient-video",
kind: "standalone",
parent: "",
data_attrs: &[
DataAttr {
name: "data-paused",
values: &[],
default: "",
description: "Boolean presence flag set by ambient-video.ts when the video is paused (user-initiated or reduced-motion guard). CSS uses `[data-paused]` to keep the toggle visible.",
},
],
example_html: r#"<div class="moss-ambient-video">
<video data-loop src="clip.mp4" autoplay muted loop playsinline preload="metadata"></video>
<button class="moss-ambient-toggle" type="button" aria-label="Pause video">⏸</button>
</div>"#,
example_markdown: "![[clip.mp4|loop]]",
status: Status::Emerging,
since: "1",
description: "JS-injected wrapper around a `video[data-loop]` element. Provides the positioning context for `.moss-ambient-toggle` and the `[data-paused]` state hook. Not emitted by the Rust synthesizer — ambient-video.ts creates it at init.",
},
ComponentEntry {
class: "moss-ambient-toggle",
kind: "instance",
parent: "moss-ambient-video",
data_attrs: &[],
example_html: r#"<button class="moss-ambient-toggle" type="button" aria-label="Pause video">⏸</button>"#,
example_markdown: "",
status: Status::Emerging,
since: "1",
description: "Chrome-free pause/play toggle button for ambient loop videos. Injected by ambient-video.ts. Keyboard-focusable; `aria-label` toggles between \"Pause video\" and \"Play video\". Visible on hover/focus of `.moss-ambient-video` and always visible when `[data-paused]`. Satisfies WCAG 2.2.2 Level A (Pause, Stop, Hide).",
},
// -------------------------------------------------------------------
// LaTeX math (ADR-030). P1 emits the escaped source in a marked
// `<code>`; P2 replaces the element's *contents* with a typeset
// `<svg>` while keeping the class and `data-moss-math` stable, so a
// theme selector written against P1 keeps working across the upgrade.
// -------------------------------------------------------------------
ComponentEntry {
class: "moss-math",
kind: "standalone",
parent: "",
data_attrs: &[
DataAttr {
name: "data-moss-math",
values: &["inline", "display"],
default: "inline",
description: "Which delimiter produced the equation: `inline` for `$…$`, `display` for `$$…$$`. Carries the distinction to CSS and to the typesetter so neither has to re-derive it from context — a theme can select on it today to centre display math; moss ships no math stylesheet of its own yet, so both variants currently inherit plain `<code>` styling.",
},
],
example_html: r#"<code class="moss-math" data-moss-math="inline">$E = mc^2$</code>"#,
example_markdown: "Energy $E = mc^2$.",
status: Status::Emerging,
since: "1",
description: "A LaTeX equation. In P1 the element holds the author's own markdown source — `$` / `$$` delimiters included — HTML-escaped: an honest fallback that never shows a blank where an equation was written, and never deletes the delimiters of prose that merely looked like math. Requires `[site].math` (default on).",
},
ComponentEntry {
class: "moss-math-scroll",
kind: "container",
parent: "",
data_attrs: &[],
example_html: r#"<div class="moss-math-scroll"><svg class="moss-math" data-moss-math="display">…</svg></div>"#,
example_markdown: "$$E = mc^2$$",
status: Status::Emerging,
since: "1",
description: "Horizontal-scroll container the build path wraps around typeset display math (`svg.moss-math[data-moss-math=\"display\"]`). On a narrow viewport a wide equation scrolls inside this box at its natural size rather than shrinking to unreadability or pushing the page into horizontal overflow. Emitted only by P2's typeset path; the P1 `<code>` fallback is never wrapped. A display SVG left unwrapped still cannot overflow the page — it falls back to scaling down via `max-width: 100%`.",
},
];
/// Implementation classes that are emitted by moss for internal functionality
/// but must not appear in the public theme-facing contract (`moss describe` /
/// `docs/contract/reference.md`). These classes ARE present in `COMPONENTS` for
/// the sync-test to validate their HTML class literals, but `is_public()` hides
/// them from agents, themes, and `reference.md` generation.
const INTERNAL_CLASSES: &[&str] = &[
"moss-apply",
"moss-apply-form",
"moss-apply-matters",
"moss-apply-hp",
"moss-apply-status",
"moss-apply-helper",
];
impl ComponentEntry {
/// True for entries that belong in the public, agent/theme-facing surface.
/// v1 rule: not retired AND not an internal implementation class.
///
/// Internal classes (e.g. all `moss-apply*`) stay in COMPONENTS so the
/// sync-test can validate them, but they must not surface in `moss describe`
/// or `docs/contract/reference.md` — they are subject to change at any time.
pub fn is_public(&self) -> bool {
self.status != Status::Retired && !INTERNAL_CLASSES.contains(&self.class)
}
}
/// Iterator over class names with `Status::Retired`. Used by the build
/// pipeline's theme lint to warn users about pre-v1 vocabulary.
///
/// Exposed as an iterator over `&'static str` so callers don't need to
/// import the `Status` enum (keeps moss-core's surface narrow).
pub fn retired_class_names() -> impl Iterator<Item = &'static str> {
COMPONENTS.iter()
.filter(|e| e.status == Status::Retired)
.map(|e| e.class)
}
#[cfg(test)]
mod tests {
use super::*;
/// Orphan-gate: every class in `INTERNAL_CLASSES` must exist as a `class`
/// in `COMPONENTS`. If a class is renamed in the emitter *and* in
/// `INTERNAL_CLASSES` but forgotten in `COMPONENTS`, it would silently
/// re-enter the public contract surface (`is_public()` only hides known
/// internals). This test prevents that gap.
#[test]
fn every_internal_class_has_a_components_entry() {
let component_classes: std::collections::HashSet<&'static str> =
COMPONENTS.iter().map(|e| e.class).collect();
for &internal in INTERNAL_CLASSES {
assert!(
component_classes.contains(internal),
"INTERNAL_CLASSES entry '{}' has no matching entry in COMPONENTS — \
add a ComponentEntry for it or remove it from INTERNAL_CLASSES",
internal
);
}
}
}