text-wrap-minor-words

text-wrap-minor-words


Experimental, CSS-first polyfill that augments text-wrap: pretty by biasing against line breaks immediately after minor words (articles, prepositions, short conjunctions) in languages where this is a widely accepted typesetting convention. It also applies a couple of safe, language-agnostic joins (e.g., Fig. 2, 20 °C).

Status: experimental. See explainer.md. Live demo: https://jlorenzetti.github.io/text-wrap-minor-words/

$3

text-wrap: pretty improves paragraph breaking but does not let authors express locale-aware preferences about breaking immediately after minor words. Many European languages treat this as a common editorial convention even in body text. This library offers a CSS-first polyfill so authors can experiment today and help inform standardization.

$3

``bash
npm i text-wrap-minor-words
`

$3

`ts
import { init } from 'text-wrap-minor-words';

// Process elements that compute to text-wrap: pretty
const ctrl = init({ observe: true });

// Optionally process a specific subtree later:
// ctrl.process(element);
`

HTML markup should declare the language (lang) on blocks:

`html


Vado a casa con la bici.

Je vais à Paris.

Jestem w domu i czekam.

See Fig. 2 for details.

It was 20 °C at 9:30 am.

A display heading if you want to opt-in later


`

$3

`html


`

$3

- Extends text-wrap: pretty behavior by inserting NBSP after minor words in languages where this is customary (Romance, Slavic, Greek by default).
- Applies safe joins regardless of language:
- label + number: Fig. 2, p. 12, § 5
- number + unit: 20 °C, 9:30 am
- honorific + Name: Mr. Smith, Dr. Müller
- initials sequence: J. K. Rowling
- numeric ranges: adds WORD JOINER around the dash

$3

Load only the core engine and register the locales you actually use. This keeps bundles small and avoids shipping unnecessary language data.

`ts
// Load the lite entry (no locales included)
import { init, registerLanguage } from 'text-wrap-minor-words/lite';

// Register only the locales you need (example: Italian)
import it from 'text-wrap-minor-words/locales/it.json';
registerLanguage('it', it);

// Optionally preload the same tags here (helps the engine avoid a first lookup)
init({ languages: ['it'] });
`

Browser global (lite):

`html

`

Notes:
- The default (non‑lite) entry includes built‑in locale data for quick trials. Prefer the lite entry in production apps.
- You can register multiple locales by calling registerLanguage(tag, data) more than once.

Advanced (CSS opt‑in per container):

You can enable the minor‑words preference declaratively on specific elements via CSS. This is useful for safe‑only languages where you want the behavior only in display contexts.

`css
h1[lang="en"], h2[lang="en"] {
--text-wrap-preferences: minor-words;
--text-wrap-minor-threshold: 1; / glue after 1‑letter tokens /
--text-wrap-minor-stoplist: "of to in on at for by a I"; / optional additions /
}
`

These custom properties are read when the preference is opted‑in on the element (or an ancestor) and the current language doesn’t have a built‑in minor‑words configuration.

$3

- Active by default: be, bg, ca, cs, el, es, fr, gl, hr, it, mk, pl, pt, ro, ru, sk, sl, sr, uk.
- Neutral by default: da, de, en, lt, lv, nb, nl, nn, sv (only safe joins; no minor-words glue in body text).
- The effective language is taken from lang (with fallback to the document root).

$3

`ts
type InitOptions = {
selector?: string; // default: 'html' (scans under elements that compute to text-wrap: pretty)
languages?: string[]; // pre-load specific BCP-47 primary subtags (e.g., ['it','en'])
observe?: boolean; // MutationObserver to process added/edited content
context?: 'all'|'display'; // if 'display', only process headings/DT
};
`

Returns a controller { process(root?), disconnect() }.

$3

- The library reads lang to select language defaults.
- Neutral languages (e.g., en, de, nl) do not enable minor-words glue by default; only safe joins apply.
- For display-only processing, pass { context: 'display' }.
- You can pre-load language data via languages: ['it','fr'] to avoid first-use compile cost.

CSS preference gate and overrides:

- You can opt in/out declaratively per container with --text-wrap-preferences: minor-words | none. On browsers without text-wrap: pretty, authors can set the preference under @supports not (text-wrap: pretty).
- When the preference is active and the current language has no built‑in minorWords, the engine reads optional overrides:
- --text-wrap-minor-threshold: (glue after tokens up to N chars; typical value: 1)
- --text-wrap-minor-stoplist: "space-separated tokens" (per‑container additions)

Example (headings in English):

`css
h1[lang="en"], h2[lang="en"] {
--text-wrap-preferences: minor-words;
--text-wrap-minor-threshold: 1;
--text-wrap-minor-stoplist: "of to in on at for by a I";
}
`

$3

- One TreeWalker pass over text nodes under elements that compute to text-wrap: pretty.
- No layout measurements; O(n) string replacements; NBSP insertions are idempotent.
- Skips pre, code, kbd, samp, script, style, textarea, math, svg, [contenteditable] and basic URL/email-like text.
- Does not cross inline elements by default.

$3

- The polyfill acts only where the computed style is text-wrap: pretty. On browsers without support, it effectively no-ops unless the author explicitly applies an opt-in selector targeting the same blocks.
- The library itself targets modern evergreen browsers (ES2020, Intl.Segmenter optional).

$3

- Language tables live in src/data/languages/.json.
- To propose additions:
1. Add or edit the JSON with minorWords (threshold + list) and lexical categories (labels, honorifics, abbrCompounds).
2. Add unit tests in tests/engine.spec.ts (or a new spec file) with input → expected output.
3. Run npm run test.

$3

- Run tests: npm run test
- Run a simple throughput benchmark: npm run bench

$3

- No apostrophe/elision handling (out of scope for now).
- Does not measure layout; it applies static glues consistent with editorial conventions.
- Does not cross inline elements unless an advanced option is introduced in future.

$3

- This repo accompanies the explainer (explainer.md) that proposes text-wrap-preferences: minor-words as an additive, language-sensitive author preference for paragraph-aware wrapping.
For a consolidated list of safe labels/honorifics used by the polyfill, see docs/LEXICON.md`.

$3

MIT