@watt-ui/react 0.0.0-stage → 0.1.0

package/src/components/data-freshness.tsx

@@ -0,0 +1,109 @@
+"use client";
+import { createContext, forwardRef, useContext } from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cx, part, useNow } from "../internal.js";
+import { parseTimestamp, formatTime } from "../domain.js";
+import type { DataQuality, PartProps, RootProps, Timestamp } from "../types.js";
+interface Freshness {
+  timestamp: Timestamp | null;
+  quality?: DataQuality;
+}
+const Context = createContext<Freshness | null>(null);
+function useFreshness() {
+  const ctx = useContext(Context);
+  if (!ctx) throw new Error("DataFreshness parts require DataFreshness.Root");
+  return ctx;
+}
+export interface DataFreshnessProps extends RootProps, Freshness {}
+const Root = forwardRef<HTMLElement, DataFreshnessProps>(
+  (
+    {
+      timestamp,
+      quality,
+      density = "comfortable",
+      asChild,
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    const Component = asChild ? Slot : "span";
+    return (
+      <Context.Provider value={{ timestamp, quality }}>
+        <Component
+          {...props}
+          ref={ref as never}
+          data-slot="data-freshness"
+          data-density={density}
+          data-quality={quality}
+          className={cx(
+            "watt-root inline-flex items-center gap-2 text-sm text-[var(--watt-muted)] data-[density=compact]:gap-1 data-[density=compact]:text-xs",
+            className,
+          )}
+        />
+      </Context.Provider>
+    );
+  },
+);
+export interface FreshnessTimeProps extends React.ComponentPropsWithoutRef<"time"> {
+  timeZone: string;
+  locale?: string;
+  formatter?: (timestamp: number) => React.ReactNode;
+  fallback?: React.ReactNode;
+}
+const Time = forwardRef<HTMLTimeElement, FreshnessTimeProps>(
+  (
+    { timeZone, locale, formatter, fallback = "—", children, ...props },
+    ref,
+  ) => {
+    const { timestamp } = useFreshness();
+    const time = parseTimestamp(timestamp);
+    return (
+      <time
+        {...props}
+        ref={ref}
+        data-slot="data-freshness-time"
+        dateTime={time === null ? undefined : new Date(time).toISOString()}
+      >
+        {children ??
+          (time === null
+            ? fallback
+            : formatter
+              ? formatter(time)
+              : formatTime(time, timeZone, locale))}
+      </time>
+    );
+  },
+);
+export interface FreshnessElapsedProps extends PartProps {
+  now?: Timestamp;
+  formatter: (elapsedMs: number) => React.ReactNode;
+  fallback?: React.ReactNode;
+}
+const Elapsed = forwardRef<HTMLElement, FreshnessElapsedProps>(
+  ({ now, formatter, fallback = "—", asChild, children, ...props }, ref) => {
+    const { timestamp } = useFreshness();
+    const clock = useNow(now === undefined);
+    const reference = now === undefined ? clock : parseTimestamp(now);
+    const time = parseTimestamp(timestamp);
+    const Component = asChild ? Slot : "span";
+    return (
+      <Component
+        {...props}
+        ref={ref as never}
+        data-slot="data-freshness-elapsed"
+      >
+        {children ??
+          (time === null || reference === null
+            ? fallback
+            : formatter(reference - time))}
+      </Component>
+    );
+  },
+);
+export const DataFreshness = {
+  Root,
+  Time,
+  Elapsed,
+  Quality: part("data-freshness-quality", "", "span"),
+};

package/src/components/energy-flow.tsx

@@ -0,0 +1,364 @@
+"use client";
+import { useComposedRefs } from "@radix-ui/react-compose-refs";
+import {
+  createContext,
+  forwardRef,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+} from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cx } from "../internal.js";
+import {
+  connection,
+  type Rect,
+  type Side,
+  type Point,
+} from "./flow-geometry.js";
+import type { EnergyFlowEdge, PartProps, RootProps } from "../types.js";
+export interface FlowAnimation {
+  type?: "particles" | "dash" | "pulse" | "none";
+  speed?: number;
+  particleSize?: number;
+  particleCount?: number;
+}
+export interface FlowStyle {
+  animation?: FlowAnimation;
+  path?: "straight" | "step" | "bezier";
+  color?: string;
+  strokeWidth?: number;
+}
+export interface EnergyFlowProps extends RootProps, FlowStyle {}
+interface FlowContext extends FlowStyle {
+  rects: ReadonlyMap<string, Rect>;
+  register: (key: string, element: HTMLElement, side?: Side) => () => void;
+}
+const Context = createContext<FlowContext | null>(null);
+const NodeContext = createContext<string | null>(null);
+const LabelContext = createContext<Point | null>(null);
+const keyFor = (node: string, port?: string) =>
+  JSON.stringify([node, port ?? null]);
+function useFlow() {
+  const ctx = useContext(Context);
+  if (!ctx) throw new Error("EnergyFlow parts require EnergyFlow.Root");
+  return ctx;
+}
+const Root = forwardRef<HTMLElement, EnergyFlowProps>(
+  (
+    {
+      asChild,
+      density = "comfortable",
+      animation,
+      path = "bezier",
+      color,
+      strokeWidth = 2,
+      children,
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    const host = useRef<HTMLElement | null>(null);
+    const elements = useRef(
+      new Map<string, { element: HTMLElement; side?: Side }>(),
+    );
+    const observer = useRef<ResizeObserver | null>(null);
+    const frame = useRef(0);
+    const [rects, setRects] = useState<ReadonlyMap<string, Rect>>(new Map());
+    const measure = useCallback(() => {
+      cancelAnimationFrame(frame.current);
+      frame.current = requestAnimationFrame(() => {
+        const root = host.current;
+        if (!root) return;
+        const rootRect = root.getBoundingClientRect();
+        const scaleX = rootRect.width / (root.offsetWidth || 1),
+          scaleY = rootRect.height / (root.offsetHeight || 1);
+        const next = new Map<string, Rect>();
+        elements.current.forEach(({ element, side }, key) => {
+          if (!element.getClientRects().length) return;
+          const r = element.getBoundingClientRect();
+          next.set(key, {
+            x:
+              (r.left - rootRect.left) / (scaleX || 1) -
+              root.clientLeft +
+              root.scrollLeft,
+            y:
+              (r.top - rootRect.top) / (scaleY || 1) -
+              root.clientTop +
+              root.scrollTop,
+            width: r.width / (scaleX || 1),
+            height: r.height / (scaleY || 1),
+            side,
+          });
+        });
+        setRects((old) =>
+          JSON.stringify([...old]) === JSON.stringify([...next]) ? old : next,
+        );
+      });
+    }, []);
+    const register = useCallback(
+      (key: string, element: HTMLElement, side?: Side) => {
+        if (elements.current.has(key))
+          throw new Error(`Duplicate EnergyFlow node/port: ${key}`);
+        elements.current.set(key, { element, side });
+        observer.current?.observe(element);
+        measure();
+        return () => {
+          observer.current?.unobserve(element);
+          elements.current.delete(key);
+          measure();
+        };
+      },
+      [measure],
+    );
+    const hostRef = useComposedRefs(host, ref);
+    useEffect(() => {
+      observer.current = new ResizeObserver(measure);
+      if (host.current) observer.current.observe(host.current);
+      elements.current.forEach(({ element }) =>
+        observer.current!.observe(element),
+      );
+      const mutation = new MutationObserver(measure);
+      if (host.current)
+        mutation.observe(host.current, {
+          attributes: true,
+          subtree: true,
+          attributeFilter: ["class", "style"],
+          childList: true,
+        });
+      window.addEventListener("resize", measure);
+      document.addEventListener("scroll", measure, true);
+      measure();
+      return () => {
+        observer.current?.disconnect();
+        observer.current = null;
+        mutation.disconnect();
+        window.removeEventListener("resize", measure);
+        document.removeEventListener("scroll", measure, true);
+        cancelAnimationFrame(frame.current);
+      };
+    }, [measure]);
+    const Component = asChild ? Slot : "div";
+    return (
+      <Context.Provider
+        value={{ register, rects, animation, path, color, strokeWidth }}
+      >
+        <Component
+          {...props}
+          ref={hostRef as never}
+          data-slot="energy-flow"
+          data-density={density}
+          className={cx("watt-root relative isolate", className)}
+        >
+          {children}
+        </Component>
+      </Context.Provider>
+    );
+  },
+);
+export interface FlowNodeProps extends PartProps {
+  id: string;
+}
+const Node = forwardRef<HTMLElement, FlowNodeProps>(
+  ({ id, asChild, className, ...props }, ref) => {
+    const { register } = useFlow();
+    const host = useRef<HTMLElement | null>(null);
+    const hostRef = useComposedRefs(host, ref);
+    useEffect(() => {
+      if (!id) throw new Error("EnergyFlow.Node requires a nonempty id");
+      if (host.current) return register(keyFor(id), host.current);
+    }, [id, register]);
+    const Component = asChild ? Slot : "div";
+    return (
+      <NodeContext.Provider value={id}>
+        <Component
+          {...props}
+          ref={hostRef as never}
+          data-slot="energy-flow-node"
+          data-node-id={id}
+          className={cx("relative z-10", className)}
+        />
+      </NodeContext.Provider>
+    );
+  },
+);
+export interface FlowPortProps extends PartProps {
+  id: string;
+  side: Side;
+}
+const Port = forwardRef<HTMLElement, FlowPortProps>(
+  ({ id, side, asChild, className, ...props }, ref) => {
+    const { register } = useFlow();
+    const node = useContext(NodeContext);
+    const host = useRef<HTMLElement | null>(null);
+    const hostRef = useComposedRefs(host, ref);
+    useEffect(() => {
+      if (!node || !id)
+        throw new Error("A named EnergyFlow.Port requires a Node");
+      if (host.current) return register(keyFor(node, id), host.current, side);
+    }, [node, id, side, register]);
+    const Component = asChild ? Slot : "span";
+    return (
+      <Component
+        {...props}
+        ref={hostRef as never}
+        data-slot="energy-flow-port"
+        data-port-id={id}
+        className={cx(
+          "absolute h-2 w-2 rounded-full bg-[var(--watt-accent)]",
+          className,
+        )}
+      />
+    );
+  },
+);
+export interface FlowEdgeProps extends EnergyFlowEdge, FlowStyle {
+  children?: React.ReactNode;
+  className?: string;
+  label?: string;
+  style?: React.CSSProperties;
+}
+function Edge({
+  source,
+  target,
+  sourcePort,
+  targetPort,
+  animation,
+  path,
+  color,
+  strokeWidth,
+  children,
+  className,
+  label,
+  style,
+}: FlowEdgeProps) {
+  const ctx = useFlow();
+  const id = `watt-${useId().replace(/:/g, "")}`;
+  const a = ctx.rects.get(keyFor(source, sourcePort)),
+    b = ctx.rects.get(keyFor(target, targetPort));
+  const settings = {
+    type: "particles",
+    speed: 1,
+    particleSize: 3,
+    particleCount: 3,
+    ...ctx.animation,
+    ...animation,
+  };
+  if (!Number.isFinite(settings.speed) || settings.speed < 0)
+    throw new Error("Flow speed must be finite and nonnegative");
+  if (
+    !Number.isFinite(settings.particleCount) ||
+    settings.particleCount < 0 ||
+    settings.particleCount > 100 ||
+    !Number.isFinite(settings.particleSize) ||
+    settings.particleSize < 0
+  )
+    throw new Error("Invalid flow particles (count 0–100, size >= 0)");
+  const width = strokeWidth ?? ctx.strokeWidth ?? 2;
+  if (!Number.isFinite(width) || width <= 0)
+    throw new Error("Flow strokeWidth must be positive");
+  if (source === target || !a || !b) return null;
+  const geometry = connection(a, b, path ?? ctx.path ?? "bezier");
+  const ink = color ?? ctx.color ?? "var(--watt-accent)";
+  const duration = 3 / (settings.speed || 1);
+  const motionStyle = {
+    animationDuration: `${duration}s`,
+    animationPlayState: settings.speed === 0 ? "paused" : "running",
+  } as React.CSSProperties;
+  return (
+    <LabelContext.Provider value={geometry.middle}>
+      <svg
+        data-slot="energy-flow-edge"
+        data-source={source}
+        data-target={target}
+        className={cx(
+          "pointer-events-none absolute inset-0 h-full w-full overflow-visible",
+          className,
+        )}
+        style={{ color: ink, ...style }}
+        role={label ? "img" : undefined}
+        aria-label={label}
+        aria-hidden={!label || undefined}
+      >
+        <defs>
+          <marker
+            id={id}
+            markerWidth="8"
+            markerHeight="8"
+            refX="7"
+            refY="4"
+            orient="auto"
+            markerUnits="userSpaceOnUse"
+          >
+            <path
+              d="M1 1 L7 4 L1 7"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="1.5"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            />
+          </marker>
+        </defs>
+        <path
+          d={geometry.path}
+          fill="none"
+          stroke="currentColor"
+          strokeWidth={width}
+          markerEnd={`url(#${id})`}
+          className={
+            settings.type === "dash"
+              ? "watt-flow-dash"
+              : settings.type === "pulse"
+                ? "watt-flow-pulse"
+                : undefined
+          }
+          style={motionStyle}
+        />
+        {settings.type === "particles" &&
+          Array.from({ length: Math.floor(settings.particleCount) }, (_, i) => (
+            <circle
+              key={i}
+              r={settings.particleSize}
+              fill="currentColor"
+              className="watt-flow-particle"
+              style={{
+                ...motionStyle,
+                offsetPath: `path('${geometry.path}')`,
+                animationDelay: `${(-duration * i) / Math.max(1, settings.particleCount)}s`,
+              }}
+            />
+          ))}
+      </svg>
+      {children}
+    </LabelContext.Provider>
+  );
+}
+const Label = forwardRef<HTMLElement, PartProps>(
+  ({ asChild, className, style, ...props }, ref) => {
+    const point = useContext(LabelContext);
+    if (!point) throw new Error("EnergyFlow.Label requires an Edge");
+    const Component = asChild ? Slot : "span";
+    return (
+      <Component
+        {...props}
+        ref={ref as never}
+        data-slot="energy-flow-label"
+        className={cx(
+          "absolute z-10 bg-[var(--watt-surface)] px-2 text-sm tabular-nums",
+          className,
+        )}
+        style={{
+          left: point.x,
+          top: point.y,
+          transform: "translate(-50%, -140%)",
+          ...style,
+        }}
+      />
+    );
+  },
+);
+export const EnergyFlow = { Root, Node, Port, Edge, Label };

package/src/components/flow-geometry.ts

@@ -0,0 +1,82 @@
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  side?: Side;
+}
+export type Side = "top" | "right" | "bottom" | "left";
+export interface Point {
+  x: number;
+  y: number;
+}
+export function anchor(rect: Rect, other: Rect): { point: Point; side: Side } {
+  const dx = other.x + other.width / 2 - rect.x - rect.width / 2;
+  const dy = other.y + other.height / 2 - rect.y - rect.height / 2;
+  const side =
+    rect.side ??
+    (Math.abs(dx) >= Math.abs(dy)
+      ? dx >= 0
+        ? "right"
+        : "left"
+      : dy >= 0
+        ? "bottom"
+        : "top");
+  return {
+    side,
+    point: {
+      x:
+        rect.x +
+        (side === "left" ? 0 : side === "right" ? rect.width : rect.width / 2),
+      y:
+        rect.y +
+        (side === "top"
+          ? 0
+          : side === "bottom"
+            ? rect.height
+            : rect.height / 2),
+    },
+  };
+}
+export function connection(
+  source: Rect,
+  target: Rect,
+  type: "straight" | "step" | "bezier",
+) {
+  const a = anchor(source, target),
+    b = anchor(target, source);
+  const start = a.point,
+    end = b.point;
+  const middle = { x: (start.x + end.x) / 2, y: (start.y + end.y) / 2 };
+  const move = `M ${start.x} ${start.y}`;
+  if (type === "straight")
+    return { path: `${move} L ${end.x} ${end.y}`, middle };
+  if (type === "step") {
+    const horizontal = a.side === "left" || a.side === "right";
+    return {
+      path: horizontal
+        ? `${move} H ${middle.x} V ${end.y} H ${end.x}`
+        : `${move} V ${middle.y} H ${end.x} V ${end.y}`,
+      middle,
+    };
+  }
+  const distance = Math.max(
+    36,
+    Math.hypot(end.x - start.x, end.y - start.y) * 0.45,
+  );
+  const offset = (side: Side) => ({
+    x: side === "left" ? -distance : side === "right" ? distance : 0,
+    y: side === "top" ? -distance : side === "bottom" ? distance : 0,
+  });
+  const da = offset(a.side),
+    db = offset(b.side);
+  const c1 = { x: start.x + da.x, y: start.y + da.y },
+    c2 = { x: end.x + db.x, y: end.y + db.y };
+  return {
+    path: `${move} C ${c1.x} ${c1.y}, ${c2.x} ${c2.y}, ${end.x} ${end.y}`,
+    middle: {
+      x: (start.x + 3 * c1.x + 3 * c2.x + end.x) / 8,
+      y: (start.y + 3 * c1.y + 3 * c2.y + end.y) / 8,
+    },
+  };
+}

package/src/components/power-metric.tsx

@@ -0,0 +1,71 @@
+"use client";
+import { forwardRef } from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cx, part } from "../internal.js";
+import { formatNumber } from "../domain.js";
+import type { PartProps, RootProps } from "../types.js";
+const Root = forwardRef<HTMLElement, RootProps>(
+  ({ asChild, density = "comfortable", className, ...props }, ref) => {
+    const Component = asChild ? Slot : "div";
+    return (
+      <Component
+        {...props}
+        ref={ref as never}
+        data-slot="power-metric"
+        data-density={density}
+        className={cx(
+          "watt-root flex flex-col gap-2 data-[density=compact]:gap-1",
+          className,
+        )}
+      />
+    );
+  },
+);
+export interface MetricValueProps extends PartProps {
+  value: number | null;
+  formatter?: (value: number) => React.ReactNode;
+  fallback?: React.ReactNode;
+}
+const Value = forwardRef<HTMLElement, MetricValueProps>(
+  (
+    {
+      asChild,
+      value,
+      formatter = formatNumber,
+      fallback = "—",
+      children,
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    const Component = asChild ? Slot : "span";
+    return (
+      <Component
+        {...props}
+        ref={ref as never}
+        data-slot="power-metric-value"
+        className={cx(
+          "text-5xl font-medium tabular-nums tracking-tight",
+          className,
+        )}
+      >
+        {children ??
+          (value !== null && Number.isFinite(value)
+            ? formatter(value)
+            : fallback)}
+      </Component>
+    );
+  },
+);
+export const PowerMetric = {
+  Root,
+  Value,
+  Label: part("power-metric-label", "text-sm text-[var(--watt-muted)]", "span"),
+  Unit: part("power-metric-unit", "text-lg text-[var(--watt-muted)]", "span"),
+  Trend: part(
+    "power-metric-trend",
+    "inline-flex items-center gap-1 text-sm",
+    "span",
+  ),
+};

package/src/components/status-indicator.tsx

@@ -0,0 +1,31 @@
+"use client";
+import { forwardRef } from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cx, part } from "../internal.js";
+import type { EquipmentStatus, RootProps } from "../types.js";
+export interface StatusIndicatorProps extends RootProps {
+  status: EquipmentStatus;
+}
+const Root = forwardRef<HTMLElement, StatusIndicatorProps>(
+  ({ status, density = "comfortable", asChild, className, ...props }, ref) => {
+    const Component = asChild ? Slot : "span";
+    return (
+      <Component
+        {...props}
+        ref={ref as never}
+        data-slot="status-indicator"
+        data-status={status}
+        data-density={density}
+        className={cx(
+          "watt-status inline-flex items-center gap-2 text-sm data-[density=compact]:gap-1 data-[density=compact]:text-xs",
+          className,
+        )}
+      />
+    );
+  },
+);
+export const StatusIndicator = {
+  Root,
+  Indicator: part("status-indicator-dot", "watt-status-dot", "span"),
+  Label: part("status-indicator-label", "", "span"),
+};