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.
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#
(typeof COPY_PROVENANCES)[number];
CopyRole#
(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#
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.
dominantRegion(areas: readonly RegionArea[]): ShellRegion | null
hierarchyHeadline#
The sentence the review reports.
hierarchyHeadline(summary: HierarchyReviewSummary): string
hierarchyReview#
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#
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.
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.
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#
landingState(observation: LandingObservation): LandingState
LandingState#
(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.
marketingMarksIn(text: string): readonly string[]
pathNamesOneObject#
Whether the route's own path carries a parameter segment.
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#
(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#
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#
routeSubject(facts: RouteSubjectFacts): RouteSubject
RouteSubject#
(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.
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#
surfaceHierarchyVerdict(observation: WorkingSurfaceObservation): SurfaceHierarchyVerdict
SurfaceHierarchyVerdict#
(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#
(typeof WORKING_SURFACE_FAULTS)[number];
workingSurfaceFaults#
The working-surface audit.
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.jsonlibs/oshun/workbench-kit/src/working-surface.ts