typehug

KO | EN

gitlite — search

#ai-agent #mcp #shell #agent #svg #android #artificial-intelligence #gpt #tailwindcss #api

(★ 9)

Keep words together. Modular typography helpers for Polish and English text, HTML, and rich text.

File Explorer

ZIP Download

- - ci.yml
- - interview.md
- - interview.md
- - 0001-public-change-explanations.md
- - domain.md
  - issue-tracker.md
  - triage-labels.md
- - 2026-09-10-web-mobile-typography.md
- api.md
- inspection.md
- releasing.md
- rules.md
- basic.mjs
- - LICENSE
  - package.json
  - README.md
  - tsconfig.json
- - LICENSE
  - package.json
  - README.md
  - tsconfig.json
- - LICENSE
  - package.json
  - README.md
  - tsconfig.json
- - LICENSE
  - package.json
  - README.md
  - tsconfig.json
- build-site.mjs
- check-packages.mjs
- serve-site.mjs
- examples.json
- favicon.svg
- index.html
- inspection-view.test.mjs
- inspection-view.ts
- inspection.test.mjs
- inspection.ts
- main.ts
- og-image.png
- og-image.svg
- page.md
- playground.test.mjs
- playground.ts
- README.md
- site.test.mjs
- styles.css
- tsconfig.json
- - consumer.ts
  - tsconfig.json
- analysis.test.mjs
- engine.test.mjs
- html.test.mjs
- packages.test.mjs
- runs.test.mjs
.gitignore
AGENTS.md
CHANGELOG.md
CONTEXT.md
CONTRIBUTING.md
LICENSE
package-lock.json
package.json
README.md
tsconfig.base.json
tsconfig.json
vercel.json

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Keep words together.

Typehug inserts nonbreaking spaces in Polish and English text. It works with strings, HTML fragments, and formatted text runs. Install one language or both; each language uses the same engine.

## Packages

| Package | Includes |
| --- | --- |
| `@typehug/pl` | Polish rules and the shared engine |
| `@typehug/en` | English rules and the shared engine |
| `@typehug/all` | Both languages, selected explicitly |
| `@typehug/core` | Engine, shared units, types, and HTML adapter for custom profiles |

```sh
npm install @typehug/pl
# Or: npm install @typehug/en
# Or: npm install @typehug/all
```

Packages provide ESM and TypeScript declarations. Node.js 22 or newer is supported. The browser bundle uses standard JavaScript with Unicode property escapes.

## Plain text

```ts
import { glue } from "@typehug/pl";

glue("Idę w dobrym kierunku.");
// "Idę w\u00a0dobrym\u00a0kierunku."
```

The result contains the Unicode character U+00A0, not the literal string `&nbsp;`. You can render it as a React text child without parsing HTML.

```tsx
{glue(description)}
```

Use an explicit language with the combined package:

```ts
import { glue } from "@typehug/all";

glue("Idę w dobrym kierunku.", { locale: "pl" });
glue("I have a question.", { locale: "en" });
```

There is no language detection. A missing or unsupported locale in `@typehug/all` throws a `RangeError`.

## Change explanations

Available since `0.2.0`. Use `analyze` to get corrected text and an explanation for each replaced space. All four package roots export `analyze`, its result types, and `ruleDescriptions`.

```ts
import { analyze, ruleDescriptions } from "@typehug/en";

const result = analyze("Wait 30 min.");
// {
//   text: "Wait 30\u00a0min.",
//   changes: [{
//     start: 7, end: 8, before: " ", after: "\u00a0",
//     rules: ["units", "lastWords"],
//   }],
// }

for (const change of result.changes) {
  console.log(change.rules.map((rule) => ruleDescriptions[rule]));
}
```

`result.text` equals `glue` with the same input and options. Each change identifies one replaced space using UTF-16 offsets into the original string, with an exclusive `end`, and lists every active supporting rule family. In this example, disabling only `units` still permits `lastWords` to make the change; disable both to leave the space unchanged.

Analysis accepts plain text. An empty `changes` array means these rules made no changes; it does not certify the text's typography or explain skipped candidates. Existing nonbreaking spaces and rejected joins are not reported as new changes. See the [analysis schema, offsets, and package signatures](docs/api.md#change-analysis).

## HTML

```ts
import { glueHtml } from "@typehug/pl/html";

glueHtml('Idę w dobrym kierunku.');
// Idę w&nbsp;dobrym&nbsp;kierunku.
```

Text joins through ordinary inline formatting and link labels. Paragraphs, ` `, and other block or replaced elements stop joins. Attributes retain their values. Code, scripts, styles, and other protected subtrees are skipped. Add `data-typehug-skip` to leave an element's text alone.

The adapter uses parse5 to parse and serialize a fragment. It may normalize entity spellings, attribute quotes, tag case, and malformed markup. It does not preserve HTML byte for byte, evaluate CSS layout, or sanitize HTML. See [HTML behavior](docs/api.md#html-fragments).

Only the `/html` entry points import the parser. The parser is an installed dependency of `@typehug/core`, but a plain-text browser bundle does not include it.

## Formatted text runs

```ts
import { glueRuns } from "@typehug/pl";

glueRuns([
  { text: "Idę w ", bold: false },
  { text: "dobrym kierunku.", bold: true },
]);
// [
//   { text: "Idę w\u00a0", bold: false },
//   { text: "dobrym\u00a0kierunku.", bold: true },
// ]
```

Adjacent runs are interpreted as one text segment, even if a word is split between them. Each edit stays in the run that owns the space. Run order, additional properties, and nested metadata are preserved; input objects are not mutated.

- `breakBefore: true` starts a new paragraph before a run.
- `skip: true` protects a run and stops joins on both sides.
- Empty runs may carry either boundary marker.

Notion, Slate, ProseMirror, and Markdown AST adapters are not included in `0.2.0`. Map their text and paragraph boundaries to runs explicitly.

## Rules

All five families are enabled by default:

| Option | Behavior |
| --- | --- |
| `shortWords` | Polish one-letter words; English `a`, `A`, and `I` |
| `units` | Numbers followed by a listed unit symbol |
| `initials` | Consecutive uppercase initials with periods |
| `abbreviations` | Listed abbreviations and references with suitable following text |
| `lastWords` | Short pairs at the end of a paragraph |

```ts
glue(text, { rules: { lastWords: false, initials: false } });
```

Rules can overlap: disabling `shortWords` does not prevent `lastWords` from joining the same pair at a paragraph ending. English short-word joins and paragraph endings are aesthetic preferences, not universal rules of English correctness.

The ending heuristic requires at least three words and a final pair of at most 24 Unicode code points, including the space and punctuation. Automatically joined groups cannot exceed 48 code points. Typehug does not measure fonts or available width, so these limits cannot guarantee a particular line layout.

Existing NBSP and narrow NBSP, line endings, tabs, repeated spaces, URLs, and email addresses are preserved. Running Typehug twice with the same profile and options returns the same result. See the exact [dictionaries, rules, and sources](docs/rules.md).

## Develop locally

```sh
git clone https://github.com/alexszczurek/typehug.git
cd typehug
npm ci
npm run check
npm run example
```

`npm run check` builds the workspaces, checks the public types, runs behavior tests, and installs packed tarballs into temporary consumer projects. It also verifies that a single-language text bundle includes neither the other language nor the HTML parser.

Read the [interface reference](docs/api.md), [contribution guide](CONTRIBUTING.md), and [release instructions](docs/releasing.md).

## Landing page

Run `npm run site:dev` to preview the marketing page and live playground at `http://127.0.0.1:4173`. Run `npm run site:check` to check the site. Build and hosting details are in the [site guide](site/README.md).

## License

[MIT](LICENSE).

typehug

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README