@mindlogic-ai/logician-ui 4.0.0-alpha.8 → 4.0.0

package/dist/theme/motion.d.ts

@@ -0,0 +1,648 @@
+/**
+ * Motion tokens — the timing layer of the design system.
+ *
+ * Laid out like the type layer: a primitive scale ({@link durations},
+ * {@link easings}) plus a named composition on top of it ({@link animationStyles}),
+ * both registered in the theme. Component code names the intent and the timing
+ * comes with it, the same way `textStyle="h3"` carries a family, size, weight,
+ * leading and tracking.
+ *
+ * ```tsx
+ * <Switch.Thumb animationStyle="spring" transitionProperty="translate" />
+ * ```
+ *
+ * ## Why the durations carry a `motion.` prefix
+ *
+ * Chakra already ships a duration scale, and two of the names we want are taken
+ * with *different* values — `slow` is 300ms there and 500ms here, `slower` is
+ * 400ms there and 700ms here. Its `dialog`, `drawer` and `progress` recipes read
+ * those, so redefining them would retime components we do not own. The easings
+ * need no prefix: Chakra's are `ease-in` / `ease-out` / `ease-in-out` /
+ * `ease-in-smooth`, so ours collide with nothing.
+ *
+ * 150ms and 200ms are deliberately absent — Chakra's `fast` and `moderate`
+ * already are those numbers, and two names for one value is worse than a
+ * prefix.
+ */
+/**
+ * The duration scale. Pick a preset from {@link animationStyles} rather than one
+ * of these directly; these are the raw material the presets are built from.
+ */
+export declare const durations: {
+    motion: {
+        /** No transition — the "off" value a reduced-motion guard swaps in. */
+        instant: {
+            value: string;
+        };
+        /**
+         * The gap that turns one event into two beats — the checkbox's tick waits
+         * this long after the box fills, the radio's dot after its ring. Short
+         * enough to read as one gesture, long enough that the second half is not
+         * lost in the first. It was written as a literal `60ms` in two presets
+         * before it had a name; a third would have invented a fourth number.
+         */
+        beat: {
+            value: string;
+        };
+        /** Contact: a pointer going down. Shorter than `fast` so it reads as touch. */
+        press: {
+            value: string;
+        };
+        /** The default for enters, leaves and reveals. */
+        base: {
+            value: string;
+        };
+        /** Deliberate moves that carry the eye across the UI. */
+        slow: {
+            value: string;
+        };
+        /** Count-ups that should feel earned. */
+        slower: {
+            value: string;
+        };
+        /**
+         * Celebration — the only band above `slower` that is not a loop.
+         *
+         * The rest of the scale answers "how long before the interface has
+         * responded", and its ceiling is `slower` because past ~700ms a response
+         * stops reading as an answer and starts reading as a wait. A celebration
+         * inverts that: the point *is* to be watched, and a burst that is over
+         * before the eye finds it has not celebrated anything.
+         *
+         * Two values for the same reason `loop` has three — the period is set by
+         * how far the thing travels, and one number for both leaves the burst
+         * sluggish or the fall frantic.
+         */
+        celebrate: {
+            /** A pop that stays near where it started: a badge, a node, a chip. */
+            burst: {
+                value: string;
+            };
+            /**
+             * A piece crossing the whole container it was thrown into. Slower than
+             * anything else in the scale on purpose: this is the one motion that is
+             * modelling gravity rather than an interface responding, and a piece that
+             * clears a dialog in under a second reads as flicked rather than dropped.
+             */
+            fall: {
+                value: string;
+            };
+        };
+        /**
+         * Continuous motion. Three values rather than one, because a loop's period
+         * is set by how far it travels: the spinner covers 360° in a 16px circle,
+         * the shimmer crosses the full width of whatever it is laid on. One number
+         * for both would leave the spinner leisurely or the sweep frantic.
+         *
+         * All three are well over the ~200ms of a finite transition. A loop is
+         * ambient — it has to stay readable without asking to be watched, and
+         * anything quick enough to be *noticed* in peripheral vision reads as
+         * agitation.
+         */
+        loop: {
+            /** One full rotation of a spinner. Preserves the 0.65s it was born with. */
+            turn: {
+                value: string;
+            };
+            /** One pass of something crossing its whole container. */
+            sweep: {
+                value: string;
+            };
+        };
+        stagger: {
+            /**
+             * The gap between one list item arriving and the next. Nested a level
+             * deeper than the rest of the scale so the token path flattens to
+             * `--chakra-durations-motion-stagger-step`, which `staggerProps` can name
+             * in a hand-written `calc()`.
+             *
+             * 35ms is the width of the window where a list reads as *dealt* rather
+             * than as either one block (below ~20ms) or a queue the reader is waiting
+             * on (above ~50ms).
+             */
+            step: {
+                value: string;
+            };
+        };
+    };
+};
+/**
+ * How many steps of {@link durations}`.motion.stagger.step` a list may accrue
+ * before the delay stops growing.
+ *
+ * The cap is the whole reason the stagger is usable. Without it the delay is
+ * linear in the index, so a 40-row list finishes arriving 1.4s after the first
+ * row — the last rows are not staggered, they are *late*, and any list long
+ * enough to be worth staggering is long enough to feel broken. Six steps is
+ * 210ms, which is under the ~250ms at which a delay stops reading as rhythm and
+ * starts reading as lag; everything past the sixth item arrives together, which
+ * nobody notices because by then the eye is at the top of the list.
+ */
+export declare const MOTION_STAGGER_MAX = 6;
+/**
+ * The easing curves.
+ *
+ * - `standard` — symmetric and unremarkable; utilitarian transitions
+ * - `emphasized` — decisive ease-out, the house curve for arriving at a value.
+ *   Covers ~96% of the distance in the first half of its duration
+ * - `overshoot` — passes the target and settles back. Because it reverses
+ *   direction it stays legible over a few pixels, which the other two do not
+ */
+export declare const easings: {
+    standard: {
+        value: string;
+    };
+    emphasized: {
+        value: string;
+    };
+    overshoot: {
+        value: string;
+    };
+};
+/**
+ * Enter and exit are not the same length, and that is a policy rather than a
+ * per-component taste.
+ *
+ * An enter has to be *read* — something new arrived and the reader has to find
+ * it — so it gets the full `motion.base` and the `emphasized` curve that covers
+ * most of the distance early and settles. An exit has already been decided:
+ * the reader dismissed the thing and is looking at what is behind it, so every
+ * millisecond the leaving element still owns the screen is a millisecond of
+ * waiting. Half the time, on the same ease-out — a symmetric curve would
+ * start the exit slowly, which is the one place a dismissal must not lag.
+ *
+ * Only the *clock* is here, never `animation-name`. Each Chakra recipe already
+ * names the right movement for its part — the menu slides from its trigger,
+ * the popover scales from its origin, the collapsible interpolates the `--height`
+ * Ark measures — and those names are the one thing a shared policy must not
+ * overwrite. Declaring the timing and nothing else lets the same preset sit on
+ * six unrelated parts: our longhands land in the `styles` layer and beat the
+ * recipe's per property, while `animation-name`, which we never declare, falls
+ * through untouched. A preset that also set the name would have flattened the
+ * collapsible's height animation into a fade.
+ *
+ * Reduced motion keeps a plain fade rather than zeroing the duration, for the
+ * reason the Modal already had one: a surface that appears with no transition
+ * at all reads as a page swap. The movement is what has to go, not the fact
+ * that something changed.
+ */
+export declare const PRESENCE_TIMING: {
+    readonly _open: {
+        readonly animationDuration: "motion.base";
+        readonly animationTimingFunction: "emphasized";
+    };
+    readonly _closed: {
+        readonly animationDuration: "fast";
+        readonly animationTimingFunction: "emphasized";
+    };
+    readonly _motionReduce: {
+        readonly _open: {
+            readonly animationName: "fade-in";
+        };
+        readonly _closed: {
+            readonly animationName: "fade-out";
+        };
+    };
+};
+/**
+ * Dash length for the `checkmark-draw` keyframe. Declared once so the pattern
+ * the tick is hidden behind and the offset the keyframe animates away are the
+ * same number. Chakra's polyline measures ~22.6 user units; 24 clears it.
+ */
+export declare const CHECKMARK_DASH = 24;
+/**
+ * The motion vocabulary — four intents, plus two escape hatches.
+ *
+ * Applied as `animationStyle="<name>"`, the same shape as `textStyle="h3"`, so
+ * a consuming app can remap one in its own config without forking anything.
+ *
+ * Each transition preset leaves `transition-property` at `none` and expects the
+ * call site to name what moves, because that part genuinely varies per element —
+ * the Switch moves its thumb, the ProgressBar its width. `none` rather than an
+ * omission is deliberate: CSS defaults `transition-property` to `all`, so a
+ * preset with no property would quietly animate every property on the element
+ * (this is how Button once animated a consumer's width and padding on hover).
+ * Forgetting the prop now means *nothing* moves, which is visible, instead of
+ * *everything* moving, which is not.
+ *
+ * ```tsx
+ * <SegmentGroup.Indicator animationStyle="travel" transitionProperty="left, width" />
+ * ```
+ */
+export declare const animationStyles: {
+    press: {
+        value: {
+            _motionReduce: {
+                transitionDuration: string;
+            };
+            transitionProperty: "scale";
+            transitionDuration: "motion.press";
+            transitionTimingFunction: "emphasized";
+        };
+    };
+    feedback: {
+        value: {
+            _motionReduce: {
+                transitionDuration: string;
+            };
+            transitionProperty: "none";
+            transitionDuration: "fast";
+            transitionTimingFunction: "standard";
+        };
+    };
+    travel: {
+        value: {
+            _motionReduce: {
+                transitionDuration: string;
+            };
+            transitionProperty: "none";
+            transitionDuration: "motion.base";
+            transitionTimingFunction: "emphasized";
+        };
+    };
+    spring: {
+        value: {
+            _motionReduce: {
+                transitionDuration: string;
+            };
+            transitionProperty: "none";
+            transitionDuration: "motion.base";
+            transitionTimingFunction: "overshoot";
+        };
+    };
+    /**
+     * For an element that needs two clocks at once, which a single duration cannot
+     * express — `Button` presses on `motion.press` while its colour and shadow run
+     * on `fast`. Write the composed `transition` shorthand yourself and take the
+     * reduced-motion guard from here.
+     */
+    composite: {
+        value: {
+            _motionReduce: {
+                transition: "none";
+            };
+        };
+    };
+    /**
+     * The enter/exit clock, for any part that has an open and a closed state.
+     *
+     * Applied as `animationStyle="presence"` to a Chakra or Ark presence part —
+     * menu content, popover, tooltip, select content, collapsible content — it
+     * retimes what that part already does without touching *what* it does. See
+     * {@link PRESENCE_TIMING} for why the ratio is what it is and why the preset
+     * deliberately declares no `animation-name`.
+     *
+     * Not every surface with an open state is reachable this way. Chakra's toast
+     * moves on a `transition` shorthand rather than a keyframe animation, so an
+     * `animation-*` clock lands on it and does nothing at all — retiming that one
+     * means rewriting the shorthand, which is a `composite` job and a separate
+     * decision.
+     */
+    presence: {
+        value: {
+            _open: {
+                readonly animationDuration: "motion.base";
+                readonly animationTimingFunction: "emphasized";
+            };
+            _closed: {
+                readonly animationDuration: "fast";
+                readonly animationTimingFunction: "emphasized";
+            };
+            _motionReduce: {
+                readonly _open: {
+                    readonly animationName: "fade-in";
+                };
+                readonly _closed: {
+                    readonly animationName: "fade-out";
+                };
+            };
+        };
+    };
+    /**
+     * `presence` for a part anchored to its trigger — menu, select, combobox,
+     * popover and tooltip content. 200ms in, 100ms out; see
+     * {@link ANCHORED_PRESENCE_TIMING}.
+     */
+    'presence-anchored': {
+        value: {
+            _open: {
+                readonly animationDuration: "moderate";
+                readonly animationTimingFunction: "emphasized";
+            };
+            _closed: {
+                readonly animationDuration: "faster";
+                readonly animationTimingFunction: "emphasized";
+            };
+            _motionReduce: {
+                readonly _open: {
+                    readonly animationName: "fade-in";
+                };
+                readonly _closed: {
+                    readonly animationName: "fade-out";
+                };
+            };
+        };
+    };
+    /**
+     * List items arriving one after another instead of all at once.
+     *
+     * Applied through {@link staggerProps}, which supplies the per-item
+     * `--stagger-index`; this preset supplies everything else, including the cap.
+     *
+     * **An animation, not a `transition-delay`.** A transition needs a previous
+     * value to interpolate from, and a list item that has just mounted has none,
+     * so the delay would have nothing to delay. Worse, `transition-delay` is
+     * unconditional: it applies to *every* later property change on that element,
+     * so a hover would wait its index out, and a filter keystroke that re-renders
+     * the list would re-delay all of it. An `animation` runs once, when the
+     * element mounts — which is precisely the enter, and only the enter.
+     *
+     * For a part that stays mounted while closed (Ark keeps menu and select
+     * content in the DOM after the first open), mounting is not enough on its own,
+     * so the closed branch parks `animation-name` at `none`. Reopening flips the
+     * name back and a changed `animation-name` restarts the animation — the same
+     * gate, expressed in the only vocabulary CSS has for "again".
+     */
+    stagger: {
+        value: {
+            '--stagger-max': string;
+            animationName: "stagger-in";
+            animationDuration: "motion.base";
+            animationTimingFunction: "emphasized";
+            animationFillMode: "both";
+            animationDelay: "calc(min(var(--stagger-index, 0), var(--stagger-max)) * var(--chakra-durations-motion-stagger-step))";
+            '[data-state="closed"] &': {
+                animationName: "none";
+            };
+            _motionReduce: {
+                animationName: "none";
+                animationDelay: "0ms";
+            };
+        };
+    };
+};
+/** Every name `animationStyle` accepts from this theme. */
+export type MotionStyleToken = keyof typeof animationStyles;
+/**
+ * Keyframes owned by the motion layer.
+ *
+ * Chakra's checkmark is already stroke-based (`fill: none`,
+ * `stroke: currentColor`, `polyline points="20 6 9 17 4 12"`), so a dash offset
+ * draws it without swapping in a custom icon.
+ */
+export declare const keyframes: {
+    'modal-in': {
+        from: {
+            opacity: string;
+            scale: string;
+            translate: string;
+        };
+        to: {
+            opacity: string;
+            scale: string;
+            translate: string;
+        };
+    };
+    'modal-out': {
+        from: {
+            opacity: string;
+            scale: string;
+        };
+        to: {
+            opacity: string;
+            scale: string;
+        };
+    };
+    'dot-pop': {
+        from: {
+            scale: string;
+            opacity: string;
+        };
+        to: {
+            scale: string;
+            opacity: string;
+        };
+    };
+    'checkmark-draw': {
+        from: {
+            strokeDashoffset: string;
+        };
+        to: {
+            strokeDashoffset: string;
+        };
+    };
+    indeterminate: {
+        from: {
+            translate: string;
+        };
+        to: {
+            translate: string;
+        };
+    };
+    'stagger-in': {
+        from: {
+            opacity: string;
+            translate: string;
+        };
+        to: {
+            opacity: string;
+            translate: string;
+        };
+    };
+    'appear-in': {
+        from: {
+            opacity: string;
+            scale: string;
+            translate: string;
+        };
+        to: {
+            opacity: string;
+            scale: string;
+            translate: string;
+        };
+    };
+    'shake-x': {
+        '0%, 100%': {
+            translate: string;
+        };
+        '20%': {
+            translate: string;
+        };
+        '40%': {
+            translate: string;
+        };
+        '60%': {
+            translate: string;
+        };
+        '80%': {
+            translate: string;
+        };
+    };
+    /** Identical to `shake-x` — see `pulse-pop-alt` for why there are two. */
+    'shake-x-alt': {
+        '0%, 100%': {
+            translate: string;
+        };
+        '20%': {
+            translate: string;
+        };
+        '40%': {
+            translate: string;
+        };
+        '60%': {
+            translate: string;
+        };
+        '80%': {
+            translate: string;
+        };
+    };
+    'reveal-open': {
+        from: {
+            gridTemplateRows: string;
+            opacity: string;
+        };
+        to: {
+            gridTemplateRows: string;
+            opacity: string;
+        };
+    };
+    'swap-in': {
+        from: {
+            opacity: string;
+            translate: string;
+        };
+        to: {
+            opacity: string;
+            translate: string;
+        };
+    };
+    'swap-out': {
+        from: {
+            opacity: string;
+            translate: string;
+        };
+        to: {
+            opacity: string;
+            translate: string;
+        };
+    };
+    'pulse-pop': {
+        '0%': {
+            scale: string;
+        };
+        '50%': {
+            scale: string;
+        };
+        '100%': {
+            scale: string;
+        };
+    };
+    /**
+     * Byte-identical to `pulse-pop`, and that is the whole point.
+     *
+     * A CSS animation restarts when its *name* changes. `Pulse` alternates
+     * between the two on each replay, which restarts the pop without remounting
+     * anything — the earlier approach, a changed React `key`, threw away the
+     * subtree and with it the user's focus and any uncontrolled state inside.
+     * Two names is the price of not doing that.
+     */
+    'pulse-pop-alt': {
+        '0%': {
+            scale: string;
+        };
+        '50%': {
+            scale: string;
+        };
+        '100%': {
+            scale: string;
+        };
+    };
+    'fly-arc': {
+        '0%': {
+            translate: string;
+            scale: string;
+            opacity: string;
+        };
+        '50%': {
+            translate: string;
+            scale: string;
+            opacity: string;
+        };
+        '100%': {
+            translate: string;
+            scale: string;
+            opacity: string;
+        };
+    };
+    'confetti-fall': {
+        '0%': {
+            translate: string;
+            rotate: string;
+            opacity: string;
+        };
+        '65%': {
+            opacity: string;
+        };
+        '100%': {
+            translate: string;
+            rotate: string;
+            opacity: string;
+        };
+    };
+};
+/**
+ * The duration scale in milliseconds, for animation tech that cannot read a CSS
+ * variable — framer-motion, `Element.animate`, `setTimeout`-driven sequences.
+ *
+ * Includes `fast` (150) and `moderate` (200), which have no `motion.*` token
+ * because Chakra already provides them: a JS consumer still needs the numbers.
+ */
+export declare const MOTION_DURATION_MS: {
+    readonly instant: 0;
+    readonly beat: 60;
+    readonly press: 120;
+    readonly fast: 150;
+    readonly moderate: 200;
+    readonly base: 300;
+    readonly slow: 500;
+    readonly slower: 700;
+    readonly celebrateBurst: 900;
+    readonly celebrateFall: 1800;
+    readonly loopTurn: 650;
+    readonly loopSweep: 1800;
+    readonly staggerStep: 35;
+};
+export type MotionDurationToken = keyof typeof MOTION_DURATION_MS;
+/** The same scale in seconds — framer-motion's `transition.duration` unit. */
+export declare const MOTION_DURATION_S: {
+    readonly instant: 0;
+    readonly beat: 0.06;
+    readonly press: 0.12;
+    readonly fast: 0.15;
+    readonly moderate: 0.2;
+    readonly base: 0.3;
+    readonly slow: 0.5;
+    readonly slower: 0.7;
+    readonly celebrateBurst: 0.9;
+    readonly celebrateFall: 1.8;
+    readonly loopTurn: 0.65;
+    readonly loopSweep: 1.8;
+    readonly staggerStep: 0.035;
+};
+/**
+ * The curves as `[x1, y1, x2, y2]` tuples — the shape framer-motion's `ease`
+ * prop accepts directly.
+ */
+export declare const MOTION_EASE: {
+    readonly standard: readonly [0.4, 0, 0.2, 1];
+    readonly emphasized: readonly [0.22, 1, 0.36, 1];
+    readonly overshoot: readonly [0.34, 1.56, 0.64, 1];
+};
+export type MotionEaseToken = keyof typeof MOTION_EASE;
+/**
+ * The same curves as CSS strings, for the rare case where the `easings` token
+ * cannot be reached (a keyframes string assembled outside a Chakra style
+ * context). Prefer `var(--chakra-easings-emphasized)` where a variable resolves.
+ */
+export declare const MOTION_EASE_CSS: Record<MotionEaseToken, string>;
+//# sourceMappingURL=motion.d.ts.map

package/dist/theme/motion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"motion.d.ts","sourceRoot":"","sources":["../../src/theme/motion.ts"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;GAGG;AACH,eAAO,MAAM,SAAS;;QAMlB,uEAAuE;;;;QAEvE;;;;;;WAMG;;;;QAEH,+EAA+E;;;;QAE/E,kDAAkD;;;;QAElD,yDAAyD;;;;QAEzD,yCAAyC;;;;QAEzC;;;;;;;;;;;;WAYG;;YAED,uEAAuE;;;;YAEvE;;;;;eAKG;;;;;QAGL;;;;;;;;;;WAUG;;YAED,4EAA4E;;;;YAE5E,0DAA0D;;;;;;YAI1D;;;;;;;;;eASG;;;;;;CAIR,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;CAInB,CAAC;AAeF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;CAalB,CAAC;AAuBX;;;;GAIG;AACH,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAwC1B;;;;;OAKG;;;;;;;;IAKH;;;;;;;;;;;;;;OAcG;;;;;;;;;;;;;;;;;;;;;IAKH;;;;OAIG;;;;;;;;;;;;;;;;;;;;;IAKH;;;;;;;;;;;;;;;;;;;OAmBG;;;;;;;;;;;;;;;;;;CAsBkC,CAAC;AAExC,2DAA2D;AAC3D,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,eAAe,CAAC;AAE5D;;;;;;GAMG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA6FpB,0EAA0E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAkD1E;;;;;;;;OAQG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+DJ,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;CAcrB,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,kBAAkB,CAAC;AAElE,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;CAcpB,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,WAAW;;;;CAId,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,WAAW,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAI3D,CAAC"}