@zakkster/lite-ui-fx 1.3.0 → 1.5.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.
Files changed (9) hide show
  1. package/CHANGELOG.md +101 -0
  2. package/README.md +24 -10
  3. package/UIFX-RECIPE-GUIDE.md +3 -2
  4. package/UIFXController.d.ts +41 -1
  5. package/UIFXController.js +211 -17
  6. package/UIFXRecipes.d.ts +94 -53
  7. package/UIFXRecipes.js +669 -282
  8. package/llms.txt +33 -10
  9. package/package.json +1 -1
package/UIFXRecipes.d.ts CHANGED
@@ -1,92 +1,123 @@
1
1
  import type { UIFXRecipe, UIFXInstance, MountOptions } from './UIFXController';
2
2
 
3
3
  // ===========================================================
4
- // RECIPE FACTORIES (all 50)
4
+ // RECIPE OPTIONS + FACTORIES (all 53)
5
5
  // ===========================================================
6
6
 
7
+ /**
8
+ * The reserved theming options every recipe factory accepts (decisions/0002).
9
+ * All optional; omitting them reproduces the recipe's shipped look byte-for-byte.
10
+ */
11
+ export interface RecipeOptions {
12
+ /** Seed for a recipe's deterministic RNG (particle bursts, jitter). */
13
+ seed?: number;
14
+ /**
15
+ * Positional palette override; wins over `theme`. For most recipes it maps
16
+ * over the role order (accent, dim, surface, ...); for an array-palette recipe
17
+ * (Confetti, Firework, Aurora, RadioOrbit, PasswordStrength, ReactionPicker)
18
+ * it IS the palette.
19
+ */
20
+ colors?: string[];
21
+ /** Named theme roles: `light` -> accent, `mid` -> dim/muted, `dark` -> surface. */
22
+ theme?: { light: string; mid: string; dark: string };
23
+ /**
24
+ * Visible canvas label. Falls back to the mount `label`, then the recipe's
25
+ * default string -- so setting only `label` keeps the visible text equal to the
26
+ * accessible name (WCAG 2.5.3 label-in-name). Ignored by recipes painting no text.
27
+ */
28
+ text?: string;
29
+ /** Canvas font string; falls back to the recipe's historical font literal. */
30
+ font?: string;
31
+ }
32
+
7
33
  // -- Vol.1: Toggles --
8
- export declare function SwarmToggle(options?: { seed?: number; count?: number }): UIFXRecipe;
9
- export declare function LiquidToggle(): UIFXRecipe;
10
- export declare function NeonPulseToggle(): UIFXRecipe;
34
+ export declare function SwarmToggle(options?: RecipeOptions & { count?: number }): UIFXRecipe;
35
+ export declare function LiquidToggle(options?: RecipeOptions): UIFXRecipe;
36
+ export declare function NeonPulseToggle(options?: RecipeOptions): UIFXRecipe;
11
37
 
12
38
  // -- Vol.1: Buttons --
13
- export declare function MagneticButton(options?: { maxPull?: number }): UIFXRecipe;
14
- export declare function ShatterButton(options?: { seed?: number }): UIFXRecipe;
15
- export declare function ConfettiButton(options?: { seed?: number; colors?: string[] }): UIFXRecipe;
16
- export declare function GlitchButton(options?: { seed?: number }): UIFXRecipe;
39
+ export declare function MagneticButton(options?: RecipeOptions & { maxPull?: number }): UIFXRecipe;
40
+ export declare function ShatterButton(options?: RecipeOptions): UIFXRecipe;
41
+ export declare function ConfettiButton(options?: RecipeOptions): UIFXRecipe;
42
+ export declare function GlitchButton(options?: RecipeOptions): UIFXRecipe;
17
43
 
18
44
  // -- Vol.1: Sliders --
19
- export declare function SparkSlider(options?: { seed?: number; color?: string }): UIFXRecipe;
20
- export declare function CosmicSlider(options?: { seed?: number; dustCount?: number }): UIFXRecipe;
21
- export declare function LaserSlider(): UIFXRecipe;
45
+ export declare function SparkSlider(options?: RecipeOptions & { color?: string }): UIFXRecipe;
46
+ export declare function CosmicSlider(options?: RecipeOptions & { dustCount?: number }): UIFXRecipe;
47
+ export declare function LaserSlider(options?: RecipeOptions): UIFXRecipe;
22
48
 
23
49
  // -- Vol.2: Toggles --
24
- export declare function PendulumToggle(): UIFXRecipe;
25
- export declare function CircuitToggle(options?: { seed?: number }): UIFXRecipe;
26
- export declare function LightningToggle(options?: { seed?: number }): UIFXRecipe;
27
- export declare function DNAToggle(): UIFXRecipe;
50
+ export declare function PendulumToggle(options?: RecipeOptions): UIFXRecipe;
51
+ export declare function CircuitToggle(options?: RecipeOptions): UIFXRecipe;
52
+ export declare function LightningToggle(options?: RecipeOptions): UIFXRecipe;
53
+ export declare function DNAToggle(options?: RecipeOptions): UIFXRecipe;
28
54
 
29
55
  // -- Vol.2: Buttons --
30
- export declare function HeartbeatButton(options?: { seed?: number }): UIFXRecipe;
31
- export declare function BreathingButton(): UIFXRecipe;
32
- export declare function InkSplashButton(options?: { seed?: number }): UIFXRecipe;
33
- export declare function PixelDissolveButton(options?: { seed?: number; cols?: number; rows?: number }): UIFXRecipe;
34
- export declare function FireworkButton(options?: { seed?: number }): UIFXRecipe;
56
+ export declare function HeartbeatButton(options?: RecipeOptions): UIFXRecipe;
57
+ export declare function BreathingButton(options?: RecipeOptions): UIFXRecipe;
58
+ export declare function InkSplashButton(options?: RecipeOptions): UIFXRecipe;
59
+ export declare function PixelDissolveButton(options?: RecipeOptions & { cols?: number; rows?: number }): UIFXRecipe;
60
+ export declare function FireworkButton(options?: RecipeOptions): UIFXRecipe;
35
61
 
36
62
  // -- Vol.2: Sliders --
37
- export declare function AuroraSlider(): UIFXRecipe;
38
- export declare function WaveSlider(options?: { seed?: number }): UIFXRecipe;
39
- export declare function ElasticBandSlider(): UIFXRecipe;
40
- export declare function GravitySlider(): UIFXRecipe;
63
+ export declare function AuroraSlider(options?: RecipeOptions): UIFXRecipe;
64
+ export declare function WaveSlider(options?: RecipeOptions): UIFXRecipe;
65
+ export declare function ElasticBandSlider(options?: RecipeOptions): UIFXRecipe;
66
+ export declare function GravitySlider(options?: RecipeOptions): UIFXRecipe;
41
67
 
42
68
  // -- Vol.2: Loaders --
43
- export declare function OrbitLoader(): UIFXRecipe;
44
- export declare function HelixLoader(): UIFXRecipe;
69
+ export declare function OrbitLoader(options?: RecipeOptions): UIFXRecipe;
70
+ export declare function HelixLoader(options?: RecipeOptions): UIFXRecipe;
45
71
 
46
72
  // -- Vol.2: Checkboxes --
47
- export declare function RippleCheck(): UIFXRecipe;
48
- export declare function MorphCheck(): UIFXRecipe;
73
+ export declare function RippleCheck(options?: RecipeOptions): UIFXRecipe;
74
+ export declare function MorphCheck(options?: RecipeOptions): UIFXRecipe;
75
+ // -- U4a: CHECKBOX recipes (honour st.indeterminate) --
76
+ export declare function TickDraw(options?: RecipeOptions): UIFXRecipe;
77
+ export declare function IndeterminateScan(options?: RecipeOptions): UIFXRecipe;
49
78
 
50
79
  // -- Vol.2: Counters --
51
- export declare function FlameCounter(options?: { seed?: number }): UIFXRecipe;
52
- export declare function GlitchCounter(options?: { seed?: number }): UIFXRecipe;
80
+ export declare function FlameCounter(options?: RecipeOptions): UIFXRecipe;
81
+ export declare function GlitchCounter(options?: RecipeOptions): UIFXRecipe;
53
82
 
54
83
  // -- Vol.2: Rating --
55
- export declare function BubbleRating(options?: { seed?: number }): UIFXRecipe;
84
+ export declare function BubbleRating(options?: RecipeOptions): UIFXRecipe;
56
85
 
57
86
  // -- Vol.3: Knobs --
58
- export declare function VolumeKnob(): UIFXRecipe;
59
- export declare function CompassKnob(): UIFXRecipe;
87
+ export declare function VolumeKnob(options?: RecipeOptions): UIFXRecipe;
88
+ export declare function CompassKnob(options?: RecipeOptions): UIFXRecipe;
60
89
 
61
90
  // -- Vol.3: Progress --
62
- export declare function RingProgress(options?: { seed?: number }): UIFXRecipe;
63
- export declare function BatteryGauge(): UIFXRecipe;
64
- export declare function SignalMeter(): UIFXRecipe;
91
+ export declare function RingProgress(options?: RecipeOptions): UIFXRecipe;
92
+ export declare function BatteryGauge(options?: RecipeOptions): UIFXRecipe;
93
+ export declare function SignalMeter(options?: RecipeOptions): UIFXRecipe;
94
+ // -- U4a: PROGRESS recipe --
95
+ export declare function LiquidFill(options?: RecipeOptions): UIFXRecipe;
65
96
 
66
97
  // -- Vol.3: Controls --
67
- export declare function PillTabs(): UIFXRecipe;
68
- export declare function Stepper(): UIFXRecipe;
69
- export declare function RadioOrbit(): UIFXRecipe;
98
+ export declare function PillTabs(options?: RecipeOptions): UIFXRecipe;
99
+ export declare function Stepper(options?: RecipeOptions): UIFXRecipe;
100
+ export declare function RadioOrbit(options?: RecipeOptions): UIFXRecipe;
70
101
 
71
102
  // -- Vol.3: Indicators --
72
- export declare function PasswordStrength(): UIFXRecipe;
73
- export declare function WaterLevel(): UIFXRecipe;
74
- export declare function HeatMap(options?: { seed?: number }): UIFXRecipe;
103
+ export declare function PasswordStrength(options?: RecipeOptions): UIFXRecipe;
104
+ export declare function WaterLevel(options?: RecipeOptions): UIFXRecipe;
105
+ export declare function HeatMap(options?: RecipeOptions): UIFXRecipe;
75
106
 
76
107
  // -- Vol.3: Mood --
77
- export declare function DayNightToggle(options?: { seed?: number }): UIFXRecipe;
78
- export declare function ReactionPicker(): UIFXRecipe;
79
- export declare function NotificationBell(): UIFXRecipe;
108
+ export declare function DayNightToggle(options?: RecipeOptions): UIFXRecipe;
109
+ export declare function ReactionPicker(options?: RecipeOptions): UIFXRecipe;
110
+ export declare function NotificationBell(options?: RecipeOptions): UIFXRecipe;
80
111
 
81
112
  // -- Vol.3: Feedback --
82
- export declare function TypewriterField(): UIFXRecipe;
83
- export declare function SoundWaveBtn(): UIFXRecipe;
84
- export declare function UploadProgress(): UIFXRecipe;
113
+ export declare function TypewriterField(options?: RecipeOptions): UIFXRecipe;
114
+ export declare function SoundWaveBtn(options?: RecipeOptions): UIFXRecipe;
115
+ export declare function UploadProgress(options?: RecipeOptions): UIFXRecipe;
85
116
 
86
117
  // -- Vol.3: Fun --
87
- export declare function ScratchReveal(options?: { seed?: number }): UIFXRecipe;
88
- export declare function TimerCountdown(): UIFXRecipe;
89
- export declare function PullRefresh(): UIFXRecipe;
118
+ export declare function ScratchReveal(options?: RecipeOptions): UIFXRecipe;
119
+ export declare function TimerCountdown(options?: RecipeOptions): UIFXRecipe;
120
+ export declare function PullRefresh(options?: RecipeOptions): UIFXRecipe;
90
121
 
91
122
  // ===========================================================
92
123
  // BARREL OBJECTS (back-compat)
@@ -151,11 +182,18 @@ export declare const UIFXRecipes3: {
151
182
  PullRefresh: typeof PullRefresh;
152
183
  };
153
184
 
185
+ /** U4a additions -- new native element types (kept out of the Vol.1-3 snapshots). */
186
+ export declare const UIFXRecipes4: {
187
+ TickDraw: typeof TickDraw;
188
+ IndeterminateScan: typeof IndeterminateScan;
189
+ LiquidFill: typeof LiquidFill;
190
+ };
191
+
154
192
  // ===========================================================
155
193
  // RECIPE REGISTRY
156
194
  // ===========================================================
157
195
 
158
- export type RecipeType = 'toggle' | 'button' | 'slider';
196
+ export type RecipeType = 'toggle' | 'button' | 'slider' | 'checkbox' | 'progress' | 'knob';
159
197
 
160
198
  export type RecipeFactory = (options?: Record<string, unknown>) => UIFXRecipe;
161
199
 
@@ -195,7 +233,7 @@ export declare function mountRecipe(
195
233
  ): UIFXInstance;
196
234
 
197
235
  // ===========================================================
198
- // DEFAULT EXPORT -- combined all-50 namespace
236
+ // DEFAULT EXPORT -- combined all-53 namespace
199
237
  // ===========================================================
200
238
 
201
239
  declare const UIFXAllRecipes: {
@@ -226,6 +264,8 @@ declare const UIFXAllRecipes: {
226
264
  HelixLoader: typeof HelixLoader;
227
265
  RippleCheck: typeof RippleCheck;
228
266
  MorphCheck: typeof MorphCheck;
267
+ TickDraw: typeof TickDraw;
268
+ IndeterminateScan: typeof IndeterminateScan;
229
269
  FlameCounter: typeof FlameCounter;
230
270
  GlitchCounter: typeof GlitchCounter;
231
271
  BubbleRating: typeof BubbleRating;
@@ -234,6 +274,7 @@ declare const UIFXAllRecipes: {
234
274
  RingProgress: typeof RingProgress;
235
275
  BatteryGauge: typeof BatteryGauge;
236
276
  SignalMeter: typeof SignalMeter;
277
+ LiquidFill: typeof LiquidFill;
237
278
  PillTabs: typeof PillTabs;
238
279
  Stepper: typeof Stepper;
239
280
  RadioOrbit: typeof RadioOrbit;