Eve library

The hierarchy review

Evidence

Revision 1

On this page

Whether each route opens on the surface it is named after, which region the screen was actually spent on, whether the words on it survive the criteria a dense layout breaks, whether the strings the product wrote are concise for the position they speak from, and whether the panel beside the work is about the work.

Generated from libs/oshun/workbench-kit/src/working-surface.ts by node scripts/v1-workbenches/generate-workbench-kit-api-reference.mjs. Ledger: S7.22.f. Do not edit by hand.

Summary#

  • src/working-surface.ts
Entry point Runtime class Authorized by
@oshun/workbench-kit/working-surface contract S7.22.f

Exports#

Symbol Kind Summary
controlLabelNamesSomething function Whether a control label names something rather than gesturing at it.
COPY_PROVENANCES enumeration Who put a string on the screen.
COPY_ROLES enumeration What a string is there to do, because that is what its length is judged against.
COPY_WORD_BUDGET constant The word budget for each role, defended in both directions.
CopyProvenance type —
CopyRole type —
CopyRun interface —
DENSITY_FLOOR_UNITS_PER_MEGAPIXEL constant How many facts a working surface must state per megapixel of first screen.
densityPerMegapixel function —
DensityReading interface —
DOMINANT_AREA_SHARE constant The share a region must hold to be the one the surface is about.
dominantRegion function The region holding a majority of the painted screen, or null where none does.
hierarchyHeadline function The sentence the review reports.
hierarchyReview function —
HierarchyReviewRow interface —
hierarchyReviewSummary function —
HierarchyReviewSummary interface —
HierarchyRow interface —
inspectorCeilingPx function The widest an inspector may be and leave the workspace a majority.
InspectorStep interface One step of a driven selection walk.
isShellRegion function The regions this audit expects to be able to rank, restated from S7.1.
LANDING_STATES enumeration What the surface was showing at the moment it opened.
LandingObservation interface —
landingState function —
LandingState type —
MARKETING_MARKS enumeration Marks that only marketing copy carries.
marketingMarksIn function Whether this run reads as marketing rather than as utility copy.
pathNamesOneObject function Whether the route's own path carries a parameter segment.
RANKED_REGIONS enumeration The regions the thesis ranks, in the order it ranks them.
READABILITY_CRITERIA enumeration The readability criteria a dense layout is the thing most likely to break.
ReadabilityCriterion type —
ReadabilityProbe interface —
READING_MEASURE_CHARACTERS constant The measure this layer has already published, in characters.
REFLOW_WIDTH_PX constant The width the reflow criterion is stated at.
RegionArea interface —
regionHierarchy function —
ROUTE_SUBJECTS enumeration The two shapes a route's subject can take, and the honest absence.
routeSubject function —
RouteSubject type —
RouteSubjectFacts interface What S1.8's descriptor says about the route's subject.
screenIsSpentOnEditing function Whether the screen is being spent on one thing the reader is writing.
ShellGeometry interface —
StatusObservation interface —
SURFACE_HIERARCHY_VERDICTS enumeration —
surfaceHierarchyVerdict function —
SurfaceHierarchyVerdict type —
TEXT_SPACING_OVERRIDES constant The overrides SC 1.4.12 requires a page to survive, as multiples of the font size.
VAGUE_CONTROL_LABELS enumeration Single-word control labels that name neither an action nor an object.
WORKING_SURFACE_FAULTS enumeration —
WorkingSurfaceFault type —
workingSurfaceFaults function The working-surface audit.
WorkingSurfaceFinding interface —
WorkingSurfaceObservation interface —

Shapes#

controlLabelNamesSomething#

Whether a control label names something rather than gesturing at it.

ts
controlLabelNamesSomething(text: string): boolean

COPY_PROVENANCES#

Who put a string on the screen.

Values: the-product, the-record, neither

COPY_ROLES#

What a string is there to do, because that is what its length is judged against.

Values: navigation-label, control-label, heading, status-word, empty-state, message, help, value

COPY_WORD_BUDGET#

The word budget for each role, defended in both directions.

CopyProvenance#

ts
(typeof COPY_PROVENANCES)[number];

CopyRole#

ts
(typeof COPY_ROLES)[number];

CopyRun#

Field Type Required Notes
runId string required —
role CopyRole required —
provenance CopyProvenance required —
text string required —

DENSITY_FLOOR_UNITS_PER_MEGAPIXEL#

How many facts a working surface must state per megapixel of first screen.

Value: 25

densityPerMegapixel#

ts
densityPerMegapixel(reading: DensityReading): number

DensityReading#

Field Type Required Notes
informationUnits number required Facts the surface states: a labelled value, a cell, a member, a status slot.
screenPixels number required Pixels of the first viewport.
contentPixels number required The area of the workspace this surface actually drew into, on the first screen: the box enclosing everything it states and everything it lets the reader edit.
editablePixels number required Of those, the pixels given to a region the reader is editing.

DOMINANT_AREA_SHARE#

The share a region must hold to be the one the surface is about.

dominantRegion#

The region holding a majority of the painted screen, or null where none does.

ts
dominantRegion(areas: readonly RegionArea[]): ShellRegion | null

hierarchyHeadline#

The sentence the review reports.

ts
hierarchyHeadline(summary: HierarchyReviewSummary): string

hierarchyReview#

ts
hierarchyReview(observations: readonly WorkingSurfaceObservation[]): readonly HierarchyReviewRow[]

HierarchyReviewRow#

Field Type Required Notes
surfaceId string required —
routeId string required —
viewport string required —
subject RouteSubject required —
landing LandingState required —
ranking readonly HierarchyRow[] — HierarchyRow required —
dominant ShellRegion | null required —
unitsPerMegapixel number required —
inspectorCeilingPx number required —
verdict SurfaceHierarchyVerdict required —

hierarchyReviewSummary#

ts
hierarchyReviewSummary(rows: readonly HierarchyReviewRow[]): HierarchyReviewSummary

HierarchyReviewSummary#

Field Type Required Notes
surfaces number required —
openingOnTheirSurface number required —
openingOnSomethingElse number required —
contradictingTheThesis number required —
notMeasured number required —
regionsRanked number required —
worstWorkspaceShare number required —
worstDensity number required —

HierarchyRow#

Field Type Required Notes
rank number required 1 is the largest.
region ShellRegion required —
areaPx number required —
share number required areaPx over the sum of every measured region's area, 0..1.

inspectorCeilingPx#

The widest an inspector may be and leave the workspace a majority.

ts
inspectorCeilingPx(geometry: ShellGeometry): number

InspectorStep#

One step of a driven selection walk.

Field Type Required Notes
stepId string required —
selectedId string | null required The id the harness selected, or null where it deliberately selected nothing.
inspectorText string required Everything the inspector region rendered at that moment.
inspectorPresent boolean required Whether the inspector region was present at all.

isShellRegion#

The regions this audit expects to be able to rank, restated from S7.1.

ts
isShellRegion(candidate: string): candidate is ShellRegion

LANDING_STATES#

What the surface was showing at the moment it opened.

Values: the-work, a-loading-placeholder, an-empty-state, a-choice-to-make-first, nothing

LandingObservation#

Field Type Required Notes
workMembersOnArrival number required Collection members inside the workspace region before any interaction.
editableOnArrival boolean required Whether an editable region is inside the workspace before any interaction.
workMembersAfterOneInteraction number required Collection members inside the workspace after exactly one interaction.
loadingOnArrival boolean required Whether a skeleton was on screen at arrival.
emptyStateOnArrival boolean required Whether an empty-state message was on screen at arrival.
subjectStatedOnTheSurface boolean required Whether the workspace stated the entity the route is bound to.
surfaceName string | null required The name the SURFACE states for itself, read off the rendered page.

landingState#

ts
landingState(observation: LandingObservation): LandingState

LandingState#

ts
(typeof LANDING_STATES)[number];

MARKETING_MARKS#

Marks that only marketing copy carries.

Values: seamless, seamlessly, effortless, effortlessly, powerful, revolutionary, unlock, supercharge, delight, stunning, beautiful, world-class, best-in-class, game-changing, cutting-edge, simply, magical, amazing, we, our, us

marketingMarksIn#

Whether this run reads as marketing rather than as utility copy.

ts
marketingMarksIn(text: string): readonly string[]

pathNamesOneObject#

Whether the route's own path carries a parameter segment.

ts
pathNamesOneObject(path: string): boolean

RANKED_REGIONS#

The regions the thesis ranks, in the order it ranks them.

Values: workspace, inspector

READABILITY_CRITERIA#

The readability criteria a dense layout is the thing most likely to break.

Values: text-spacing, reflow, reader-text-scale, reading-measure

ReadabilityCriterion#

ts
(typeof READABILITY_CRITERIA)[number];

ReadabilityProbe#

Field Type Required Notes
criterion ReadabilityCriterion required —
taken boolean required Whether the probe was actually run.
clippedElements number required Elements whose content no longer fits the box drawn around it.
overlappingRuns number required Text runs that landed on top of another text run.
shellScrollsSideways boolean required Whether the SHELL scrolls sideways — never the document, which clips.
runsOverTheMeasure number required Text runs longer than the published measure.
runsIgnoringTheTextScale number required Text elements whose computed size did not follow the reader's text scale.
runsExamined number required How many text elements the probe looked at, so a zero is not vacuous.

READING_MEASURE_CHARACTERS#

The measure this layer has already published, in characters.

Value: 75

REFLOW_WIDTH_PX#

The width the reflow criterion is stated at.

Value: 320

RegionArea#

Field Type Required Notes
region ShellRegion required —
areaPx number required Pixels of the first viewport this region covers.
widthPx number required —
heightPx number required —

regionHierarchy#

ts
regionHierarchy(areas: readonly RegionArea[]): readonly HierarchyRow[]

ROUTE_SUBJECTS#

The two shapes a route's subject can take, and the honest absence.

Values: one-object, a-collection, not-derivable

routeSubject#

ts
routeSubject(facts: RouteSubjectFacts): RouteSubject

RouteSubject#

ts
(typeof ROUTE_SUBJECTS)[number];

RouteSubjectFacts#

What S1.8's descriptor says about the route's subject.

Field Type Required Notes
routeId string required —
path string required —
declaredName string required The name the route declares for itself, resolved through the host's own text function.
entityParameter string | null required S1.8 deepLink.entityParameter, or null where the route declares no deep link.
boundEntityId string | null required The value that parameter is bound to on the surface under measurement.

screenIsSpentOnEditing#

Whether the screen is being spent on one thing the reader is writing.

ts
screenIsSpentOnEditing(reading: DensityReading): boolean

ShellGeometry#

Field Type Required Notes
shellWidthPx number required The shell's own border box.
shellHeightPx number required —
regionsHeightPx number required The height of the row the working regions share, above the status band.
railWidthPx number required The fixed rails the working regions sit beside, in pixels of width.
navWidthPx number required —

StatusObservation#

Field Type Required Notes
onTheFirstScreen boolean required Whether the status region intersects the first viewport.
slotsRendered number required How many status slots the region rendered.

SURFACE_HIERARCHY_VERDICTS#

Values: opens-on-its-working-surface, opens-on-something-else, hierarchy-contradicts-the-thesis, surface-not-measured

surfaceHierarchyVerdict#

ts
surfaceHierarchyVerdict(observation: WorkingSurfaceObservation): SurfaceHierarchyVerdict

SurfaceHierarchyVerdict#

ts
(typeof SURFACE_HIERARCHY_VERDICTS)[number];

TEXT_SPACING_OVERRIDES#

The overrides SC 1.4.12 requires a page to survive, as multiples of the font size.

VAGUE_CONTROL_LABELS#

Single-word control labels that name neither an action nor an object.

Values: more, manage, details, options, actions, go, here, click, submit, ok, other, misc, items, things

WORKING_SURFACE_FAULTS#

Values: hierarchy-not-measured, route-subject-not-derivable, surface-does-not-name-the-route-it-opened, route-does-not-open-on-the-work, the-work-appears-only-after-an-interaction, route-subject-not-stated-on-the-surface, collection-route-opens-on-one-object, workspace-does-not-hold-a-majority, a-region-other-than-the-workspace-holds-the-majority, inspector-outranks-the-workspace, inspector-permitted-wider-than-dominance-allows, status-region-not-on-the-first-screen, status-region-states-nothing, readability-criterion-not-taken, text-clipped-at-the-declared-text-spacing, text-overlaps-at-the-declared-text-spacing, shell-scrolls-sideways-at-the-reflow-width, text-does-not-follow-the-readers-scale, line-longer-than-the-published-measure, information-density-below-the-floor, copy-longer-than-its-role-allows, control-label-names-nothing, marketing-register-in-utility-copy, text-attributable-to-neither-the-product-nor-the-record, inspector-does-not-name-the-selection, inspector-shows-a-subject-with-nothing-selected

WorkingSurfaceFault#

ts
(typeof WORKING_SURFACE_FAULTS)[number];

workingSurfaceFaults#

The working-surface audit.

ts
workingSurfaceFaults(observations: readonly WorkingSurfaceObservation[]): readonly WorkingSurfaceFinding[]

WorkingSurfaceFinding#

Field Type Required Notes
kind WorkingSurfaceFault required —
subject string required —
detail string required —

WorkingSurfaceObservation#

Field Type Required Notes
surfaceId string required —
viewport { readonly width: number; readonly height: number } required —
route RouteSubjectFacts required —
geometry ShellGeometry required —
shippedInspectorMaxPx number required The inspector width the shell permits at this geometry, as it ships.
regions readonly RegionArea[] — RegionArea required —
landing LandingObservation required —
density DensityReading required —
readability readonly ReadabilityProbe[] — ReadabilityProbe required —
copy readonly CopyRun[] — CopyRun required —
inspectorWalk readonly InspectorStep[] — InspectorStep required —
status StatusObservation required —

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
HierarchyReviewRow.verdict SurfaceHierarchyVerdict —
LANDING_STATES enumeration What the surface was showing at the moment it opened.
LandingObservation.emptyStateOnArrival boolean Whether an empty-state message was on screen at arrival.
LandingObservation.subjectStatedOnTheSurface boolean Whether the workspace stated the entity the route is bound to.
landingState function —
LandingState type —
SURFACE_HIERARCHY_VERDICTS enumeration —
surfaceHierarchyVerdict function —
SurfaceHierarchyVerdict type —
WorkingSurfaceObservation.status StatusObservation —

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/working-surface.ts