ui-theme 0.1.0__py3-none-any.whl

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.
ui_theme/effects.py ADDED
@@ -0,0 +1,449 @@
1
+ """Animated effects, described over time and semantic colour.
2
+
3
+ An effect is a function of time: `frame(elapsed)` says what it shows that long
4
+ after it started, so a skipped tick shows the right state on the next one. A
5
+ frame names theme colours and fractions of the thing it decorates (a line, a
6
+ bar, a block of text), never pixels or terminal cells: a terminal backend
7
+ samples it into cells, Qt into a painter, a web view into CSS.
8
+
9
+ Frames:
10
+
11
+ - `Gradient`: theme colours repeating along a line, shifted by a fraction;
12
+ - `Ribbon`: a finite gradient with tapered, fractional-height ink;
13
+ - `Mix`: one colour part of the way from one theme colour to another;
14
+ - `Band`: a theme colour over a span of a line;
15
+ - `TextFrame`: lines of text, each character in its own colour.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ from abc import ABC, abstractmethod
21
+ from collections.abc import Callable
22
+ from dataclasses import dataclass
23
+ from math import cos, floor, tau
24
+ from typing import TYPE_CHECKING, Any, ClassVar, Generic, TypeVar
25
+
26
+ from ui_theme.colour import Rgb
27
+ from ui_theme.scheme import (
28
+ AccentColour,
29
+ BackgroundColour,
30
+ ColourScheme,
31
+ ForegroundColour,
32
+ MutedColour,
33
+ PrimaryColour,
34
+ SecondaryColour,
35
+ ThemeColour,
36
+ )
37
+
38
+ if TYPE_CHECKING:
39
+ from ui_theme.backend import Backend
40
+
41
+ FrameT = TypeVar("FrameT", bound="Frame", covariant=True)
42
+
43
+
44
+ class Frame(ABC):
45
+ """What an effect shows at one moment."""
46
+
47
+ @abstractmethod
48
+ def paint(self, backend: Backend[Any, Any, Any, Any], target: Any) -> Any:
49
+ """This frame in `backend`'s paint, for `target` (its geometry or element)."""
50
+
51
+
52
+ @dataclass(frozen=True)
53
+ class Gradient(Frame):
54
+ """Theme colours repeating along a line, one cycle per line length, moved `offset` of it."""
55
+
56
+ stops: tuple[type[ThemeColour], ...]
57
+ offset: float
58
+
59
+ def at(self, position: float) -> tuple[type[ThemeColour], type[ThemeColour], float]:
60
+ """The two stops around `position` (0–1 along the line) and how far between them."""
61
+ place = ((position - self.offset) % 1.0) * len(self.stops)
62
+ index = int(place) % len(self.stops)
63
+ return self.stops[index], self.stops[(index + 1) % len(self.stops)], place - int(place)
64
+
65
+ def sample(self, position: float) -> tuple[type[ThemeColour], type[ThemeColour], float, float]:
66
+ """Colour stops, blend and fraction of the target's ink height at this point."""
67
+ return (*self.at(position), 1.0)
68
+
69
+ def paint(self, backend: Backend[Any, Any, Any, Any], target: Any) -> Any:
70
+ return backend.paint_gradient(self, target)
71
+
72
+
73
+ @dataclass(frozen=True)
74
+ class Ribbon(Gradient):
75
+ """A finite gradient with a bright core and tapered, fractional-height tails."""
76
+
77
+ start: float
78
+ end: float
79
+ thickness: float
80
+ taper_fraction: ClassVar[float] = 1 / 8
81
+
82
+ def sample(self, position: float) -> tuple[type[ThemeColour], type[ThemeColour], float, float]:
83
+ place = (position - self.start) / (self.end - self.start)
84
+ if not 0 < place < 1:
85
+ return self.stops[0], self.stops[0], 0.0, 0.0
86
+ # The complete finite palette spans the full-height body. Its last
87
+ # colour is reached before the ink tapers away, never wrapped to first.
88
+ colour_place = min(1.0, max(0.0,
89
+ (place - self.taper_fraction) / (1 - 2 * self.taper_fraction)))
90
+ scaled = colour_place * (len(self.stops) - 1)
91
+ index = int(scaled)
92
+ start = self.stops[index]
93
+ end = self.stops[min(index + 1, len(self.stops) - 1)]
94
+ amount = scaled - index
95
+ amount = amount * amount * (3 - 2 * amount)
96
+ edge = min(1.0, place / self.taper_fraction, (1 - place) / self.taper_fraction)
97
+ edge = edge * edge * (3 - 2 * edge)
98
+ return start, end, amount, self.thickness * edge
99
+
100
+
101
+ @dataclass(frozen=True)
102
+ class Mix(Frame):
103
+ """A colour `amount` of the way from `start` to `end` (0 is start, 1 is end)."""
104
+
105
+ start: type[ThemeColour]
106
+ end: type[ThemeColour]
107
+ amount: float
108
+
109
+ def rgb(self, scheme: ColourScheme) -> Rgb:
110
+ return scheme.rgb(self.start).blend(scheme.rgb(self.end), self.amount)
111
+
112
+ def paint(self, backend: Backend[Any, Any, Any, Any], target: Any) -> Any:
113
+ return backend.paint_mix(self, target)
114
+
115
+
116
+ @dataclass(frozen=True)
117
+ class Band(Frame):
118
+ """`colour` over `start`–`end`."""
119
+
120
+ colour: type[ThemeColour]
121
+ start: float
122
+ end: float
123
+
124
+ def covers(self, position: float) -> bool:
125
+ return self.start <= position < self.end
126
+
127
+ def paint(self, backend: Backend[Any, Any, Any, Any], target: Any) -> Any:
128
+ return backend.paint_band(self, target)
129
+
130
+
131
+ @dataclass(frozen=True)
132
+ class TextFrame(Frame):
133
+ """Lines of text; each character with its colour (None: the ordinary text colour)."""
134
+
135
+ lines: tuple[tuple[tuple[str, Rgb | None], ...], ...]
136
+
137
+ def paint(self, backend: Backend[Any, Any, Any, Any], target: Any) -> Any:
138
+ return backend.paint_text(self, target)
139
+
140
+
141
+ @dataclass(frozen=True)
142
+ class Amount(Frame):
143
+ """A unitless paint amount; the frontend owns its physical rendering."""
144
+
145
+ value: float
146
+
147
+ def paint(self, backend: object, target: object) -> float:
148
+ return self.value
149
+
150
+
151
+ class Effect(ABC, Generic[FrameT]):
152
+ """An animation: a frame for any time since it started."""
153
+
154
+ # How often a frontend should show a new frame.
155
+ frames_per_second: float
156
+ # How long it runs; None runs until stopped.
157
+ duration: float | None
158
+
159
+ @abstractmethod
160
+ def frame(self, elapsed: float) -> FrameT: ...
161
+
162
+ def at(self, elapsed: float, position: float) -> FrameT:
163
+ """The frame for a row `position` of the way through the thing being animated.
164
+
165
+ An effect that treats its rows alike shows them one frame, so position changes
166
+ nothing here; one that plays row after row says so by overriding this. A painter
167
+ passes the row it is drawing and never asks which kind of effect it holds.
168
+ """
169
+ return self.frame(elapsed)
170
+
171
+ @property
172
+ @abstractmethod
173
+ def final(self) -> FrameT:
174
+ """What shows when it has finished, or when animation is off."""
175
+
176
+ @property
177
+ def finite(self) -> bool:
178
+ return self.duration is not None
179
+
180
+ def finished(self, elapsed: float) -> bool:
181
+ return self.remaining(elapsed) == 0.0
182
+
183
+ def remaining(self, elapsed: float) -> float | None:
184
+ """Seconds until it finishes; None runs until stopped."""
185
+ return None if self.duration is None else max(0.0, self.duration - elapsed)
186
+
187
+ def cadence_time(self, now: float) -> float:
188
+ """The shared cadence boundary containing this clock sample."""
189
+ return floor(now * self.frames_per_second) / self.frames_per_second
190
+
191
+ def phase_time(self, elapsed: float, now: float) -> float:
192
+ """Repeated effects share the clock phase; finite effects start at zero."""
193
+ return elapsed if self.finite else self.cadence_time(now)
194
+
195
+ @staticmethod
196
+ def phase(elapsed: float, period: float) -> float:
197
+ return (elapsed / period) % 1.0
198
+
199
+ @classmethod
200
+ def oscillation(cls, elapsed: float, period: float) -> float:
201
+ return (1 - cos(tau * cls.phase(elapsed, period))) / 2
202
+
203
+ @staticmethod
204
+ def progress(elapsed: float, duration: float) -> float:
205
+ return min(1.0, max(0.0, elapsed / duration))
206
+
207
+ @staticmethod
208
+ def ease_out(progress: float) -> float:
209
+ return 1 - (1 - progress) ** 2
210
+
211
+
212
+ @dataclass(frozen=True)
213
+ class Transition(Effect[FrameT]):
214
+ """One eased, finite interpolation, producing its declared frame type."""
215
+
216
+ frame_type: Callable[[float], FrameT]
217
+ start: float
218
+ end: float
219
+ duration: float
220
+ frames_per_second: float
221
+
222
+ def frame(self, elapsed: float) -> FrameT:
223
+ progress = self.ease_out(self.progress(elapsed, self.duration))
224
+ return self.frame_type(self.start + (self.end - self.start) * progress)
225
+
226
+ @property
227
+ def final(self) -> FrameT:
228
+ return self.frame_type(self.end)
229
+
230
+
231
+ @dataclass(frozen=True)
232
+ class GradientSweep(Effect[Gradient]):
233
+ """A band of theme colours moving along a line, one pass per period."""
234
+
235
+ stops: tuple[type[ThemeColour], ...]
236
+ period: float
237
+ frames_per_second: float
238
+ duration: float | None = None
239
+
240
+ def frame(self, elapsed: float) -> Gradient:
241
+ return Gradient(self.stops, self.phase(elapsed, self.period))
242
+
243
+ @property
244
+ def final(self) -> Gradient:
245
+ return Gradient(self.stops, 0.0)
246
+
247
+
248
+ @dataclass(frozen=True)
249
+ class BreathingSweep(Effect[Ribbon]):
250
+ """A tapered gradient travels, shrinks and expands; its size is never progress."""
251
+
252
+ stops: tuple[type[ThemeColour], ...]
253
+ period: float
254
+ breathing_period: float
255
+ minimum_width: float
256
+ maximum_width: float
257
+ minimum_thickness: float
258
+ maximum_thickness: float
259
+ frames_per_second: float
260
+ duration: float | None = None
261
+
262
+ def frame(self, elapsed: float) -> Ribbon:
263
+ breath = self.oscillation(elapsed, self.breathing_period)
264
+ width = self.minimum_width + (self.maximum_width - self.minimum_width) * breath
265
+ thickness = self.minimum_thickness + (self.maximum_thickness - self.minimum_thickness) * breath
266
+ lead = self.phase(elapsed, self.period) * (1 + width)
267
+ return Ribbon(self.stops, 0.0, lead - width, lead, thickness)
268
+
269
+ @property
270
+ def final(self) -> Ribbon:
271
+ width = (self.minimum_width + self.maximum_width) / 2
272
+ thickness = (self.minimum_thickness + self.maximum_thickness) / 2
273
+ return Ribbon(self.stops, 0.0, (1 - width) / 2, (1 + width) / 2, thickness)
274
+
275
+ @dataclass(frozen=True)
276
+ class Pulse(Effect[Mix]):
277
+ """A colour mix breathes between declared bounds, without a frame counter."""
278
+
279
+ start: type[ThemeColour]
280
+ end: type[ThemeColour]
281
+ minimum: float
282
+ maximum: float
283
+ period: float
284
+ frames_per_second: float
285
+ duration: float | None = None
286
+
287
+ def frame(self, elapsed: float) -> Mix:
288
+ return Mix(self.start, self.end,
289
+ self.maximum - (self.maximum - self.minimum) * self.oscillation(elapsed, self.period))
290
+
291
+ @property
292
+ def final(self) -> Mix:
293
+ return Mix(self.start, self.end, self.maximum)
294
+
295
+
296
+ class TextFade(Effect[Mix]):
297
+ """An effect text rises through: it says which theme colour its frames begin at.
298
+
299
+ A painter that draws text on its own background re-roots a background-origin
300
+ frame in that background, so the text rises out of the surface it sits on
301
+ rather than out of the theme's. Everything else about it is `Effect`: one
302
+ frame per elapsed time, and `at` for an effect that plays row after row.
303
+ """
304
+
305
+ start: type[ThemeColour]
306
+ """The theme colour its frames begin at."""
307
+
308
+
309
+ @dataclass(frozen=True)
310
+ class Fade(TextFade):
311
+ """From one theme colour to another, easing out, over `duration` seconds."""
312
+
313
+ start: type[ThemeColour]
314
+ end: type[ThemeColour]
315
+ duration: float
316
+ frames_per_second: float
317
+
318
+ def frame(self, elapsed: float) -> Mix:
319
+ return Mix(self.start, self.end, self.ease_out(self.progress(elapsed, self.duration)))
320
+
321
+ @property
322
+ def final(self) -> Mix:
323
+ return Mix(self.start, self.end, 1.0)
324
+
325
+ def ending_at(self, end: type[ThemeColour]) -> Fade:
326
+ return Fade(self.start, end, self.duration, self.frames_per_second)
327
+
328
+
329
+ @dataclass(frozen=True)
330
+ class CrossingBand(Effect[Band]):
331
+ """A band of `width` whose leading edge travels from before a line to past its end.
332
+
333
+ Members differ only in how far through the crossing they are at a moment: once, or
334
+ again and again.
335
+ """
336
+
337
+ colour: type[ThemeColour]
338
+ width: float
339
+ frames_per_second: float
340
+
341
+ @abstractmethod
342
+ def travelled(self, elapsed: float) -> float:
343
+ """How far through a crossing this moment is, 0 to 1."""
344
+
345
+ def frame(self, elapsed: float) -> Band:
346
+ lead = self.travelled(elapsed) * (1 + self.width)
347
+ return Band(self.colour, lead - self.width, lead)
348
+
349
+
350
+ @dataclass(frozen=True)
351
+ class Wipe(CrossingBand):
352
+ """A band of colour crossing a line once, leaving nothing behind."""
353
+
354
+ duration: float
355
+
356
+ def travelled(self, elapsed: float) -> float:
357
+ return self.progress(elapsed, self.duration)
358
+
359
+ @property
360
+ def final(self) -> Band:
361
+ return Band(self.colour, 1.0, 1.0)
362
+
363
+
364
+ @dataclass(frozen=True)
365
+ class BandSweep(CrossingBand):
366
+ """A band of colour crossing a line again and again, one pass per period.
367
+
368
+ What a busy indicator needs, and why it is not a Wipe: being busy has no duration to
369
+ progress through, so a band that reaches the end and stays there, or a bar that fills
370
+ as an agent works, is a claim about how far along the work is that nobody can honour.
371
+ This one only says that something is still happening.
372
+ """
373
+
374
+ period: float
375
+ duration: float | None = None
376
+
377
+ def travelled(self, elapsed: float) -> float:
378
+ return self.phase(elapsed, self.period)
379
+
380
+ @property
381
+ def final(self) -> Band:
382
+ """Animation off, or nothing happening: no band at all, and the text as it is."""
383
+ return Band(self.colour, 0.0, 0.0)
384
+
385
+
386
+ @dataclass(frozen=True)
387
+ class PlayedText(Effect[TextFrame]):
388
+ """Text frames built in advance, shown at `frames_per_second`; the last one stays."""
389
+
390
+ frames: tuple[TextFrame, ...]
391
+ frames_per_second: float
392
+
393
+ @property
394
+ def duration(self) -> float | None: # type: ignore[override]
395
+ return len(self.frames) / self.frames_per_second
396
+
397
+ def phase_time(self, elapsed: float, now: float) -> float:
398
+ return elapsed
399
+
400
+ def frame(self, elapsed: float) -> TextFrame:
401
+ index = max(0, int(elapsed * self.frames_per_second))
402
+ count = len(self.frames)
403
+ return self.frames[min(count - 1, index) if self.finite else index % count]
404
+
405
+ @property
406
+ def final(self) -> TextFrame:
407
+ return self.frames[-1]
408
+
409
+
410
+ CURSOR_BLINK = Pulse(
411
+ BackgroundColour, AccentColour, minimum=0.2, maximum=1.0, period=1.0, frames_per_second=2,
412
+ )
413
+
414
+ # A working agent, shown through its own name rather than a glyph beside it. Tristan,
415
+ # 2026-11-08: "replace the spinner with a colour/bold wave through the letters of the
416
+ # thread or channel name". The spinner cost a cell of every row's width to say something
417
+ # the row's own letters can say, and at eight characters of visible name on a phone that
418
+ # cell is expensive. A third of the name's width keeps the wave readable on a short name
419
+ # without washing a long one; the period is slower than the spinner's 10fps flicker,
420
+ # which read as urgency rather than as work.
421
+ NAME_WAVE = BandSweep(AccentColour, width=0.34, period=1.4, frames_per_second=20)
422
+
423
+ # The busy indicator while an agent works.
424
+ ACTIVITY_SWEEP = BreathingSweep(
425
+ (PrimaryColour, AccentColour, SecondaryColour),
426
+ period=3.2, breathing_period=2.7, minimum_width=0.32, maximum_width=0.64,
427
+ minimum_thickness=0.5, maximum_thickness=0.5, frames_per_second=20,
428
+ )
429
+
430
+ # Goal standby is a quiet marker, not a claim of active work.
431
+ STANDBY_PULSE = Pulse(
432
+ BackgroundColour, MutedColour, minimum=0.45, maximum=1.0,
433
+ period=1.6, frames_per_second=20,
434
+ )
435
+
436
+ # A message that has just arrived: its colour fades from the accent to its own.
437
+ NEW_MESSAGE = Fade(AccentColour, AccentColour, duration=0.4, frames_per_second=30)
438
+
439
+ # Changed text rises from the background into each run's own colour.
440
+ NEW_TEXT = Fade(BackgroundColour, ForegroundColour, duration=0.35, frames_per_second=30)
441
+
442
+ # Sidebar placement and appearance share one duration, cadence and easing.
443
+ _SIDEBAR_DURATION = 0.25
444
+ _SIDEBAR_FPS = 60
445
+ SIDEBAR_ENTER = Transition(Amount, 0.0, 1.0, _SIDEBAR_DURATION, _SIDEBAR_FPS)
446
+ SIDEBAR_EXIT = Transition(Amount, 1.0, 0.0, _SIDEBAR_DURATION, _SIDEBAR_FPS)
447
+
448
+ # The current tab's underline when a tab is chosen.
449
+ TAB_WIPE = Wipe(AccentColour, width=0.35, duration=0.25, frames_per_second=60)
ui_theme/py.typed ADDED
File without changes