@jcsoftdev/ui 0.1.3 → 0.1.5

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.d.ts

@@ -22,7 +22,7 @@ export interface GaugeChartProps {
     variant?: "semi" | "three-quarter";
     /** Filled arc (`progress`) or a pointer over the bands (`needle`). */
     mode?: "progress" | "needle";
-    /** Colored bands. With `progress` they sit behind the arc and the arc takes the color of the band it is in. */
+    /** Colored bands. With `progress` the track stays neutral, the arc takes the color of the band it is in, and a band shows only while hovered or focused. */
     ranges?: readonly GaugeRange[];
     height?: number | "fill";
     /** Width / height ratio; sizes the drawing from the container width when `height` is not "fill". */

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";
@@ -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,
@@ -276,7 +282,7 @@ function GaugePlot({
               )
             }
           ) }) : null,
-          bands.length === 0 ? /* @__PURE__ */ jsx(
+          bands.length === 0 || !needle ? /* @__PURE__ */ jsx(
             "path",
             {
               d: arcLine(cx, cy, mid, a0 + capAngle, a1 - capAngle),
@@ -285,7 +291,8 @@ function GaugePlot({
               strokeLinecap: roundedCaps ? "round" : "butt",
               style: { stroke: "var(--chart-grid)" }
             }
-          ) : /* @__PURE__ */ jsx("g", { mask: roundedCaps ? `url(#${uid}-track)` : void 0, children: bandPaths.map((path, index) => {
+          ) : null,
+          bands.length > 0 ? /* @__PURE__ */ jsx("g", { mask: roundedCaps ? `url(#${uid}-track)` : void 0, children: bandPaths.map((path, index) => {
             const item = bands[index];
             if (!item || !path) return null;
             return /* @__PURE__ */ jsx(
@@ -294,14 +301,14 @@ function GaugePlot({
                 d: path,
                 width: band,
                 color: rangeColor(item),
-                opacity: needle ? 0.92 : 0.26,
-                dimmed: focused != null && focused !== index,
+                opacity: needle ? 0.92 : focused === index ? 0.32 : 0,
+                dimmed: needle && focused != null && focused !== index,
                 onEnter: (event) => nav.hover(index, event),
                 onLeave: nav.leave
               },
               index
             );
-          }) }),
+          }) }) : null,
           !needle && fraction > 0 ? /* @__PURE__ */ jsx(
             "path",
             {

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.3",
+  "version": "0.1.5",
   "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";
@@ -35,7 +41,7 @@ export interface GaugeChartProps {
   variant?: "semi" | "three-quarter";
   /** Filled arc (`progress`) or a pointer over the bands (`needle`). */
   mode?: "progress" | "needle";
-  /** Colored bands. With `progress` they sit behind the arc and the arc takes the color of the band it is in. */
+  /** Colored bands. With `progress` the track stays neutral, the arc takes the color of the band it is in, and a band shows only while hovered or focused. */
   ranges?: readonly GaugeRange[];
   height?: number | "fill";
   /** Width / height ratio; sizes the drawing from the container width when `height` is not "fill". */
@@ -309,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,
@@ -400,7 +406,7 @@ function GaugePlot({
           </defs>
         ) : null}
 
-        {bands.length === 0 ? (
+        {bands.length === 0 || !needle ? (
           <path
             d={arcLine(cx, cy, mid, a0 + capAngle, a1 - capAngle)}
             fill="none"
@@ -408,7 +414,8 @@ function GaugePlot({
             strokeLinecap={roundedCaps ? "round" : "butt"}
             style={{ stroke: "var(--chart-grid)" }}
           />
-        ) : (
+        ) : null}
+        {bands.length > 0 ? (
           <g mask={roundedCaps ? `url(#${uid}-track)` : undefined}>
             {bandPaths.map((path, index) => {
               const item = bands[index];
@@ -420,15 +427,18 @@ function GaugePlot({
                   d={path}
                   width={band}
                   color={rangeColor(item)}
-                  opacity={needle ? 0.92 : 0.26}
-                  dimmed={focused != null && focused !== index}
+                  // In progress mode the bands behind the arc would show as a
+                  // patchwork of tints next to it, so they stay invisible hit areas
+                  // and only appear while explored.
+                  opacity={needle ? 0.92 : focused === index ? 0.32 : 0}
+                  dimmed={needle && focused != null && focused !== index}
                   onEnter={(event) => nav.hover(index, event)}
                   onLeave={nav.leave}
                 />
               );
             })}
           </g>
-        )}
+        ) : null}
 
         {!needle && fraction > 0 ? (
           <path

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;