@orkestrel/test 0.0.8 → 0.0.9

package/dist/src/browser/index.d.ts

@@ -22,6 +22,28 @@ export declare const ACCESSIBLE_ROLES: readonly string[];
  */
 export declare function blendColor(front: Color, back: Color): Color;
 
+/**
+ * Builds one unmounted element of a known tag, wearing the classes, text, and attributes asked for.
+ *
+ * @param tag - The HTML tag name, which fixes the returned element's exact type.
+ * @param options - The class list, the text, and the attributes to apply.
+ * @returns The built element, not yet in any document.
+ *
+ * @remarks
+ * The element is unmounted on purpose, so a fixture is assembled before the page ever sees it and a
+ * test decides where it goes. Nothing here resolves against the cascade: a built element computes no
+ * style and lays out no box until {@link mount} puts it in the document.
+ *
+ * The text is set as text rather than parsed as markup, so a `<` in it stays a `<`. Use
+ * {@link render} where the fixture is markup.
+ *
+ * @example
+ * ```ts
+ * const button = build('button', { classes: 'primary', text: 'Save', attributes: { type: 'button' } })
+ * ```
+ */
+export declare function build<K extends keyof HTMLElementTagNameMap>(tag: K, options?: ElementOptions): HTMLElementTagNameMap[K];
+
 /**
  * The page a browser paints an unstyled document onto.
  *
@@ -178,6 +200,51 @@ export declare function clickDisclosure(name: string): Promise<void>;
  */
 export declare type Color = readonly [red: number, green: number, blue: number, alpha: number];
 
+/**
+ * Determines whether two colors render the same, within the rounding a browser does.
+ *
+ * @param first - A CSS color expression or an already-parsed color.
+ * @param second - A CSS color expression or an already-parsed color.
+ * @returns `true` when every channel and the alpha agree within the tolerance; `false` otherwise,
+ * including when either side names no readable color.
+ *
+ * @remarks
+ * Each string side is resolved through {@link rgba}, so a keyword, a token reference, and the
+ * `rgb()` the engine computes for either of them compare equal without a test converting anything
+ * first. A side that resolves to nothing makes the answer `false` rather than a throw, because this
+ * is a predicate.
+ *
+ * The tolerance is half a channel step on the 0–255 scale, and the alpha is scaled onto that same
+ * range before it is compared, so one number covers both. Half a step is what a composite of
+ * translucent layers and a `color-mix()` round trip actually drift by; anything a reader could see
+ * is further than that and reports unequal.
+ *
+ * @example
+ * ```ts
+ * colorEqual('rebeccapurple', 'rgb(102, 51, 153)') // true
+ * colorEqual('red', [0, 0, 255, 1]) // false
+ * ```
+ */
+export declare function colorEqual(first: string | Color, second: string | Color): boolean;
+
+/**
+ * Sets one field's value and commits it, the way typing and then leaving the field does.
+ *
+ * @param element - The input or textarea to write into.
+ * @param text - The value to set.
+ *
+ * @remarks
+ * The order is the browser's: {@link typeInput} first, so `input` is dispatched with the value
+ * already set, and one bubbling `change` after it. A component that reads the value from either
+ * event therefore reads `text` from both.
+ *
+ * @example
+ * ```ts
+ * commitInput(requireValue(container.querySelector('input')), 'Ada')
+ * ```
+ */
+export declare function commitInput(element: HTMLInputElement | HTMLTextAreaElement, text: string): void;
+
 /**
  * The roles whose accessible name is the text a reader can see inside them.
  *
@@ -226,6 +293,60 @@ export declare const CONTENT_ROLES: readonly string[];
  */
 export declare function contrast(element: Element, floor?: Color): number;
 
+/**
+ * Creates one console channel that records every call it receives and hands that call on unchanged.
+ *
+ * @param name - The channel's name, which prefixes each line it records.
+ * @param output - The list each call is recorded into, appended to in place.
+ * @param forward - The channel every call is passed on to after it is recorded.
+ * @returns A channel carrying the console's own call signature.
+ *
+ * @remarks
+ * One call becomes one line. Every argument of that call is put through `String` and joined with a
+ * space, so a call carrying several values reads as the one line the page printed rather than as
+ * several entries.
+ *
+ * Nothing is swallowed. The record happens first and `forward` receives the arguments it would have
+ * received, so a page recorded through this prints exactly what it printed without it. The list
+ * belongs to the caller, so a channel writes into whatever it was handed and holds no state of its
+ * own. {@link createJournal} builds one channel per console method over one list.
+ *
+ * @example
+ * ```ts
+ * const output: string[] = []
+ * console.log = createChannel('log', output, console.log)
+ * ```
+ */
+export declare function createChannel(name: string, output: string[], forward: (...data: unknown[]) => void): (...data: unknown[]) => void;
+
+/**
+ * Creates one real drag event carrying a live data transfer, ready to dispatch.
+ *
+ * @param name - The event type, such as `dragstart`.
+ * @param options - Any `DragEventInit` member, each one overriding the default beneath it.
+ * @returns A real `DragEvent` of that type.
+ *
+ * @remarks
+ * A drag event with no `dataTransfer` is the shape that makes a drop handler fail in a test and work
+ * in a browser, so one is allocated. Pass your own to seed it: a `dataTransfer` given in `options`
+ * replaces the allocated one, which is how a drop is driven with the payload the drag was supposed
+ * to carry.
+ *
+ * The platform declares the `dataTransfer` member on the constructed event as nullable, so calling
+ * code still narrows it even though this always supplies one.
+ *
+ * `bubbles` and `cancelable` are set, because a drop handler that never prevents the default event
+ * is a drop the browser handles itself.
+ *
+ * @example
+ * ```ts
+ * const started = createDragEvent('dragstart')
+ * started.dataTransfer?.setData('text/plain', 'row-3')
+ * element.dispatchEvent(started)
+ * ```
+ */
+export declare function createDragEvent(name: string, options?: DragEventInit): DragEvent;
+
 /**
  * Creates the journal one scenario records its steps and the page's own output into.
  *
@@ -252,6 +373,30 @@ export declare function contrast(element: Element, floor?: Color): number;
  */
 export declare function createJournal(): JournalInterface;
 
+/**
+ * Creates one real pointer event, ready to dispatch.
+ *
+ * @param name - The event type, such as `pointerdown`.
+ * @param options - Any `PointerEventInit` member, each one overriding the default beneath it.
+ * @returns A real `PointerEvent` of that type.
+ *
+ * @remarks
+ * The defaults are what a browser's own pointer event carries and a hand-built one does not:
+ * `bubbles` and `cancelable` are set, so a delegated listener hears it and a handler can prevent it,
+ * and `pointerId`, `pointerType`, and `isPrimary` describe a single primary mouse, so a component
+ * that branches on the pointer kind takes the branch a mouse takes. Override any of them by naming
+ * it; a touch is `{ pointerType: 'touch' }` and nothing else has to be restated.
+ *
+ * The event is real rather than a shaped object, so `instanceof PointerEvent` holds and the
+ * coordinate and modifier members a handler reads are the ones the platform defines.
+ *
+ * @example
+ * ```ts
+ * element.dispatchEvent(createPointerEvent('pointerdown', { clientX: 10, clientY: 20 }))
+ * ```
+ */
+export declare function createPointerEvent(name: string, options?: PointerEventInit): PointerEvent;
+
 /**
  * Creates the capture portfolio one run places its screenshots through.
  *
@@ -333,6 +478,24 @@ export declare function describeFocus(element: Element): string;
  */
 export declare function describeTree(element: Element): string;
 
+/**
+ * Options for one built element.
+ *
+ * @remarks
+ * `classes` is written the way a `class` attribute is written — one space-separated string — so a
+ * fixture reads as the markup it stands in for. `attributes` is set name by name after the class
+ * list and the text, so an `attributes` entry named `class` wins over `classes` rather than merging
+ * with it.
+ */
+export declare interface ElementOptions {
+    /** The class list, space-separated, exactly as a `class` attribute writes it. */
+    readonly classes?: string;
+    /** The text the element carries, set as text rather than parsed as markup. */
+    readonly text?: string;
+    /** Every attribute to set, keyed by attribute name. */
+    readonly attributes?: Readonly<Record<string, string>>;
+}
+
 /**
  * Expands a capture registry across every variant into the filenames a complete portfolio holds.
  *
@@ -407,6 +570,49 @@ export declare const FIELD_ROLES: Readonly<Record<string, string>>;
  */
 export declare function fillAccessible(name: string, text: string): Promise<void>;
 
+/**
+ * Finds the animation the cascade declares under one name.
+ *
+ * @param name - The exact `@keyframes` name.
+ * @returns The first matching rule in {@link readRules} order, or `undefined` when the cascade
+ * declares no animation under that name.
+ *
+ * @remarks
+ * The name is matched exactly, which is where this parts from {@link findRule}: a selector is
+ * compound and a fragment of one is a useful question, and an animation name is one atom that either
+ * is or is not the one an `animation` declaration references.
+ *
+ * @example
+ * ```ts
+ * findKeyframes('fade')?.cssRules.length
+ * ```
+ */
+export declare function findKeyframes(name: string): CSSKeyframesRule | undefined;
+
+/**
+ * Finds the first style rule in the cascade whose selector carries a fragment.
+ *
+ * @param selector - The selector fragment to look for, matched as a substring of the whole selector
+ * text.
+ * @returns The first matching rule in {@link readRules} order, or `undefined` when no rule carries
+ * the fragment.
+ *
+ * @remarks
+ * This proves a declaration exists in the cascade at all, which is a different question from what an
+ * element resolves to: {@link style} reads the winner, and a rule this finds may be overridden by
+ * another. Assert on this where the subject is the stylesheet, and on `style` where the subject is
+ * the rendered result.
+ *
+ * The match is a substring, so `findRule('.card')` finds `.card`, `.card:hover`, and
+ * `.panel > .card` alike. Pass more of the selector to narrow it.
+ *
+ * @example
+ * ```ts
+ * findRule('.card')?.style.getPropertyValue('padding')
+ * ```
+ */
+export declare function findRule(selector: string): CSSStyleRule | undefined;
+
 /**
  * What sequential keyboard navigation can reach, before disabled and unrendered elements go.
  *
@@ -608,6 +814,35 @@ export declare function measureContrast(front: Color, back: Color): number;
  */
 export declare function measureLuminance(color: Color): number;
 
+/**
+ * Puts one element into the document and hands it straight back.
+ *
+ * @param element - The element to attach.
+ * @returns The same element, now appended to `document.body`.
+ *
+ * @remarks
+ * What this buys is the composition, not the attachment: the `append` method returns `void`, and
+ * this hands the element back, so it fits where an expression is expected. The {@link render} helper
+ * returns its fixture through it, and the {@link rgba} helper probes through `mount(build('span'))`.
+ * A bare `append` call breaks each of those call sites.
+ *
+ * Being connected is what the attachment then buys: `getComputedStyle` resolves against the shipped
+ * cascade, custom properties inherit from `:root`, and the element lays out a real box. A detached
+ * element answers each of those questions with the initial value instead, which reads as a styling
+ * defect rather than as a detached node.
+ *
+ * Taking it back out belongs to the consumer's teardown, because this records nothing: a browser
+ * test file shares one page, so a fixture left behind is the next test's resolver ambiguity. Build a
+ * recorded container in a setup module and remove it from an `afterEach` hook.
+ *
+ * @example
+ * ```ts
+ * const panel = mount(build('div', { classes: 'surface' }))
+ * panel.remove()
+ * ```
+ */
+export declare function mount<T extends Element>(element: T): T;
+
 /**
  * Parses one computed CSS color value into straight sRGB channels.
  *
@@ -630,6 +865,31 @@ export declare function measureLuminance(color: Color): number;
  */
 export declare function parseColor(value: string): Color | undefined;
 
+/**
+ * Reads one resolved CSS length as a number of pixels.
+ *
+ * @param element - The element whose resolved style to inspect.
+ * @param property - The CSS property name, registered or custom.
+ * @returns The leading numeric part of the resolved value, and `0` when it carries none.
+ *
+ * @remarks
+ * A resolved length is text with a unit — `'12px'` — so this reads the number in front of the unit
+ * and discards the rest. The unit is not checked: the resolved value of a length is in pixels in
+ * every case a browser hands back, and a property that resolves to something else is the caller's
+ * mistake rather than this reader's.
+ *
+ * An unparsable value reads as `0` rather than as absence, because every caller of this is measuring
+ * and `'auto'`, `'none'`, and `''` each contribute no pixels to what a reader sees. Where the
+ * distinction matters, read the text with {@link style} instead.
+ *
+ * @example
+ * ```ts
+ * pixels(button, 'padding-left') // 12
+ * pixels(button, 'width') // 0 when the width resolves to `auto`
+ * ```
+ */
+export declare function pixels(element: Element, property: string): number;
+
 /** The registry of capture states one run places, and the files it wrote placing them. */
 export declare interface PortfolioInterface {
     /** The name of the variant this run renders. */
@@ -715,12 +975,24 @@ export declare function readBackdrop(element: Element, floor: Color): Color;
 /**
  * Collects every class token the stylesheets loaded into this document actually define.
  *
- * @returns The set of class names reachable in the shipped cascade.
+ * @returns The set of class names reachable in the shipped cascade, in {@link readRules} order.
  *
  * @remarks
  * The set is what an authored-class conformance check measures against, so a class no loaded
  * stylesheet defines — an invented utility, a misspelled framework name — is absent from it.
  *
+ * The tokens come from the {@link readRules} walk, which decides both the membership and the
+ * insertion order this reader reports, and each answer is a deliberate difference from 0.0.8. A
+ * class declared inside a grouping rule — a media query, a supports block, a layer, a nested style
+ * rule — counts as defined, because a class the cascade defines under a condition is still one the
+ * cascade defines; 0.0.8 read the top-level rules alone. Insertion order is breadth-first, so a
+ * top-level class lands before a class declared inside an earlier grouping rule; 0.0.8 popped a
+ * stack and inserted the deepest rule first. Iterate the set where the order is the subject, and
+ * read `has` where membership is.
+ *
+ * `@keyframes` children are outside that walk, so an animation's own rules define no token here.
+ * Reach the animation itself through {@link findKeyframes}.
+ *
  * @example
  * ```ts
  * readCascade().has('card')
@@ -905,6 +1177,35 @@ export declare function readRole(element: Element): string | undefined;
  */
 export declare function readRows(root: ParentNode, selector: string): readonly string[];
 
+/**
+ * Collects every rule the stylesheets loaded into this document hold, nested grouping rules
+ * included.
+ *
+ * @returns Every rule reachable in the shipped cascade: each sheet's own rules in sheet order, then
+ * the rules nested inside them, level by level.
+ *
+ * @remarks
+ * The walk is iterative and reads the list it is still appending to, which is what expands a media
+ * query, a supports block, a layer, and a nested style rule without recursion. Expanding by level
+ * rather than by depth is why a top-level rule is always met before a rule nested inside an earlier
+ * one; {@link findRule} returns the first match in exactly this order.
+ *
+ * The descent reaches a `CSSGroupingRule` and nothing else, and a `@keyframes` rule is not one. The
+ * `@keyframes` rule itself is collected wherever it sits, and the keyframe rules inside it are not;
+ * {@link findKeyframes} is the door to those.
+ *
+ * A stylesheet the document cannot read — a cross-origin sheet with no CORS grant — throws from its
+ * own `cssRules` getter, and that sheet is skipped rather than ending the walk. What a page loaded
+ * from another origin declares is unreadable to every caller here, so the alternative is a helper
+ * that works until a test page adds a font or an analytics stylesheet.
+ *
+ * @example
+ * ```ts
+ * readRules().filter((rule) => rule instanceof CSSKeyframesRule)
+ * ```
+ */
+export declare function readRules(): readonly CSSRule[];
+
 /**
  * Reads the states one element is announced in.
  *
@@ -984,19 +1285,57 @@ export declare function readValue(role: string, name: string): string;
 export declare function releasePane(): void;
 
 /**
- * Renders trusted fixture markup into a container attached to the document.
+ * Deletes one IndexedDB database and reports what the request actually did.
+ *
+ * @param name - The database name to delete.
+ * @returns A promise resolving after the deletion completes.
+ * @throws Thrown when the request errors, and when an open connection blocks it.
+ *
+ * @remarks
+ * Deleting a database that was never created succeeds, so this is safe to call from a teardown hook
+ * that runs whether or not the test reached the code that opens one.
+ *
+ * A block is a rejection rather than a wait. `blocked` fires when another connection is still open,
+ * and a suite that swallowed it would leave the next test reading the previous test's records
+ * through a database that reports itself deleted. The connection holding it open is the caller's to
+ * close, so the block is handed back rather than absorbed.
+ *
+ * @example
+ * ```ts
+ * afterEach(() => removeDatabase('ledger'))
+ * ```
+ */
+export declare function removeDatabase(name: string): Promise<void>;
+
+/**
+ * Renders one fixture into the document, from trusted markup or from a tag and its classes.
+ *
+ * @param first - The fixture markup, or the HTML tag name when `second` is present.
+ * @param second - The class list when `first` supplies the tag name.
+ * @returns The attached container for the markup form, and the attached element itself for the tag
+ * form.
+ *
+ * @remarks
+ * The class list is required in the tag form, which is what keeps the two forms apart: a
+ * one-argument call is always markup. A tag with no classes is `mount(build(tag))`.
  *
- * @param markup - The fixture markup to render.
- * @returns The attached container.
+ * The markup form parses `first` into a fresh container and returns that container, so the fixture's
+ * own nodes are its children. The tag form returns the element itself, typed as exactly that tag.
+ * Both attach to `document.body` and neither records anything, so removal is the caller's, exactly
+ * as it is for {@link mount}.
  *
  * @example
  * ```ts
  * const container = render('<button type="button">Save</button>')
+ * const panel = render('section', 'surface muted')
  * container.remove()
+ * panel.remove()
  * ```
  */
 export declare function render(markup: string): HTMLDivElement;
 
+export declare function render<K extends keyof HTMLElementTagNameMap>(tag: K, classes: string): HTMLElementTagNameMap[K];
+
 /**
  * Resolves one visible, focus-reachable interactive element by its exact accessible name. A
  * wholly-off-viewport target is scrolled into view before reachability is measured.
@@ -1054,6 +1393,57 @@ export declare function resolveAccessible(role: string, name: string): HTMLEleme
  */
 export declare function resolveRendered(first: string, second?: string): HTMLElement;
 
+/**
+ * Resolves any CSS color expression to straight sRGB channels, by asking the browser.
+ *
+ * @param value - Any value the `color` property accepts: a keyword, a hex triple, a `var()`
+ * reference, a `color-mix()`, or an already-computed `rgb()`.
+ * @returns The resolved color's channels, or `undefined` when the CSSOM refuses the value or the
+ * computed result names no color {@link parseColor} speaks.
+ *
+ * @remarks
+ * This is the live half of the pair {@link parseColor} opens. `parseColor` reads text and speaks
+ * only the computed syntaxes a cascade hands back; this stages a probe element, hands it to the real
+ * cascade, and reads back what the engine computed — which is the only way a keyword, a hex triple,
+ * or a `var()` reference becomes channels at all. The read itself goes through `parseColor`, so both
+ * halves agree on what a computed value means.
+ *
+ * The probe is mounted, because an unmounted element inherits nothing and a `var()` reference to a
+ * token declared on `:root` would resolve to the initial value instead. It is removed in a `finally`,
+ * so a value that throws on the way through leaves no node behind.
+ *
+ * Refusal is the CSSOM's: an expression it will not parse leaves the probe's inline `color` empty
+ * and this returns `undefined`. A `var()` naming an undeclared custom property is not refused,
+ * because the cascade accepts it and computes the inherited color, so a test that means to catch a
+ * missing token asserts on {@link token} rather than on this.
+ *
+ * @example
+ * ```ts
+ * rgba('rebeccapurple') // [102, 51, 153, 1]
+ * rgba('not-a-color') // undefined
+ * ```
+ */
+export declare function rgba(value: string): Color | undefined;
+
+/**
+ * Reads one custom property from the document element.
+ *
+ * @param name - The custom property name, with or without its leading dashes.
+ * @returns The resolved value, trimmed; an empty string when the document declares no such property.
+ *
+ * @remarks
+ * This is {@link token} against `document.documentElement`, which is where a theme declares its
+ * tokens and where a `[data-theme]` switch retunes them. It exists as its own name because that
+ * element is the one a token question is nearly always about, and naming it at every call site
+ * buries the question.
+ *
+ * @example
+ * ```ts
+ * rootToken('surface')
+ * ```
+ */
+export declare function rootToken(name: string): string;
+
 /**
  * Sets the tester's viewport and renders the runner's pane at the size that viewport claims.
  *
@@ -1099,8 +1489,13 @@ export declare function stagePane(width: number, height: number): Promise<void>;
  * Reads one resolved CSS property from a real browser element.
  *
  * @param element - The element whose resolved style to inspect.
- * @param property - The CSS property name.
- * @returns The browser's resolved property value.
+ * @param property - The CSS property name, registered or custom.
+ * @returns The browser's resolved property value, trimmed; an empty string when the element resolves
+ * none.
+ *
+ * @remarks
+ * The value is trimmed, so what comes back is the value and never the whitespace around it. Internal
+ * whitespace is kept: `--shadow: 0 0 2px` reads back with its spaces.
  *
  * @example
  * ```ts
@@ -1109,6 +1504,32 @@ export declare function stagePane(width: number, height: number): Promise<void>;
  */
 export declare function style(element: Element, property: string): string;
 
+/**
+ * Reads one custom property from an element's resolved style.
+ *
+ * @param element - The element whose resolved style to inspect.
+ * @param name - The custom property name, with or without its leading dashes.
+ * @returns The resolved value, trimmed; an empty string when the element inherits no such property.
+ *
+ * @remarks
+ * The dashes are optional because a token is spoken about both ways — `--surface` in a stylesheet
+ * and `surface` in prose — and a reader that accepted only one spelling would turn that into a silent
+ * empty string. An absent token reads as `''`, which is what the CSSOM returns and is
+ * indistinguishable from a token declared empty; assert on the value you expect rather than on
+ * presence.
+ *
+ * Resolution is inheritance, so a token declared on `:root` reads from any mounted descendant and
+ * from an unmounted element reads as `''`. Use {@link rootToken} where the declaration is the
+ * document's.
+ *
+ * @example
+ * ```ts
+ * token(panel, 'surface') // '#ffffff'
+ * token(panel, '--surface') // '#ffffff'
+ * ```
+ */
+export declare function token(element: Element, name: string): string;
+
 /**
  * Reaches a named control only through natural forward Tab traversal from the current focus.
  *
@@ -1137,6 +1558,31 @@ export declare function traverseAccessible(name: string): Promise<HTMLElement>;
  */
 export declare function typeAccessible(name: string, text: string): Promise<void>;
 
+/**
+ * Sets one field's value and announces it the way typing into the field does.
+ *
+ * @param element - The input or textarea to write into.
+ * @param text - The value to set.
+ *
+ * @remarks
+ * This is the synthetic pair of {@link typeAccessible}, for a component that listens for `input` and
+ * a test that has the element already. It sets the value in one write and dispatches one bubbling
+ * `input` event, so a delegated listener on an ancestor hears it. It sends no keystrokes, so a
+ * component reading `key`, composition, or selection sees nothing. The dispatched event is a plain
+ * `Event`, never an `InputEvent`, so a component reading `inputType` or testing
+ * `instanceof InputEvent` sees neither. Drive a component that reads any of those through
+ * `typeAccessible` instead.
+ *
+ * No `change` event follows. Use {@link commitInput} where the component waits for the field to be
+ * committed.
+ *
+ * @example
+ * ```ts
+ * typeInput(requireValue(container.querySelector('input')), 'Ada')
+ * ```
+ */
+export declare function typeInput(element: HTMLInputElement | HTMLTextAreaElement, text: string): void;
+
 /**
  * Waits for one animation frame to settle pending browser paint work.
  *