@sierragridteam/design-system 0.4.1 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sierragridteam/design-system",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "type": "module",
   "files": [
     "src",
@@ -34,5 +34,5 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "gitHead": "10d05287109e4726f13f0f37fe80589f37b0474c"
+  "gitHead": "f3ec7cb9ab2125b517575b324401e942828092c1"
 }

package/src/components/TimeSeriesChart.astro

@@ -0,0 +1,36 @@
+---
+import { buildTimeSeries, formatChartTime, type TimeSeriesChartOptions } from '../lib/time-series';
+interface Props extends TimeSeriesChartOptions { id?: string }
+const { id, ...options } = Astro.props;
+const model = buildTimeSeries(options);
+---
+<sierra-time-series id={id} data-options={JSON.stringify(options)}>
+  <figure class="ds-time-series" aria-label={options.label}>
+    <figcaption><strong>{options.label}</strong>{options.description && <p>{options.description}</p>}</figcaption>
+    <p>Time: UTC · Values: {options.unit || 'unitless'}</p>
+    <details>
+      <summary>View data table</summary>
+      <div class="table-wrap" tabindex="0" role="region" aria-label={`${options.label} values`}>
+        <table class="table">
+          <caption>{options.label} — {options.unit || 'unitless'}, UTC</caption>
+          <thead><tr><th scope="col">Series</th><th scope="col">Time (UTC)</th><th scope="col">Value</th></tr></thead>
+          <tbody>{model.series.flatMap(series => series.points.map(point => <tr><td>{series.label}</td><td>{formatChartTime(point.time)}</td><td>{point.value === null ? 'Not reported' : point.value}</td></tr>))}</tbody>
+        </table>
+      </div>
+    </details>
+    {model.empty && <p>No numeric samples. Data availability is determined by the source.</p>}
+  </figure>
+</sierra-time-series>
+<script>
+  import { renderTimeSeries } from '../lib/time-series-render';
+  import type { TimeSeriesChartOptions, TimeSeries } from '../lib/time-series';
+  class SierraTimeSeries extends HTMLElement {
+    private current?: TimeSeriesChartOptions;
+    connectedCallback() { this.options = this.current ?? JSON.parse(this.dataset.options!); }
+    get options(): TimeSeriesChartOptions { return structuredClone(this.current!); }
+    set options(value: TimeSeriesChartOptions) { renderTimeSeries(this,value); this.current=structuredClone(value); }
+    get series(): TimeSeries[] { return this.options.series; }
+    set series(value: TimeSeries[]) { this.options = { ...this.options, series:value }; }
+  }
+  if (!customElements.get('sierra-time-series')) customElements.define('sierra-time-series',SierraTimeSeries);
+</script>

package/src/lib/time-series-render.ts

@@ -0,0 +1,156 @@
+import {
+  buildTimeSeries,
+  formatChartTime,
+  type TimeSeriesChartOptions,
+} from "./time-series";
+const patterns = ["", "6 3", "2 3", "8 3 2 3"];
+/** Replaces this chart only; creates text nodes rather than interpolating HTML. */
+export function renderTimeSeries(
+  root: HTMLElement,
+  options: TimeSeriesChartOptions,
+) {
+  const model = buildTimeSeries(options);
+  const tableWasOpen = root.querySelector("details")?.open ?? false;
+  const node = (tag: string, text?: string) => {
+    const n = document.createElement(tag);
+    if (text !== undefined) n.textContent = text;
+    return n;
+  };
+  const figure = node("figure");
+  figure.className = "ds-time-series";
+  figure.setAttribute("aria-label", options.label);
+  const caption = node("figcaption");
+  caption.append(node("strong", options.label));
+  if (options.description) caption.append(node("p", options.description));
+  figure.append(caption);
+  if (model.empty)
+    figure.append(
+      node(
+        "p",
+        "No numeric samples. Data availability is determined by the source.",
+      ),
+    );
+  else {
+    const svgNode = (tag: string, attrs: Record<string, string>) => {
+      const n = document.createElementNS("http://www.w3.org/2000/svg", tag);
+      for (const [k, v] of Object.entries(attrs)) n.setAttribute(k, v);
+      return n;
+    };
+    const svg = svgNode("svg", {
+      viewBox: "0 0 640 240",
+      role: "img",
+      "aria-label": `${options.label}. Time in UTC; values ${options.unit || "unitless"}. Full values in the table below.`,
+    });
+    const plot = svgNode("svg", {
+      x: "65",
+      y: "15",
+      width: "550",
+      height: "180",
+      viewBox: "0 0 100 100",
+      preserveAspectRatio: "none",
+      overflow: "hidden",
+    });
+    plot.append(
+      svgNode("path", {
+        d: "M0 0 V100 H100",
+        class: "ds-chart-axis",
+        "vector-effect": "non-scaling-stroke",
+      }),
+    );
+    for (let i = 0; i < model.series.length; i++)
+      for (const segment of model.series[i].segments) {
+        const attrs = {
+          class: `ds-chart-series ds-chart-series-${i % 4}`,
+          "vector-effect": "non-scaling-stroke",
+          "stroke-dasharray": patterns[i % 4],
+        };
+        plot.append(
+          svgNode("path", {
+            ...attrs,
+            d: segment.map((p, j) => `${j ? "L" : "M"}${p.x},${p.y}`).join(" "),
+          }),
+        );
+        for (const p of segment)
+          plot.append(
+            svgNode("ellipse", {
+              cx: String(p.x),
+              cy: String(p.y),
+              rx: "0.55",
+              ry: "1.6",
+              class: `ds-chart-dot ds-chart-series-${i % 4}`,
+            }),
+          );
+      }
+    svg.append(plot);
+    const label = (x: number, y: number, text: string, anchor = "start") => {
+      const n = svgNode("text", {
+        x: String(x),
+        y: String(y),
+        "text-anchor": anchor,
+      });
+      n.textContent = text;
+      svg.append(n);
+    };
+    label(58, 22, `${Number(model.valueDomain[1].toPrecision(5))}`, "end");
+    label(58, 195, `${Number(model.valueDomain[0].toPrecision(5))}`, "end");
+    label(65, 215, formatChartTime(model.timeDomain[0]));
+    label(615, 234, formatChartTime(model.timeDomain[1]), "end");
+    figure.append(
+      svg,
+      node("p", `Values: ${options.unit || "unitless"} · Time: UTC`),
+    );
+  }
+  const legend = node("ul");
+  legend.className = "ds-chart-legend";
+  model.series.forEach((s, i) => {
+    const li = node("li");
+    const swatch = node("span");
+    swatch.className = `ds-chart-swatch ds-chart-series-${i % 4}`;
+    swatch.setAttribute("aria-hidden", "true");
+    li.append(swatch, document.createTextNode(s.label));
+    legend.append(li);
+  });
+  figure.append(legend);
+  const details = node("details") as HTMLDetailsElement;
+  details.open = tableWasOpen;
+  details.append(node("summary", "View data table"));
+  const region = node("div");
+  region.className = "table-wrap";
+  region.tabIndex = 0;
+  region.setAttribute("role", "region");
+  region.setAttribute("aria-label", `${options.label} values`);
+  const table = node("table");
+  table.className = "table";
+  table.append(
+    node("caption", `${options.label} — ${options.unit || "unitless"}, UTC`),
+  );
+  const head = node("thead"),
+    row = node("tr");
+  for (const title of [
+    "Series",
+    "Time (UTC)",
+    `Value${options.unit ? ` (${options.unit})` : ""}`,
+  ]) {
+    const th = node("th", title);
+    th.setAttribute("scope", "col");
+    row.append(th);
+  }
+  head.append(row);
+  table.append(head);
+  const body = node("tbody");
+  for (const s of model.series)
+    for (const p of s.points) {
+      const tr = node("tr");
+      tr.append(
+        node("td", s.label),
+        node("td", formatChartTime(p.time)),
+        node("td", p.value === null ? "Not reported" : String(p.value)),
+      );
+      body.append(tr);
+    }
+  table.append(body);
+  region.append(table);
+  details.append(region);
+  figure.append(details);
+  root.replaceChildren(figure);
+}

package/src/lib/time-series.ts

@@ -0,0 +1,115 @@
+export interface TimeSeriesPoint {
+  time: number;
+  value: number | null;
+}
+export interface TimeSeries {
+  id: string;
+  label: string;
+  points: TimeSeriesPoint[];
+}
+export interface TimeSeriesChartOptions {
+  label: string;
+  description?: string;
+  series: TimeSeries[];
+  unit?: string;
+  timeDomain?: [number, number];
+  valueDomain?: [number, number];
+  maxGapMs?: number;
+}
+export interface TimeSeriesChartElement extends HTMLElement {
+  options: TimeSeriesChartOptions;
+  series: TimeSeries[];
+}
+export function formatChartTime(time: number): string {
+  return new Date(time)
+    .toISOString()
+    .replace("T", " ")
+    .replace(".000Z", " UTC")
+    .replace("Z", " UTC");
+}
+function domain(
+  explicit: [number, number] | undefined,
+  values: number[],
+  fallback: [number, number],
+  constantPadding?: number,
+): [number, number] {
+  if (explicit) {
+    if (!explicit.every(Number.isFinite) || explicit[0] >= explicit[1])
+      throw new RangeError("Chart domains must be finite and increasing");
+    return [...explicit];
+  }
+  if (!values.length) return fallback;
+  let lo = Infinity,
+    hi = -Infinity;
+  for (const value of values) {
+    lo = Math.min(lo, value);
+    hi = Math.max(hi, value);
+  }
+  if (lo === hi) {
+    const padding = constantPadding ?? Math.max(Math.abs(lo) * 0.05, 1);
+    return [lo - padding, hi + padding];
+  }
+  return [lo, hi];
+}
+/** Coordinates use a normalized 0–100 plot. Null/nonfinite values break lines. */
+export function buildTimeSeries(options: TimeSeriesChartOptions) {
+  if (
+    options.maxGapMs !== undefined &&
+    (!Number.isFinite(options.maxGapMs) || options.maxGapMs <= 0)
+  )
+    throw new RangeError("maxGapMs must be positive and finite");
+  const ids = new Set<string>();
+  const series = options.series.map((series) => {
+    if (ids.has(series.id)) throw new Error("Series IDs must be unique");
+    ids.add(series.id);
+    return {
+      ...series,
+      points: series.points
+        .filter((p) => Number.isFinite(p.time) && Math.abs(p.time) <= 8.64e15)
+        .map((p) => ({
+          ...p,
+          value: p.value !== null && Number.isFinite(p.value) ? p.value : null,
+        }))
+        .sort((a, b) => a.time - b.time),
+    };
+  });
+  const times = series.flatMap((s) => s.points.map((p) => p.time));
+  const values = series.flatMap((s) =>
+    s.points.filter((p) => p.value !== null).map((p) => p.value!),
+  );
+  const timeDomain = domain(options.timeDomain, times, [0, 1], 1000);
+  if (timeDomain.some((value) => Math.abs(value) > 8.64e15))
+    throw new RangeError("Time domain must contain representable dates");
+  const valueDomain = domain(options.valueDomain, values, [0, 1]);
+  const scale = (n: number, d: [number, number]) =>
+    (100 * (n - d[0])) / (d[1] - d[0]);
+  return {
+    timeDomain,
+    valueDomain,
+    empty: !values.length,
+    series: series.map((s) => {
+      const segments: { x: number; y: number }[][] = [];
+      let segment: { x: number; y: number }[] = [];
+      let previous: number | undefined;
+      for (const p of s.points) {
+        if (
+          p.value === null ||
+          (previous !== undefined &&
+            options.maxGapMs !== undefined &&
+            p.time - previous > options.maxGapMs)
+        ) {
+          if (segment.length) segments.push(segment);
+          segment = [];
+        }
+        if (p.value !== null)
+          segment.push({
+            x: scale(p.time, timeDomain),
+            y: 100 - scale(p.value, valueDomain),
+          });
+        previous = p.time;
+      }
+      if (segment.length) segments.push(segment);
+      return { ...s, segments };
+    }),
+  };
+}

package/src/styles/components.css

@@ -2233,3 +2233,24 @@ sierra-copy [data-copy-check] {
 .ds-values tr:last-child > :is(th, td) {
   border-bottom: 0;
 }
+
+/* Time series: colors identify series, never source health or severity. */
+.ds-time-series { margin: 0; min-width: 0; }
+.ds-time-series svg { display: block; width: 100%; height: auto; overflow: hidden; }
+.ds-time-series text { fill: var(--ink-secondary); font-family: var(--font-mono); font-size: var(--fs-small); }
+.ds-time-series figcaption p, .ds-time-series > p { color: var(--ink-secondary); font-size: var(--fs-small); }
+.ds-chart-axis { fill: none; stroke: var(--line-control); }
+.ds-chart-series { fill: none; stroke: currentColor; stroke-width: 2; }
+.ds-chart-dot { fill: currentColor; }
+.ds-chart-series-0 { color: var(--brand-green); }
+.ds-chart-series-1 { color: var(--brand-brass-text); }
+.ds-chart-series-2 { color: var(--ink-secondary); }
+.ds-chart-series-3 { color: var(--ink-strong); }
+.ds-chart-legend { display: flex; flex-wrap: wrap; gap: var(--space-4); list-style: none; padding: 0; }
+.ds-chart-legend li { overflow-wrap: anywhere; }
+.ds-chart-swatch { display: inline-block; width: var(--space-6); border-top: 2px solid currentColor; margin-right: var(--space-2); vertical-align: middle; }
+.ds-chart-swatch.ds-chart-series-1 { border-top-style: dashed; }
+.ds-chart-swatch.ds-chart-series-2 { border-top-style: dotted; }
+.ds-chart-swatch.ds-chart-series-3 { border-top-style: double; border-top-width: 3px; }
+.ds-time-series summary { cursor: pointer; }
+.ds-time-series td { overflow-wrap: anywhere; }