Module role_spec 

Canonical ROLE → semantic HTML element mapping (spec/OPCODE.md §semantic properties) + typography-driven heading levels, shared with the TypeScript DOM client: the Rust renderer consumes these tables directly, and pathland-ts-codegen emits the TS equivalents into generated/role-spec.ts — so the semantic-tag / ARIA / heading mapping cannot drift between the renderers.

Rule summary:

• ROLE is semantic structure only. The catalog (see pathland_core::role) holds landmarks, headings, paragraphs and lists — interactive/control roles (button, link, checkbox, …) are NOT roles: they are intrinsic to the control components (BUTTON → <button>, TOGGLE → <input type="checkbox">, MENU → role="menu"), and a custom-looking button uses Button + ButtonStyle.
• A role retags only a generic div/span shell (see GENERIC_COMPONENTS) to its semantic element (<nav>, <main>, …).
• Control components keep their native element and emit no ARIA role from ROLE.
• Headings come from a TEXT_STYLE typography (LargeTitle…Headline → <h1>–<h5>, always a heading) or from ROLE_HEADER (default <h2>); raw font modifiers never imply a heading. Non-heading text defaults to <span>; ROLE_PARAGRAPH gives <p>.

Structs

RoleTag

A role that maps onto a native semantic HTML element. On a generic shell the role renders as RoleTag::tag; when the role is applied to a non-generic component, RoleTag::aria is the ARIA fallback.

Enums

ShellKind

How a role interacts with an element’s shell. Decided from the component when known; the DOM client derives it from the element’s tag when hydrating (it has no component for SSR-provided nodes).

Constants

GENERIC_COMPONENTS

Components whose shell is a generic div/span — the only shells a semantic role retags. Control components keep their native element.

HEADING_STYLES

The TEXT_STYLE typographies that imply a heading element (<h1>–<h5>), mapping style code → heading level. A title/headline style on a TEXT is always a heading, even without ROLE_HEADER.

NATIVE_ROLE_COMPONENTS

Components whose native element conveys their role — they never emit an ARIA role from the ROLE property.

ROLE_TAGS

Semantic roles with a native element. HEADER (heading) defaults to <h2> — its level is raised by a TEXT_STYLE typography (see HEADING_STYLES). SUMMARY maps to <section> (a named region).

Functions

aria_role

The ARIA role attribute value to emit for (shell kind, role), or None when the element already conveys the role (a semantic tag or a native control element). Control roles no longer exist in the catalog, so any unknown/reserved code is a no-op.

heading_level

The heading level a TEXT_STYLE typography implies, or None for the non-heading styles (Subheadline, Body, Callout, Footnote, Caption, Caption2).

heading_tag

The heading element tag for a level (1 → h1 … 5 → h5).

semantic_tag

The semantic tag a (shell kind, role) pair resolves to, or None when the element keeps its default shell tag.

shell_kind

Resolve a component to its shell kind.

text_tag

The effective tag for a generic TEXT shell: a heading TEXT_STYLE wins (always a heading), then the semantic role (ROLE_HEADER → <h2>, ROLE_PARAGRAPH → <p>, landmarks), else None (→ <span>).