@gridui/text-morph 1.1.2 → 2.1.0
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 +76 -9
- package/dist/index.js +464 -133
- package/dist/index.js.map +3 -3
- package/dist/styled.js +2 -0
- package/dist/styles.local.css +41 -0
- package/dist/text-morph/exits.d.ts +14 -0
- package/dist/text-morph/measurement.d.ts +23 -0
- package/dist/text-morph/mode.d.ts +9 -0
- package/dist/text-morph/motion-state.d.ts +29 -0
- package/dist/text-morph/observe-layout.d.ts +8 -0
- package/dist/text-morph/options.d.ts +4 -0
- package/dist/text-morph/timing.d.ts +0 -1
- package/dist/text-morph/transition.d.ts +4 -1
- package/docs/catalog.json +3 -1
- package/docs/reference/text-morph.md +10 -0
- package/package.json +12 -7
package/README.md
CHANGED
|
@@ -21,6 +21,16 @@ import { TextMorph } from "@gridui/text-morph";
|
|
|
21
21
|
retain their formatting. The host owns `locale` and formatting policy. Supply
|
|
22
22
|
the same locale on the server and client when formatting numbers.
|
|
23
23
|
|
|
24
|
+
## Styles
|
|
25
|
+
|
|
26
|
+
Load Theme once. Use `@gridui/text-morph/styled` for automatic component CSS in
|
|
27
|
+
CSS-aware bundlers, or keep the CSS-free root import and load `@gridui/text-morph/styles.css`.
|
|
28
|
+
Both entries expose the same root API. The standalone stylesheet includes component
|
|
29
|
+
dependency styles; Theme/reset remain separate. See the
|
|
30
|
+
[integration guide](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/docs/usage/integration.md)
|
|
31
|
+
for static HTML loading, SSR limits, and avoiding duplicate CSS.
|
|
32
|
+
|
|
33
|
+
|
|
24
34
|
## Matching and rendering
|
|
25
35
|
|
|
26
36
|
Matching preserves complete Unicode graphemes, prioritizes identical whole words,
|
|
@@ -33,22 +43,39 @@ dates, versions, and other values that should not use numeric place matching.
|
|
|
33
43
|
matching and anchors insertion/deletion identity around that caret, including
|
|
34
44
|
repeated digits. Complex replacements fall back to ordinary text matching. The
|
|
35
45
|
component displays text; it does not own an input, selection, or visible caret.
|
|
46
|
+
Changing locale or effective numeric matching (including entering/leaving caret
|
|
47
|
+
mode) rebuilds the visual segmentation immediately, even when the text is unchanged.
|
|
48
|
+
It cancels active decoration without emitting a new animation start or completion.
|
|
36
49
|
|
|
37
50
|
`as` defaults to `span` and accepts `div`, `p`, `h1`–`h6`, `strong`, and `em`.
|
|
38
51
|
Native attributes and the root ref are forwarded. Explicit `\n` breaks are
|
|
39
|
-
supported. Automatic wrapping
|
|
40
|
-
|
|
41
|
-
|
|
52
|
+
supported. Automatic wrapping and rich markup remain outside this component's
|
|
53
|
+
contract; use ordinary text for prose.
|
|
54
|
+
|
|
55
|
+
`mode="auto"` (default) uses whole-run transitions for RTL context, bidi controls,
|
|
56
|
+
and scripts outside Latin, Han, kana, and Hangul. `mode="text"` always keeps the
|
|
57
|
+
entire string in one shaped run, including Latin kerning and ligatures.
|
|
58
|
+
`mode="characters"` explicitly selects grapheme/place matching; use it only after
|
|
59
|
+
checking the chosen script and font. Auto is a conservative script policy, not a
|
|
60
|
+
font shaping detector. Whole-run transitions retain timed/spring motion policy.
|
|
61
|
+
`locale` configures number formatting and segmentation; native `lang` and `dir`
|
|
62
|
+
separately describe the content. Set them on the root or inherit them from a
|
|
63
|
+
language boundary; never infer language from direction.
|
|
64
|
+
|
|
65
|
+
Font completion/failure, ancestor font-profile/style/class/direction changes,
|
|
66
|
+
and viewport typography changes settle obsolete motion and rebuild natural
|
|
67
|
+
geometry. Refresh cancels active decoration without inventing a text change.
|
|
68
|
+
Observers and font listeners are removed on unmount.
|
|
42
69
|
|
|
43
70
|
## Motion
|
|
44
71
|
|
|
45
72
|
| Option | Behavior |
|
|
46
73
|
| --- | --- |
|
|
47
|
-
| `duration` | Finite nonnegative milliseconds;
|
|
74
|
+
| `duration` | Finite nonnegative milliseconds; explicit duration selects timed playback. Without it, CSS easing uses Theme duration and spring easing settles physically. |
|
|
48
75
|
| `ease` | CSS easing string or `{ stiffness, damping, mass, precision }` spring parameters |
|
|
49
76
|
| `scale` | Shrink removed characters while fading them out; defaults to false |
|
|
50
77
|
| `disabled` | Apply the new value immediately |
|
|
51
|
-
| `respectReducedMotion` |
|
|
78
|
+
| `respectReducedMotion` | Deprecated compatibility prop; system preferences are always respected. |
|
|
52
79
|
| `debug` | Outline visual segments without logging content |
|
|
53
80
|
| `onAnimationStart` | Once when an animated update starts |
|
|
54
81
|
| `onAnimationComplete` | Once when every animation in that update finishes |
|
|
@@ -56,10 +83,18 @@ prose and typography that requires those behaviors.
|
|
|
56
83
|
|
|
57
84
|
The default duration and easing use `--gridui-motion-duration-normal` and
|
|
58
85
|
`--gridui-motion-ease-out`. Springs accept positive finite parameters, with
|
|
59
|
-
precision between 0 and 1.
|
|
60
|
-
|
|
86
|
+
precision between 0 and 1. A spring ease without an explicit duration uses the
|
|
87
|
+
shared numeric spring controller. Position and velocity survive retargeting for
|
|
88
|
+
retained visual identities, including layout-coordinate rebasing after text changes.
|
|
89
|
+
Precision sets the rest distance/speed tolerance in local value units (pixels for
|
|
90
|
+
position/size, unitless for opacity/scale). There is no authored fixed duration.
|
|
91
|
+
|
|
92
|
+
An explicit duration retains the existing WAAPI path, including sampled spring
|
|
93
|
+
curves when ease is an object. CSS `linear()` support is detected for that timed
|
|
94
|
+
path; unsupported easing falls back to the theme. Switching between timed and
|
|
95
|
+
physical modes settles/cancels the current run before the next update. Explicit zero
|
|
61
96
|
duration, first render, and unchanged text do not emit animation start or
|
|
62
|
-
complete callbacks.
|
|
97
|
+
complete callbacks. Reduced motion
|
|
63
98
|
settles the text immediately and cancels any active animation.
|
|
64
99
|
|
|
65
100
|
## Hook composition
|
|
@@ -89,7 +124,7 @@ updates settle immediately. The component always respects reduced motion.
|
|
|
89
124
|
|
|
90
125
|
Segmentation, matching, timing, the imperative visual controller, and the React
|
|
91
126
|
hook live separately in `src/text-morph/`. React owns semantic content; the
|
|
92
|
-
controller owns only its empty visual layer. No animation
|
|
127
|
+
controller owns only its empty visual layer. No separate animation engine, global
|
|
93
128
|
configuration, application state, or framework adapter is introduced.
|
|
94
129
|
|
|
95
130
|
This implements the React-facing capabilities studied in
|
|
@@ -100,3 +135,35 @@ See [component ownership](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/
|
|
|
100
135
|
and [release history](https://github.com/sudo-ui/GridUI-React-Monorepo/tree/main/packages-core/text-morph/.changeset/history).
|
|
101
136
|
|
|
102
137
|
[Component reference](docs/reference/README.md) contains focused API pages for each public component.
|
|
138
|
+
|
|
139
|
+
Shared animation policy and tempo come from `MotionConfig` in `@gridui/motion`.
|
|
140
|
+
Disabled or reduced-motion policy settles decoration without disabling interaction.
|
|
141
|
+
See the [motion guide](https://github.com/sudo-ui/GridUI-React-Monorepo/tree/main/packages-core/motion)
|
|
142
|
+
for CSS scopes, portal behavior, and specialized timing contracts.
|
|
143
|
+
|
|
144
|
+
Rapid updates retain segment and glyph identities separately. A rolling glyph
|
|
145
|
+
continues with its own velocity when retained or moved to its exit; a newly created
|
|
146
|
+
glyph starts with zero velocity. Equal characters do not share state. Reappearing
|
|
147
|
+
text whose previous node already exited gets a new identity. Old run callbacks
|
|
148
|
+
cancel once and cannot complete a replacement run. Repeated updates within one frame
|
|
149
|
+
also retain the current initial velocity before the next engine sample.
|
|
150
|
+
|
|
151
|
+
Obsolete exits have a per-instance budget: twice the current segment count, with a
|
|
152
|
+
floor of eight and a ceiling of 256 tracked exits. Excess oldest exits are removed
|
|
153
|
+
and their numeric channels disposed. Current identities are never evicted. This
|
|
154
|
+
bounds retained decoration during sustained updates and slow spring settling; it
|
|
155
|
+
may shorten obsolete exit effects. Disabled/reduced motion still settles all exits.
|
|
156
|
+
|
|
157
|
+
TextMorph owns matching, layout measurement, exit lifetime and a private per-instance
|
|
158
|
+
motion-state map. Private measurement and exit-lifecycle helpers keep DOM geometry
|
|
159
|
+
and subtree disposal separate from numeric state. Shared Motion owns numeric execution. Natural layout is measured
|
|
160
|
+
in a synchronous batch; numeric updates batch owned DOM writes without React frame
|
|
161
|
+
renders or a layout read on every frame. No global registry or new physics solver
|
|
162
|
+
is introduced. Explicit newline changes are supported; automatic wrapping and
|
|
163
|
+
continuous observation of external layout changes remain outside the contract.
|
|
164
|
+
|
|
165
|
+
Physical animation performs main-thread numeric updates and intrinsic size writes
|
|
166
|
+
can incur layout. The package now imports the numeric Motion executor even when a
|
|
167
|
+
consumer chooses timed playback at runtime; measure bundle/runtime costs for large
|
|
168
|
+
or rapidly changing text workloads. The timed mode remains available through an
|
|
169
|
+
explicit duration. See the motion roadmap for the measured follow-up baseline.
|