bidi-kit 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Nour Yahyaoui
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,364 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
1
+ # bidi-kit
2
+
3
+ Arabic words inside English sentences, French sentences inside Arabic paragraphs — with the
4
+ punctuation, numbers, quotation marks and fonts that go with them.
5
+
6
+ ```ts
7
+ import { paragraph } from "bidi-kit";
8
+
9
+ const html = paragraph(
10
+ ["The greeting is ", { text: "مرحبا", dir: "rtl", lang: "ar" }, "."],
11
+ { lang: "en" },
12
+ );
13
+ // <p dir="ltr" lang="en">The greeting is <bdi dir="rtl" lang="ar">مرحبا</bdi>.</p>
14
+ ```
15
+
16
+ Zero dependencies. No fonts bundled. TypeScript types, ESM, CommonJS **and a single-file classic
17
+ script for plain HTML pages**. Runs in the browser, in Node, in an edge worker; nothing in `dist`
18
+ imports `node:`.
19
+
20
+ ## What it fixes
21
+
22
+ | Symptom | Cause | What bidi-kit does |
23
+ | --- | --- | --- |
24
+ | The full stop after an Arabic name renders on the wrong side | The stop is neutral, so it is absorbed into the Arabic run | `paragraph()` ends the run at the stop and isolates the Arabic |
25
+ | `+216 71 123 456` gets split and reordered inside Arabic | Digits are weak characters with no direction of their own | `segments()` keeps a number with its own punctuation as one left-to-right run |
26
+ | A French quotation inside an Arabic paragraph reads backwards | The quotation inherits the paragraph's direction | The run is isolated with `dir="ltr"`, or wrapped in `<bdi>` |
27
+ | Diacritics are clipped, or one word is rendered in two different faces | The Latin face has no Arabic glyphs, and the line-height is set for Latin | A system Arabic stack with raised line-height, from `FONT_STACKS` and `CSS` |
28
+ | `dir="auto"` guesses wrong on a number-led string | First-strong detection is a heuristic | `detectDirection()` is explicit, and testable |
29
+ | An invisible `U+202E` renames a file or a field | Bidi control characters are invisible by design | `stripBidiControls()` removes them; `audit()` reports them as errors |
30
+
31
+ ## Install
32
+
33
+ ```bash
34
+ npm install bidi-kit
35
+ ```
36
+
37
+ Node 18 or newer for the CLI; the library itself has no engine requirement beyond ES2022.
38
+
39
+ ## Use it without a build step
40
+
41
+ Three ways, depending on what your HTML file already is.
42
+
43
+ **1. A classic `<script>` tag** — no modules, no bundler, and it works when the page is opened by
44
+ double-clicking it:
45
+
46
+ ```html
47
+ <script src="./bidi-kit/dist/bidi-kit.global.js"></script>
48
+ <script>
49
+ const kit = window.bidiKit;
50
+ document.querySelector("#line").innerHTML = kit.paragraph([
51
+ "Sent to ",
52
+ { text: "أحمد بن علي", dir: "rtl", lang: "ar" },
53
+ " this morning.",
54
+ ]);
55
+ </script>
56
+ ```
57
+
58
+ `dist/bidi-kit.global.js` is 23 kB, sets `window.bidiKit`, and carries the same 31 exports as the
59
+ module build — `tests/global.test.mjs` runs both and compares their output string for string. This is
60
+ the file to copy into a static folder, a CMS "custom HTML" box, or a Jekyll/Hugo/WordPress template.
61
+
62
+ **2. `<script type="module">`** — the ES module build, no bundler, served over HTTP:
63
+
64
+ ```html
65
+ <script type="module">
66
+ import { paragraph, CSS, FONT_STACKS } from "./bidi-kit/dist/esm/index.js";
67
+
68
+ const style = document.createElement("style");
69
+ style.textContent = CSS;
70
+ document.head.append(style);
71
+ </script>
72
+ ```
73
+
74
+ Modules will not load from `file://`, so this needs any static server (`python3 -m http.server`,
75
+ `npx serve`, your framework's dev server).
76
+
77
+ **3. Straight from this repository, through a CDN** — no npm account, no publish, works today:
78
+
79
+ ```html
80
+ <script src="https://cdn.jsdelivr.net/gh/Nour-yahyaoui/ui-storm@main/static/bidi-kit.js"></script>
81
+ ```
82
+
83
+ `static/bidi-kit.js` is the committed copy of the bundle (`npm run static:sync` writes it; CI fails when
84
+ it drifts from the build). Pin `@main` to a tag or a commit hash for a URL that never changes.
85
+
86
+ Use the CDN, not `raw.githubusercontent.com`: raw GitHub answers with `text/plain` and `nosniff`, and
87
+ browsers refuse to execute a script served that way. A CDN in front of the same repository sends a
88
+ JavaScript content type, which is the entire difference.
89
+
90
+ **4. From the npm CDN** — nothing to install, once the package is published:
91
+
92
+ ```html
93
+ <script src="https://cdn.jsdelivr.net/npm/bidi-kit@0.1.0/dist/bidi-kit.global.js"></script>
94
+
95
+ <script type="module">
96
+ import { paragraph } from "https://cdn.jsdelivr.net/npm/bidi-kit@0.1.0/dist/esm/index.js";
97
+ </script>
98
+ ```
99
+
100
+ The `unpkg` and `jsdelivr` fields in `package.json` point at the global build, so
101
+ `https://unpkg.com/bidi-kit` resolves to it directly.
102
+
103
+ **Whichever you choose**, two lines are still yours to write: put `lang` on `<html>`, and let user
104
+ text set its own direction with `dir="auto"` (or `kit.apply(element, text)`). Everything else is in
105
+ the package.
106
+
107
+ There is a worked example of the first option:
108
+ [`demo/plain.html`](demo/plain.html) — one script tag, no modules, no build. The project landing page
109
+ at [`site/index.html`](../../site/index.html) is a second one, and it loads the script from the
110
+ repository-backed CDN described above, with a local fallback.
111
+
112
+ ## The four things you will actually call
113
+
114
+ ### 1. `paragraph(parts, options)` — a paragraph built out of mixed runs
115
+
116
+ ```ts
117
+ import { paragraph, FONT_STACKS } from "bidi-kit";
118
+
119
+ const html = paragraph(
120
+ [
121
+ { text: "قال المدير:", dir: "rtl", lang: "ar" },
122
+ " ",
123
+ { text: "« Bonjour à tous »", dir: "ltr", lang: "fr", font: FONT_STACKS.latin },
124
+ " ",
125
+ { text: "ثم غادر.", dir: "rtl", lang: "ar", font: FONT_STACKS.arabic },
126
+ ],
127
+ { lang: "ar" },
128
+ );
129
+ ```
130
+
131
+ Each named part becomes a `<bdi>` with its own `dir`, `lang` and, if you pass one, font. Strings
132
+ are escaped; pass `{ html: true }` only for markup you have already sanitised.
133
+
134
+ ### 2. `segments(text, base?)` — where the runs are
135
+
136
+ ```ts
137
+ import { segments } from "bidi-kit";
138
+
139
+ segments("Write to أحمد.");
140
+ // [ { text: "Write to ", dir: "ltr", start: 0, end: 9 },
141
+ // { text: "أحمد", dir: "rtl", start: 9, end: 13 },
142
+ // { text: ".", dir: "ltr", start: 13, end: 14 } ]
143
+ ```
144
+
145
+ `base` is the paragraph direction. Omit it and the first strong character decides, which is what
146
+ the browser would assume anyway.
147
+
148
+ ### 3. `bdi(text, options)` and `apply(el, text)` — the small ones
149
+
150
+ ```ts
151
+ import { bdi, apply } from "bidi-kit";
152
+
153
+ bdi("أحمد", { lang: "ar" }); // <bdi lang="ar">أحمد</bdi>
154
+ apply(document.querySelector("#name"), "أحمد"); // textContent + dir="rtl"
155
+ ```
156
+
157
+ ### 4. `CSS` and `ROOT_CSS` — the rules that stop it happening again
158
+
159
+ ```ts
160
+ import { CSS, ROOT_CSS, ARABIC_FEATURES } from "bidi-kit";
161
+
162
+ const style = document.createElement("style");
163
+ style.textContent = CSS + ROOT_CSS;
164
+ document.head.append(style);
165
+ ```
166
+
167
+ `CSS` isolates every `[dir]`/`[lang]` element, aligns by direction rather than by side, gives
168
+ Arabic blocks a line-height that leaves room for the marks, and switches `[lang^="ar"]` to a face
169
+ that has the glyphs. `ROOT_CSS` puts `unicode-bidi: plaintext` on `html`, so a page that forgets
170
+ `dir` on one container still behaves.
171
+
172
+ ## API
173
+
174
+ ### Direction
175
+
176
+ | Function | Returns | Notes |
177
+ | --- | --- | --- |
178
+ | `detectDirection(text)` | `"ltr" \| "rtl" \| "neutral"` | First strong character, exactly what `dir="auto"` means |
179
+ | `resolveDirection(text)` | `"ltr" \| "rtl"` | Never neutral; safe to write to an attribute |
180
+ | `hasRtl(text)` | `boolean` | Any character of an RTL script |
181
+ | `hasArabic(text)` | `boolean` | Arabic *letters*; Arabic-Indic digits do not count |
182
+ | `isRtlCodePoint(cp)` | `boolean` | Script table, `U+0590`–`U+08FF` and the presentational blocks |
183
+
184
+ ### Runs
185
+
186
+ `segments(text, base?)` returns `{ text, dir, start, end }[]`, with `start`/`end` as UTF-16
187
+ indices into the original string.
188
+
189
+ The rules, in one place:
190
+
191
+ - a strong character starts a run and decides its direction;
192
+ - Arabic-Indic digits and Arabic punctuation (`,`, `;`, `?`, `%`) stay inside an Arabic run, so
193
+ `مرحبا،` does not break in half;
194
+ - Latin digits read left to right even inside Arabic, and `.` `,` `+` `-` `%` travel with the
195
+ number they belong to, so `1,248.50%` stays one run;
196
+ - brackets, quotes and symbols are neutral: they take the direction of the runs on both sides
197
+ when those agree, and otherwise the base direction — which is why an English full stop after
198
+ an Arabic name stays in the English sentence;
199
+ - combining marks and invisible controls never split a run.
200
+
201
+ ### Plain text
202
+
203
+ | Function | Use |
204
+ | --- | --- |
205
+ | `isolate(text, { dir })` | `FSI…PDI` (or `RLI`/`LRI`) around the whole string, for `aria-label`, canvas, terminals, CSV |
206
+ | `isolateRunsText(text)` | Every run isolated individually, for plain-text output |
207
+ | `stripBidiControls(text)` | Removes `U+061C`, `U+200E`, `U+200F`, `U+202A`–`U+202E`, `U+2066`–`U+2069` |
208
+ | `hasBidiControls(text)` | True when any of the above is present |
209
+ | `LRI`, `RLI`, `FSI`, `PDI`, `BIDI_CONTROL_CHARACTERS` | The constants, exported |
210
+
211
+ ### HTML
212
+
213
+ | Function | Emits |
214
+ | --- | --- |
215
+ | `bdi(text, opts)` | `<bdi>` with optional `dir`, `lang`, `class`, inline `font-family` |
216
+ | `inline(text, opts)` | `<span dir="auto">`; pass `element: "bdi"` for the other one |
217
+ | `paragraph(parts, opts)` | `<p>` with a resolved `dir`, `lang`, and one `<bdi>` per named part |
218
+ | `escapeHtml(text)` | Escapes `& < > " '` |
219
+ | `apply(el, text, opts)` | Sets `textContent` and `dir` on an element-shaped object |
220
+
221
+ `inline` and `bdi` never trust their input; `paragraph` escapes strings unless `{ html: true }`.
222
+
223
+ ### Fonts
224
+
225
+ | Export | What it is |
226
+ | --- | --- |
227
+ | `FONT_STACKS` | `arabic`, `hebrew`, `latin` stacks made of system faces |
228
+ | `fontStack(locale)` | Stack for a BCP-47 tag; `ar`, `fa`, `ur`, `ps` get Arabic |
229
+ | `ARABIC_FEATURES` | `"kern" 1, "liga" 1, "calt" 1, "rlig" 1, "init" 1, "medi" 1, "fina" 1` |
230
+ | `UNICODE_RANGES` | `unicode-range` per script, so a downloaded face is fetched only when needed |
231
+ | `fontFace(opts)` | An `@font-face` block with the range, weight and `font-display` filled in |
232
+ | `fontFamilyRule(selector, script)` | A one-line declaration block |
233
+
234
+ The Arabic stack is `"Noto Naskh Arabic", "Noto Sans Arabic", "Amiri", "Scheherazade New",
235
+ "Geeza Pro", "Segoe UI", "Noto Sans", sans-serif`. It starts with a naskh text face because that
236
+ is what Arabic prose is set in — and because a face without the glyphs makes the browser fall back
237
+ per glyph, which is what "one word, two fonts" looks like.
238
+
239
+ ### Audit
240
+
241
+ ```ts
242
+ import { audit, formatAudit } from "bidi-kit";
243
+
244
+ audit('<span dir="rtl">مرحبا</span>');
245
+ // [{ rule: "inline-direction-without-isolation", severity: "warning", index: 0, … }]
246
+ ```
247
+
248
+ Rules: `bidi-control-character` (error), `inline-direction-without-isolation`,
249
+ `physical-text-align`, `physical-css-property`, `document-without-lang`. It is a lint, not a
250
+ proof.
251
+
252
+ ## CLI
253
+
254
+ ```bash
255
+ npx bidi-kit check page.html # exits 1 when a bidi control character is found
256
+ npx bidi-kit runs note.txt # prints each run and its direction
257
+ npx bidi-kit isolate note.txt
258
+ npx bidi-kit dir article.txt
259
+ ```
260
+
261
+ With no file, every command reads standard input:
262
+
263
+ ```bash
264
+ printf 'مرحبا، هذا نص.' | npx bidi-kit dir
265
+ ```
266
+
267
+ None of these examples carry trailing comments, deliberately: `cmd.exe` on Windows would pass the
268
+ `#` and the words after it to the command as arguments.
269
+
270
+ ## Why not just `dir="rtl"`?
271
+
272
+ Because a paragraph is not one direction. `dir` sets the base direction of the *block*, and the
273
+ Unicode bidi algorithm then decides the order of everything inside it — invisibly, per character,
274
+ using rules that are right in isolation and surprising in bulk. The two things the algorithm cannot
275
+ know are:
276
+
277
+ 1. **Where the author meant a boundary.** Punctuation and digits are neutral; their direction is
278
+ inherited. That is why a full stop after an Arabic name lands on the wrong side, and why a phone
279
+ number inside Arabic gets chopped into pieces that reassemble in the wrong order.
280
+ 2. **Which script owns a stray character.** `(`, `"`, `«` and `-` are shared, and mirroring only
281
+ works when the pairing is inside the same directional run.
282
+
283
+ An isolate (`<bdi>`, `U+2066`–`U+2069`) tells the algorithm "this is a complete unit, resolve it
284
+ internally" — which fixes both, provided the unit boundaries are right. That is the whole job of
285
+ this package: finding the boundaries, then using the mechanism the standard already has.
286
+
287
+ The old answer was `RLE … PDF` and `LRE … PDF`. Those are *embeddings*, which leak the surrounding
288
+ direction into the run and are deprecated in CSS for exactly that reason. bidi-kit never emits them.
289
+
290
+ ## Security: the invisible characters
291
+
292
+ Overrides and isolates are the raw material of display spoofing: `U+202E` reverses everything after
293
+ it, so `invoice\u202Efdp.exe` is displayed as `invoiceexe.pdf`. The same trick hides text in a code
294
+ review, a pull request diff, a filename, or a form field.
295
+
296
+ ```ts
297
+ import { stripBidiControls, audit } from "bidi-kit";
298
+
299
+ const safe = stripBidiControls(untrusted); // before storing, logging or rendering
300
+ audit(untrusted); // reports it as an error instead
301
+ ```
302
+
303
+ `stripBidiControls` removes `U+061C`, `U+200E`, `U+200F`, `U+202A`–`U+202E` and `U+2066`–`U+2069`
304
+ and touches nothing else.
305
+
306
+ ## What it does not do
307
+
308
+ - **It does not implement the Unicode bidi algorithm.** Browsers do that correctly; a second
309
+ implementation would only disagree with them. bidi-kit works out boundaries and isolation.
310
+ - **It does not shape Arabic**, and it does not join letters. That is the renderer's job.
311
+ - **It does not ship fonts.** `fontFace()` writes the rule; you choose the bytes, so the licence
312
+ and the subsetting stay your decision.
313
+ - **It does not do line breaking.** A wrapped RTL paragraph is still the browser's business;
314
+ the `unicode-bidi: plaintext` in `ROOT_CSS` is the only help that is safe to give.
315
+
316
+ ## Demo
317
+
318
+ ```bash
319
+ npm run build
320
+ npm run demo
321
+ ```
322
+
323
+ The demo is served on <http://localhost:4173>. `npm run demo` builds first if `dist` is missing.
324
+
325
+ The demo page shows five side-by-side comparisons — naive `textContent` versus bidi-kit — for an
326
+ English sentence ending in Arabic, an Arabic paragraph quoting French, numbers and an email in
327
+ Arabic, a French paragraph with an Arabic name, and Arabic with full tashkeel. Below them is a
328
+ playground that runs the real library on your own text and prints the runs it found.
329
+
330
+ ## Tests
331
+
332
+ ```bash
333
+ npm ci
334
+ npm test
335
+ npm run pack:check
336
+ ```
337
+
338
+ `npm test` builds ESM and CJS, then runs `node --test`. `npm run pack:check` builds and then asserts
339
+ what `npm publish` would upload — both module formats, the declarations, the CLI, the README and the
340
+ licence in; the sources and dependencies out.
341
+
342
+ 48 tests covering run boundaries, punctuation at every kind of edge, phone numbers, URLs, emails,
343
+ hashtags, guillemets, combining marks, base direction, isolates, control-character stripping, the
344
+ HTML builders, the font and CSS tokens, the audit rules, ESM/CJS parity, the absence of `node:`
345
+ imports in the browser build, the single-file browser bundle (loaded as a browser would, and as a
346
+ CommonJS file, then compared against the module build), the demo server, and refusal to serve a path
347
+ outside the package. CI runs the same suite on Windows.
348
+
349
+ ## Windows
350
+
351
+ Everything here runs on Windows, and CI proves it on every push (the `bidi-kit on Windows` job):
352
+
353
+ - the build invokes `node_modules/typescript/bin/tsc` with the current Node binary, never the
354
+ `.bin/tsc` shim, which is a `.cmd` file on Windows and cannot be spawned directly;
355
+ - test discovery passes a glob to `node --test`, which expands it itself, so it does not depend on
356
+ the shell;
357
+ - `npm run pack:check` is a script, not a shell one-liner.
358
+
359
+ One thing to watch: `cmd.exe` has no inline comments. `npm publish # ready` sends `#` and `ready` to
360
+ npm as a tag, and npm will refuse. Copy the commands without the annotations.
361
+
362
+ ## Licence
363
+
364
+ MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,77 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * bidi-kit on the command line.
4
+ *
5
+ * The three things that are hard to see in a browser — which run is which
6
+ * direction, what an invisible control character is doing, and whether a
7
+ * template has a physical `text-align` — are all easy to print in a terminal.
8
+ */
9
+ import { readFile } from "node:fs/promises";
10
+ import { existsSync } from "node:fs";
11
+ import { dirname, join } from "node:path";
12
+ import { fileURLToPath } from "node:url";
13
+
14
+ const entry = join(dirname(fileURLToPath(import.meta.url)), "..", "dist", "esm", "index.js");
15
+ if (!existsSync(entry)) {
16
+ console.error("bidi-kit is not built: run `npm run build` first.");
17
+ process.exit(2);
18
+ }
19
+ const { audit, formatAudit, segments, isolateRunsText, resolveDirection } = await import(entry);
20
+
21
+ const USAGE = `bidi-kit — mixed-direction text, checked from the terminal
22
+
23
+ Usage
24
+ bidi-kit check <file...> report bidi hazards in HTML or CSS (exit 1 on errors)
25
+ bidi-kit runs <file> print each run with its direction
26
+ bidi-kit isolate <file> print the text with every run isolated
27
+ bidi-kit dir <file> print the resolved paragraph direction
28
+
29
+ Use - to read stdin. With no file, stdin is read.`;
30
+
31
+ const [, , command = "check", ...rest] = process.argv;
32
+
33
+ async function readInputs(files) {
34
+ if (files.length === 0 || files.includes("-")) {
35
+ const chunks = [];
36
+ for await (const chunk of process.stdin) chunks.push(chunk);
37
+ return [{ name: "<stdin>", text: Buffer.concat(chunks).toString("utf8") }];
38
+ }
39
+ return Promise.all(
40
+ files.map(async (file) => ({ name: file, text: await readFile(file, "utf8") })),
41
+ );
42
+ }
43
+
44
+ if (command === "--help" || command === "-h" || command === "help") {
45
+ console.log(USAGE);
46
+ process.exit(0);
47
+ }
48
+
49
+ if (!["check", "runs", "isolate", "dir"].includes(command)) {
50
+ console.error(`unknown command: ${command}\n\n${USAGE}`);
51
+ process.exit(2);
52
+ }
53
+
54
+ const inputs = await readInputs(rest);
55
+ let failed = false;
56
+
57
+ for (const { name, text } of inputs) {
58
+ if (command === "check") {
59
+ const issues = audit(text);
60
+ if (issues.length === 0) continue;
61
+ console.log(formatAudit(issues, name === "<stdin>" ? undefined : name));
62
+ if (issues.some((issue) => issue.severity === "error")) failed = true;
63
+ }
64
+ if (command === "runs") {
65
+ for (const run of segments(text)) {
66
+ console.log(`${run.dir.padEnd(4)} ${String(run.start).padStart(4)} ${JSON.stringify(run.text)}`);
67
+ }
68
+ }
69
+ if (command === "isolate") {
70
+ console.log(isolateRunsText(text));
71
+ }
72
+ if (command === "dir") {
73
+ console.log(resolveDirection(text));
74
+ }
75
+ }
76
+
77
+ process.exit(failed ? 1 : 0);