bidi-kit 0.1.0 → 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/README.md +80 -5
- package/dist/bidi-kit.global.js +606 -0
- package/package.json +10 -6
package/README.md
CHANGED
|
@@ -13,8 +13,9 @@ const html = paragraph(
|
|
|
13
13
|
// <p dir="ltr" lang="en">The greeting is <bdi dir="rtl" lang="ar">مرحبا</bdi>.</p>
|
|
14
14
|
```
|
|
15
15
|
|
|
16
|
-
Zero dependencies. No fonts bundled. TypeScript types, ESM
|
|
17
|
-
in Node, in an edge worker; nothing in `dist`
|
|
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:`.
|
|
18
19
|
|
|
19
20
|
## What it fixes
|
|
20
21
|
|
|
@@ -35,6 +36,79 @@ npm install bidi-kit
|
|
|
35
36
|
|
|
36
37
|
Node 18 or newer for the CLI; the library itself has no engine requirement beyond ES2022.
|
|
37
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
|
+
|
|
38
112
|
## The four things you will actually call
|
|
39
113
|
|
|
40
114
|
### 1. `paragraph(parts, options)` — a paragraph built out of mixed runs
|
|
@@ -265,11 +339,12 @@ npm run pack:check
|
|
|
265
339
|
what `npm publish` would upload — both module formats, the declarations, the CLI, the README and the
|
|
266
340
|
licence in; the sources and dependencies out.
|
|
267
341
|
|
|
268
|
-
|
|
342
|
+
48 tests covering run boundaries, punctuation at every kind of edge, phone numbers, URLs, emails,
|
|
269
343
|
hashtags, guillemets, combining marks, base direction, isolates, control-character stripping, the
|
|
270
344
|
HTML builders, the font and CSS tokens, the audit rules, ESM/CJS parity, the absence of `node:`
|
|
271
|
-
imports in the browser build,
|
|
272
|
-
|
|
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.
|
|
273
348
|
|
|
274
349
|
## Windows
|
|
275
350
|
|
|
@@ -0,0 +1,606 @@
|
|
|
1
|
+
/*! bidi-kit v0.1.1 — MIT — generated by scripts/build-global.mjs, do not edit.
|
|
2
|
+
* Arabic inside English, French inside Arabic. https://github.com/Nour-yahyaoui/ui-storm */
|
|
3
|
+
(function (root, factory) {
|
|
4
|
+
if (typeof module === "object" && module.exports) module.exports = factory();
|
|
5
|
+
else root.bidiKit = factory();
|
|
6
|
+
})(typeof globalThis !== "undefined" ? globalThis : this, function () {
|
|
7
|
+
"use strict";
|
|
8
|
+
|
|
9
|
+
// ---- segment.js --------------------------------------------------------
|
|
10
|
+
const RTL_RANGES = [
|
|
11
|
+
[0x0590, 0x05ff], // Hebrew
|
|
12
|
+
[0x0600, 0x06ff], // Arabic
|
|
13
|
+
[0x0700, 0x074f], // Syriac
|
|
14
|
+
[0x0750, 0x077f], // Arabic Supplement
|
|
15
|
+
[0x0780, 0x07bf], // Thaana
|
|
16
|
+
[0x07c0, 0x07ff], // NKo
|
|
17
|
+
[0x0800, 0x083f], // Samaritan
|
|
18
|
+
[0x0840, 0x085f], // Mandaic
|
|
19
|
+
[0x0860, 0x086f], // Syriac Supplement
|
|
20
|
+
[0x0870, 0x08ff], // Arabic Extended-B and -A
|
|
21
|
+
[0xfb1d, 0xfb4f], // Hebrew presentation forms
|
|
22
|
+
[0xfb50, 0xfdff], // Arabic presentation forms A
|
|
23
|
+
[0xfe70, 0xfeff], // Arabic presentation forms B
|
|
24
|
+
[0x1e800, 0x1e8df], // Mende Kikakui
|
|
25
|
+
[0x1e900, 0x1e95f], // Adlam
|
|
26
|
+
[0x1ee00, 0x1eeff], // Arabic mathematical alphabetic symbols
|
|
27
|
+
];
|
|
28
|
+
/** Arabic comma, semicolon, question mark, percent and the rest of the set. */
|
|
29
|
+
const ARABIC_PUNCTUATION = /[\u060C\u061B\u061F\u066A-\u066D\u06D4]/u;
|
|
30
|
+
const ARABIC_DIGITS = /[\u0660-\u0669\u06F0-\u06F9]/u;
|
|
31
|
+
const ANY_DIGIT = /\p{Nd}/u;
|
|
32
|
+
const MARK = /\p{M}/u;
|
|
33
|
+
const WHITESPACE_OR_FORMAT = /[\s\p{Z}\p{M}\p{Cf}]/u;
|
|
34
|
+
/** A neutral that joins a number when it sits between two digits: `1,000.5%`. */
|
|
35
|
+
const NUMERIC_JOINER = /[.,:+\-\u066B\u066C]/u;
|
|
36
|
+
/** A percent sign is part of the number it follows, not a sentence of its own. */
|
|
37
|
+
const NUMERIC_SUFFIX = /[%\u2030\u066A]/u;
|
|
38
|
+
/** True when the code point belongs to a script written right to left. */
|
|
39
|
+
function isRtlCodePoint(codePoint) {
|
|
40
|
+
for (const [start, end] of RTL_RANGES) {
|
|
41
|
+
if (codePoint >= start && codePoint <= end)
|
|
42
|
+
return true;
|
|
43
|
+
}
|
|
44
|
+
return false;
|
|
45
|
+
}
|
|
46
|
+
/** True when the string contains at least one right-to-left character. */
|
|
47
|
+
function hasRtl(text) {
|
|
48
|
+
for (const char of text) {
|
|
49
|
+
if (isRtlCodePoint(char.codePointAt(0) ?? 0))
|
|
50
|
+
return true;
|
|
51
|
+
}
|
|
52
|
+
return false;
|
|
53
|
+
}
|
|
54
|
+
/** True when the string contains Arabic letters, as opposed to just Arabic digits. */
|
|
55
|
+
function hasArabic(text) {
|
|
56
|
+
for (const char of text) {
|
|
57
|
+
const codePoint = char.codePointAt(0) ?? 0;
|
|
58
|
+
const inArabicScript = (codePoint >= 0x0600 && codePoint <= 0x06ff) ||
|
|
59
|
+
(codePoint >= 0x0750 && codePoint <= 0x077f) ||
|
|
60
|
+
(codePoint >= 0xfb50 && codePoint <= 0xfdff) ||
|
|
61
|
+
(codePoint >= 0xfe70 && codePoint <= 0xfeff);
|
|
62
|
+
if (inArabicScript && /\p{L}/u.test(char))
|
|
63
|
+
return true;
|
|
64
|
+
}
|
|
65
|
+
return false;
|
|
66
|
+
}
|
|
67
|
+
function baseClass(char) {
|
|
68
|
+
if (char === "\u200f")
|
|
69
|
+
return "rtl";
|
|
70
|
+
if (char === "\u200e")
|
|
71
|
+
return "ltr";
|
|
72
|
+
if (ARABIC_DIGITS.test(char))
|
|
73
|
+
return "rtlWeak";
|
|
74
|
+
if (ANY_DIGIT.test(char))
|
|
75
|
+
return "ltrWeak";
|
|
76
|
+
if (MARK.test(char))
|
|
77
|
+
return "join";
|
|
78
|
+
if (WHITESPACE_OR_FORMAT.test(char))
|
|
79
|
+
return "join";
|
|
80
|
+
if (ARABIC_PUNCTUATION.test(char))
|
|
81
|
+
return "rtlWeak";
|
|
82
|
+
if (isRtlCodePoint(char.codePointAt(0) ?? 0))
|
|
83
|
+
return "rtl";
|
|
84
|
+
// Letters are what is left: a symbol or a bracket is neutral, a letter is not.
|
|
85
|
+
return /\p{L}/u.test(char) ? "ltr" : "neutral";
|
|
86
|
+
}
|
|
87
|
+
function classAt(chars, index) {
|
|
88
|
+
const char = chars[index];
|
|
89
|
+
const cls = baseClass(char);
|
|
90
|
+
if (cls !== "neutral")
|
|
91
|
+
return cls;
|
|
92
|
+
const previous = chars[index - 1];
|
|
93
|
+
const next = chars[index + 1];
|
|
94
|
+
const numeric = (digit) => digit === undefined || !ANY_DIGIT.test(digit)
|
|
95
|
+
? null
|
|
96
|
+
: ARABIC_DIGITS.test(digit)
|
|
97
|
+
? "rtlWeak"
|
|
98
|
+
: "ltrWeak";
|
|
99
|
+
const beforeIsDigit = numeric(previous);
|
|
100
|
+
if (beforeIsDigit === null)
|
|
101
|
+
return cls;
|
|
102
|
+
if (NUMERIC_SUFFIX.test(char))
|
|
103
|
+
return beforeIsDigit;
|
|
104
|
+
if (!NUMERIC_JOINER.test(char))
|
|
105
|
+
return cls;
|
|
106
|
+
return numeric(next) === null ? cls : beforeIsDigit;
|
|
107
|
+
}
|
|
108
|
+
/**
|
|
109
|
+
* Splits text into runs that each have one direction.
|
|
110
|
+
*
|
|
111
|
+
* The browser implements the Unicode bidi algorithm correctly; what it cannot
|
|
112
|
+
* know is where the author meant a boundary to be. This answers that question,
|
|
113
|
+
* and nothing else:
|
|
114
|
+
*
|
|
115
|
+
* - a strong character starts a run and decides its direction;
|
|
116
|
+
* - Arabic digits and Arabic punctuation stay inside an Arabic run, so `مرحبا،`
|
|
117
|
+
* does not break in half;
|
|
118
|
+
* - Latin digits read left to right even inside Arabic, so `123.45%` stays one
|
|
119
|
+
* piece;
|
|
120
|
+
* - brackets, quotes and symbols are neutral: they take the direction of the
|
|
121
|
+
* runs on both sides when those agree, and otherwise the base direction — so
|
|
122
|
+
* an English full stop after an Arabic name ends the English sentence instead
|
|
123
|
+
* of moving to the wrong side of the name.
|
|
124
|
+
*
|
|
125
|
+
* Pass `base` when you know the paragraph direction — say, because the column
|
|
126
|
+
* is Arabic and this is one row of it. By default the base is the direction of
|
|
127
|
+
* the first strong character, which is what the browser would assume anyway.
|
|
128
|
+
*/
|
|
129
|
+
function segments(text, base) {
|
|
130
|
+
const fallback = base ?? (detectDirection(text) === "rtl" ? "rtl" : "ltr");
|
|
131
|
+
const chars = Array.from(text);
|
|
132
|
+
const drafts = [];
|
|
133
|
+
let current = null;
|
|
134
|
+
let offset = 0;
|
|
135
|
+
for (let index = 0; index < chars.length; index += 1) {
|
|
136
|
+
const char = chars[index];
|
|
137
|
+
const start = offset;
|
|
138
|
+
const end = offset + char.length;
|
|
139
|
+
offset = end;
|
|
140
|
+
const cls = classAt(chars, index);
|
|
141
|
+
const dir = cls === "rtl" || cls === "rtlWeak" ? "rtl" : cls === "ltr" || cls === "ltrWeak" ? "ltr" : cls === "join" ? (current ? current.dir : "neutral") : "neutral";
|
|
142
|
+
if (current && current.dir === dir) {
|
|
143
|
+
current.text += char;
|
|
144
|
+
current.end = end;
|
|
145
|
+
continue;
|
|
146
|
+
}
|
|
147
|
+
if (current)
|
|
148
|
+
drafts.push(current);
|
|
149
|
+
current = { text: char, dir, start, end };
|
|
150
|
+
}
|
|
151
|
+
if (current)
|
|
152
|
+
drafts.push(current);
|
|
153
|
+
const resolved = resolveNeutrals(drafts, fallback);
|
|
154
|
+
return merge(resolved);
|
|
155
|
+
}
|
|
156
|
+
/** N1/N2 in miniature: a neutral takes the direction of agreeing neighbours, else the base. */
|
|
157
|
+
function resolveNeutrals(drafts, base) {
|
|
158
|
+
return drafts.map((draft, index) => {
|
|
159
|
+
if (draft.dir !== "neutral")
|
|
160
|
+
return draft;
|
|
161
|
+
const before = previousDirection(drafts, index);
|
|
162
|
+
const after = nextDirection(drafts, index);
|
|
163
|
+
const fallback = before !== "neutral" && before === after ? before : base;
|
|
164
|
+
return { ...draft, dir: fallback };
|
|
165
|
+
});
|
|
166
|
+
}
|
|
167
|
+
function previousDirection(drafts, index) {
|
|
168
|
+
for (let cursor = index - 1; cursor >= 0; cursor -= 1) {
|
|
169
|
+
const draft = drafts[cursor];
|
|
170
|
+
if (draft && draft.dir !== "neutral")
|
|
171
|
+
return draft.dir;
|
|
172
|
+
}
|
|
173
|
+
return "neutral";
|
|
174
|
+
}
|
|
175
|
+
function nextDirection(drafts, index) {
|
|
176
|
+
for (let cursor = index + 1; cursor < drafts.length; cursor += 1) {
|
|
177
|
+
const draft = drafts[cursor];
|
|
178
|
+
if (draft && draft.dir !== "neutral")
|
|
179
|
+
return draft.dir;
|
|
180
|
+
}
|
|
181
|
+
return "neutral";
|
|
182
|
+
}
|
|
183
|
+
function merge(drafts) {
|
|
184
|
+
const merged = [];
|
|
185
|
+
for (const draft of drafts) {
|
|
186
|
+
const last = merged[merged.length - 1];
|
|
187
|
+
if (last && last.dir === draft.dir) {
|
|
188
|
+
last.text += draft.text;
|
|
189
|
+
last.end = draft.end;
|
|
190
|
+
continue;
|
|
191
|
+
}
|
|
192
|
+
merged.push({ text: draft.text, dir: draft.dir, start: draft.start, end: draft.end });
|
|
193
|
+
}
|
|
194
|
+
return merged;
|
|
195
|
+
}
|
|
196
|
+
/**
|
|
197
|
+
* The direction of the first strong character, which is what `dir="auto"`
|
|
198
|
+
* resolves to. `neutral` means the text has no strong character at all.
|
|
199
|
+
*/
|
|
200
|
+
function detectDirection(text) {
|
|
201
|
+
const chars = Array.from(text);
|
|
202
|
+
for (let index = 0; index < chars.length; index += 1) {
|
|
203
|
+
const cls = baseClass(chars[index]);
|
|
204
|
+
if (cls === "rtl" || cls === "rtlWeak")
|
|
205
|
+
return "rtl";
|
|
206
|
+
if (cls === "ltr" || cls === "ltrWeak")
|
|
207
|
+
return "ltr";
|
|
208
|
+
}
|
|
209
|
+
return "neutral";
|
|
210
|
+
}
|
|
211
|
+
/**
|
|
212
|
+
* Like {@link detectDirection}, but resolves `neutral` to `ltr` — the same
|
|
213
|
+
* fallback HTML uses for `dir="auto"`, so this is always safe to write to an
|
|
214
|
+
* attribute.
|
|
215
|
+
*/
|
|
216
|
+
function resolveDirection(text) {
|
|
217
|
+
return detectDirection(text) === "rtl" ? "rtl" : "ltr";
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
// ---- isolate.js --------------------------------------------------------
|
|
221
|
+
/** Left-to-right isolate. */
|
|
222
|
+
const LRI = "\u2066";
|
|
223
|
+
/** Right-to-left isolate. */
|
|
224
|
+
const RLI = "\u2067";
|
|
225
|
+
/** First-strong isolate: the reader's bidi algorithm picks the direction. */
|
|
226
|
+
const FSI = "\u2068";
|
|
227
|
+
/** Pop directional isolate. */
|
|
228
|
+
const PDI = "\u2069";
|
|
229
|
+
/** Every character that can change the visual order without being visible. */
|
|
230
|
+
const BIDI_CONTROLS = /[\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]/g;
|
|
231
|
+
/**
|
|
232
|
+
* Wraps text in an isolate, for plain-text contexts where an element is not an
|
|
233
|
+
* option: an `aria-label`, a canvas, a terminal, a spreadsheet cell, a JSON
|
|
234
|
+
* field that something else will render.
|
|
235
|
+
*
|
|
236
|
+
* In HTML, prefer {@link bdi} — an element is inspectable, stylable and cannot
|
|
237
|
+
* leak a stray `PDI` when a string is concatenated badly.
|
|
238
|
+
*/
|
|
239
|
+
function isolate(text, options = {}) {
|
|
240
|
+
if (text === "")
|
|
241
|
+
return "";
|
|
242
|
+
const dir = options.dir ?? "auto";
|
|
243
|
+
if (dir === "rtl")
|
|
244
|
+
return RLI + text + PDI;
|
|
245
|
+
if (dir === "ltr")
|
|
246
|
+
return LRI + text + PDI;
|
|
247
|
+
return FSI + text + PDI;
|
|
248
|
+
}
|
|
249
|
+
/** True when the string carries invisible bidi control characters. */
|
|
250
|
+
function hasBidiControls(text) {
|
|
251
|
+
return /[\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]/u.test(text);
|
|
252
|
+
}
|
|
253
|
+
/**
|
|
254
|
+
* Removes every invisible bidi control character.
|
|
255
|
+
*
|
|
256
|
+
* Use this on anything a stranger wrote. Overrides and isolates are the raw
|
|
257
|
+
* material of display-spoofing bugs — the class of attack that turned source
|
|
258
|
+
* code review into a guessing game — and a text field that passes them through
|
|
259
|
+
* to a terminal, a diff or a filename is a bug, not a feature.
|
|
260
|
+
*/
|
|
261
|
+
function stripBidiControls(text) {
|
|
262
|
+
return text.replace(BIDI_CONTROLS, "");
|
|
263
|
+
}
|
|
264
|
+
/**
|
|
265
|
+
* Rewrites text so each run is explicitly isolated, for plain-text output.
|
|
266
|
+
*
|
|
267
|
+
* Unlike {@link isolate}, which wraps the whole string, this keeps an English
|
|
268
|
+
* sentence readable by a terminal that only understands the bidi algorithm: the
|
|
269
|
+
* Arabic run gets an RLI/PDI pair and everything else is left alone.
|
|
270
|
+
*/
|
|
271
|
+
function isolateRunsText(text) {
|
|
272
|
+
return segments(text)
|
|
273
|
+
.map((segment) => {
|
|
274
|
+
if (segment.dir === "rtl")
|
|
275
|
+
return RLI + segment.text + PDI;
|
|
276
|
+
if (segment.dir === "ltr")
|
|
277
|
+
return LRI + segment.text + PDI;
|
|
278
|
+
return segment.text;
|
|
279
|
+
})
|
|
280
|
+
.join("");
|
|
281
|
+
}
|
|
282
|
+
/** The invisible characters, exported so a UI can explain what it stripped. */
|
|
283
|
+
const BIDI_CONTROL_CHARACTERS = [
|
|
284
|
+
"\u061C",
|
|
285
|
+
"\u200E",
|
|
286
|
+
"\u200F",
|
|
287
|
+
"\u202A",
|
|
288
|
+
"\u202B",
|
|
289
|
+
"\u202C",
|
|
290
|
+
"\u202D",
|
|
291
|
+
"\u202E",
|
|
292
|
+
"\u2066",
|
|
293
|
+
"\u2067",
|
|
294
|
+
"\u2068",
|
|
295
|
+
"\u2069",
|
|
296
|
+
];
|
|
297
|
+
|
|
298
|
+
// ---- html.js -----------------------------------------------------------
|
|
299
|
+
const ESCAPES = {
|
|
300
|
+
"&": "&",
|
|
301
|
+
"<": "<",
|
|
302
|
+
">": ">",
|
|
303
|
+
'"': """,
|
|
304
|
+
"'": "'",
|
|
305
|
+
};
|
|
306
|
+
/** Escapes text for use as element content or in a quoted attribute value. */
|
|
307
|
+
function escapeHtml(text) {
|
|
308
|
+
return text.replace(/[&<>"']/g, (char) => ESCAPES[char] ?? char);
|
|
309
|
+
}
|
|
310
|
+
function attribute(name, value) {
|
|
311
|
+
return value === undefined || value === "" ? "" : ` ${name}="${escapeHtml(value)}"`;
|
|
312
|
+
}
|
|
313
|
+
function styleValue(font) {
|
|
314
|
+
return font ? `font-family: ${font}` : undefined;
|
|
315
|
+
}
|
|
316
|
+
/**
|
|
317
|
+
* A `<bdi>` element wrapping `text`.
|
|
318
|
+
*
|
|
319
|
+
* `<bdi>` is the one HTML element whose whole job is this problem: it isolates
|
|
320
|
+
* its content from the surrounding paragraph, so neither the reader's text nor
|
|
321
|
+
* the browser's bidi algorithm can drag a neighbouring word into the wrong
|
|
322
|
+
* place. Reach for it before reaching for a mark you cannot see.
|
|
323
|
+
*/
|
|
324
|
+
function bdi(text, options = {}) {
|
|
325
|
+
return inline(text, { ...options, element: options.element ?? "bdi" });
|
|
326
|
+
}
|
|
327
|
+
/** A `<span dir>` that isolates by style instead of by element. */
|
|
328
|
+
function inline(text, options = {}) {
|
|
329
|
+
const element = options.element ?? "span";
|
|
330
|
+
const dir = options.dir ?? "auto";
|
|
331
|
+
const attributes = [
|
|
332
|
+
dir === "auto" && element === "bdi" ? "" : attribute("dir", dir),
|
|
333
|
+
attribute("lang", options.lang),
|
|
334
|
+
attribute("class", options.class),
|
|
335
|
+
attribute("style", styleValue(options.font)),
|
|
336
|
+
].join("");
|
|
337
|
+
return `<${element}${attributes}>${escapeHtml(text)}</${element}>`;
|
|
338
|
+
}
|
|
339
|
+
/**
|
|
340
|
+
* Builds one paragraph out of mixed parts.
|
|
341
|
+
*
|
|
342
|
+
* Named parts get an explicit direction and, if you pass one, a font: that is
|
|
343
|
+
* how an Arabic sentence in a French paragraph ends up in a face that actually
|
|
344
|
+
* has the glyphs, instead of a fallback the operating system picked without
|
|
345
|
+
* asking. Strings are treated as plain text and escaped unless `html` is set.
|
|
346
|
+
*/
|
|
347
|
+
function paragraph(parts, options = {}) {
|
|
348
|
+
const plain = parts
|
|
349
|
+
.map((part) => {
|
|
350
|
+
const text = typeof part === "string" ? part : part.text;
|
|
351
|
+
// The direction of a paragraph comes from its words, not from its tags.
|
|
352
|
+
return options.html ? text.replace(/<[^>]*>/g, " ") : text;
|
|
353
|
+
})
|
|
354
|
+
.join("");
|
|
355
|
+
const dir = options.dir === undefined || options.dir === "auto" ? resolveDirection(plain) : options.dir;
|
|
356
|
+
const body = parts
|
|
357
|
+
.map((part) => {
|
|
358
|
+
if (typeof part === "string")
|
|
359
|
+
return options.html ? part : escapeHtml(part);
|
|
360
|
+
const attributes = [
|
|
361
|
+
attribute("dir", part.dir ?? "auto"),
|
|
362
|
+
attribute("lang", part.lang),
|
|
363
|
+
attribute("style", styleValue(part.font)),
|
|
364
|
+
].join("");
|
|
365
|
+
const inner = options.html ? part.text : escapeHtml(part.text);
|
|
366
|
+
return `<bdi${attributes}>${inner}</bdi>`;
|
|
367
|
+
})
|
|
368
|
+
.join("");
|
|
369
|
+
const attributes = [
|
|
370
|
+
attribute("dir", dir),
|
|
371
|
+
attribute("lang", options.lang),
|
|
372
|
+
attribute("class", options.class),
|
|
373
|
+
].join("");
|
|
374
|
+
return `<p${attributes}>${body}</p>`;
|
|
375
|
+
}
|
|
376
|
+
/**
|
|
377
|
+
* Sets element text and direction in one call. The container decides the
|
|
378
|
+
* paragraph's base direction; each run inside it is left to the bidi
|
|
379
|
+
* algorithm, which is what makes an English sentence with an Arabic name look
|
|
380
|
+
* like an English sentence.
|
|
381
|
+
*/
|
|
382
|
+
function apply(element, text, options = {}) {
|
|
383
|
+
element.textContent = text;
|
|
384
|
+
element.setAttribute?.("dir", options.dir ?? resolveDirection(text));
|
|
385
|
+
return element;
|
|
386
|
+
}
|
|
387
|
+
|
|
388
|
+
// ---- fonts.js ----------------------------------------------------------
|
|
389
|
+
/**
|
|
390
|
+
* Font stacks per script.
|
|
391
|
+
*
|
|
392
|
+
* Two failures produce the "broken Arabic" look people blame on bidi:
|
|
393
|
+
*
|
|
394
|
+
* 1. the Latin face has no Arabic glyphs, so the browser falls back per glyph —
|
|
395
|
+
* the word changes shape halfway through and the diacritics sit too low;
|
|
396
|
+
* 2. the Arabic face is a *naskh* text face rendered at a Latin line-height,
|
|
397
|
+
* and the kasra, the hamza below and the tail of a final yeh are clipped.
|
|
398
|
+
*
|
|
399
|
+
* The stacks below put a known-good Arabic face first, keep a Latin face that
|
|
400
|
+
* does not interfere, and end in `sans-serif` rather than in nothing.
|
|
401
|
+
*/
|
|
402
|
+
const FONT_STACKS = {
|
|
403
|
+
arabic: [
|
|
404
|
+
'"Noto Naskh Arabic"',
|
|
405
|
+
'"Noto Sans Arabic"',
|
|
406
|
+
'"Amiri"',
|
|
407
|
+
'"Scheherazade New"',
|
|
408
|
+
'"Geeza Pro"',
|
|
409
|
+
'"Segoe UI"',
|
|
410
|
+
'"Noto Sans"',
|
|
411
|
+
"sans-serif",
|
|
412
|
+
].join(", "),
|
|
413
|
+
hebrew: ['"Noto Sans Hebrew"', '"Arial Hebrew"', '"Gisha"', '"David CLM"', "sans-serif"].join(", "),
|
|
414
|
+
latin: ['"Noto Sans"', "system-ui", "-apple-system", '"Segoe UI"', "Roboto", "sans-serif"].join(", "),
|
|
415
|
+
};
|
|
416
|
+
/** The stack to use for a locale tag; anything not RTL gets the Latin stack. */
|
|
417
|
+
function fontStack(locale) {
|
|
418
|
+
if (!locale)
|
|
419
|
+
return FONT_STACKS.latin;
|
|
420
|
+
const language = locale.toLowerCase().split(/[-_]/)[0] ?? "";
|
|
421
|
+
if (language === "ar" || language === "fa" || language === "ur" || language === "ps") {
|
|
422
|
+
return FONT_STACKS.arabic;
|
|
423
|
+
}
|
|
424
|
+
if (language === "he" || language === "yi")
|
|
425
|
+
return FONT_STACKS.hebrew;
|
|
426
|
+
return FONT_STACKS.latin;
|
|
427
|
+
}
|
|
428
|
+
/** The `font-feature-settings` that keep Arabic words from looking two-tone. */
|
|
429
|
+
const ARABIC_FEATURES = '"kern" 1, "liga" 1, "calt" 1, "rlig" 1, "init" 1, "medi" 1, "fina" 1';
|
|
430
|
+
/**
|
|
431
|
+
* The `unicode-range` for a script, so a downloaded face is only fetched for
|
|
432
|
+
* the characters it actually covers. Without it, a page with one Arabic
|
|
433
|
+
* headline downloads the Arabic font for every reader.
|
|
434
|
+
*/
|
|
435
|
+
const UNICODE_RANGES = {
|
|
436
|
+
arabic: "U+0600-06FF, U+0750-077F, U+0870-088E, U+08A0-08FF, U+FB50-FDFF, U+FE70-FEFF, U+1EE00-1EEFF",
|
|
437
|
+
hebrew: "U+0590-05FF, U+FB1D-FB4F",
|
|
438
|
+
latin: "U+0000-00FF, U+0131, U+0152-0153, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193",
|
|
439
|
+
};
|
|
440
|
+
/**
|
|
441
|
+
* Builds an `@font-face` rule.
|
|
442
|
+
*
|
|
443
|
+
* It is deliberately a string and not a file: the package ships no fonts, so a
|
|
444
|
+
* consumer decides where the bytes come from — a local install, a CDN, or a
|
|
445
|
+
* self-hosted file — and this only removes the chance of getting the
|
|
446
|
+
* `unicode-range` and the metrics wrong while doing it.
|
|
447
|
+
*/
|
|
448
|
+
function fontFace(options) {
|
|
449
|
+
const script = options.script ?? "arabic";
|
|
450
|
+
const sources = Array.isArray(options.src) ? options.src : [options.src];
|
|
451
|
+
const lines = [
|
|
452
|
+
` font-family: "${options.family}";`,
|
|
453
|
+
` src: ${sources.join(", ")};`,
|
|
454
|
+
` font-weight: ${options.weight ?? "400"};`,
|
|
455
|
+
` font-style: ${options.style ?? "normal"};`,
|
|
456
|
+
` font-display: ${options.display ?? "swap"};`,
|
|
457
|
+
` unicode-range: ${options.unicodeRange ?? UNICODE_RANGES[script]};`,
|
|
458
|
+
];
|
|
459
|
+
if (options.sizeAdjust)
|
|
460
|
+
lines.push(` size-adjust: ${options.sizeAdjust};`);
|
|
461
|
+
return `@font-face {\n${lines.join("\n")}\n}`;
|
|
462
|
+
}
|
|
463
|
+
/** A `font-family` declaration that pairs an Arabic face with a Latin one. */
|
|
464
|
+
function fontFamilyRule(selector, script = "arabic") {
|
|
465
|
+
return `${selector} {\n font-family: ${FONT_STACKS[script]};\n}`;
|
|
466
|
+
}
|
|
467
|
+
|
|
468
|
+
// ---- css.js ------------------------------------------------------------
|
|
469
|
+
/**
|
|
470
|
+
* The rules that keep mixed-script text from breaking, as a string you can
|
|
471
|
+
* drop in a `<style>` tag or a stylesheet.
|
|
472
|
+
*
|
|
473
|
+
* Every line here fixes a specific, reproducible glitch:
|
|
474
|
+
*
|
|
475
|
+
* - `unicode-bidi: isolate` stops an inline element's direction from leaking
|
|
476
|
+
* into its neighbours;
|
|
477
|
+
* - `text-align: start` makes alignment follow the text instead of the page —
|
|
478
|
+
* `left` is a bug the moment one paragraph is Arabic;
|
|
479
|
+
* - the line-height on Arabic blocks is not aesthetics: naskh faces put marks
|
|
480
|
+
* above and below the baseline, and a 1.2 line-height cuts them off;
|
|
481
|
+
* - `white-space: normal` (and no `text-overflow: ellipsis` on RTL) keeps a
|
|
482
|
+
* wrapped Arabic sentence from being reordered across lines.
|
|
483
|
+
*/
|
|
484
|
+
const CSS = `:where([dir], [lang]):not(html, body) { unicode-bidi: isolate; }
|
|
485
|
+
[dir="rtl"] { text-align: right; direction: rtl; }
|
|
486
|
+
[dir="ltr"] { text-align: left; direction: ltr; }
|
|
487
|
+
[dir="auto"] { text-align: start; }
|
|
488
|
+
:where([lang^="ar"], [lang^="fa"], [lang^="ur"], [lang^="ps"], .script-arabic) {
|
|
489
|
+
font-family: ${FONT_STACKS.arabic};
|
|
490
|
+
font-feature-settings: ${ARABIC_FEATURES};
|
|
491
|
+
line-height: 1.9;
|
|
492
|
+
}
|
|
493
|
+
:where([lang^="he"], [lang^="yi"], .script-hebrew) {
|
|
494
|
+
font-family: ${FONT_STACKS.hebrew};
|
|
495
|
+
line-height: 1.7;
|
|
496
|
+
}
|
|
497
|
+
:where(bdi, [dir="auto"]) { unicode-bidi: isolate; }
|
|
498
|
+
`;
|
|
499
|
+
/**
|
|
500
|
+
* Rules to add once, on `html` or `body`, when a page mixes scripts and wants
|
|
501
|
+
* the browser to stop guessing.
|
|
502
|
+
*/
|
|
503
|
+
const ROOT_CSS = `html { unicode-bidi: plaintext; }
|
|
504
|
+
body { text-align: start; }
|
|
505
|
+
:lang(ar) { font-variant-numeric: normal; }
|
|
506
|
+
`;
|
|
507
|
+
/** A single declaration block for one element, for inline-style applications. */
|
|
508
|
+
function inlineStyle(options = {}) {
|
|
509
|
+
const declarations = [];
|
|
510
|
+
if (options.dir) {
|
|
511
|
+
declarations.push(`direction: ${options.dir === "auto" ? "inherit" : options.dir}`);
|
|
512
|
+
declarations.push("unicode-bidi: isolate");
|
|
513
|
+
}
|
|
514
|
+
if (options.script) {
|
|
515
|
+
declarations.push(`font-family: ${FONT_STACKS[options.script]}`);
|
|
516
|
+
if (options.script === "arabic") {
|
|
517
|
+
declarations.push(`font-feature-settings: ${ARABIC_FEATURES}`);
|
|
518
|
+
declarations.push("line-height: 1.9");
|
|
519
|
+
}
|
|
520
|
+
}
|
|
521
|
+
return declarations.join("; ");
|
|
522
|
+
}
|
|
523
|
+
|
|
524
|
+
// ---- audit.js ----------------------------------------------------------
|
|
525
|
+
const RULES = [
|
|
526
|
+
{
|
|
527
|
+
id: "bidi-control-character",
|
|
528
|
+
severity: "error",
|
|
529
|
+
pattern: /[\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069]/gu,
|
|
530
|
+
message: "Invisible bidi control character. It reorders text without showing why; strip it from anything a stranger wrote.",
|
|
531
|
+
},
|
|
532
|
+
{
|
|
533
|
+
id: "inline-direction-without-isolation",
|
|
534
|
+
severity: "warning",
|
|
535
|
+
pattern: /<span[^>]*\bdir=/giu,
|
|
536
|
+
message: "<span dir=...> does not isolate. Use <bdi>, or add unicode-bidi: isolate to the rule.",
|
|
537
|
+
},
|
|
538
|
+
{
|
|
539
|
+
id: "physical-text-align",
|
|
540
|
+
severity: "warning",
|
|
541
|
+
pattern: /text-align\s*:\s*(left|right)\b/giu,
|
|
542
|
+
message: "text-align: left/right is physical. Use start/end so Arabic paragraphs align correctly.",
|
|
543
|
+
},
|
|
544
|
+
{
|
|
545
|
+
id: "physical-css-property",
|
|
546
|
+
severity: "warning",
|
|
547
|
+
pattern: /\b(padding|margin|border)-(left|right)\b/giu,
|
|
548
|
+
message: "Logical properties (padding-inline-start, margin-inline-end, border-inline-start) mirror with direction.",
|
|
549
|
+
},
|
|
550
|
+
{
|
|
551
|
+
id: "document-without-lang",
|
|
552
|
+
severity: "warning",
|
|
553
|
+
pattern: /<html(?![^>]*\blang=)[^>]*>/giu,
|
|
554
|
+
message: "<html> has no lang. Screen readers pick a voice from it, and Arabic is unreadable in an English voice.",
|
|
555
|
+
},
|
|
556
|
+
];
|
|
557
|
+
/**
|
|
558
|
+
* Reports the markers that predict a bidi bug, for a string of HTML or CSS.
|
|
559
|
+
*
|
|
560
|
+
* This is a lint, not a proof: it finds patterns that are almost always wrong
|
|
561
|
+
* and never claims a document that passes is correct. It is meant for a CI step
|
|
562
|
+
* on content, and for the moment a translator asks why their paragraph is
|
|
563
|
+
* backwards.
|
|
564
|
+
*/
|
|
565
|
+
function audit(source) {
|
|
566
|
+
const issues = [];
|
|
567
|
+
for (const rule of RULES) {
|
|
568
|
+
rule.pattern.lastIndex = 0;
|
|
569
|
+
for (const match of source.matchAll(rule.pattern)) {
|
|
570
|
+
const index = match.index ?? 0;
|
|
571
|
+
issues.push({
|
|
572
|
+
rule: rule.id,
|
|
573
|
+
severity: rule.severity,
|
|
574
|
+
message: rule.message,
|
|
575
|
+
index,
|
|
576
|
+
snippet: source.slice(index, index + 40),
|
|
577
|
+
});
|
|
578
|
+
}
|
|
579
|
+
}
|
|
580
|
+
return issues.sort((a, b) => a.index - b.index);
|
|
581
|
+
}
|
|
582
|
+
/** Formats {@link audit} output as one line per finding, for a terminal. */
|
|
583
|
+
function formatAudit(issues, file) {
|
|
584
|
+
if (issues.length === 0)
|
|
585
|
+
return "no bidi issues found";
|
|
586
|
+
return issues
|
|
587
|
+
.map((issue) => {
|
|
588
|
+
const where = file ? `${file}: ` : "";
|
|
589
|
+
return `${where}[${issue.severity}] ${issue.rule} at ${issue.index}: ${issue.message}`;
|
|
590
|
+
})
|
|
591
|
+
.join("\n");
|
|
592
|
+
}
|
|
593
|
+
|
|
594
|
+
// ---- index.js ----------------------------------------------------------
|
|
595
|
+
/**
|
|
596
|
+
* bidi-kit — mixed-direction text that behaves.
|
|
597
|
+
*
|
|
598
|
+
* The browser already implements the Unicode bidi algorithm correctly. What it
|
|
599
|
+
* cannot know is where the author meant a boundary to be, which face has the
|
|
600
|
+
* glyphs, or that a paragraph is Arabic until it has read the first character.
|
|
601
|
+
* This package supplies those answers, and nothing else: no runtime
|
|
602
|
+
* dependencies, no fonts, no framework.
|
|
603
|
+
*/
|
|
604
|
+
|
|
605
|
+
return { segments, detectDirection, resolveDirection, hasRtl, hasArabic, isRtlCodePoint, isolate, isolateRunsText, hasBidiControls, stripBidiControls, BIDI_CONTROL_CHARACTERS, LRI, RLI, FSI, PDI, bdi, inline, paragraph, escapeHtml, apply, FONT_STACKS, ARABIC_FEATURES, UNICODE_RANGES, fontStack, fontFace, fontFamilyRule, CSS, ROOT_CSS, inlineStyle, audit, formatAudit };
|
|
606
|
+
});
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "bidi-kit",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "Right-to-left text that behaves: Arabic inside English, French inside Arabic, no bidi glitches.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"bidi",
|
|
@@ -17,7 +17,7 @@
|
|
|
17
17
|
"author": "Nour Yahyaoui",
|
|
18
18
|
"repository": {
|
|
19
19
|
"type": "git",
|
|
20
|
-
"url": "https://github.com/Nour-yahyaoui/ui-storm.git",
|
|
20
|
+
"url": "git+https://github.com/Nour-yahyaoui/ui-storm.git",
|
|
21
21
|
"directory": "packages/bidi-kit"
|
|
22
22
|
},
|
|
23
23
|
"type": "module",
|
|
@@ -34,7 +34,7 @@
|
|
|
34
34
|
"./package.json": "./package.json"
|
|
35
35
|
},
|
|
36
36
|
"bin": {
|
|
37
|
-
"bidi-kit": "
|
|
37
|
+
"bidi-kit": "bin/bidi-kit.mjs"
|
|
38
38
|
},
|
|
39
39
|
"files": [
|
|
40
40
|
"dist",
|
|
@@ -50,11 +50,15 @@
|
|
|
50
50
|
"typecheck": "tsc -p tsconfig.esm.json --noEmit",
|
|
51
51
|
"test": "npm run build && node --test tests/*.test.mjs",
|
|
52
52
|
"demo": "node scripts/serve.mjs",
|
|
53
|
-
"prepublishOnly": "npm test",
|
|
53
|
+
"prepublishOnly": "npm test && node scripts/sync-static.mjs --check",
|
|
54
54
|
"test:only": "node --test tests/*.test.mjs",
|
|
55
|
-
"pack:check": "npm run build && node scripts/check-tarball.mjs"
|
|
55
|
+
"pack:check": "npm run build && node scripts/check-tarball.mjs",
|
|
56
|
+
"static:sync": "npm run build && node scripts/sync-static.mjs",
|
|
57
|
+
"static:check": "npm run build && node scripts/sync-static.mjs --check"
|
|
56
58
|
},
|
|
57
59
|
"devDependencies": {
|
|
58
60
|
"typescript": "^5.9.3"
|
|
59
|
-
}
|
|
61
|
+
},
|
|
62
|
+
"unpkg": "./dist/bidi-kit.global.js",
|
|
63
|
+
"jsdelivr": "./dist/bidi-kit.global.js"
|
|
60
64
|
}
|