When a nested border or elevation adds meaning, what an unwarranted one should be flattened into, and the before/after measurement that proves the flattening lost nothing.
Generated from libs/oshun/workbench-kit/src/composition.ts by
node scripts/v1-workbenches/generate-workbench-kit-api-reference.mjs. Ledger:
S7.22.b. Do not edit by hand.
Summary#
src/composition.ts
| Entry point | Runtime class | Authorized by |
|---|---|---|
@oshun/workbench-kit/composition |
contract |
S7.22.b |
Exports#
| Symbol | Kind | Summary |
|---|---|---|
| ALIGNMENT_TOLERANCE_PX | constant | How far two edges may be apart and still count as the same line. |
| BOUNDARY_CARRIES | enumeration | The things a reader gets from a boundary that a flattening has to keep. |
| BoundaryCarried | type | — |
| boundaryCarries | function | What this boundary is carrying, measured. |
| boxDepth | function | How many boxes enclose this one. |
| CHANNEL_CLAIMS | constant | The sentence each of S7.22.a's four channels says to a reader. |
| ChannelReading | interface | One channel's values across every instance of the same component part. |
| channelWarrants | function | The warrants this channel actually has, measured. |
| COMPOSITION_VERDICTS | enumeration | — |
| compositionFaults | function | The composition as drawn. |
| CompositionFinding | interface | — |
| compositionHeadline | function | The sentence the review reports. |
| compositionInventory | function | — |
| CompositionRow | interface | — |
| CompositionSnapshot | interface | One composition, measured. |
| compositionSummary | function | — |
| CompositionSummary | interface | — |
| CompositionTransition | interface | — |
| compositionVerdict | function | One verdict per container, derived. |
| CompositionVerdict | type | — |
| CONCENTRIC_INSET_PX | constant | How close a box's edges may be to its parent box's content edges before the two lines are one line drawn twice. |
| DESTINATION_COST_ORDER | enumeration | Cheapest first, where cheap means least added to the page. |
| DESTINATION_PRESERVES | constant | What each destination can still carry. |
| DESTINATIONS_FOR_ARRANGEMENT | constant | Which destinations an arrangement leaves available. |
| DESTINATIONS_NEEDING_A_SET | enumeration | Destinations that describe a SET and are therefore unavailable to one box. |
| DESTINATIONS_THE_PARENT_NAMES | enumeration | The six the item names, kept visible so the seventh is arguable. |
| ENCLOSURE_WARRANTS | enumeration | The seven facts that justify a nested boundary. |
| EnclosureWarrant | type | — |
| FLATTENING_DESTINATIONS | enumeration | Where an unwarranted boundary goes. |
| FLATTENING_FAULTS | enumeration | — |
| FlatteningDestination | type | — |
| FlatteningFault | type | — |
| flatteningFaults | function | The before/after composition review. |
| FlatteningPrescription | interface | — |
| isConcentric | function | True when this box's edges sit on its parent box's content edges. |
| MAX_PARALLEL_EDGES | constant | The most parallel edges that may run above one run of text. |
| NamedGroup | interface | — |
| NestedObservation | interface | A container measured again, with the facts a NESTED boundary is judged on. |
| NESTING_FAULTS | enumeration | — |
| NestingFault | type | — |
| parallelEdges | function | How many parallel edges run above this box's own content. |
| prescribeFlattening | function | Where this boundary should go, or null when nothing available can carry it. |
| Rect | interface | — |
| ROLE_WARRANTS | constant | The warrant each of S7.22.a's ten roles brings with it, and the three that bring none. |
| SIBLING_ARRANGEMENTS | enumeration | How a box sits relative to the other boxes at its level. |
| siblingArrangement | function | How this box sits relative to the boxes at its level. |
| SiblingArrangement | type | — |
| STATE_WARRANT_VERDICTS | enumeration | The three answers a state warrant can have, and one of them is not an answer. |
| StateSignal | interface | — |
| stateWarrantVerdict | function | What a channel's variance across the instances of its part says. |
| StateWarrantVerdict | type | — |
| unwarrantedChannels | function | The channels this box draws that nothing in the document justifies. |
| WARRANTS_FOR_CHANNEL | constant | Which warrants can justify which claim. |
Shapes#
ALIGNMENT_TOLERANCE_PX#
How far two edges may be apart and still count as the same line.
Value: 2
BOUNDARY_CARRIES#
The things a reader gets from a boundary that a flattening has to keep.
Values: grouping, a-name-of-its-own, a-state-signal, membership,
separation
BoundaryCarried#
(typeof BOUNDARY_CARRIES)[number];
boundaryCarries#
What this boundary is carrying, measured.
boundaryCarries(observation: NestedObservation): readonly BoundaryCarried[]
boxDepth#
How many boxes enclose this one.
boxDepth(observation: NestedObservation): number
CHANNEL_CLAIMS#
The sentence each of S7.22.a's four channels says to a reader.
ChannelReading#
One channel's values across every instance of the same component part.
| Field | Type | Required | Notes |
|---|---|---|---|
channel |
ContainerEnclosure | required | — |
shapeValues |
readonly string[] |
required | Distinct non-colour values of the channel across the class group. |
colourValues |
readonly string[] |
required | Distinct colour values of the channel across the class group. |
instances |
number |
required | How many elements in this document share this element's class list. |
channelWarrants#
The warrants this channel actually has, measured.
channelWarrants(observation: NestedObservation, channel: ContainerEnclosure): readonly EnclosureWarrant[]
COMPOSITION_VERDICTS#
Values: boundary-warranted, boundary-partly-warranted,
boundary-unwarranted, boundary-unwarranted-and-unreplaceable,
boundary-not-nested
compositionFaults#
The composition as drawn.
compositionFaults(observations: readonly NestedObservation[]): readonly CompositionFinding[]
CompositionFinding#
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
NestingFault | FlatteningFault — FlatteningFault, NestingFault |
required | — |
subject |
string |
required | — |
detail |
string |
required | — |
compositionHeadline#
The sentence the review reports.
compositionHeadline(summary: CompositionSummary): string
compositionInventory#
compositionInventory(observations: readonly NestedObservation[]): readonly CompositionRow[]
CompositionRow#
| Field | Type | Required | Notes |
|---|---|---|---|
containerId |
string |
required | — |
hostId |
string |
required | — |
role |
ContainerRole | required | — |
boxDepth |
number |
required | — |
parallelEdges |
number |
required | — |
arrangement |
SiblingArrangement | required | — |
channels |
readonly ContainerEnclosure[] — ContainerEnclosure |
required | — |
warrants |
readonly EnclosureWarrant[] — EnclosureWarrant |
required | — |
carried |
readonly BoundaryCarried[] — BoundaryCarried |
required | — |
destination |
FlatteningDestination | null — FlatteningDestination |
required | — |
verdict |
CompositionVerdict | required | — |
CompositionSnapshot#
One composition, measured.
| Field | Type | Required | Notes |
|---|---|---|---|
label |
string |
required | — |
statements |
readonly string[] |
required | — |
namedGroups |
readonly NamedGroup[] — NamedGroup |
required | — |
readingOrder |
readonly string[] |
required | — |
stateSignals |
readonly StateSignal[] — StateSignal |
required | — |
boxes |
number |
required | — |
maxParallelEdges |
number |
required | — |
compositionSummary#
compositionSummary(rows: readonly CompositionRow[], transitions: readonly CompositionTransition[]): CompositionSummary
CompositionSummary#
| Field | Type | Required | Notes |
|---|---|---|---|
containers |
number |
required | — |
nested |
number |
required | — |
warranted |
number |
required | — |
partlyWarranted |
number |
required | — |
unwarranted |
number |
required | — |
unreplaceable |
number |
required | — |
deepestParallelEdges |
number |
required | — |
transitionsTaken |
number |
required | — |
transitionsPrescribed |
number |
required | — |
CompositionTransition#
| Field | Type | Required | Notes |
|---|---|---|---|
subject |
string |
required | — |
destination |
string |
required | — |
before |
CompositionSnapshot | required | — |
after |
CompositionSnapshot | required | — |
compositionVerdict#
One verdict per container, derived.
compositionVerdict(observation: NestedObservation): CompositionVerdict
CompositionVerdict#
(typeof COMPOSITION_VERDICTS)[number];
CONCENTRIC_INSET_PX#
How close a box's edges may be to its parent box's content edges before the two lines are one line drawn twice.
Value: 3
DESTINATION_COST_ORDER#
Cheapest first, where cheap means least added to the page.
Values: unwrap, divider, column, list, group, section, region
DESTINATION_PRESERVES#
What each destination can still carry.
DESTINATIONS_FOR_ARRANGEMENT#
Which destinations an arrangement leaves available.
DESTINATIONS_NEEDING_A_SET#
Destinations that describe a SET and are therefore unavailable to one box.
Values: list
DESTINATIONS_THE_PARENT_NAMES#
The six the item names, kept visible so the seventh is arguable.
Values: region, section, column, divider, list, group
ENCLOSURE_WARRANTS#
The seven facts that justify a nested boundary.
Values: the-box-is-the-object, the-box-is-the-control,
the-box-is-one-square-of-a-ruling, the-box-is-drawn-over-the-document,
the-boundary-is-a-line-and-not-a-box,
the-box-states-one-value-about-something-else, the-box-cuts-a-scroll,
the-box-is-a-named-area-of-the-page,
the-box-holds-nothing-and-is-a-drawn-indication, the-channel-carries-a-state
EnclosureWarrant#
(typeof ENCLOSURE_WARRANTS)[number];
FLATTENING_DESTINATIONS#
Where an unwarranted boundary goes.
Values: region, section, column, divider, list, group, unwrap
FLATTENING_FAULTS#
Values: flattening-lost-a-statement, flattening-reordered-the-statements,
flattening-changed-the-reading-order, flattening-lost-a-named-group,
flattening-lost-a-state-signal, flattening-removed-no-boundary,
flattening-deepened-the-composition, transition-not-taken,
transition-took-an-unprescribed-destination,
destination-outside-the-vocabulary
FlatteningDestination#
(typeof FLATTENING_DESTINATIONS)[number];
FlatteningFault#
(typeof FLATTENING_FAULTS)[number];
flatteningFaults#
The before/after composition review.
flatteningFaults(transitions: readonly CompositionTransition[], prescriptions: readonly FlatteningPrescription[]): readonly CompositionFinding[]
FlatteningPrescription#
| Field | Type | Required | Notes |
|---|---|---|---|
containerId |
string |
required | — |
channels |
readonly ContainerEnclosure[] — ContainerEnclosure |
required | — |
arrangement |
SiblingArrangement | required | — |
carried |
readonly BoundaryCarried[] — BoundaryCarried |
required | — |
destination |
FlatteningDestination | null — FlatteningDestination |
required | — |
reason |
string |
required | — |
isConcentric#
True when this box's edges sit on its parent box's content edges.
isConcentric(observation: NestedObservation): boolean
MAX_PARALLEL_EDGES#
The most parallel edges that may run above one run of text.
Value: 3
NamedGroup#
| Field | Type | Required | Notes |
|---|---|---|---|
name |
string |
required | — |
role |
string |
required | — |
NestedObservation#
A container measured again, with the facts a NESTED boundary is judged on.
| Field | Type | Required | Notes |
|---|---|---|---|
container |
ContainerObservation | required | — |
enclosingBoxes |
readonly string[] |
required | The container ids of the enclosing elements that DRAW AS A BOX, outermost first. |
parentBoxId |
string | null |
required | The nearest enclosing box, or null when this box stands on the page. |
elevatedAncestors |
number |
required | How many of the enclosing boxes draw an elevation. |
parentContentBox |
Rect | null — Rect |
required | The parent box's content rectangle, or null. |
frame |
Rect | required | This element's border-box rectangle in document coordinates. |
siblingFrames |
readonly Rect[] — Rect |
required | The frames of the boxes at this level under the same parent box. |
membersAreContiguous |
boolean |
required | Whether this box and the boxes at its level occupy consecutive positions under one parent, with nothing else between them. |
channelReadings |
readonly ChannelReading[] — ChannelReading |
required | One reading per channel this element draws. |
namesItself |
boolean |
required | Whether this element carries a name of its own that nothing else states — an aria-label or an aria-labelledby, as opposed to a heading inside it. |
holdsAHeading |
boolean |
required | Whether the element or a descendant carries a heading. |
gathers |
number |
required | How many element children the box gathers. |
NESTING_FAULTS#
Values: nested-boundary-with-no-warrant, enclosure-channel-with-no-warrant,
concentric-boundary, elevation-inside-an-elevation,
too-many-parallel-edges-above-the-content,
state-signal-carried-by-colour-alone, state-warrant-not-settled-by-this-run,
no-destination-carries-what-this-boundary-carries,
observation-nests-under-a-box-the-run-never-measured,
nesting-chain-disagrees-with-the-parent-box
NestingFault#
(typeof NESTING_FAULTS)[number];
parallelEdges#
How many parallel edges run above this box's own content.
parallelEdges(observation: NestedObservation): number
prescribeFlattening#
Where this boundary should go, or null when nothing available can carry it.
prescribeFlattening(observation: NestedObservation): FlatteningPrescription | null
Rect#
| Field | Type | Required | Notes |
|---|---|---|---|
top |
number |
required | — |
right |
number |
required | — |
bottom |
number |
required | — |
left |
number |
required | — |
ROLE_WARRANTS#
The warrant each of S7.22.a's ten roles brings with it, and the three that bring none.
SIBLING_ARRANGEMENTS#
How a box sits relative to the other boxes at its level.
Values: alone, stacked, side-by-side, wrapped
siblingArrangement#
How this box sits relative to the boxes at its level.
siblingArrangement(observation: NestedObservation): SiblingArrangement
SiblingArrangement#
(typeof SIBLING_ARRANGEMENTS)[number];
STATE_WARRANT_VERDICTS#
The three answers a state warrant can have, and one of them is not an answer.
Values: varies-in-shape, varies-in-colour-only, constant,
single-instance
StateSignal#
| Field | Type | Required | Notes |
|---|---|---|---|
part |
string |
required | The part the signal belongs to — a class name, not an element id. |
channel |
string |
required | — |
values |
readonly string[] |
required | The distinct values observed across the instances of that part. |
stateWarrantVerdict#
What a channel's variance across the instances of its part says.
stateWarrantVerdict(reading: ChannelReading): StateWarrantVerdict
StateWarrantVerdict#
(typeof STATE_WARRANT_VERDICTS)[number];
unwarrantedChannels#
The channels this box draws that nothing in the document justifies.
unwarrantedChannels(observation: NestedObservation): readonly ContainerEnclosure[]
WARRANTS_FOR_CHANNEL#
Which warrants can justify which claim.
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 |
|---|---|---|
COMPOSITION_VERDICTS |
enumeration |
— |
CompositionRow.verdict |
CompositionVerdict |
— |
CompositionSnapshot.statements |
readonly string[] |
— |
CompositionSnapshot.stateSignals |
readonly StateSignal[] |
— |
compositionVerdict |
function |
One verdict per container, derived. |
CompositionVerdict |
type |
— |
STATE_WARRANT_VERDICTS |
enumeration |
The three answers a state warrant can have, and one of them is not an answer. |
stateWarrantVerdict |
function |
What a channel's variance across the instances of its part says. |
StateWarrantVerdict |
type |
— |
Compatibility#
| Symbol | Type | Notes |
|---|---|---|
CompositionRow.arrangement |
SiblingArrangement |
— |
DESTINATIONS_FOR_ARRANGEMENT |
constant |
Which destinations an arrangement leaves available. |
FlatteningPrescription.arrangement |
SiblingArrangement |
— |
SIBLING_ARRANGEMENTS |
enumeration |
How a box sits relative to the other boxes at its level. |
siblingArrangement |
function |
How this box sits relative to the boxes at its level. |
SiblingArrangement |
type |
— |
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/composition.ts