kb-text-layout: Multiline text measurement & layout.

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Warnings:


[Skip to Readme]

Properties

Versions 0.1.0.0, 0.1.0.1, 0.1.0.2, 0.1.2.0, 0.2.0.0
Change log CHANGELOG.md
Dependencies base (>=4.18 && <5), bytestring, containers, filepath, hyphenation, kb-text-layout, kb-text-shape (>=0.3 && <0.4), text, vector, zstd [details]
License BSD-3-Clause
Copyright 2026 IC Rainbow
Author IC Rainbow
Maintainer aenor.realm@gmail.com
Category Text
Source repo head: git clone https://gitlab.com/dpwiz/text-layout
Uploaded by AlexanderBondarenko at 2026-11-17T20:19:04Z

Modules

Flags

Manual Flags

NameDescriptionDefault
demos

Build the demo executables and benchmarks.

Disabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for kb-text-layout-0.2.0.0

[back to package description]

kb-text-layout

Multiline text measurement & layout on top of kb-text-shape, inspired by pretext. Prepare a text once, then lay it out at any width.

import Data.Text.IO qualified as Text
import KB.Text.Layout.Break qualified as Break
import KB.Text.Layout.Measure qualified as Measure
import KB.Text.Shape qualified as KBTS

main :: IO ()
main =
  KBTS.withContext \shape -> do
    font <- KBTS.pushFontFromFile shape "demos/assets/Ubuntu-R.ttf" 0

    ctx <- Measure.createLayoutContext shape
    style <- Measure.newStyle ctx font 1.0
    prepared <- Measure.prepare ctx style "Soft hy\173phen\173ation and non\160breaking\160spaces."

    let maxWidth = 24
    let ranges = Break.layoutGreedy prepared maxWidth
    putStrLn $ "Stats: " <> show (Break.layoutStats ranges)
    putStrLn ""
    -- Stats: LayoutStats {lineCount = 2, maxLineWidth = 13.909091}

    putStrLn "Ranges:"
    mapM_ print ranges
    -- LineRange {from = Cursor {segment = 0, grapheme = 0}, to = Cursor {segment = 9, grapheme = 0}, width = 13.909091, ended = Wrapped}
    -- LineRange {from = Cursor {segment = 10, grapheme = 0}, to = Cursor {segment = 15, grapheme = 0}, width = 13.470421, ended = Finished}
    putStrLn ""

    putStrLn "Lines:"
    let laidout = map (Break.materializeLineRange prepared) ranges
    -- Soft hyphenation and
    -- non breaking spaces.
    mapM_ Text.putStrLn laidout

Everything after prepare is pure: relayout at another width is a fold over cached widths, with no shaper calls.

Units

To make sizes comparable across different fonts layout space is cap-height-normalized. newStyle ctx font 1.0 scales the font so a capital H is exactly 1.0 layout units tall. Style.em carries the em size in the same units for renderers that need CSS or pixel sizes.

Line height is a caller-chosen number of cap units. Ascenders and descenders overhang the fixed line box, so vertical font metrics never enter layout.

⚠️ Fonts without a cap-height metric fail at load time.

Faces

newStyleWith takes a Face, a font together with variation axis values and OpenType feature overrides. Axes the face leaves out keep their defaults, and static fonts ignore axes. A tag listed twice keeps its last value, as in CSS.

import KB.Text.Shape.FFI.Enums.FeatureTag qualified as FeatureTag

bold <- Measure.newStyleWith ctx (Measure.face font){Measure.variations = [KBTS.Variation (KBTS.fourcc 'w' 'g' 'h' 't') 700]} 1.0
digits <- Measure.newStyleWith ctx (Measure.face font){Measure.features = [(FeatureTag.FEATURE_TAG_tnum, 1)]} 1.0

The renderer has to apply the same settings, for example with CSS font-variation-settings and font-feature-settings. The cap height always comes from the font's default instance. Axis values never change Style.scale.

Demos

The demo executables live in demos/ behind the demos package flag (off by default).

Use make demos to run everything and rebuild the HTML pages.

Use stack bench to see the relative cost of each layout.

Limitations