What makes a box a card, derived from what the engine painted rather than from an attribute, and the seven interactions a card may name.
Generated from libs/oshun/workbench-kit/src/card-use.ts by
node scripts/v1-workbenches/generate-workbench-kit-api-reference.mjs. Ledger:
S7.22.a. Do not edit by hand.
Summary#
src/card-use.ts
| Entry point | Runtime class | Authorized by |
|---|---|---|
@oshun/workbench-kit/card-use |
contract |
S7.22.a |
Exports#
| Symbol | Kind | Summary |
|---|---|---|
| AUTHORED_ORIGINS | enumeration | Origins a component author wrote and can therefore be asked to change. |
| CARD_INTERACTIONS_THE_PARENT_NAMES | enumeration | The four S7.22.a spells out. |
| CARD_USE_FAULTS | enumeration | — |
| CardDrive | interface | — |
| CardInteractionWord | type | — |
| CardUseFault | type | — |
| cardUseFaults | function | The card-use review. |
| CardUseFinding | interface | The container inventory and the card-use review (S7.22.a). |
| cardUseHeadline | function | The sentence the review reports. |
| cardUseInventory | function | — |
| cardUseSummary | function | — |
| CardUseSummary | interface | — |
| CELL_ROLES | enumeration | Computed ARIA roles whose element is one square of a ruling. |
| COLLECTION_CONTAINER_ROLES | enumeration | Roles whose element is the collection its children are members of. |
| COLLECTION_CONTEXTS | enumeration | How this element sits relative to the nearest collection above it. |
| COLLECTION_MEMBER_ROLES | enumeration | Roles whose element stands for one member of a collection. |
| collectionContext | function | Where this element sits relative to the nearest collection above it. |
| CollectionContext | type | — |
| CONTAINER_DISPOSITIONS | enumeration | — |
| CONTAINER_ENCLOSURES | enumeration | The four ways an element draws a boundary between its content and the surface. |
| CONTAINER_INVENTORY_FAULTS | enumeration | — |
| CONTAINER_ROLES | enumeration | The derived role of an enclosure. |
| containerDisposition | function | One disposition per container, derived. |
| ContainerDisposition | type | — |
| ContainerEnclosure | type | — |
| ContainerInventoryFault | type | — |
| containerInventoryFaults | function | — |
| ContainerObservation | interface | — |
| ContainerRole | type | — |
| CONTROL_ROLES | enumeration | Computed ARIA roles whose element IS a control rather than a place to put content. |
| derivedContainerRole | function | The role the drawing implies, with the declaration deliberately unread. |
| drawsAsABox | function | True when the boundary closes into a shape rather than marking a line. |
| DRIVE_OUTCOMES | enumeration | What happened when the run tried to perform a declared interaction. |
| DriveOutcome | type | — |
| effectiveInteraction | function | The one word a container is held to: its declaration when the vocabulary accepts it, otherwise the first interaction its own markup announces. |
| enclosesContent | function | True when the enclosure is a box AND holds its content away from its own edge. |
| ENCLOSURE_ORIGINS | enumeration | Where the enclosure came from, which decides whether this review can answer for it at all. |
| EnclosureOrigin | type | — |
| INTERACTION_ANNOUNCEMENTS | constant | The markup that announces an interaction, where a standard one exists. |
| INTERACTION_EVIDENCE | constant | The observable each interaction is settled by. |
| INTERACTION_EVIDENCE_KINDS | enumeration | What must be observed to have changed when a reader performs each interaction. |
| INTERACTION_SEATS | enumeration | Where the interaction on a container actually sits. |
| InteractionEvidenceKind | type | — |
| INTERACTIONS_A_CARD_MAY_NAME | enumeration | The seven the layer performs, plus the honest absence. |
| InteractionSeat | type | — |
| InventoryRow | interface | — |
| InventoryRun | interface | — |
| isEnclosed | function | True when the element drew a boundary of any kind. |
| LANDMARK_ROLES | enumeration | Computed ARIA roles that make an element a named area of the page. |
| MARK_MAX_LINES | constant | The tallest a box of one text run can be and still be a MARK rather than a place to put content. |
| MEANINGFUL_CARD_INTERACTIONS | enumeration | The seven that are an interaction; none is the eighth word and is not one. |
| MIN_CLOSED_EDGES | constant | Below this many drawn edges, a stroke marks an edge rather than closing a shape. |
| MIN_PADDED_SIDES | constant | Below this, an enclosure holds nothing away from its own edge. |
| OBJECT_IDENTITY_SIGNALS | enumeration | The two announcements that make a CONTROL stand for an object. |
| OVERLAY_ROLES | enumeration | Computed ARIA roles whose element is drawn over the document rather than in it. |
| REFUSED_CARD_INTERACTIONS | constant | Words that will be offered and must not be accepted. |
| RefusedInteraction | interface | — |
| REPEAT_GROUP_FLOOR | constant | How many identically-enclosed siblings make a repeat, when nothing says so. |
| repeatsAsACollection | function | True when the enclosure is one of a set of things drawn the same way. |
| ROLES_OUTSIDE_THE_CARD_QUESTION | enumeration | Roles whose boundary is not a claim about content gathered together. |
| ROLES_THE_PARENT_NAMES | enumeration | The three words S7.22.a itself uses for the things it is asking about. |
Shapes#
AUTHORED_ORIGINS#
Origins a component author wrote and can therefore be asked to change.
Values: layer-stylesheet, unscoped-stylesheet, inline-style
CARD_INTERACTIONS_THE_PARENT_NAMES#
The four S7.22.a spells out.
Values: selectable, draggable, comparable, previewable
CARD_USE_FAULTS#
Values: card-declares-no-interaction,
card-interaction-outside-the-vocabulary, card-interaction-refused-by-name,
card-is-a-border-around-its-own-control,
card-declares-an-interaction-nothing-performs,
card-not-distinguishable-from-its-siblings,
declared-interaction-never-driven, declared-interaction-not-performed,
drive-observed-the-wrong-evidence, non-card-declares-a-card-interaction,
interaction-driven-with-no-declaration,
declared-interaction-not-announced-in-the-markup
CardDrive#
| Field | Type | Required | Notes |
|---|---|---|---|
containerId |
string |
required | — |
interaction |
string |
required | The word the drive was performed against. |
outcome |
DriveOutcome | required | — |
evidence |
InteractionEvidenceKind | null — InteractionEvidenceKind |
required | What the run observed to have changed, or null when nothing did. |
before |
string |
required | The observable before and after, so a drive that changed nothing is legible. |
after |
string |
required | — |
CardInteractionWord#
(typeof INTERACTIONS_A_CARD_MAY_NAME)[number];
CardUseFault#
(typeof CARD_USE_FAULTS)[number];
cardUseFaults#
The card-use review.
cardUseFaults(observations: readonly ContainerObservation[], drives: readonly CardDrive[]): readonly CardUseFinding[]
CardUseFinding#
The container inventory and the card-use review (S7.22.a).
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
ContainerInventoryFault | CardUseFault — CardUseFault, ContainerInventoryFault |
required | — |
subject |
string |
required | — |
detail |
string |
required | — |
cardUseHeadline#
The sentence the review reports.
cardUseHeadline(summary: CardUseSummary): string
cardUseInventory#
cardUseInventory(observations: readonly ContainerObservation[], drives: readonly CardDrive[]): readonly InventoryRow[]
cardUseSummary#
cardUseSummary(rows: readonly InventoryRow[], run: InventoryRun): CardUseSummary
CardUseSummary#
| Field | Type | Required | Notes |
|---|---|---|---|
containers |
number |
required | — |
cards |
number |
required | — |
driven |
number |
required | — |
declaredOnly |
number |
required | — |
withoutInteraction |
number |
required | — |
notReviewable |
number |
required | — |
componentsReached |
number |
required | — |
componentsNotExercised |
number |
required | — |
CELL_ROLES#
Computed ARIA roles whose element is one square of a ruling.
Values: cell, columnheader, gridcell, rowheader
COLLECTION_CONTAINER_ROLES#
Roles whose element is the collection its children are members of.
Values: feed, grid, list, listbox, menu, radiogroup, table,
tablist, tree, treegrid
COLLECTION_CONTEXTS#
How this element sits relative to the nearest collection above it.
Values: container, member, none
COLLECTION_MEMBER_ROLES#
Roles whose element stands for one member of a collection.
Values: article, listitem, option, row, tab, treeitem
collectionContext#
Where this element sits relative to the nearest collection above it.
collectionContext(observation: ContainerObservation): CollectionContext
CollectionContext#
(typeof COLLECTION_CONTEXTS)[number];
CONTAINER_DISPOSITIONS#
Values: card-interaction-driven, card-interaction-declared-only,
card-with-no-interaction, boundary-carries-meaning,
boundary-not-reviewable
CONTAINER_ENCLOSURES#
The four ways an element draws a boundary between its content and the surface.
Values: border, elevation, fill, inset-rule
CONTAINER_INVENTORY_FAULTS#
Values: container-drawn-by-no-layer-stylesheet,
container-enclosure-claimed-by-two-stylesheets,
declared-role-contradicts-the-drawn-role,
declared-role-outside-the-vocabulary, container-with-no-inner-space,
component-not-exercised, observation-names-a-host-the-run-did-not-load
CONTAINER_ROLES#
The derived role of an enclosure.
Values: region, section, card, panel, well, control, overlay,
divider, cell, mark
containerDisposition#
One disposition per container, derived.
containerDisposition(observation: ContainerObservation, drives: readonly CardDrive[]): ContainerDisposition
ContainerDisposition#
(typeof CONTAINER_DISPOSITIONS)[number];
ContainerEnclosure#
(typeof CONTAINER_ENCLOSURES)[number];
ContainerInventoryFault#
(typeof CONTAINER_INVENTORY_FAULTS)[number];
containerInventoryFaults#
containerInventoryFaults(run: InventoryRun): readonly CardUseFinding[]
ContainerObservation#
| Field | Type | Required | Notes |
|---|---|---|---|
containerId |
string |
required | Stable within one run; the caller's join key between an observation and a drive. |
hostId |
string |
required | The fixture host whose document this was measured in. |
stylesheets |
readonly string[] |
required | The layer stylesheets carrying a rule that matched this element AND declared one of the enclosure properties. Empty means the boundary came from somewhere this review cannot reach. |
enclosureOrigin |
EnclosureOrigin | required | Which party declared the boundary; see ENCLOSURE_ORIGINS. |
enclosures |
readonly ContainerEnclosure[] — ContainerEnclosure |
required | — |
edgesDrawn |
number |
required | How many of the four edges carry a stroke, 0..4. |
paddingSides |
number |
required | How many of the four sides hold content away from the edge, 0..4. |
repeatSiblings |
number |
required | Members of this element's identically-enclosed sibling group, itself included. One means the enclosure does not repeat. |
ownRole |
string | null |
required | The computed ARIA role of the element itself, or null when it has none. |
parentRole |
string | null |
required | The computed ARIA role of the nearest ancestor carrying one, or null. |
soleElementChild |
boolean |
required | Whether this element is reached from its role-bearing ancestor through sole-child steps only — i.e. it IS the whole of that member. |
hasElementChildren |
boolean |
required | Whether the element has any element children at all. |
holdsOnlyControls |
boolean |
required | Whether every element child is an interactive control, and there is at least one. |
blockLines |
number |
required | The element's rendered height in whole line-heights. |
impliedInteractions |
readonly string[] |
required | The interactions the MARKUP announces, read off the element itself. |
scrolls |
boolean |
required | Whether any overflow axis is not visible, i.e. the box scrolls. |
holdsOwnText |
boolean |
required | Whether the element has text of its OWN — a direct child text node that is not whitespace. |
statedName |
string | null |
required | The name the container STATES: its aria-label when it has one, otherwise its own normalised visible text. |
siblingNames |
readonly string[] |
required | The stated names of the other members of the repeat group. |
seat |
InteractionSeat | required | Where the interaction actually lives, measured rather than declared. |
declaredRole |
string | null |
required | data-container-role, when the component wrote one. |
declaredInteraction |
string | null |
required | data-card-interaction, when the component wrote one. |
nestingDepth |
number |
required | Enclosing containers above this one in the document. |
ContainerRole#
(typeof CONTAINER_ROLES)[number];
CONTROL_ROLES#
Computed ARIA roles whose element IS a control rather than a place to put content.
Values: button, checkbox, combobox, link, menuitem, radio,
searchbox, slider, spinbutton, switch, textbox
derivedContainerRole#
The role the drawing implies, with the declaration deliberately unread.
derivedContainerRole(observation: ContainerObservation): ContainerRole
drawsAsABox#
True when the boundary closes into a shape rather than marking a line.
drawsAsABox(observation: ContainerObservation): boolean
DRIVE_OUTCOMES#
What happened when the run tried to perform a declared interaction.
Values: performed, refused, not-attempted
DriveOutcome#
(typeof DRIVE_OUTCOMES)[number];
effectiveInteraction#
The one word a container is held to: its declaration when the vocabulary accepts it, otherwise the first interaction its own markup announces.
effectiveInteraction(observation: ContainerObservation): CardInteractionWord | null
enclosesContent#
True when the enclosure is a box AND holds its content away from its own edge.
enclosesContent(observation: ContainerObservation): boolean
ENCLOSURE_ORIGINS#
Where the enclosure came from, which decides whether this review can answer for it at all.
Values: layer-stylesheet, unscoped-stylesheet, inline-style, user-agent
EnclosureOrigin#
(typeof ENCLOSURE_ORIGINS)[number];
INTERACTION_ANNOUNCEMENTS#
The markup that announces an interaction, where a standard one exists.
INTERACTION_EVIDENCE#
The observable each interaction is settled by.
INTERACTION_EVIDENCE_KINDS#
What must be observed to have changed when a reader performs each interaction.
Values: selection-state-on-the-container, location-or-rendered-object,
expanded-state-on-the-container, container-left-the-document,
container-changed-parent-or-position, comparison-surface-names-it,
preview-surface-names-it
INTERACTION_SEATS#
Where the interaction on a container actually sits.
Values: the-container-itself, a-descendant-control, nothing
InteractionEvidenceKind#
(typeof INTERACTION_EVIDENCE_KINDS)[number];
INTERACTIONS_A_CARD_MAY_NAME#
The seven the layer performs, plus the honest absence.
Values: selectable, draggable, comparable, previewable, navigable,
expandable, dismissable, none
InteractionSeat#
(typeof INTERACTION_SEATS)[number];
InventoryRow#
| Field | Type | Required | Notes |
|---|---|---|---|
containerId |
string |
required | — |
hostId |
string |
required | — |
role |
ContainerRole | required | — |
enclosures |
readonly ContainerEnclosure[] — ContainerEnclosure |
required | — |
stylesheets |
readonly string[] |
required | — |
declaredInteraction |
string | null |
required | — |
disposition |
ContainerDisposition | required | — |
InventoryRun#
| Field | Type | Required | Notes |
|---|---|---|---|
components |
readonly string[] |
required | Every component file the layer ships, from a walk of the directory. |
hostsLoaded |
readonly string[] |
required | The hosts the run actually loaded. |
hostSubjects |
Readonly<Record<string, readonly string[]>> |
required | Which components each loaded host renders. |
observations |
readonly ContainerObservation[] — ContainerObservation |
required | — |
isEnclosed#
True when the element drew a boundary of any kind.
isEnclosed(observation: ContainerObservation): boolean
LANDMARK_ROLES#
Computed ARIA roles that make an element a named area of the page.
Values: banner, complementary, contentinfo, form, main, navigation,
region, search
MARK_MAX_LINES#
The tallest a box of one text run can be and still be a MARK rather than a place to put content.
Value: 2
MEANINGFUL_CARD_INTERACTIONS#
The seven that are an interaction; none is the eighth word and is not one.
Values: selectable, draggable, comparable, previewable, navigable,
expandable, dismissable
MIN_CLOSED_EDGES#
Below this many drawn edges, a stroke marks an edge rather than closing a shape.
Value: 3
MIN_PADDED_SIDES#
Below this, an enclosure holds nothing away from its own edge.
Value: 2
OBJECT_IDENTITY_SIGNALS#
The two announcements that make a CONTROL stand for an object.
Values: selectable, draggable
OVERLAY_ROLES#
Computed ARIA roles whose element is drawn over the document rather than in it.
Values: alertdialog, dialog, menu, tooltip
REFUSED_CARD_INTERACTIONS#
Words that will be offered and must not be accepted.
RefusedInteraction#
| Field | Type | Required | Notes |
|---|---|---|---|
word |
string |
required | — |
reason |
string |
required | — |
REPEAT_GROUP_FLOOR#
How many identically-enclosed siblings make a repeat, when nothing says so.
Value: 3
repeatsAsACollection#
True when the enclosure is one of a set of things drawn the same way.
repeatsAsACollection(observation: ContainerObservation): boolean
ROLES_OUTSIDE_THE_CARD_QUESTION#
Roles whose boundary is not a claim about content gathered together.
Values: control, overlay, divider, cell, mark
ROLES_THE_PARENT_NAMES#
The three words S7.22.a itself uses for the things it is asking about.
Values: container, card, panel
Valid examples#
No committed fixture corpus covers this page's accepted cases; they are unit-level and live in the module's own spec.
Invalid examples#
No committed fixture corpus covers this page's refused cases; they are unit-level and live in the module's own spec.
Authorization and scope#
Not applicable: nothing on this page carries an actor, a grant, a scope or a tenant, so authorization is decided entirely by the caller.
Idempotency and concurrency#
Not applicable: nothing on this page is retried or applied twice: these are declarations, not operations.
Pagination#
Not applicable: nothing on this page returns a collection a caller reads in pages.
State and failure#
| Symbol | Type | Notes |
| --------------------------------- | -------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| CardDrive.outcome | DriveOutcome | — |
| ContainerObservation.statedName | string | null | The name the container STATES: its aria-label when it has one, otherwise its own normalised visible text. |
| DRIVE_OUTCOMES | enumeration | What happened when the run tried to perform a declared interaction. |
| DriveOutcome | type | — |
| REFUSED_CARD_INTERACTIONS | constant | Words that will be offered and must not be accepted. |
Compatibility#
Not applicable: nothing on this page is versioned independently of the package.
Deprecation#
Not applicable: nothing on this page can be deprecated on its own; the package version is its lifecycle.
Evidence#
evidence/v1-workbenches/workbench-kit-export-map.jsonlibs/oshun/workbench-kit/src/card-use.ts