@watt-ui/react 0.1.0 → 0.1.2

package/src/components/telemetry-chart.tsx

@@ -13,6 +13,7 @@ import {
 } from "react";
 import type { EChartsCoreOption, EChartsType } from "echarts/core";
 import { cx, part } from "../internal.js";
+import { MotionProvider, motionStyle, useChangeFeedback } from "../motion.js";
 import { nearestIndex, prepareSeries, lowerBound } from "../chart/data.js";
 import {
   chartOption,
@@ -24,6 +25,7 @@ import type {
   TelemetrySeries,
   TimeRange,
   DataQuality,
+  MotionProps,
 } from "../types.js";
 export interface ChartInspection {
   timestamp: number;
@@ -36,7 +38,9 @@ export interface ChartInspection {
     quality?: DataQuality;
   }[];
 }
-export interface TelemetryChartProps extends Omit<RootProps, "onError"> {
+export interface TelemetryChartProps
+  extends Omit<RootProps, "onError">,
+    MotionProps {
   series: readonly TelemetrySeries[];
   timeZone: string;
   locale?: string;
@@ -83,6 +87,8 @@ const Root = forwardRef<HTMLDivElement, TelemetryChartProps>(
       asChild,
       children,
       className,
+      style,
+      motion,
       ...props
     },
     ref,
@@ -142,34 +148,37 @@ const Root = forwardRef<HTMLDivElement, TelemetryChartProps>(
     }, [options, prepared, range, timeZone]);
     const Component = asChild ? Slot : "div";
     return (
-      <Context.Provider
-        value={{
-          series: prepared,
-          timeZone,
-          locale,
-          range,
-          onRangeChange,
-          sampling,
-          options,
-          events,
-          inspection,
-          inspect,
-          hidden,
-          toggle,
-          onReady,
-          onError,
-        }}
-      >
-        <Component
-          {...props}
-          ref={ref}
-          data-slot="telemetry-chart"
-          data-density={density}
-          className={cx("watt-root min-w-0", className)}
+      <MotionProvider motion={motion}>
+        <Context.Provider
+          value={{
+            series: prepared,
+            timeZone,
+            locale,
+            range,
+            onRangeChange,
+            sampling,
+            options,
+            events,
+            inspection,
+            inspect,
+            hidden,
+            toggle,
+            onReady,
+            onError,
+          }}
         >
-          {children}
-        </Component>
-      </Context.Provider>
+          <Component
+            {...props}
+            ref={ref}
+            data-slot="telemetry-chart"
+            data-density={density}
+            style={{ ...style, ...motionStyle(motion) }}
+            className={cx("watt-root min-w-0", className)}
+          >
+            {children}
+          </Component>
+        </Context.Provider>
+      </MotionProvider>
     );
   },
 );
@@ -432,11 +441,18 @@ const Legend = forwardRef<
               type="button"
               aria-pressed={!ctx.hidden.has(s.id)}
               onClick={() => ctx.toggle(s.id)}
-              className="inline-flex items-center gap-2"
+              className="watt-chart-legend-toggle inline-flex items-center gap-2"
             >
               <span
-                className="h-2 w-2 rounded-full"
-                style={{ background: s.color ?? "var(--watt-accent)" }}
+                aria-hidden="true"
+                data-slot="telemetry-chart-legend-marker"
+                className="watt-motion h-2 w-2 rounded-full border border-current"
+                style={{
+                  color: s.color ?? "var(--watt-accent)",
+                  background: ctx.hidden.has(s.id)
+                    ? "transparent"
+                    : "currentColor",
+                }}
               />
               {s.label}
             </button>
@@ -446,24 +462,30 @@ const Legend = forwardRef<
     </div>
   );
 });
-function Tooltip({
-  children,
-  ...props
-}: Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
-  children: (inspection: ChartInspection | null) => React.ReactNode;
-}) {
+const Tooltip = forwardRef<
+  HTMLDivElement,
+  Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
+    children: (inspection: ChartInspection | null) => React.ReactNode;
+  }
+>(function Tooltip({ children, className, ...props }, ref) {
   const { inspection } = useChart();
+  const host = useRef<HTMLDivElement>(null);
+  const hostRef = useComposedRefs(host, ref);
+  useChangeFeedback(host, inspection !== null);
   return (
     <div
       {...props}
+      ref={hostRef}
       data-slot="telemetry-chart-tooltip"
+      data-state={inspection ? "active" : "idle"}
+      className={cx("watt-motion", className)}
       aria-live={props["aria-live"] ?? "polite"}
       aria-atomic={props["aria-atomic"] ?? true}
     >
       {children(inspection)}
     </div>
   );
-}
+});
 export const TelemetryChart = {
   Root,
   Canvas,

package/src/index.ts

@@ -8,7 +8,10 @@ export { AlarmFeed } from "./components/alarm-feed.js";
 export { AssetTree } from "./components/asset-tree.js";
 export { formatNumber, formatTime, parseTimestamp } from "./domain.js";
 export type * from "./types.js";
-export type { MetricValueProps } from "./components/power-metric.js";
+export type {
+  PowerMetricProps,
+  MetricValueProps,
+} from "./components/power-metric.js";
 export type { StatusIndicatorProps } from "./components/status-indicator.js";
 export type { BatterySOCProps } from "./components/battery-soc.js";
 export type {
@@ -34,4 +37,5 @@ export type {
   AssetTreeProps,
   AssetTreeRow,
   AssetTreeItem,
+  AssetTreeIndicatorProps,
 } from "./components/asset-tree.js";

package/src/motion.tsx

@@ -0,0 +1,117 @@
+"use client";
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  type CSSProperties,
+  type ReactNode,
+  type RefObject,
+} from "react";
+import type { Motion, MotionProps } from "./types.js";
+
+const Context = createContext<Motion>(true);
+const useMotionEffect =
+  typeof document === "undefined" ? useEffect : useLayoutEffect;
+const noop = () => {};
+export function useMotion(own?: Motion): Motion {
+  const parent = useContext(Context);
+  return own ?? parent;
+}
+
+export function MotionProvider({
+  motion,
+  children,
+}: MotionProps & { children: ReactNode }) {
+  const parent = useContext(Context);
+  return (
+    <Context.Provider value={motion ?? parent}>{children}</Context.Provider>
+  );
+}
+
+export function motionStyle(motion?: Motion): CSSProperties {
+  if (motion === undefined) return {};
+  const duration =
+    motion === false ? 0 : motion === true ? 240 : (motion.duration ?? 240);
+  if (!Number.isFinite(duration) || duration < 0)
+    throw new Error(
+      "Motion duration must be finite and nonnegative milliseconds",
+    );
+  return {
+    "--watt-motion-duration": `${duration}ms`,
+    "--watt-motion-property": duration === 0 ? "none" : "initial",
+    "--watt-motion-easing":
+      typeof motion === "object"
+        ? (motion.easing ?? "cubic-bezier(0.16, 1, 0.3, 1)")
+        : "cubic-bezier(0.16, 1, 0.3, 1)",
+  } as CSSProperties;
+}
+
+/** Bounded feedback only: never changes text, data, row geometry or DOM identity. */
+export function animateMotion(
+  element: HTMLElement,
+  frames: Keyframe[],
+): () => void {
+  if (!element.animate || document.hidden || !element.getClientRects().length)
+    return noop;
+  const preference = window.matchMedia("(prefers-reduced-motion: reduce)");
+  if (preference.matches) return noop;
+  const styles = getComputedStyle(element);
+  const time = styles.transitionDuration.split(",")[0] ?? "0s";
+  const duration = parseFloat(time) * (time.trim().endsWith("ms") ? 1 : 1000);
+  if (!(duration > 0)) return noop;
+  let animation: Animation;
+  try {
+    animation = element.animate(frames, {
+      duration,
+      easing: styles.transitionTimingFunction,
+    });
+  } catch {
+    return noop; // A consumer's unsupported CSS easing must not block live readings.
+  }
+  const detach = () => {
+    preference.removeEventListener("change", stop);
+    document.removeEventListener("visibilitychange", onVisibility);
+  };
+  const stop = () => {
+    animation.cancel();
+    detach();
+  };
+  const onVisibility = () => {
+    if (document.hidden) stop();
+  };
+  preference.addEventListener("change", stop);
+  document.addEventListener("visibilitychange", onVisibility);
+  animation.addEventListener("finish", detach, { once: true });
+  animation.addEventListener("cancel", detach, { once: true });
+  return stop;
+}
+
+export function highlightChange(element: HTMLElement): () => void {
+  const styles = getComputedStyle(element);
+  const background = styles.backgroundColor;
+  const accent = styles.getPropertyValue("--watt-accent").trim() || "#355dff";
+  return animateMotion(element, [
+    { backgroundColor: `color-mix(in srgb, ${accent} 10%, ${background})` },
+    { backgroundColor: background },
+  ]);
+}
+
+export function useChangeFeedback(
+  ref: RefObject<HTMLElement | null>,
+  value: unknown,
+  ownMotion?: Motion,
+) {
+  const motion = useMotion(ownMotion);
+  const duration = typeof motion === "object" ? motion.duration : undefined;
+  const easing = typeof motion === "object" ? motion.easing : undefined;
+  const previous = useRef(value);
+  useMotionEffect(() => {
+    const changed = !Object.is(previous.current, value);
+    previous.current = value;
+    if (changed && motion !== false && ref.current)
+      return highlightChange(ref.current);
+  }, [value, ref, motion === false, duration, easing]);
+}
+

package/src/styles.css

@@ -22,6 +22,8 @@
   --watt-warning: #996009;
   --watt-critical: #c43b40;
   --watt-radius: 12px;
+  --watt-motion-duration: 240ms;
+  --watt-motion-easing: cubic-bezier(0.16, 1, 0.3, 1);
 }
 .dark,
 [data-theme="dark"] {
@@ -39,6 +41,36 @@
   color: var(--watt-foreground);
   font-variant-numeric: tabular-nums;
 }
+.watt-motion {
+  transition-property: none;
+  transition-duration: var(--watt-motion-duration, 240ms);
+  transition-timing-function: var(--watt-motion-easing, ease-out);
+}
+.watt-motion.watt-status {
+  transition-property: var(--watt-motion-property, color);
+}
+.watt-soc-fill {
+  transition-property: var(--watt-motion-property, width);
+}
+[data-slot="battery-soc"][data-invalid] .watt-soc-fill {
+  transition-duration: 0s;
+}
+[data-slot="asset-tree-row"] {
+  transition-property: var(--watt-motion-property, background-color);
+}
+[data-slot="asset-tree-indicator"] {
+  transition-property: var(--watt-motion-property, transform);
+}
+[data-slot="telemetry-chart-legend-marker"] {
+  transition-property: var(--watt-motion-property, background-color, scale);
+}
+.watt-chart-legend-toggle[aria-pressed="false"] {
+  text-decoration: line-through;
+}
+.watt-chart-legend-toggle[aria-pressed="false"]
+  [data-slot="telemetry-chart-legend-marker"] {
+  scale: 0.75;
+}
 .watt-status {
   color: var(--watt-muted);
 }
@@ -120,6 +152,13 @@
   }
 }
 @media (prefers-reduced-motion: reduce) {
+  .watt-motion {
+    transition-duration: 0s !important;
+    transition-property: none !important;
+  }
+  .watt-status {
+    transition: none;
+  }
   .watt-flow-dash,
   .watt-flow-pulse {
     animation: none !important;

package/src/types.ts

@@ -1,15 +1,41 @@
-import type { HTMLAttributes } from "react";
+import type { CSSProperties, HTMLAttributes } from "react";
 
 export type PowerUnit = "W" | "kW" | "MW";
 export type EnergyUnit = "Wh" | "kWh" | "MWh";
 export type MeasurementUnit =
-  PowerUnit | EnergyUnit | "V" | "A" | "Hz" | "°C" | "%" | "W/m²";
+  | PowerUnit
+  | EnergyUnit
+  | "V"
+  | "A"
+  | "Hz"
+  | "°C"
+  | "%"
+  | "W/m²";
 export type Timestamp = string | number;
 export type DataQuality =
-  "good" | "uncertain" | "stale" | "missing" | "bad" | "offline";
+  | "good"
+  | "uncertain"
+  | "stale"
+  | "missing"
+  | "bad"
+  | "offline";
 export type EquipmentStatus =
-  "normal" | "standby" | "stopped" | "warning" | "fault" | "offline";
+  | "normal"
+  | "standby"
+  | "stopped"
+  | "warning"
+  | "fault"
+  | "offline";
 export type Density = "compact" | "comfortable";
+export interface MotionOptions {
+  /** Duration in milliseconds; zero disables transitions. */
+  duration?: number;
+  easing?: CSSProperties["transitionTimingFunction"];
+}
+export type Motion = boolean | MotionOptions;
+export interface MotionProps {
+  motion?: Motion;
+}
 export interface PartProps extends HTMLAttributes<HTMLElement> {
   asChild?: boolean;
 }