kang-components 0.2.0 → 0.4.0

package/dist/animated-text.d.ts

@@ -0,0 +1,49 @@
+/**
+ * AnimatedText — a domain-free cross-fading text cycler.
+ *
+ * Shows one of several string `variants`, periodically cross-fading to the next
+ * (a swap at the opacity-0 midpoint via react-spring's `onRest`). With two
+ * variants it simply toggles back and forth; with more it rotates in order.
+ *
+ * Domain-free: it knows nothing about languages, characters, or app state. The
+ * consumer decides what the variants are (e.g. an i18n layer maps its own
+ * language model down to `variants` + `staticIndex`). This keeps the multilingual
+ * knowledge in the app and the motion mechanics here.
+ *
+ * Layout never reflows during a swap: every candidate string is also rendered as
+ * a hidden sizer span stacked in the same grid cell, so the box is always sized
+ * to the widest candidate. Pass `sizers` when the set of strings that must fit is
+ * wider than the visible `variants` (e.g. the variants you cycle are a subset of
+ * all possible values).
+ *
+ * react-spring is used deliberately (not CSS): the text swap must happen exactly
+ * at the fade's midpoint, which needs `onRest`. This matches the project's
+ * CSS-first animation policy, which routes "animations requiring onRest" to
+ * react-spring. `@react-spring/web` and `react` are optional peer dependencies —
+ * only this module pulls them in.
+ */
+import { CSSProperties } from 'react';
+export type AnimatedTextProps = {
+    /** Strings to cross-fade between, in order. Two → toggle; more → rotate. */
+    variants: string[];
+    /** Cycle through variants (true) or hold a single static variant (false). Default true. */
+    animate?: boolean;
+    /** Which variant to show when `animate` is false. Default 0. */
+    staticIndex?: number;
+    /**
+     * Strings reserved (rendered hidden) purely to size the box so it never
+     * reflows mid-swap. Defaults to `variants`. Provide a wider set when the
+     * cycled variants are a subset of all possible values.
+     */
+    sizers?: string[];
+    /** Start at opacity 0 and fade in on mount. */
+    fadeIn?: boolean;
+    /** Maximum ms between cross-fade cycles (the minimum is 3500). Default 15000. */
+    maxDelay?: number;
+    /** Element to render the text grid as. Default 'div'. */
+    htmlElement?: keyof JSX.IntrinsicElements;
+    /** Styles for the text; font-related props are applied to every (visible + sizer) span. */
+    textStyles?: CSSProperties;
+};
+export default function AnimatedText({ variants, animate, staticIndex, sizers, fadeIn, maxDelay, htmlElement, textStyles, }: AnimatedTextProps): import("react").JSX.Element;
+//# sourceMappingURL=animated-text.d.ts.map

package/dist/animated-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animated-text.d.ts","sourceRoot":"","sources":["../src/animated-text.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAiB,aAAa,EAA+B,MAAM,OAAO,CAAC;AAGlF,MAAM,MAAM,iBAAiB,GAAG;IAC/B,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,2FAA2F;IAC3F,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,GAAG,CAAC,iBAAiB,CAAC;IAC1C,2FAA2F;IAC3F,UAAU,CAAC,EAAE,aAAa,CAAC;CAC3B,CAAC;AAKF,MAAM,CAAC,OAAO,UAAU,YAAY,CAAC,EACpC,QAAQ,EACR,OAAc,EACd,WAAe,EACf,MAAM,EACN,MAAc,EACd,QAAgB,EAChB,WAAmB,EACnB,UAAU,GACV,EAAE,iBAAiB,+BAwDnB"}

package/dist/animated-text.js

@@ -0,0 +1,70 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * AnimatedText — a domain-free cross-fading text cycler.
+ *
+ * Shows one of several string `variants`, periodically cross-fading to the next
+ * (a swap at the opacity-0 midpoint via react-spring's `onRest`). With two
+ * variants it simply toggles back and forth; with more it rotates in order.
+ *
+ * Domain-free: it knows nothing about languages, characters, or app state. The
+ * consumer decides what the variants are (e.g. an i18n layer maps its own
+ * language model down to `variants` + `staticIndex`). This keeps the multilingual
+ * knowledge in the app and the motion mechanics here.
+ *
+ * Layout never reflows during a swap: every candidate string is also rendered as
+ * a hidden sizer span stacked in the same grid cell, so the box is always sized
+ * to the widest candidate. Pass `sizers` when the set of strings that must fit is
+ * wider than the visible `variants` (e.g. the variants you cycle are a subset of
+ * all possible values).
+ *
+ * react-spring is used deliberately (not CSS): the text swap must happen exactly
+ * at the fade's midpoint, which needs `onRest`. This matches the project's
+ * CSS-first animation policy, which routes "animations requiring onRest" to
+ * react-spring. `@react-spring/web` and `react` are optional peer dependencies —
+ * only this module pulls them in.
+ */
+import { createElement, useEffect, useRef, useState } from 'react';
+import { animated, useSpring } from '@react-spring/web';
+const MIN_DELAY = 3500;
+const FIRST_CYCLE_DELAY = 500;
+export default function AnimatedText({ variants, animate = true, staticIndex = 0, sizers, fadeIn = false, maxDelay = 15000, htmlElement = 'div', textStyles, }) {
+    const [cycle, setCycle] = useState(0);
+    const [spring, springApi] = useSpring(() => ({
+        opacity: fadeIn ? 0 : 1,
+        config: { duration: 600 },
+    }));
+    const wasAnimating = useRef(animate);
+    useEffect(() => {
+        if (!animate) {
+            wasAnimating.current = animate;
+            return;
+        }
+        const justActivated = !wasAnimating.current && animate;
+        wasAnimating.current = animate;
+        const delay = justActivated
+            ? FIRST_CYCLE_DELAY
+            : Math.floor(Math.random() * (maxDelay - MIN_DELAY + 1)) + MIN_DELAY;
+        const timer = setTimeout(() => {
+            springApi.start({
+                opacity: 0,
+                onRest: () => {
+                    setCycle((c) => c + 1);
+                    springApi.start({ opacity: 1 });
+                },
+            });
+        }, delay);
+        return () => clearTimeout(timer);
+    }, [cycle, animate, springApi, maxDelay]);
+    const count = variants.length || 1;
+    const visibleText = animate
+        ? variants[cycle % count]
+        : variants[staticIndex] ?? variants[0];
+    const { fontSize, fontFamily, fontWeight, fontStyle, letterSpacing, lineHeight, ...rest } = textStyles || {};
+    const fontStyles = { fontSize, fontFamily, fontWeight, fontStyle, letterSpacing, lineHeight };
+    const gridStyle = { ...rest, display: 'inline-grid', alignContent: 'center' };
+    const visibleStyle = { ...fontStyles, gridArea: '1 / 1' };
+    const hiddenStyle = { ...fontStyles, gridArea: '1 / 1', visibility: 'hidden' };
+    const sizerStrings = sizers ?? variants;
+    return (_jsx(animated.div, { style: { ...spring, display: 'inline-block' }, children: createElement(htmlElement, { style: gridStyle }, createElement('span', { style: visibleStyle, key: 'visible' }, visibleText), ...sizerStrings.map((s, i) => createElement('span', { style: hiddenStyle, key: `sizer-${i}`, 'aria-hidden': true }, s))) }));
+}
+//# sourceMappingURL=animated-text.js.map

package/dist/animated-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"animated-text.js","sourceRoot":"","sources":["../src/animated-text.tsx"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,4 +1,10 @@
 export { BOUNCE_CURVE, PRESS_SCALE_PRIMARY, PRESS_SCALE_SUBTLE, pressPrimary, pressSubtle, pressPrimaryScale, pressSubtleScale, } from './press.js';
 export { useAnimatedAction } from './use-animated-action.js';
 export { actionSheetContainer, actionSheetList, actionSheetRow, } from './action-sheet.js';
+export { Ripple, rippleAnimation, useRipple } from './ripple.js';
+export type { RippleState } from './ripple.js';
+export { SPRING_COMFORTABLE, SPRING_COMFORTABLE_SLOW, SPRING_SNAPPY, SPRING_RESPONSIVE, SPRING_STAGGERED, SPRING_INSTANT, SPRING_GENTLE, SPRING_VERY_SLOW, SPRING_LANDING, SPRING_RISING, } from './spring.js';
+export type { SpringConfigConstant } from './spring.js';
+export { default as AnimatedText } from './animated-text.js';
+export type { AnimatedTextProps } from './animated-text.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,gBAAgB,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,OAAO,EACN,oBAAoB,EACpB,eAAe,EACf,cAAc,GACd,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,gBAAgB,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,OAAO,EACN,oBAAoB,EACpB,eAAe,EACf,cAAc,GACd,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACjE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EACN,kBAAkB,EAClB,uBAAuB,EACvB,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,aAAa,GACb,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAExD,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC7D,YAAY,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -1,4 +1,7 @@
 export { BOUNCE_CURVE, PRESS_SCALE_PRIMARY, PRESS_SCALE_SUBTLE, pressPrimary, pressSubtle, pressPrimaryScale, pressSubtleScale, } from './press.js';
 export { useAnimatedAction } from './use-animated-action.js';
 export { actionSheetContainer, actionSheetList, actionSheetRow, } from './action-sheet.js';
+export { Ripple, rippleAnimation, useRipple } from './ripple.js';
+export { SPRING_COMFORTABLE, SPRING_COMFORTABLE_SLOW, SPRING_SNAPPY, SPRING_RESPONSIVE, SPRING_STAGGERED, SPRING_INSTANT, SPRING_GENTLE, SPRING_VERY_SLOW, SPRING_LANDING, SPRING_RISING, } from './spring.js';
+export { default as AnimatedText } from './animated-text.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,gBAAgB,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,OAAO,EACN,oBAAoB,EACpB,eAAe,EACf,cAAc,GACd,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,gBAAgB,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,OAAO,EACN,oBAAoB,EACpB,eAAe,EACf,cAAc,GACd,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGjE,OAAO,EACN,kBAAkB,EAClB,uBAAuB,EACvB,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,aAAa,GACb,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/ripple.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Material-style ripple — a domain-free press-feedback overlay.
+ *
+ * Two pieces that work together:
+ * - `useRipple<T>()` — a pure React hook that tracks the active ripple's
+ *   position and which target fired it. `trigger(event, target)` records the
+ *   click point relative to the element; `isTarget(value)` tells a given
+ *   element whether it owns the current ripple.
+ * - `Ripple` — a styled `<span>` placed inside the (relatively-positioned)
+ *   pressable element. Give it `key={ripple.key}` so each press restarts the
+ *   animation, and `$x`/`$y` from the ripple state.
+ *
+ * The fill reads `theme.colors.ripple` (a generic styling token, not app
+ * domain) and falls back to `rgba(0, 0, 0, 0.1)` when absent — so it works with
+ * or without a themed `ThemeProvider`.
+ *
+ * `styled-components` is an optional peer dependency, used only by this module;
+ * consumers that import only the press / action-sheet string primitives never
+ * pull it in.
+ */
+import { type MouseEvent } from 'react';
+export interface RippleState<T> {
+    x: number;
+    y: number;
+    key: number;
+    target: T;
+}
+export declare const rippleAnimation: import("styled-components/dist/models/Keyframes").default;
+export declare const Ripple: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("styled-components").FastOmit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "$x" | "$y"> & {
+    $x: number;
+    $y: number;
+}, never> & Partial<Pick<import("styled-components").FastOmit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "$x" | "$y"> & {
+    $x: number;
+    $y: number;
+}, never>>> & string;
+export declare function useRipple<T>(): {
+    ripple: RippleState<T> | null;
+    trigger: (e: MouseEvent<HTMLElement>, target: T) => void;
+    isTarget: (value: T) => boolean;
+};
+//# sourceMappingURL=ripple.d.ts.map

package/dist/ripple.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ripple.d.ts","sourceRoot":"","sources":["../src/ripple.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAyB,KAAK,UAAU,EAAE,MAAM,OAAO,CAAC;AAM/D,MAAM,WAAW,WAAW,CAAC,CAAC;IAC7B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,CAAC,CAAC;CACV;AAED,eAAO,MAAM,eAAe,2DAS3B,CAAC;AAEF,eAAO,MAAM,MAAM;QAAqB,MAAM;QAAM,MAAM;;QAAlB,MAAM;QAAM,MAAM;oBAazD,CAAC;AAEF,wBAAgB,SAAS,CAAC,CAAC;;iBAGM,UAAU,CAAC,WAAW,CAAC,UAAU,CAAC;sBAWzD,CAAC;EAKV"}

package/dist/ripple.js

@@ -0,0 +1,63 @@
+/**
+ * Material-style ripple — a domain-free press-feedback overlay.
+ *
+ * Two pieces that work together:
+ * - `useRipple<T>()` — a pure React hook that tracks the active ripple's
+ *   position and which target fired it. `trigger(event, target)` records the
+ *   click point relative to the element; `isTarget(value)` tells a given
+ *   element whether it owns the current ripple.
+ * - `Ripple` — a styled `<span>` placed inside the (relatively-positioned)
+ *   pressable element. Give it `key={ripple.key}` so each press restarts the
+ *   animation, and `$x`/`$y` from the ripple state.
+ *
+ * The fill reads `theme.colors.ripple` (a generic styling token, not app
+ * domain) and falls back to `rgba(0, 0, 0, 0.1)` when absent — so it works with
+ * or without a themed `ThemeProvider`.
+ *
+ * `styled-components` is an optional peer dependency, used only by this module;
+ * consumers that import only the press / action-sheet string primitives never
+ * pull it in.
+ */
+import { useCallback, useState } from 'react';
+// Named imports (not the default) so this resolves consistently across bundler
+// and raw ESM/CJS environments — styled-components v6's default export is the
+// CJS namespace under Node's interop, where `styled.span` is undefined.
+import { styled, keyframes } from 'styled-components';
+export const rippleAnimation = keyframes `
+	0% {
+		transform: scale(0);
+		opacity: 0.6;
+	}
+	100% {
+		transform: scale(10);
+		opacity: 0;
+	}
+`;
+export const Ripple = styled.span `
+	position: absolute;
+	left: ${({ $x }) => $x}px;
+	top: ${({ $y }) => $y}px;
+	width: 50px;
+	height: 50px;
+	margin-left: -25px;
+	margin-top: -25px;
+	border-radius: 50%;
+	background-color: ${({ theme }) => theme?.colors?.ripple ?? 'rgba(0, 0, 0, 0.1)'};
+	pointer-events: none;
+	animation: ${rippleAnimation} 0.4s ease-out forwards;
+`;
+export function useRipple() {
+    const [ripple, setRipple] = useState(null);
+    const trigger = useCallback((e, target) => {
+        const rect = e.currentTarget.getBoundingClientRect();
+        setRipple({
+            x: e.clientX - rect.left,
+            y: e.clientY - rect.top,
+            key: Date.now(),
+            target,
+        });
+    }, []);
+    const isTarget = useCallback((value) => ripple !== null && ripple.target === value, [ripple]);
+    return { ripple, trigger, isTarget };
+}
+//# sourceMappingURL=ripple.js.map

package/dist/ripple.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ripple.js","sourceRoot":"","sources":["../src/ripple.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAmB,MAAM,OAAO,CAAC;AAC/D,+EAA+E;AAC/E,8EAA8E;AAC9E,wEAAwE;AACxE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAStD,MAAM,CAAC,MAAM,eAAe,GAAG,SAAS,CAAA;;;;;;;;;CASvC,CAAC;AAEF,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAA4B;;SAEpD,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE;QACf,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE;;;;;;qBAMD,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAChC,KAA0C,EAAE,MAAM,EAAE,MAAM,IAAI,oBAAoB;;cAEvE,eAAe;CAC5B,CAAC;AAEF,MAAM,UAAU,SAAS;IACxB,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAwB,IAAI,CAAC,CAAC;IAElE,MAAM,OAAO,GAAG,WAAW,CAAC,CAAC,CAA0B,EAAE,MAAS,EAAE,EAAE;QACrE,MAAM,IAAI,GAAG,CAAC,CAAC,aAAa,CAAC,qBAAqB,EAAE,CAAC;QACrD,SAAS,CAAC;YACT,CAAC,EAAE,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,IAAI;YACxB,CAAC,EAAE,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG;YACvB,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE;YACf,MAAM;SACN,CAAC,CAAC;IACJ,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,QAAQ,GAAG,WAAW,CAC3B,CAAC,KAAQ,EAAE,EAAE,CAAC,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,MAAM,KAAK,KAAK,EACxD,CAAC,MAAM,CAAC,CACR,CAAC;IAEF,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AACtC,CAAC"}

package/dist/spring.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared spring-animation configuration constants — the generic motion
+ * vocabulary for Kang consumers.
+ *
+ * Domain-free and dependency-free: each constant is a plain
+ * `{ tension, friction, mass? }` object. That shape is structurally
+ * assignable to `@react-spring/web`'s `SpringConfig` (whose fields are all
+ * optional), so a consumer can pass these straight into `useSpring`/`api.start`
+ * `config:` without Kang taking a react-spring dependency.
+ *
+ * These mirror the presets that previously lived in `ymy-components` so feel is
+ * identical across apps. Use the named constant instead of an inline literal so
+ * every animation shares one tuned set of physics.
+ */
+/** A react-spring-compatible spring physics config (mass defaults to 1 in react-spring). */
+export interface SpringConfigConstant {
+    tension: number;
+    friction: number;
+    mass?: number;
+}
+/** Base comfortable config — smooth, relaxed animations. */
+export declare const SPRING_COMFORTABLE: SpringConfigConstant;
+/** Slower comfortable variant for background/gradient transitions. */
+export declare const SPRING_COMFORTABLE_SLOW: SpringConfigConstant;
+/** Snappy config — quick, responsive animations. */
+export declare const SPRING_SNAPPY: SpringConfigConstant;
+/** Responsive config — for UI elements that need quick feedback. */
+export declare const SPRING_RESPONSIVE: SpringConfigConstant;
+/** Staggered/lagged config — for cascading animations. */
+export declare const SPRING_STAGGERED: SpringConfigConstant;
+/** Instant config — near-immediate transitions. */
+export declare const SPRING_INSTANT: SpringConfigConstant;
+/** Gentle config — subtle, unobtrusive animations. */
+export declare const SPRING_GENTLE: SpringConfigConstant;
+/** Very slow config — for delayed/transitional animations. */
+export declare const SPRING_VERY_SLOW: SpringConfigConstant;
+/** Landing config — for "settling" hero animations with slight overshoot. */
+export declare const SPRING_LANDING: SpringConfigConstant;
+/** Rising config — for reverse hero animations, smoother deceleration. */
+export declare const SPRING_RISING: SpringConfigConstant;
+//# sourceMappingURL=spring.d.ts.map

package/dist/spring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spring.d.ts","sourceRoot":"","sources":["../src/spring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,4FAA4F;AAC5F,MAAM,WAAW,oBAAoB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED,4DAA4D;AAC5D,eAAO,MAAM,kBAAkB,EAAE,oBAAqD,CAAC;AAEvF,sEAAsE;AACtE,eAAO,MAAM,uBAAuB,EAAE,oBAAqD,CAAC;AAE5F,oDAAoD;AACpD,eAAO,MAAM,aAAa,EAAE,oBAAqD,CAAC;AAElF,oEAAoE;AACpE,eAAO,MAAM,iBAAiB,EAAE,oBAAqD,CAAC;AAEtF,0DAA0D;AAC1D,eAAO,MAAM,gBAAgB,EAAE,oBAAqD,CAAC;AAErF,mDAAmD;AACnD,eAAO,MAAM,cAAc,EAAE,oBAAqD,CAAC;AAEnF,sDAAsD;AACtD,eAAO,MAAM,aAAa,EAAE,oBAAqD,CAAC;AAElF,8DAA8D;AAC9D,eAAO,MAAM,gBAAgB,EAAE,oBAAoD,CAAC;AAEpF,6EAA6E;AAC7E,eAAO,MAAM,cAAc,EAAE,oBAA8D,CAAC;AAE5F,0EAA0E;AAC1E,eAAO,MAAM,aAAa,EAAE,oBAA8D,CAAC"}

package/dist/spring.js

@@ -0,0 +1,35 @@
+/**
+ * Shared spring-animation configuration constants — the generic motion
+ * vocabulary for Kang consumers.
+ *
+ * Domain-free and dependency-free: each constant is a plain
+ * `{ tension, friction, mass? }` object. That shape is structurally
+ * assignable to `@react-spring/web`'s `SpringConfig` (whose fields are all
+ * optional), so a consumer can pass these straight into `useSpring`/`api.start`
+ * `config:` without Kang taking a react-spring dependency.
+ *
+ * These mirror the presets that previously lived in `ymy-components` so feel is
+ * identical across apps. Use the named constant instead of an inline literal so
+ * every animation shares one tuned set of physics.
+ */
+/** Base comfortable config — smooth, relaxed animations. */
+export const SPRING_COMFORTABLE = { tension: 200, friction: 25 };
+/** Slower comfortable variant for background/gradient transitions. */
+export const SPRING_COMFORTABLE_SLOW = { tension: 150, friction: 25 };
+/** Snappy config — quick, responsive animations. */
+export const SPRING_SNAPPY = { tension: 325, friction: 30 };
+/** Responsive config — for UI elements that need quick feedback. */
+export const SPRING_RESPONSIVE = { tension: 300, friction: 30 };
+/** Staggered/lagged config — for cascading animations. */
+export const SPRING_STAGGERED = { tension: 750, friction: 30 };
+/** Instant config — near-immediate transitions. */
+export const SPRING_INSTANT = { tension: 900, friction: 30 };
+/** Gentle config — subtle, unobtrusive animations. */
+export const SPRING_GENTLE = { tension: 185, friction: 25 };
+/** Very slow config — for delayed/transitional animations. */
+export const SPRING_VERY_SLOW = { tension: 50, friction: 20 };
+/** Landing config — for "settling" hero animations with slight overshoot. */
+export const SPRING_LANDING = { tension: 280, friction: 22, mass: 1 };
+/** Rising config — for reverse hero animations, smoother deceleration. */
+export const SPRING_RISING = { tension: 220, friction: 26, mass: 1 };
+//# sourceMappingURL=spring.js.map

package/dist/spring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spring.js","sourceRoot":"","sources":["../src/spring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH,4DAA4D;AAC5D,MAAM,CAAC,MAAM,kBAAkB,GAAyB,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;AAEvF,sEAAsE;AACtE,MAAM,CAAC,MAAM,uBAAuB,GAAyB,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;AAE5F,oDAAoD;AACpD,MAAM,CAAC,MAAM,aAAa,GAAyB,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;AAElF,oEAAoE;AACpE,MAAM,CAAC,MAAM,iBAAiB,GAAyB,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;AAEtF,0DAA0D;AAC1D,MAAM,CAAC,MAAM,gBAAgB,GAAyB,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;AAErF,mDAAmD;AACnD,MAAM,CAAC,MAAM,cAAc,GAAyB,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;AAEnF,sDAAsD;AACtD,MAAM,CAAC,MAAM,aAAa,GAAyB,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;AAElF,8DAA8D;AAC9D,MAAM,CAAC,MAAM,gBAAgB,GAAyB,EAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;AAEpF,6EAA6E;AAC7E,MAAM,CAAC,MAAM,cAAc,GAAyB,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AAE5F,0EAA0E;AAC1E,MAAM,CAAC,MAAM,aAAa,GAAyB,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "kang-components",
-	"version": "0.2.0",
-	"description": "Generic, domain-free React UI primitives (CSS-first press feedback, delayed-action hook).",
+	"version": "0.4.0",
+	"description": "Generic, domain-free React UI primitives (CSS-first press feedback, delayed-action hook, spring presets, cross-fading text).",
 	"type": "module",
 	"license": "MIT",
 	"repository": {
@@ -26,16 +26,26 @@
 		"prepublishOnly": "npm run build"
 	},
 	"peerDependencies": {
-		"react": ">=18"
+		"@react-spring/web": ">=9",
+		"react": ">=18",
+		"styled-components": ">=6"
 	},
 	"peerDependenciesMeta": {
+		"@react-spring/web": {
+			"optional": true
+		},
 		"react": {
 			"optional": true
+		},
+		"styled-components": {
+			"optional": true
 		}
 	},
 	"devDependencies": {
+		"@react-spring/web": "^9.7.5",
 		"@types/react": "^18.3.18",
 		"react": "^18.3.1",
+		"styled-components": "^6.1.16",
 		"typescript": "~5.6.2"
 	}
 }