lecodes-sdk 1.0.0 → 1.1.0

package/dist/types/ui/UINode.d.ts

@@ -1,4 +1,6 @@
 import type { FetchResponse } from "../runtime/fetch";
+import type { Animation } from "../animate/tween/Animation";
+import { type TweenMeta } from "../animate/tween/spec";
 export interface UINode {
     readonly type: string;
     /** Author-given semantic name (a stable selector for tests + AI review feedback). */
@@ -158,8 +160,12 @@ export type TextStyle = {
 export type Reactive<T> = {
     [K in keyof T]: NonNullable<T[K]> extends object ? T[K] : T[K] | (() => T[K]);
 };
+/** The curve of a state block's swap (`$class` / `onPressed` / `onFocused` with a `duration`): a
+ *  curve name (`outCubic`, `inOutSine`, `smoothstep` — the default — …), `cubic-bezier(x1,y1,x2,y2)`
+ *  or `steps(n)`. A function cannot ride a style block; use `animateTo` for those. */
+export type LayerEasing = string;
 /** User-defined style classes: any `$`-prefixed key in `.style()` declares a state block toggled
- *  from code via the `el.class` proxy; `duration`/`delay` animate the swap. Class state INHERITS
+ *  from code via the `el.class` proxy; `duration`/`delay`/`easing` animate the swap. Class state INHERITS
  *  down the tree (CSS-`.dark`-on-body style): a class set on a node also activates same-name `$`
  *  blocks on all descendants within the same root (docs/style-class-cascade-plan.md).
  *  `$pressed`/`$focused` are reserved — hosts toggle them on press/focus (they beat other
@@ -172,6 +178,7 @@ export type ClassStyles<T> = {
     [key: `$${string}`]: T & {
         duration?: number;
         delay?: number;
+        easing?: LayerEasing;
     };
 };
 /** Value accepted by a `el.class` write: a boolean sets the class, a `() => boolean` binds it —
@@ -245,25 +252,15 @@ export type StyleFn<R, T extends object> = ((style: Reactive<T> & OrientationSty
  *  chaining — and per-key readable/writable (`el.style.opacity = 0.5`; a `() => value` write
  *  installs a reactive binding). */
 export type Style<R, T extends object> = StyleFn<R, T> & T & OrientationStyles<T> & ClassStyles<T>;
-/** The `animateTo`/`animateFrom` surface: target style props plus the flat meta keys below
- *  (stripped before the commit into the element's style). */
-export type AnimateStyle<R, T extends object> = ((style: T & {
-    /** Tween length in **milliseconds** (default 225). */
-    duration?: number;
-    /** Wait before starting, in **milliseconds**. A looping animation delays once, not per cycle. */
-    delay?: number;
-    /** Escape hatch: target an internal style layer (the onPressed/orientation mechanism). Not part of the supported surface. */
-    layer?: number;
-    /** `false` = animate without writing the targets into the element's style (e.g. a fade-out right before `.hide()`). */
-    commit?: boolean;
-    /** Repeat the animation: `true` = forever, a number = that many cycles. A looping animation is an
-     *  effect, not a state change — it never commits, and the element ends back at its base style.
-     *  The loop stops when a later `animateTo`/`animateFrom` runs on the element or it leaves the screen. */
-    loop?: boolean | number;
-    /** `"ping-pong"` (default) animates there and back each cycle — no jump. `"restart"` snaps back and
-     *  replays forward — for full-turn spinners (`transform: "rotate(360deg)"`) and shimmers. Only meaningful with `loop`. */
-    loopMode?: "restart" | "ping-pong";
-}) => R);
+/** Style props of an animate bag: a single value (tween from the current value) or an array of
+ *  KEYFRAMES (`opacity: [1, 0.3, 1]`, offsets via `times`). */
+export type AnimateProps<T extends object> = {
+    [K in keyof T]?: T[K] | T[K][];
+};
+/** The `animateTo`/`animateFrom` surface: target style props (single values or keyframe arrays) plus
+ *  the flat meta keys — `duration` / `delay` / `easing` / `times` / `loop` / `loopMode` / `commit` /
+ *  `clock`, see {@link TweenMeta}. Returns the {@link Animation} handle (seek, rate, `finished`). */
+export type AnimateStyle<R, T extends object> = ((style: AnimateProps<T> & TweenMeta) => Animation);
 export type AppearStyle<R, T> = (arg: {
     from: T;
     duration?: number;
@@ -306,10 +303,13 @@ export declare class Element<T extends string> {
     constructor(type: T, style: any);
     get style(): any;
     /** Tween to the target style and commit it (unless `commit: false` or looping — a loop is an
-     *  effect, not a state change). Meta keys: `duration`/`delay`/`loop`/… — see {@link AnimateStyle}. */
-    animateTo(style: any): this;
-    /** Tween FROM the given style to the element's current one (entrance animations). */
-    animateFrom(style: any): this;
+     *  effect, not a state change). A prop value may be an array of keyframes; meta keys
+     *  `duration`/`delay`/`easing`/`times`/`loop`/… — see {@link AnimateStyle}. Returns the
+     *  {@link Animation} handle. */
+    animateTo(style: any): Animation;
+    /** Tween FROM the given style to the element's current one (entrance animations): the element's
+     *  own style is the implicit last keyframe. Never modifies the stored style. */
+    animateFrom(style: any): Animation;
     protected _classProxy?: any;
     /** Style-class control — flips the `$`-class blocks declared in `.style()`. One proxy, same
      *  contract as `el.style`: