@watt-ui/react 0.1.1 → 0.1.2

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,9 +41,38 @@
   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);
-  transition: color 140ms ease-out;
 }
 .watt-status[data-status="normal"] {
   color: var(--watt-positive);
@@ -121,6 +152,10 @@
   }
 }
 @media (prefers-reduced-motion: reduce) {
+  .watt-motion {
+    transition-duration: 0s !important;
+    transition-property: none !important;
+  }
   .watt-status {
     transition: none;
   }

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;
 }