@jcsoftdev/ui 0.1.2 → 0.1.4

package/dist/charts/core/distribution/xy-points.js

@@ -14,7 +14,7 @@ import { ChartFrame } from "../chart-frame.js";
 import { tint } from "../color-scale.js";
 import { ChartDataTable } from "../data-table.js";
 import { formatNumber, resolveFormat } from "../format.js";
-import { useEntryAnimation } from "../motion.js";
+import { fadeKeyframes, useEntryAnimation } from "../motion.js";
 import { TONE_COLORS } from "../palette.js";
 import { formatDate } from "../scales/time.js";
 import { ChartTooltip } from "../tooltip.js";
@@ -633,7 +633,7 @@ function XYPointPlot({
         );
       });
       root.querySelectorAll("[data-trend]").forEach((line) => {
-        line.animate([{ opacity: 0 }, { opacity: 1 }], {
+        line.animate(fadeKeyframes(line), {
           duration: 500,
           delay: 500,
           easing: "ease-out",
@@ -647,7 +647,7 @@ function XYPointPlot({
     wrapRef,
     (root) => {
       root.querySelectorAll("[data-canvas]").forEach((layer) => {
-        layer.animate([{ opacity: 0 }, { opacity: 1 }], {
+        layer.animate(fadeKeyframes(layer), {
           duration: 450,
           easing: "ease-out",
           fill: "backwards"

package/dist/charts/core/motion.d.ts

@@ -19,6 +19,12 @@ export interface EntryAnimationOptions {
 export declare function useEntryAnimation<T extends Element>(ref: RefObject<T | null>, play: (root: T) => void, { disabled, replayKey }?: EntryAnimationOptions): void;
 /** Reveals children left to right by scaling a clip rectangle. */
 export declare function revealClip(element: Element, duration?: number, delay?: number): void;
+/**
+ * Fade-in keyframes that end at the element's own opacity. Ending at 1 would
+ * show a translucent element at full strength, then snap it back when the
+ * animation finishes.
+ */
+export declare function fadeKeyframes(element: Element): Keyframe[];
 /** Fades an element in. */
 export declare function fadeIn(element: Element, duration?: number, delay?: number): void;
 /**

package/dist/charts/core/motion.js

@@ -1,5 +1,6 @@
 "use client";
 import { useEffect, useRef, useState } from "react";
+import { useIsomorphicLayoutEffect } from "./use-chart-size.js";
 const QUERY = "(prefers-reduced-motion: reduce)";
 function useReducedMotion() {
   const [reduced, setReduced] = useState(false);
@@ -21,7 +22,7 @@ function prefersReducedMotion() {
   return typeof window !== "undefined" && !!window.matchMedia?.(QUERY).matches;
 }
 function useEntryAnimation(ref, play, { disabled = false, replayKey } = {}) {
-  useEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     const root = ref.current;
     if (disabled || !root || typeof root.animate !== "function" || prefersReducedMotion()) return;
     play(root);
@@ -35,8 +36,12 @@ function revealClip(element, duration = 900, delay = 0) {
     fill: "backwards"
   });
 }
+function fadeKeyframes(element) {
+  const resting = typeof getComputedStyle === "function" ? getComputedStyle(element).opacity : "1";
+  return [{ opacity: 0 }, { opacity: resting || "1" }];
+}
 function fadeIn(element, duration = 400, delay = 0) {
-  element.animate([{ opacity: 0 }, { opacity: 1 }], {
+  element.animate(fadeKeyframes(element), {
     duration,
     delay,
     easing: "ease-out",
@@ -60,7 +65,7 @@ function useAnimatedNumber(target, {
     const startedAt = performance.now();
     let frame = 0;
     const tick = (now) => {
-      const progress = Math.min(1, (now - startedAt) / duration);
+      const progress = Math.min(1, Math.max(0, (now - startedAt) / duration));
       const eased = 1 - (1 - progress) ** 3;
       setValue(start + (target - start) * eased);
       if (progress < 1) frame = requestAnimationFrame(tick);
@@ -74,6 +79,7 @@ export {
   EASE_OUT,
   easeOutCubic,
   fadeIn,
+  fadeKeyframes,
   revealClip,
   useAnimatedNumber,
   useEntryAnimation,

package/dist/charts/core/use-drill.js

@@ -50,7 +50,7 @@ function useAnimatedView(target, { disabled = false, duration = 650 } = {}) {
     let frame = 0;
     const start = performance.now();
     const step = (now) => {
-      const t = Math.min(1, (now - start) / duration);
+      const t = Math.min(1, Math.max(0, (now - start) / duration));
       const next = interpolateView(from, to, easeOutCubic(t));
       current.current = next;
       setView(next);

package/dist/charts/donut-chart/donut-chart.js

@@ -620,7 +620,7 @@ function useTweenedValues(items, disabled) {
     const started = performance.now();
     let frame = 0;
     const step = (now) => {
-      const t = easeOutCubic(Math.min(1, (now - started) / 700));
+      const t = easeOutCubic(Math.min(1, Math.max(0, (now - started) / 700)));
       const next = {};
       for (const id of Object.keys(target)) {
         const start = from[id] ?? 0;

package/dist/charts/gauge-chart/gauge-chart.js

@@ -6,7 +6,13 @@ import { DECORATIVE } from "../core/a11y.js";
 import { ChartFrame } from "../core/chart-frame.js";
 import { ChartDataTable } from "../core/data-table.js";
 import { resolveFormat } from "../core/format.js";
-import { EASE_OUT, fadeIn, useAnimatedNumber, useEntryAnimation } from "../core/motion.js";
+import {
+  EASE_OUT,
+  fadeIn,
+  fadeKeyframes,
+  useAnimatedNumber,
+  useEntryAnimation
+} from "../core/motion.js";
 import { TONE_COLORS } from "../core/palette.js";
 import { arcLine, degToRad, polarPoint, radToDeg } from "../core/polar.js";
 import { ChartTooltip } from "../core/tooltip.js";
@@ -164,7 +170,7 @@ function GaugePlot({
   );
   const capAngle = roundedCaps ? band / 2 / mid : 0;
   const fraction = toFraction(shown);
-  const active = bands.find((item) => shown >= item.from && shown <= item.to);
+  const active = bands.find((item) => value >= item.from && value <= item.to);
   const valueColor = active ? rangeColor(active) : "var(--accent-word)";
   const progressEnd = a0 + capAngle + (span - 2 * capAngle) * fraction;
   const bandPaths = useMemo(
@@ -202,7 +208,7 @@ function GaugePlot({
     svgRef,
     (root) => {
       root.querySelectorAll("[data-band]").forEach((node, i) => {
-        node.animate([{ opacity: 0 }, { opacity: 1 }], {
+        node.animate(fadeKeyframes(node), {
           duration: 500,
           delay: i * 90,
           easing: EASE_OUT,

package/dist/charts/heatmap-chart/heatmap-grid.js

@@ -8,7 +8,7 @@ import {
   rangeColor,
   scaleGradient
 } from "../core/color-scale.js";
-import { EASE_OUT, useEntryAnimation } from "../core/motion.js";
+import { EASE_OUT, fadeKeyframes, useEntryAnimation } from "../core/motion.js";
 import { ChartTooltip } from "../core/tooltip.js";
 import { DEFAULT_LABELS } from "../core/types.js";
 import { useCanvasPaint } from "../core/use-canvas.js";
@@ -99,7 +99,7 @@ function HeatmapGrid({
     svgRef,
     (element) => {
       element.querySelectorAll("[data-column]").forEach((group, index) => {
-        group.animate([{ opacity: 0 }, { opacity: 1 }], {
+        group.animate(fadeKeyframes(group), {
           duration: 420,
           delay: Math.min(index * (360 / Math.max(1, columns)), 360),
           easing: EASE_OUT,

package/dist/charts/histogram/histogram.js

@@ -18,7 +18,7 @@ import {
 } from "../core/distribution/stats.js";
 import { useDistributionLegend } from "../core/distribution/use-legend.js";
 import { formatNumber, formatPercent, resolveFormat } from "../core/format.js";
-import { EASE_OUT, useEntryAnimation } from "../core/motion.js";
+import { EASE_OUT, fadeKeyframes, useEntryAnimation } from "../core/motion.js";
 import { barPath, linePath } from "../core/path.js";
 import { ChartTooltip } from "../core/tooltip.js";
 function Histogram({
@@ -285,7 +285,7 @@ function HistogramPlot({
         });
       });
       root.querySelectorAll("[data-curve]").forEach((curve) => {
-        curve.animate([{ opacity: 0 }, { opacity: 1 }], {
+        curve.animate(fadeKeyframes(curve), {
           duration: 500,
           delay: 420,
           easing: "ease-out",

package/dist/charts/maps/geo/use-map-view.js

@@ -59,7 +59,7 @@ function useMapView({
       const from = viewRef.current;
       const start = performance.now();
       const step = (now) => {
-        const t = Math.min(1, (now - start) / DURATION);
+        const t = Math.min(1, Math.max(0, (now - start) / DURATION));
         const e = easeOut(t);
         const k = from.k * (goal.k / from.k) ** e;
         apply({ k, x: from.x + (goal.x - from.x) * e, y: from.y + (goal.y - from.y) * e });

package/dist/charts/tree-chart/tree-chart.js

@@ -10,7 +10,7 @@ import {
 import { cn } from "../../utils/cn.js";
 import { ChartFrame } from "../core/chart-frame.js";
 import { ChartDataTable } from "../core/data-table.js";
-import { EASE_OUT, useEntryAnimation } from "../core/motion.js";
+import { EASE_OUT, fadeKeyframes, useEntryAnimation } from "../core/motion.js";
 import { treeFitView } from "../core/tree-fit.js";
 import {
   treeEdgePath,
@@ -388,7 +388,7 @@ function TreePlot({
         );
       });
       root.querySelectorAll("[data-tree-edges]").forEach((element) => {
-        element.animate([{ opacity: 0 }, { opacity: 1 }], {
+        element.animate(fadeKeyframes(element), {
           duration: 500,
           delay: 160,
           easing: "ease-out",

package/dist/charts/tree-chart/use-tree-transition.js

@@ -58,7 +58,7 @@ function useTreeTransition(layout, parentOf, { disabled = false, duration = 360
     let frame = 0;
     const start = performance.now();
     const step = (now) => {
-      const t = Math.min(1, (now - start) / duration);
+      const t = Math.min(1, Math.max(0, (now - start) / duration));
       if (t >= 1) {
         show(final);
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jcsoftdev/ui",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Token-driven React component library: React 19, Radix, Tailwind v4.",
   "author": "jcsoftdev",
   "license": "MIT",

package/src/charts/core/distribution/xy-points.tsx

@@ -17,7 +17,7 @@ import { ChartFrame } from "../chart-frame.js";
 import { tint } from "../color-scale.js";
 import { ChartDataTable } from "../data-table.js";
 import { formatNumber, resolveFormat, type ValueFormat } from "../format.js";
-import { useEntryAnimation } from "../motion.js";
+import { fadeKeyframes, useEntryAnimation } from "../motion.js";
 import { type ChartTone, TONE_COLORS } from "../palette.js";
 import { formatDate } from "../scales/time.js";
 import { ChartTooltip, type TooltipRow } from "../tooltip.js";
@@ -858,7 +858,7 @@ function XYPointPlot({
         );
       });
       root.querySelectorAll("[data-trend]").forEach((line) => {
-        line.animate([{ opacity: 0 }, { opacity: 1 }], {
+        line.animate(fadeKeyframes(line), {
           duration: 500,
           delay: 500,
           easing: "ease-out",
@@ -873,7 +873,7 @@ function XYPointPlot({
     wrapRef,
     (root) => {
       root.querySelectorAll("[data-canvas]").forEach((layer) => {
-        layer.animate([{ opacity: 0 }, { opacity: 1 }], {
+        layer.animate(fadeKeyframes(layer), {
           duration: 450,
           easing: "ease-out",
           fill: "backwards",

package/src/charts/core/motion.ts

@@ -1,6 +1,7 @@
 "use client";
 
 import { type RefObject, useEffect, useRef, useState } from "react";
+import { useIsomorphicLayoutEffect } from "./use-chart-size.js";
 
 const QUERY = "(prefers-reduced-motion: reduce)";
 
@@ -47,8 +48,10 @@ export function useEntryAnimation<T extends Element>(
   play: (root: T) => void,
   { disabled = false, replayKey }: EntryAnimationOptions = {},
 ): void {
-  // biome-ignore lint/correctness/useExhaustiveDependencies: replays only when the key changes.
-  useEffect(() => {
+  // A layout effect starts the animations before the first paint. With a plain
+  // effect the final state paints for one frame, then `fill: "backwards"` hides
+  // it again, which reads as a flicker. Replays only when the key changes.
+  useIsomorphicLayoutEffect(() => {
     const root = ref.current;
     if (disabled || !root || typeof root.animate !== "function" || prefersReducedMotion()) return;
     play(root);
@@ -65,9 +68,19 @@ export function revealClip(element: Element, duration = 900, delay = 0): void {
   });
 }
 
+/**
+ * Fade-in keyframes that end at the element's own opacity. Ending at 1 would
+ * show a translucent element at full strength, then snap it back when the
+ * animation finishes.
+ */
+export function fadeKeyframes(element: Element): Keyframe[] {
+  const resting = typeof getComputedStyle === "function" ? getComputedStyle(element).opacity : "1";
+  return [{ opacity: 0 }, { opacity: resting || "1" }];
+}
+
 /** Fades an element in. */
 export function fadeIn(element: Element, duration = 400, delay = 0): void {
-  element.animate([{ opacity: 0 }, { opacity: 1 }], {
+  element.animate(fadeKeyframes(element), {
     duration,
     delay,
     easing: "ease-out",
@@ -100,7 +113,8 @@ export function useAnimatedNumber(
     const startedAt = performance.now();
     let frame = 0;
     const tick = (now: number) => {
-      const progress = Math.min(1, (now - startedAt) / duration);
+      // rAF timestamps are the frame start and can precede `startedAt`.
+      const progress = Math.min(1, Math.max(0, (now - startedAt) / duration));
       const eased = 1 - (1 - progress) ** 3;
       setValue(start + (target - start) * eased);
       if (progress < 1) frame = requestAnimationFrame(tick);

package/src/charts/core/use-drill.ts

@@ -86,7 +86,7 @@ export function useAnimatedView(
     let frame = 0;
     const start = performance.now();
     const step = (now: number) => {
-      const t = Math.min(1, (now - start) / duration);
+      const t = Math.min(1, Math.max(0, (now - start) / duration));
       const next = interpolateView(from, to, easeOutCubic(t));
       current.current = next;
       setView(next);

package/src/charts/donut-chart/donut-chart.tsx

@@ -810,7 +810,7 @@ function useTweenedValues(items: readonly Resolved[], disabled: boolean): number
     const started = performance.now();
     let frame = 0;
     const step = (now: number) => {
-      const t = easeOutCubic(Math.min(1, (now - started) / 700));
+      const t = easeOutCubic(Math.min(1, Math.max(0, (now - started) / 700)));
       const next: Record<string, number> = {};
       for (const id of Object.keys(target)) {
         const start = from[id] ?? 0;

package/src/charts/gauge-chart/gauge-chart.tsx

@@ -6,7 +6,13 @@ import { DECORATIVE } from "../core/a11y.js";
 import { ChartFrame } from "../core/chart-frame.js";
 import { ChartDataTable } from "../core/data-table.js";
 import { resolveFormat, type ValueFormat } from "../core/format.js";
-import { EASE_OUT, fadeIn, useAnimatedNumber, useEntryAnimation } from "../core/motion.js";
+import {
+  EASE_OUT,
+  fadeIn,
+  fadeKeyframes,
+  useAnimatedNumber,
+  useEntryAnimation,
+} from "../core/motion.js";
 import { type ChartTone, TONE_COLORS } from "../core/palette.js";
 import { arcLine, degToRad, polarPoint, radToDeg } from "../core/polar.js";
 import { ChartTooltip } from "../core/tooltip.js";
@@ -264,7 +270,9 @@ function GaugePlot({
   const capAngle = roundedCaps ? band / 2 / mid : 0;
 
   const fraction = toFraction(shown);
-  const active = bands.find((item) => shown >= item.from && shown <= item.to);
+  // Colour and label follow the target value, so they do not flip band by band
+  // while the arc or needle sweeps towards it.
+  const active = bands.find((item) => value >= item.from && value <= item.to);
   const valueColor = active ? rangeColor(active) : "var(--accent-word)";
   const progressEnd = a0 + capAngle + (span - 2 * capAngle) * fraction;
 
@@ -307,7 +315,7 @@ function GaugePlot({
     svgRef,
     (root) => {
       root.querySelectorAll("[data-band]").forEach((node, i) => {
-        node.animate([{ opacity: 0 }, { opacity: 1 }], {
+        node.animate(fadeKeyframes(node), {
           duration: 500,
           delay: i * 90,
           easing: EASE_OUT,

package/src/charts/heatmap-chart/heatmap-grid.tsx

@@ -11,7 +11,7 @@ import {
   scaleGradient,
 } from "../core/color-scale.js";
 import type { ValueFormatter } from "../core/format.js";
-import { EASE_OUT, useEntryAnimation } from "../core/motion.js";
+import { EASE_OUT, fadeKeyframes, useEntryAnimation } from "../core/motion.js";
 import { ChartTooltip } from "../core/tooltip.js";
 import { type ChartLabels, DEFAULT_LABELS } from "../core/types.js";
 import { useCanvasPaint } from "../core/use-canvas.js";
@@ -172,7 +172,7 @@ export function HeatmapGrid({
     svgRef,
     (element) => {
       element.querySelectorAll("[data-column]").forEach((group, index) => {
-        group.animate([{ opacity: 0 }, { opacity: 1 }], {
+        group.animate(fadeKeyframes(group), {
           duration: 420,
           delay: Math.min(index * (360 / Math.max(1, columns)), 360),
           easing: EASE_OUT,

package/src/charts/histogram/histogram.tsx

@@ -20,7 +20,7 @@ import {
 } from "../core/distribution/stats.js";
 import { type ColoredSeries, useDistributionLegend } from "../core/distribution/use-legend.js";
 import { formatNumber, formatPercent, resolveFormat, type ValueFormat } from "../core/format.js";
-import { EASE_OUT, useEntryAnimation } from "../core/motion.js";
+import { EASE_OUT, fadeKeyframes, useEntryAnimation } from "../core/motion.js";
 import { barPath, linePath } from "../core/path.js";
 import { ChartTooltip, type TooltipRow } from "../core/tooltip.js";
 
@@ -400,7 +400,7 @@ function HistogramPlot({
         });
       });
       root.querySelectorAll("[data-curve]").forEach((curve) => {
-        curve.animate([{ opacity: 0 }, { opacity: 1 }], {
+        curve.animate(fadeKeyframes(curve), {
           duration: 500,
           delay: 420,
           easing: "ease-out",

package/src/charts/maps/geo/use-map-view.ts

@@ -90,7 +90,7 @@ export function useMapView<E extends Element>({
       const from = viewRef.current;
       const start = performance.now();
       const step = (now: number) => {
-        const t = Math.min(1, (now - start) / DURATION);
+        const t = Math.min(1, Math.max(0, (now - start) / DURATION));
         const e = easeOut(t);
         // Interpolate zoom geometrically so the speed feels constant.
         const k = from.k * (goal.k / from.k) ** e;

package/src/charts/tree-chart/tree-chart.tsx

@@ -12,7 +12,7 @@ import {
 import { cn } from "../../utils/cn.js";
 import { ChartFrame } from "../core/chart-frame.js";
 import { ChartDataTable } from "../core/data-table.js";
-import { EASE_OUT, useEntryAnimation } from "../core/motion.js";
+import { EASE_OUT, fadeKeyframes, useEntryAnimation } from "../core/motion.js";
 import { type TreeFitMode, treeFitView } from "../core/tree-fit.js";
 import {
   type TreeDirection,
@@ -568,7 +568,7 @@ function TreePlot({
         );
       });
       root.querySelectorAll("[data-tree-edges]").forEach((element) => {
-        element.animate([{ opacity: 0 }, { opacity: 1 }], {
+        element.animate(fadeKeyframes(element), {
           duration: 500,
           delay: 160,
           easing: "ease-out",

package/src/charts/tree-chart/use-tree-transition.ts

@@ -92,7 +92,7 @@ export function useTreeTransition(
     let frame = 0;
     const start = performance.now();
     const step = (now: number) => {
-      const t = Math.min(1, (now - start) / duration);
+      const t = Math.min(1, Math.max(0, (now - start) / duration));
       if (t >= 1) {
         show(final);
         return;