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 +21 -0
- package/README.md +364 -3
- package/bin/bidi-kit.mjs +77 -0
- package/dist/bidi-kit.global.js +606 -0
- package/dist/cjs/audit.js +72 -0
- package/dist/cjs/css.js +59 -0
- package/dist/cjs/fonts.js +84 -0
- package/dist/cjs/html.js +96 -0
- package/dist/cjs/index.js +49 -0
- package/dist/cjs/isolate.js +84 -0
- package/dist/cjs/package.json +3 -0
- package/dist/cjs/segment.js +217 -0
- package/dist/cjs/types.js +2 -0
- package/dist/esm/audit.d.ts +12 -0
- package/dist/esm/audit.js +68 -0
- package/dist/esm/css.d.ts +26 -0
- package/dist/esm/css.js +55 -0
- package/dist/esm/fonts.d.ts +36 -0
- package/dist/esm/fonts.js +78 -0
- package/dist/esm/html.d.ts +32 -0
- package/dist/esm/html.js +89 -0
- package/dist/esm/index.d.ts +16 -0
- package/dist/esm/index.js +15 -0
- package/dist/esm/isolate.d.ts +43 -0
- package/dist/esm/isolate.js +77 -0
- package/dist/esm/segment.d.ts +40 -0
- package/dist/esm/segment.js +209 -0
- package/dist/esm/types.d.ts +92 -0
- package/dist/esm/types.js +1 -0
- package/package.json +64 -6
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
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
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).
|
package/bin/bidi-kit.mjs
ADDED
|
@@ -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);
|