what-text 0.11.0 → 0.11.2
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 +87 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# what-text
|
|
2
|
+
|
|
3
|
+
Optional text engine for [What Framework](https://whatfw.com), powered by [@chenglou/pretext](https://www.npmjs.com/package/@chenglou/pretext). Provides text measurement/layout utilities and alpha text-rendering components (`TextFlow`, `TextCanvas`, `TextSVG`).
|
|
4
|
+
|
|
5
|
+
This package is **optional and off by default** — nothing here runs unless you opt in, and `@chenglou/pretext` is an optional peer dependency that is lazy-loaded on first use.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install what-text @chenglou/pretext
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
`@chenglou/pretext` is an optional peer: APIs that need it (`measureText`, the components, `configureText({ measure: true })`) lazy-load it via dynamic `import()` and throw a clear "install it with: npm install @chenglou/pretext" error if it's missing.
|
|
14
|
+
|
|
15
|
+
## Text measurement
|
|
16
|
+
|
|
17
|
+
```js
|
|
18
|
+
import { measureText, configureText } from 'what-text';
|
|
19
|
+
|
|
20
|
+
// One-off measurement: layout a string at a given font/width/line-height.
|
|
21
|
+
// Waits for document.fonts.ready, lazy-loads Pretext, caches prepared text (LRU).
|
|
22
|
+
const layout = await measureText(
|
|
23
|
+
'The quick brown fox jumps over the lazy dog',
|
|
24
|
+
'16px Inter, sans-serif',
|
|
25
|
+
400, // container width in px
|
|
26
|
+
24 // line height in px
|
|
27
|
+
);
|
|
28
|
+
// layout.lines -> per-line layout from Pretext
|
|
29
|
+
|
|
30
|
+
// Opt into automatic measurement of text inserted by what-core's renderer.
|
|
31
|
+
// Registers a hook with what-core; skipped during hydration; off by default.
|
|
32
|
+
configureText({ measure: true, cacheSize: 1000 });
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
- Measurements are cached in an LRU keyed on `font|text` (`cacheSize` entries, default 1000).
|
|
36
|
+
- The cache is cleared automatically when new fonts finish loading (`document.fonts` `loadingdone`).
|
|
37
|
+
- `configureText({ measure: false })` unregisters the hook again.
|
|
38
|
+
|
|
39
|
+
## Components (alpha)
|
|
40
|
+
|
|
41
|
+
> All three components are `@alpha` — APIs may change without a major version bump. `TextCanvas` and `TextSVG` have no text selection or accessibility story yet.
|
|
42
|
+
|
|
43
|
+
```jsx
|
|
44
|
+
import { TextFlow, TextCanvas, TextSVG } from 'what-text';
|
|
45
|
+
|
|
46
|
+
// Magazine-style multi-column flow. Works WITHOUT Pretext (falls back to CSS
|
|
47
|
+
// columns); the `around` shape-flow prop requires Pretext.
|
|
48
|
+
<TextFlow columns={3} gap="1.5rem">{() => article()}</TextFlow>
|
|
49
|
+
|
|
50
|
+
// Text rendered to <canvas> via Pretext layout (requires Pretext).
|
|
51
|
+
<TextCanvas width={600} height={200} font="16px Inter, sans-serif">
|
|
52
|
+
{() => content()}
|
|
53
|
+
</TextCanvas>
|
|
54
|
+
|
|
55
|
+
// Text rendered as SVG <text>/<tspan> lines via Pretext layout (requires Pretext).
|
|
56
|
+
<TextSVG width={600} height={200} font="16px Inter, sans-serif">
|
|
57
|
+
{() => content()}
|
|
58
|
+
</TextSVG>
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Children may be a plain string or a reactive function — the components re-layout when signals they read change.
|
|
62
|
+
|
|
63
|
+
## API
|
|
64
|
+
|
|
65
|
+
| Export | Description |
|
|
66
|
+
|---|---|
|
|
67
|
+
| `configureText(opts)` | `{ measure: boolean, cacheSize: number }` — toggles the what-core text-insert measurement hook |
|
|
68
|
+
| `getTextConfig()` | Current config (copy) |
|
|
69
|
+
| `measureText(text, font, width, lineHeight)` | Async: font-ready gate → Pretext prepare (cached) → line layout |
|
|
70
|
+
| `clearMeasureCache()` | Drop all cached measurements |
|
|
71
|
+
| `ensurePretext()` | Lazy-load and return the `@chenglou/pretext` module |
|
|
72
|
+
| `TextFlow` | Multi-column text flow (`columns`, `gap`, `around`) — CSS-columns fallback without Pretext |
|
|
73
|
+
| `TextCanvas` | Canvas text rendering (`width`, `height`, `font`) — requires Pretext |
|
|
74
|
+
| `TextSVG` | SVG text rendering (`width`, `height`, `font`) — requires Pretext |
|
|
75
|
+
|
|
76
|
+
## Example
|
|
77
|
+
|
|
78
|
+
A live demo (reflow sliders, canvas/SVG tabs) lives in [`example/`](./example) — `npm install && npm run dev` inside that directory.
|
|
79
|
+
|
|
80
|
+
## Links
|
|
81
|
+
|
|
82
|
+
- [Documentation](https://whatfw.com)
|
|
83
|
+
- [GitHub](https://github.com/CelsianJs/what-framework)
|
|
84
|
+
|
|
85
|
+
## License
|
|
86
|
+
|
|
87
|
+
MIT
|