@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 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, rich markup, and connected-script shaping across
40
- segment boundaries are outside this component's contract; use ordinary text for
41
- prose and typography that requires those behaviors.
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; defaults to the theme duration, or the spring's settling duration |
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` | Follow the system's reduced-motion preference. Defaults to `true`. |
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. Sampling and duration are bounded. CSS `linear()`
60
- support is detected; unsupported easing falls back to the theme. Explicit zero
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. When `respectReducedMotion` is enabled, reduced motion
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 dependency, global
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.