Eve library

Container inventory and card use

Evidence

Revision 1

On this page

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#

ts
(typeof INTERACTIONS_A_CARD_MAY_NAME)[number];

CardUseFault#

ts
(typeof CARD_USE_FAULTS)[number];

cardUseFaults#

The card-use review.

ts
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.

ts
cardUseHeadline(summary: CardUseSummary): string

cardUseInventory#

ts
cardUseInventory(observations: readonly ContainerObservation[], drives: readonly CardDrive[]): readonly InventoryRow[]

cardUseSummary#

ts
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.

ts
collectionContext(observation: ContainerObservation): CollectionContext

CollectionContext#

ts
(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.

ts
containerDisposition(observation: ContainerObservation, drives: readonly CardDrive[]): ContainerDisposition

ContainerDisposition#

ts
(typeof CONTAINER_DISPOSITIONS)[number];

ContainerEnclosure#

ts
(typeof CONTAINER_ENCLOSURES)[number];

ContainerInventoryFault#

ts
(typeof CONTAINER_INVENTORY_FAULTS)[number];

containerInventoryFaults#

ts
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#

ts
(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.

ts
derivedContainerRole(observation: ContainerObservation): ContainerRole

drawsAsABox#

True when the boundary closes into a shape rather than marking a line.

ts
drawsAsABox(observation: ContainerObservation): boolean

DRIVE_OUTCOMES#

What happened when the run tried to perform a declared interaction.

Values: performed, refused, not-attempted

DriveOutcome#

ts
(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.

ts
effectiveInteraction(observation: ContainerObservation): CardInteractionWord | null

enclosesContent#

True when the enclosure is a box AND holds its content away from its own edge.

ts
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#

ts
(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#

ts
(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#

ts
(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.

ts
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.

ts
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.json
  • libs/oshun/workbench-kit/src/card-use.ts