Susegad UI Accessibility GitHub

How this site looks

The view settings need JavaScript. Every page reads well without them.

Mood

The same pages, in three moods.

Theme

Foundations

Image tier

A picture's size, known early, so text laid by script can wrap round a picture before its bytes arrive: an oracle that reads the intrinsic size from the file header (PNG, JPEG with EXIF orientation, GIF, WebP, AVIF) by a streamed fetch it cancels, falling back to a warmed image, with the pure geometry beside it…

Open the live demo npx @susegad/cli add image

Stands on: Type tier

The prompt

the prompt

A picture's size, known early, so text laid by script can wrap round a picture before its bytes arrive.

For a picture in a box, use aspect-ratio and object-fit: the platform owns them. This tier is for the case CSS cannot do, text that a script lays line by line (the type tier) beside floated pictures, and a canvas that must place a picture itself.

The prompt

Make a small image tier in three parts, with the same shape as the type tier. First, an oracle: the one module that goes to the network or the decoder for a picture's intrinsic size, and answers early, before the picture has loaded. It reads, in this order, a size the page already has (width and height attributes, a CMS field, recorded by URL); the header of the file, by a streamed fetch that asks for a byte range, parses as chunks arrive and cancels at the first answer; and last a warmed image element polled for its natural width, for what a fetch cannot read (a cross-origin picture with no CORS, an SVG). The header parser is pure and separate: PNG, GIF, JPEG (every frame marker, and EXIF orientation 5 to 8 swapping width and height), WebP (lossy, lossless and extended) and AVIF (the primary item's spatial extents, turned by its rotation property). The oracle caches by resolved URL, shares one request between concurrent callers, lets a caller's abort signal end its own wait and the request when nobody waits, cancels everything on dispose, never throws into a caller (an unknown size is null), and takes its fetch and Image constructor as options so Node can test the whole path.

Second, a pure geometry core that imports nothing: fitRect for contain, cover and none with alignment (object-position) and a focal point, returning the drawn rectangle and the crop in picture pixels; reserve for the box a picture needs at a width, with a ratio fallback that says it guessed; flowColumn for a column with left and right floats, giving the reserved boxes and a shape function (top, bottom) -> { x, w } | null for the type tier's layIntoShape, floats stacking down their side and going below one on the other side if they would meet it; and flowAround, which takes a type-tier layout as an argument and lays text beside those floats.

Third, a live surface loaded only by dynamic import in warm and playful, which reads each figure's size (attributes first, then the oracle), waits for the sizes at most 600 ms, lays the paragraphs beside boxes reserved from them, writes one span per line inside each paragraph so the words stay the paragraph's own text, and re-lays on resize and text zoom. Quiet, reduced motion and no JavaScript get plain CSS floats and aspect-ratio from width and height attributes, and never request the oracle, the type tier or Pretext. Nothing may import the oracle except the live surface.

Test the geometry against CSS object-position and against its own invariants, plant faults in it and in the parser and check each is caught, and check in a browser that delayed pictures change no line and no box when they arrive.

Words to code

When you sayTechniqueWhat happens
the size, earlythe oracleimageOracle.dims(src, { signal }) resolves { w, h, source } ('known', 'bytes', 'img') or null; peek(src) answers from the cache at once.
a size the page already hasrecordrecord(src, { w, h }) makes dims answer with source: 'known' and no request.
read the header, stopstreamed range fetchRange: bytes=0-262143, the parser runs on each chunk, the transfer is cancelled at the first answer.
as the browser shows itorientationJPEG EXIF 5 to 8 and AVIF irot 90 and 270 swap width and height before the answer.
never throwsnull for unknowna 404, a missing fetch, a throwing Image, an abort and a timeout all resolve null.
stop when nobody waitsabort countingeach caller's signal ends its own wait; the request is aborted when the last waiter leaves. dispose() aborts all.
like object-fitfitRectfitRect(dims, box, 'contain', 'cover' or 'none', { align, focus }) returns { x, y, w, h, scale, crop }; without focus it is object-position.
keep this point in viewfocal pointfocus: { x, y } (0 to 1) is brought to the middle of the box, clamped so the picture still covers it.
the box before the bytesreservereserve(dims, width, ratio?) gives { w, h, guessed }; no size and no ratio gives null.
text beside a floated pictureflowColumnflowColumn(col, floats, { gap }) returns { boxes, shape, bottom }; shape goes to layIntoShape.
laid before the picture arrivesflowAroundflowAround(layout, blocks, col, floats, { gap, minWidth }) returns { lines, fits, bottom, boxes }.
no word squeezed into a sliverminWidthbands narrower than minWidth are stepped over, so the text starts below the float.
the live tier onlymountFlowmountFlow(root) in flow.live.js, imported dynamically, only when registerState(root) is not quiet and not reduced.
the plain readingCSSfloats, img { width: 100%; height: auto } and width and height attributes: no oracle request.

Budget

About 33 KB of source with its comments across four files: the header parser 8.5 KB, the oracle 8.4 KB, the geometry 8.3 KB and the live surface 8.3 KB. Budgeted apart from the type tier while the foundations go in.

A picture's size, known before its bytes arrive, so text laid by script can wrap round a picture without moving when the picture lands (decisions 0029 and 0030). The second oracle of the bake-and-reflow core, built like the type tier it works with.

Use CSS first. For a picture in a box, give the <img> its width and height and use aspect-ratio and object-fit. This tier is for text a script lays line by line beside floated pictures, and for a canvas that places a picture itself.

Install

node <path-to-susegad-ui>/packages/cli/bin/susegad.mjs add image    # brings the type tier and Pretext with it

In a page

<div class="flow" id="flow">
  <figure data-side="right" data-share="0.42"><img src="a.jpg" width="1200" height="800" alt="…"></figure>
  <figure data-side="left" data-share="0.34" data-y="236"><img src="b.png" alt="…"></figure>
  <p>…</p>
</div>
<script type="module">
  import { registerState } from 'susegad/core/register.js';
  const root = document.getElementById('flow'), s = registerState(root);
  if (s.register !== 'quiet' && !s.reducedMotion) {
    const { mountFlow } = await import('susegad/image/flow.live.js');
    mountFlow(root, { gap: 16, minWidth: 112 });
  }
</script>

Float the figures in CSS for the plain reading. mountFlow reads each picture's size from its width and height, or from its file header when it has none; waits for the sizes (600 ms at most); and lays the paragraphs beside boxes reserved from them. One span per line goes inside each <p>, so the words stay real text, in order. destroy() gives the plain reading back.

API

ExportWhat it does
imageOracle (measure.js)The shared oracle. dims(src, { signal }), peek(src), record(src, { w, h }), dimsOfBytes(bytes), dimsOfBlob(blob), forget(src?), dispose().
createImageOracle({ fetch, Image, base, maxBytes, timeoutMs })A separate oracle with its own cache; the fetch and Image can be replaced.
readHeader(bytes) (header.core.js){ kind, w, h, orientation }, { more: true } or null. Pure.
fitRect(dims, box, mode, { align, focus })Where a picture lands in a box (contain, cover, none), with the crop in picture pixels.
reserve(dims, width, ratio?)The box a picture needs at a width.
flowColumn(col, floats, { gap })The reserved boxes and the column's room as a shape for layIntoShape.
flowAround(layout, blocks, col, floats, opts)Text laid beside floats, from a type-tier layout.
mountFlow(root, opts) (flow.live.js)The live surface. ready, relayout(), destroy(). Fires sg-flow on the root after each layout.

Cores and components import layout.core.js and header.core.js, never measure.js; packages/type/boundary.test.js enforces it.

Limits

A very large EXIF block can push the frame header past 256 KB; the <img> fallback answers then. WebP's EXIF orientation is not read. SVG has no header. The first layout waits at most 600 ms for sizes, and a picture whose size is still unknown then gets a guessed box and one re-layout when its size lands.