Eve library

Composition and flattening

Evidence

Revision 1

On this page

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#

ts
(typeof BOUNDARY_CARRIES)[number];

boundaryCarries#

What this boundary is carrying, measured.

ts
boundaryCarries(observation: NestedObservation): readonly BoundaryCarried[]

boxDepth#

How many boxes enclose this one.

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

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

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

ts
compositionHeadline(summary: CompositionSummary): string

compositionInventory#

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

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

ts
compositionVerdict(observation: NestedObservation): CompositionVerdict

CompositionVerdict#

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

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

ts
(typeof FLATTENING_DESTINATIONS)[number];

FlatteningFault#

ts
(typeof FLATTENING_FAULTS)[number];

flatteningFaults#

The before/after composition review.

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

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

ts
(typeof NESTING_FAULTS)[number];

parallelEdges#

How many parallel edges run above this box's own content.

ts
parallelEdges(observation: NestedObservation): number

prescribeFlattening#

Where this boundary should go, or null when nothing available can carry it.

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

ts
siblingArrangement(observation: NestedObservation): SiblingArrangement

SiblingArrangement#

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

ts
stateWarrantVerdict(reading: ChannelReading): StateWarrantVerdict

StateWarrantVerdict#

ts
(typeof STATE_WARRANT_VERDICTS)[number];

unwarrantedChannels#

The channels this box draws that nothing in the document justifies.

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