@watt-ui/react 0.0.0-stage → 0.1.1

package/src/components/telemetry-chart.tsx

@@ -0,0 +1,476 @@
+"use client";
+import { useComposedRefs } from "@radix-ui/react-compose-refs";
+import { Slot } from "@radix-ui/react-slot";
+import {
+  createContext,
+  forwardRef,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import type { EChartsCoreOption, EChartsType } from "echarts/core";
+import { cx, part } from "../internal.js";
+import { nearestIndex, prepareSeries, lowerBound } from "../chart/data.js";
+import {
+  chartOption,
+  hasManagedConflict,
+  type ChartConfig,
+} from "../chart/options.js";
+import type {
+  RootProps,
+  TelemetrySeries,
+  TimeRange,
+  DataQuality,
+} from "../types.js";
+export interface ChartInspection {
+  timestamp: number;
+  values: {
+    id: string;
+    label: string;
+    unit: string;
+    timestamp: number;
+    value: number | null;
+    quality?: DataQuality;
+  }[];
+}
+export interface TelemetryChartProps extends Omit<RootProps, "onError"> {
+  series: readonly TelemetrySeries[];
+  timeZone: string;
+  locale?: string;
+  range?: TimeRange;
+  onRangeChange?: (range: TimeRange) => void;
+  sampling?: "minmax" | "none";
+  options?: EChartsCoreOption;
+  events?: Readonly<
+    Record<string, (event: unknown, chart: EChartsType) => void>
+  >;
+  onReady?: (chart: EChartsType) => void;
+  onError?: (error: Error) => void;
+}
+interface ChartContext extends ChartConfig {
+  inspection: ChartInspection | null;
+  inspect: (timestamp: number | null) => void;
+  hidden: Set<string>;
+  toggle: (id: string) => void;
+  onRangeChange?: TelemetryChartProps["onRangeChange"];
+  events?: TelemetryChartProps["events"];
+  onReady?: TelemetryChartProps["onReady"];
+  onError?: TelemetryChartProps["onError"];
+}
+const Context = createContext<ChartContext | null>(null);
+function useChart() {
+  const ctx = useContext(Context);
+  if (!ctx) throw new Error("Chart parts require TelemetryChart.Root");
+  return ctx;
+}
+const Root = forwardRef<HTMLDivElement, TelemetryChartProps>(
+  (
+    {
+      series,
+      timeZone,
+      locale,
+      range,
+      onRangeChange,
+      sampling = "minmax",
+      options,
+      events,
+      onReady,
+      onError,
+      density = "comfortable",
+      asChild,
+      children,
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    const prepared = useMemo(() => prepareSeries(series), [series]);
+    const [hidden, setHidden] = useState<Set<string>>(() => new Set());
+    const [timestamp, setTimestamp] = useState<number | null>(null);
+    const inspect = useCallback(
+      (time: number | null) => setTimestamp(time),
+      [],
+    );
+    const toggle = useCallback(
+      (id: string) =>
+        setHidden((old) => {
+          const next = new Set(old);
+          if (next.has(id)) next.delete(id);
+          else next.add(id);
+          return next;
+        }),
+      [],
+    );
+    const inspection = useMemo<ChartInspection | null>(
+      () =>
+        timestamp === null
+          ? null
+          : {
+              timestamp,
+              values: prepared
+                .filter((s) => !hidden.has(s.id))
+                .flatMap((s) => {
+                  const index = nearestIndex(s.points, timestamp);
+                  const p = s.points[index];
+                  return p
+                    ? [
+                        {
+                          id: s.id,
+                          label: s.label,
+                          unit: s.unit,
+                          timestamp: p[0],
+                          value: p[1],
+                          quality: s.sourcePoints[index]?.quality,
+                        },
+                      ]
+                    : [];
+                }),
+            },
+      [timestamp, prepared, hidden],
+    );
+    useEffect(() => {
+      if (
+        hasManagedConflict({ series: prepared, range, timeZone, options }) &&
+        process.env.NODE_ENV !== "production"
+      )
+        console.warn(
+          "Watt UI: explicit chart props override series, axes, zoom, tooltip and legend options.",
+        );
+    }, [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)}
+        >
+          {children}
+        </Component>
+      </Context.Provider>
+    );
+  },
+);
+export interface ChartCanvasProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Trusted output of renderTelemetrySVG, never untrusted HTML. */
+  previewSvg?: string;
+  height?: number;
+}
+const Canvas = forwardRef<HTMLDivElement, ChartCanvasProps>(
+  (
+    { previewSvg, height = 300, className, style, onKeyDown, ...props },
+    forwardedRef,
+  ) => {
+    const ctx = useChart();
+    const ctxRef = useRef(ctx);
+    ctxRef.current = ctx;
+    const host = useRef<HTMLDivElement>(null);
+    const instance = useRef<EChartsType | null>(null);
+    const localRange = useRef<TimeRange | undefined>(undefined);
+    const previousRange = useRef(ctx.range);
+    const bindings = useRef(new Map<string, (event: unknown) => void>());
+    const [ready, setReady] = useState(false);
+    const [error, setError] = useState<Error | null>(null);
+    const canvasRef = useComposedRefs(host, forwardedRef);
+    const render = useRef<() => void>(() => {});
+    useEffect(() => {
+      let alive = true,
+        frame = 0,
+        firstRendered = false;
+      let observer: ResizeObserver | undefined;
+      import("../chart/engine.js")
+        .then(({ initCanvas }) => {
+          if (!alive || !host.current) return;
+          const chart = initCanvas(host.current);
+          instance.current = chart;
+          render.current = () => {
+            cancelAnimationFrame(frame);
+            frame = requestAnimationFrame(() => {
+              if (!alive || !host.current) return;
+              try {
+                const current = ctxRef.current;
+                const styles = getComputedStyle(host.current);
+                chart.resize({ silent: true });
+                chart.setOption(
+                  chartOption(
+                    {
+                      ...current,
+                      range: current.range ?? localRange.current,
+                      series: current.series.filter(
+                        (s) => !current.hidden.has(s.id),
+                      ),
+                    },
+                    host.current.clientWidth,
+                    {
+                      text:
+                        styles.getPropertyValue("--watt-muted").trim() ||
+                        "#667085",
+                      border:
+                        styles.getPropertyValue("--watt-border").trim() ||
+                        "#e7e9ee",
+                      accent:
+                        styles.getPropertyValue("--watt-accent").trim() ||
+                        "#355dff",
+                    },
+                  ),
+                  { notMerge: true, lazyUpdate: false },
+                );
+                setReady(true);
+                if (!firstRendered) {
+                  firstRendered = true;
+                  ctxRef.current.onReady?.(chart);
+                }
+              } catch (reason) {
+                const failure =
+                  reason instanceof Error ? reason : new Error(String(reason));
+                setError(failure);
+                ctxRef.current.onError?.(failure);
+              }
+            });
+          };
+          chart.on("updateAxisPointer", (event: unknown) => {
+            const e = event as { axesInfo?: { value: number }[] };
+            const value = e.axesInfo?.[0]?.value;
+            if (value !== undefined) ctxRef.current.inspect(value);
+          });
+          chart.on("datazoom", () => {
+            const zoom = (
+              chart.getOption() as {
+                dataZoom?: { startValue?: number; endValue?: number }[];
+              }
+            ).dataZoom?.[0];
+            if (
+              typeof zoom?.startValue === "number" &&
+              typeof zoom.endValue === "number" &&
+              zoom.startValue < zoom.endValue
+            ) {
+              localRange.current = [zoom.startValue, zoom.endValue];
+              ctxRef.current.onRangeChange?.(localRange.current);
+            }
+          });
+          for (const name of Object.keys(ctxRef.current.events ?? {})) {
+            const handler = (event: unknown) =>
+              ctxRef.current.events?.[name]?.(event, chart);
+            bindings.current.set(name, handler);
+            chart.on(name, handler);
+          }
+          observer = new ResizeObserver(() => render.current());
+          observer.observe(host.current);
+          render.current();
+        })
+        .catch((reason) => {
+          if (alive) {
+            const failure =
+              reason instanceof Error ? reason : new Error(String(reason));
+            setError(failure);
+            ctxRef.current.onError?.(failure);
+          }
+        });
+      return () => {
+        alive = false;
+        cancelAnimationFrame(frame);
+        observer?.disconnect();
+        instance.current?.dispose();
+        instance.current = null;
+        bindings.current.clear();
+        render.current = () => {};
+      };
+    }, []);
+    useEffect(() => {
+      if (previousRange.current !== ctx.range) {
+        if (ctx.range === undefined) localRange.current = undefined;
+        previousRange.current = ctx.range;
+      }
+      render.current();
+    }, [
+      ctx.series,
+      ctx.range,
+      ctx.sampling,
+      ctx.options,
+      ctx.hidden,
+      ctx.timeZone,
+      ctx.locale,
+    ]);
+    const eventNames = Object.keys(ctx.events ?? {})
+      .sort()
+      .join("\0");
+    useEffect(() => {
+      const chart = instance.current;
+      if (!chart || !ready) return;
+      const names = new Set(eventNames ? eventNames.split("\0") : []);
+      for (const [name, handler] of bindings.current)
+        if (!names.has(name)) {
+          chart.off(name, handler);
+          bindings.current.delete(name);
+        }
+      for (const name of names)
+        if (!bindings.current.has(name)) {
+          const handler = (event: unknown) =>
+            ctxRef.current.events?.[name]?.(event, chart);
+          bindings.current.set(name, handler);
+          chart.on(name, handler);
+        }
+    }, [eventNames, ready]);
+    return (
+      <div
+        data-slot="telemetry-chart-canvas-wrapper"
+        className="relative min-w-0"
+        style={{ height }}
+      >
+        {!ready && previewSvg && (
+          <div
+            aria-hidden="true"
+            className="watt-chart-preview absolute inset-0"
+            dangerouslySetInnerHTML={{ __html: previewSvg }}
+          />
+        )}
+        <div
+          {...props}
+          ref={canvasRef}
+          role="img"
+          tabIndex={0}
+          aria-busy={!ready && !error}
+          data-slot="telemetry-chart-canvas"
+          data-error={!!error || undefined}
+          className={cx(
+            "h-full w-full outline-offset-4 focus-visible:outline-2 focus-visible:outline-[var(--watt-accent)]",
+            className,
+          )}
+          style={style}
+          onKeyDown={(event) => {
+            onKeyDown?.(event);
+            if (event.defaultPrevented) return;
+            const points = ctx.series.find(
+              (s) => !ctx.hidden.has(s.id),
+            )?.points;
+            if (!points?.length) return;
+            if (
+              ["ArrowLeft", "ArrowRight", "Home", "End"].includes(event.key)
+            ) {
+              event.preventDefault();
+              const i = ctx.inspection
+                ? lowerBound(points, ctx.inspection.timestamp)
+                : -1;
+              const index =
+                event.key === "Home"
+                  ? 0
+                  : event.key === "End"
+                    ? points.length - 1
+                    : Math.max(
+                        0,
+                        Math.min(
+                          points.length - 1,
+                          i + (event.key === "ArrowRight" ? 1 : -1),
+                        ),
+                      );
+              const time = points[index]![0];
+              ctx.inspect(time);
+              instance.current?.dispatchAction({
+                type: "showTip",
+                x: instance.current.convertToPixel({ xAxisIndex: 0 }, time),
+                y: 50,
+              });
+            } else if (event.key === "Escape") ctx.inspect(null);
+          }}
+        />
+      </div>
+    );
+  },
+);
+const Legend = forwardRef<
+  HTMLDivElement,
+  Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
+    children?: (series: {
+      id: string;
+      label: string;
+      color?: string;
+      hidden: boolean;
+      toggle: () => void;
+    }) => React.ReactNode;
+  }
+>(({ children, className, ...props }, ref) => {
+  const ctx = useChart();
+  return (
+    <div
+      {...props}
+      ref={ref}
+      data-slot="telemetry-chart-legend"
+      className={cx("flex flex-wrap gap-4 text-sm", className)}
+    >
+      {ctx.series.map((s) => (
+        <span key={s.id}>
+          {children ? (
+            children({
+              ...s,
+              hidden: ctx.hidden.has(s.id),
+              toggle: () => ctx.toggle(s.id),
+            })
+          ) : (
+            <button
+              type="button"
+              aria-pressed={!ctx.hidden.has(s.id)}
+              onClick={() => ctx.toggle(s.id)}
+              className="inline-flex items-center gap-2"
+            >
+              <span
+                className="h-2 w-2 rounded-full"
+                style={{ background: s.color ?? "var(--watt-accent)" }}
+              />
+              {s.label}
+            </button>
+          )}
+        </span>
+      ))}
+    </div>
+  );
+});
+function Tooltip({
+  children,
+  ...props
+}: Omit<React.HTMLAttributes<HTMLDivElement>, "children"> & {
+  children: (inspection: ChartInspection | null) => React.ReactNode;
+}) {
+  const { inspection } = useChart();
+  return (
+    <div
+      {...props}
+      data-slot="telemetry-chart-tooltip"
+      aria-live={props["aria-live"] ?? "polite"}
+      aria-atomic={props["aria-atomic"] ?? true}
+    >
+      {children(inspection)}
+    </div>
+  );
+}
+export const TelemetryChart = {
+  Root,
+  Canvas,
+  Legend,
+  Tooltip,
+  Description: part(
+    "telemetry-chart-description",
+    "text-sm text-[var(--watt-muted)]",
+  ),
+};

package/src/domain.ts

@@ -0,0 +1,64 @@
+import type { Timestamp } from "./types.js";
+
+/** Strings require an explicit ISO timezone; numbers are Unix milliseconds. */
+export function parseTimestamp(
+  value: Timestamp | null | undefined,
+): number | null {
+  if (typeof value === "number")
+    return Number.isFinite(value) && Math.abs(value) <= 8.64e15 ? value : null;
+  if (
+    !value ||
+    !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(
+      value,
+    )
+  )
+    return null;
+  const [year, month, day] = value.slice(0, 10).split("-").map(Number) as [
+    number,
+    number,
+    number,
+  ];
+  const days =
+    [
+      31,
+      year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0) ? 29 : 28,
+      31,
+      30,
+      31,
+      30,
+      31,
+      31,
+      30,
+      31,
+      30,
+      31,
+    ][month - 1] ?? 0;
+  if (month < 1 || month > 12 || day < 1 || day > days) return null;
+  const result = Date.parse(value);
+  return Number.isFinite(result) ? result : null;
+}
+export function formatNumber(
+  value: number | null | undefined,
+  locale = "en-US",
+  digits = 1,
+): string {
+  return value == null || !Number.isFinite(value)
+    ? "—"
+    : new Intl.NumberFormat(locale, { maximumFractionDigits: digits }).format(
+        value,
+      );
+}
+export function formatTime(
+  value: Timestamp,
+  timeZone: string,
+  locale = "en-GB",
+): string {
+  const time = parseTimestamp(value);
+  return time === null
+    ? "—"
+    : new Intl.DateTimeFormat(locale, {
+        timeZone,
+        hour: "2-digit",
+        minute: "2-digit",
+      }).format(time);
+}

package/src/icons/index.tsx

@@ -0,0 +1,49 @@
+import { createLucideIcon } from "lucide-react";
+export {
+  SolarPanel,
+  Sun,
+  Battery,
+  BatteryCharging,
+  UtilityPole,
+  Factory,
+  House,
+  CircuitBoard,
+  PlugZap,
+  Zap,
+} from "lucide-react";
+export type { LucideProps as EnergyIconProps } from "lucide-react";
+export const Inverter = createLucideIcon("inverter", [
+  ["rect", { x: "5", y: "3", width: "14", height: "18", rx: "2", key: "body" }],
+  [
+    "path",
+    {
+      d: "M8 7h3m-3 3h3m3-3h2m-2 3h2M8 16c1-3 2 3 3 0s2 3 3 0 2 0 2 0",
+      key: "controls",
+    },
+  ],
+]);
+export const Busbar = createLucideIcon("busbar", [
+  ["path", { d: "M3 6h18M5 6v9m7-9v9m7-9v9", key: "bus" }],
+  ["circle", { cx: "5", cy: "18", r: "2", key: "a" }],
+  ["circle", { cx: "12", cy: "18", r: "2", key: "b" }],
+  ["circle", { cx: "19", cy: "18", r: "2", key: "c" }],
+]);
+export const BatteryRack = createLucideIcon("battery-rack", [
+  ["rect", { x: "5", y: "3", width: "14", height: "18", rx: "2", key: "rack" }],
+  [
+    "path",
+    {
+      d: "M5 9h14M5 15h14M8 6h2m-2 6h2m-2 6h2m6-12h.01M16 12h.01M16 18h.01",
+      key: "modules",
+    },
+  ],
+]);
+export const Transformer = createLucideIcon("transformer", [
+  [
+    "path",
+    {
+      d: "M7 3v3m10-3v3M7 18v3m10-3v3M10 6H7a3 3 0 0 0 0 6 3 3 0 0 0 0 6h3m4-12h3a3 3 0 0 1 0 6 3 3 0 0 1 0 6h-3M12 5v14",
+      key: "windings",
+    },
+  ],
+]);

package/src/index.ts

@@ -0,0 +1,37 @@
+export { PowerMetric } from "./components/power-metric.js";
+export { StatusIndicator } from "./components/status-indicator.js";
+export { DataFreshness } from "./components/data-freshness.js";
+export { BatterySOC } from "./components/battery-soc.js";
+export { TelemetryChart } from "./components/telemetry-chart.js";
+export { EnergyFlow } from "./components/energy-flow.js";
+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 { StatusIndicatorProps } from "./components/status-indicator.js";
+export type { BatterySOCProps } from "./components/battery-soc.js";
+export type {
+  DataFreshnessProps,
+  FreshnessTimeProps,
+  FreshnessElapsedProps,
+} from "./components/data-freshness.js";
+export type {
+  TelemetryChartProps,
+  ChartCanvasProps,
+  ChartInspection,
+} from "./components/telemetry-chart.js";
+export type {
+  EnergyFlowProps,
+  FlowAnimation,
+  FlowStyle,
+  FlowNodeProps,
+  FlowPortProps,
+  FlowEdgeProps,
+} from "./components/energy-flow.js";
+export type { AlarmFeedProps } from "./components/alarm-feed.js";
+export type {
+  AssetTreeProps,
+  AssetTreeRow,
+  AssetTreeItem,
+} from "./components/asset-tree.js";

package/src/internal.tsx

@@ -0,0 +1,57 @@
+"use client";
+import { forwardRef, useSyncExternalStore } from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+import type { PartProps } from "./types.js";
+export function cx(...values: ClassValue[]) {
+  return twMerge(clsx(values));
+}
+export function part(slot: string, defaults = "", tag: "div" | "span" = "div") {
+  const Part = forwardRef<HTMLElement, PartProps>(
+    ({ asChild, className, ...props }, ref) => {
+      const Component = asChild ? Slot : tag;
+      return (
+        <Component
+          {...props}
+          ref={ref as never}
+          data-slot={slot}
+          className={cx(defaults, className)}
+        />
+      );
+    },
+  );
+  Part.displayName = slot;
+  return Part;
+}
+let instant: number | null = null;
+let timer: ReturnType<typeof setInterval> | undefined;
+const listeners = new Set<() => void>();
+function subscribe(listener: () => void) {
+  listeners.add(listener);
+  if (!timer) {
+    instant = Date.now();
+    timer = setInterval(() => {
+      instant = Date.now();
+      listeners.forEach((fn) => fn());
+    }, 1000);
+  }
+  return () => {
+    listeners.delete(listener);
+    if (!listeners.size) {
+      clearInterval(timer);
+      timer = undefined;
+      instant = null;
+    }
+  };
+}
+const snapshot = () => instant;
+const serverSnapshot = () => null;
+const noopSubscribe = () => () => {};
+export function useNow(enabled: boolean) {
+  return useSyncExternalStore(
+    enabled ? subscribe : noopSubscribe,
+    snapshot,
+    serverSnapshot,
+  );
+}