# Composition and flattening

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](#alignment_tolerance_px)               | constant    | How far two edges may be apart and still count as the same line.                                                |
| [BOUNDARY_CARRIES](#boundary_carries)                           | enumeration | The things a reader gets from a boundary that a flattening has to keep.                                         |
| [BoundaryCarried](#boundarycarried)                             | type        | —                                                                                                               |
| [boundaryCarries](#boundarycarries)                             | function    | What this boundary is carrying, measured.                                                                       |
| [boxDepth](#boxdepth)                                           | function    | How many boxes enclose this one.                                                                                |
| [CHANNEL_CLAIMS](#channel_claims)                               | constant    | The sentence each of S7.22.a's four channels says to a reader.                                                  |
| [ChannelReading](#channelreading)                               | interface   | One channel's values across every instance of the same component part.                                          |
| [channelWarrants](#channelwarrants)                             | function    | The warrants this channel actually has, measured.                                                               |
| [COMPOSITION_VERDICTS](#composition_verdicts)                   | enumeration | —                                                                                                               |
| [compositionFaults](#compositionfaults)                         | function    | The composition as drawn.                                                                                       |
| [CompositionFinding](#compositionfinding)                       | interface   | —                                                                                                               |
| [compositionHeadline](#compositionheadline)                     | function    | The sentence the review reports.                                                                                |
| [compositionInventory](#compositioninventory)                   | function    | —                                                                                                               |
| [CompositionRow](#compositionrow)                               | interface   | —                                                                                                               |
| [CompositionSnapshot](#compositionsnapshot)                     | interface   | One composition, measured.                                                                                      |
| [compositionSummary](#compositionsummary)                       | function    | —                                                                                                               |
| [CompositionSummary](#compositionsummary)                       | interface   | —                                                                                                               |
| [CompositionTransition](#compositiontransition)                 | interface   | —                                                                                                               |
| [compositionVerdict](#compositionverdict)                       | function    | One verdict per container, derived.                                                                             |
| [CompositionVerdict](#compositionverdict)                       | type        | —                                                                                                               |
| [CONCENTRIC_INSET_PX](#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](#destination_cost_order)               | enumeration | Cheapest first, where cheap means least added to the page.                                                      |
| [DESTINATION_PRESERVES](#destination_preserves)                 | constant    | What each destination can still carry.                                                                          |
| [DESTINATIONS_FOR_ARRANGEMENT](#destinations_for_arrangement)   | constant    | Which destinations an arrangement leaves available.                                                             |
| [DESTINATIONS_NEEDING_A_SET](#destinations_needing_a_set)       | enumeration | Destinations that describe a SET and are therefore unavailable to one box.                                      |
| [DESTINATIONS_THE_PARENT_NAMES](#destinations_the_parent_names) | enumeration | The six the item names, kept visible so the seventh is arguable.                                                |
| [ENCLOSURE_WARRANTS](#enclosure_warrants)                       | enumeration | The seven facts that justify a nested boundary.                                                                 |
| [EnclosureWarrant](#enclosurewarrant)                           | type        | —                                                                                                               |
| [FLATTENING_DESTINATIONS](#flattening_destinations)             | enumeration | Where an unwarranted boundary goes.                                                                             |
| [FLATTENING_FAULTS](#flattening_faults)                         | enumeration | —                                                                                                               |
| [FlatteningDestination](#flatteningdestination)                 | type        | —                                                                                                               |
| [FlatteningFault](#flatteningfault)                             | type        | —                                                                                                               |
| [flatteningFaults](#flatteningfaults)                           | function    | The before/after composition review.                                                                            |
| [FlatteningPrescription](#flatteningprescription)               | interface   | —                                                                                                               |
| [isConcentric](#isconcentric)                                   | function    | True when this box's edges sit on its parent box's content edges.                                               |
| [MAX_PARALLEL_EDGES](#max_parallel_edges)                       | constant    | The most parallel edges that may run above one run of text.                                                     |
| [NamedGroup](#namedgroup)                                       | interface   | —                                                                                                               |
| [NestedObservation](#nestedobservation)                         | interface   | A container measured again, with the facts a NESTED boundary is judged on.                                      |
| [NESTING_FAULTS](#nesting_faults)                               | enumeration | —                                                                                                               |
| [NestingFault](#nestingfault)                                   | type        | —                                                                                                               |
| [parallelEdges](#paralleledges)                                 | function    | How many parallel edges run above this box's own content.                                                       |
| [prescribeFlattening](#prescribeflattening)                     | function    | Where this boundary should go, or null when nothing available can carry it.                                     |
| [Rect](#rect)                                                   | interface   | —                                                                                                               |
| [ROLE_WARRANTS](#role_warrants)                                 | constant    | The warrant each of S7.22.a's ten roles brings with it, and the three that bring none.                          |
| [SIBLING_ARRANGEMENTS](#sibling_arrangements)                   | enumeration | How a box sits relative to the other boxes at its level.                                                        |
| [siblingArrangement](#siblingarrangement)                       | function    | How this box sits relative to the boxes at its level.                                                           |
| [SiblingArrangement](#siblingarrangement)                       | type        | —                                                                                                               |
| [STATE_WARRANT_VERDICTS](#state_warrant_verdicts)               | enumeration | The three answers a state warrant can have, and one of them is not an answer.                                   |
| [StateSignal](#statesignal)                                     | interface   | —                                                                                                               |
| [stateWarrantVerdict](#statewarrantverdict)                     | function    | What a channel's variance across the instances of its part says.                                                |
| [StateWarrantVerdict](#statewarrantverdict)                     | type        | —                                                                                                               |
| [unwarrantedChannels](#unwarrantedchannels)                     | function    | The channels this box draws that nothing in the document justifies.                                             |
| [WARRANTS_FOR_CHANNEL](#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](./card-use.md#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](#flatteningfault), [NestingFault](#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](./card-use.md#containerrole)                                             | required | —     |
| `boxDepth`      | `number`                                                                                 | required | —     |
| `parallelEdges` | `number`                                                                                 | required | —     |
| `arrangement`   | [SiblingArrangement](#siblingarrangement)                                                | required | —     |
| `channels`      | `readonly ContainerEnclosure[]` — [ContainerEnclosure](./card-use.md#containerenclosure) | required | —     |
| `warrants`      | `readonly EnclosureWarrant[]` — [EnclosureWarrant](#enclosurewarrant)                    | required | —     |
| `carried`       | `readonly BoundaryCarried[]` — [BoundaryCarried](#boundarycarried)                       | required | —     |
| `destination`   | `FlatteningDestination \| null` — [FlatteningDestination](#flatteningdestination)        | required | —     |
| `verdict`       | [CompositionVerdict](#compositionverdict)                                                | required | —     |

#### CompositionSnapshot

One composition, measured.

| Field              | Type                                                   | Required | Notes |
| ------------------ | ------------------------------------------------------ | -------- | ----- |
| `label`            | `string`                                               | required | —     |
| `statements`       | `readonly string[]`                                    | required | —     |
| `namedGroups`      | `readonly NamedGroup[]` — [NamedGroup](#namedgroup)    | required | —     |
| `readingOrder`     | `readonly string[]`                                    | required | —     |
| `stateSignals`     | `readonly StateSignal[]` — [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](#compositionsnapshot) | required | —     |
| `after`       | [CompositionSnapshot](#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](./card-use.md#containerenclosure) | required | —     |
| `arrangement` | [SiblingArrangement](#siblingarrangement)                                                | required | —     |
| `carried`     | `readonly BoundaryCarried[]` — [BoundaryCarried](#boundarycarried)                       | required | —     |
| `destination` | `FlatteningDestination \| null` — [FlatteningDestination](#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](./card-use.md#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](#rect)                                  | required | The parent box's content rectangle, or null.                                                                                                          |
| `frame`                | [Rect](#rect)                                                   | required | This element's border-box rectangle in document coordinates.                                                                                          |
| `siblingFrames`        | `readonly Rect[]` — [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](#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`
