@jcsoftdev/ui 0.0.0-stage → 0.1.0

package/dist/charts/timeline-chart/timeline-chart.js

@@ -0,0 +1,524 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { AxisBottom, estimateTextWidth, GridLines } from "../core/axes.js";
+import { ChartFrame } from "../core/chart-frame.js";
+import { ChartDataTable } from "../core/data-table.js";
+import { ChartLegend } from "../core/legend.js";
+import { EASE_OUT, fadeIn, useEntryAnimation } from "../core/motion.js";
+import { seriesColor } from "../core/palette.js";
+import { PlotOverlay } from "../core/plot-overlay.js";
+import { ChartTooltip } from "../core/tooltip.js";
+import { resolveLabels } from "../core/types.js";
+import { useSeriesState } from "../core/use-series-state.js";
+import { assignLanes, clockTicks, fitLaneHeight, formatClock } from "./timeline-lanes.js";
+const DEFAULT_TEXTS = {
+  group: "Status",
+  row: "Row",
+  time: "Time",
+  duration: "Duration",
+  now: "Now",
+  minutes: "min",
+  hours: "h"
+};
+const MARGIN = { top: 22, right: 12, bottom: 30 };
+const ROW_PAD = 8;
+const GAP = 3;
+const HOUR = 36e5;
+const FALLBACK_GROUP = "__none";
+function duration(ms, texts) {
+  const minutes = Math.round(ms / 6e4);
+  if (minutes < 60) return `${minutes} ${texts.minutes}`;
+  const h = Math.floor(minutes / 60);
+  const m = minutes % 60;
+  return m ? `${h} ${texts.hours} ${m} ${texts.minutes}` : `${h} ${texts.hours}`;
+}
+function fitText(text, room, size = 11) {
+  if (estimateTextWidth(text, size) <= room) return text;
+  const chars = Math.floor(room / (size * 0.58)) - 1;
+  return chars >= 3 ? `${text.slice(0, chars).trimEnd()}\u2026` : "";
+}
+const BarMark = memo(function BarMark2({
+  x,
+  y,
+  width,
+  height,
+  color,
+  active,
+  muted,
+  text
+}) {
+  return /* @__PURE__ */ jsxs(
+    "g",
+    {
+      "data-bar": "",
+      className: "motion-safe:transition-opacity motion-safe:duration-150",
+      style: {
+        opacity: muted ? 0.35 : 1,
+        transformBox: "fill-box",
+        transformOrigin: "left center"
+      },
+      children: [
+        /* @__PURE__ */ jsx(
+          "rect",
+          {
+            x,
+            y,
+            width,
+            height,
+            rx: 7,
+            strokeWidth: active ? 2 : 0,
+            style: { fill: color, fillOpacity: active ? 1 : 0.88, stroke: "var(--ink)" }
+          }
+        ),
+        text ? /* @__PURE__ */ jsx(
+          "text",
+          {
+            x: x + 8,
+            y: y + height / 2,
+            dy: "0.34em",
+            className: "pointer-events-none font-bold text-[11px]",
+            style: { fill: "var(--surface)" },
+            children: text
+          }
+        ) : null
+      ]
+    }
+  );
+});
+function TimelineChart({
+  rows,
+  items,
+  groups = [],
+  title,
+  description,
+  domain,
+  now = false,
+  height: heightMode,
+  aspectRatio,
+  laneHeight = 28,
+  grid = true,
+  legend,
+  tooltip = true,
+  loading,
+  animate = true,
+  initialHidden,
+  texts: textOverrides,
+  labels: labelOverrides,
+  className
+}) {
+  const labels = resolveLabels(labelOverrides);
+  const texts = { ...DEFAULT_TEXTS, ...textOverrides };
+  const state = useSeriesState(initialHidden);
+  const [clock, setClock] = useState(null);
+  useEffect(() => {
+    if (now === "auto") setClock(Date.now());
+    else setClock(null);
+  }, [now]);
+  const nowValue = now === false ? null : now === "auto" ? clock : +now;
+  const colorOf = useMemo(() => {
+    const map = new Map(groups.map((group, i) => [group.id, seriesColor(i, group.color)]));
+    return (id) => map.get(id ?? "") ?? "var(--accent-word)";
+  }, [groups]);
+  const layout = useMemo(() => {
+    const visibleItems = items.filter((item) => !state.isHidden(item.group ?? FALLBACK_GROUP));
+    const rowLayouts = rows.map((row, rowIndex) => {
+      const own = visibleItems.filter((item) => item.rowId === row.id);
+      const { lanes, count } = assignLanes(
+        own.map((item) => ({ start: +item.start, end: +item.end }))
+      );
+      return { row, rowIndex, own, lanes, count: Math.max(1, count) };
+    });
+    let t0 = Number.POSITIVE_INFINITY;
+    let t1 = Number.NEGATIVE_INFINITY;
+    for (const item of items) {
+      t0 = Math.min(t0, +item.start);
+      t1 = Math.max(t1, +item.end);
+    }
+    const start = domain ? +domain[0] : Number.isFinite(t0) ? Math.floor(t0 / HOUR) * HOUR : 0;
+    const end = domain ? +domain[1] : Number.isFinite(t1) ? Math.ceil(t1 / HOUR) * HOUR : HOUR;
+    let top = MARGIN.top;
+    const placed = [];
+    const bands = rowLayouts.map((entry) => {
+      const height = entry.count * (laneHeight + GAP) - GAP + ROW_PAD * 2;
+      const band = { ...entry, top: top - MARGIN.top, height };
+      entry.own.forEach((item, i) => {
+        placed.push({
+          item,
+          start: +item.start,
+          end: +item.end,
+          row: entry.rowIndex,
+          lane: entry.lanes[i],
+          color: colorOf(item.group),
+          group: item.group ?? FALLBACK_GROUP
+        });
+      });
+      top += height;
+      return band;
+    });
+    placed.sort((a, b) => a.row - b.row || a.start - b.start || a.lane - b.lane);
+    return { bands, placed, start, end, plotHeight: top - MARGIN.top };
+  }, [rows, items, domain, laneHeight, colorOf, state]);
+  const totalHeight = layout.plotHeight + MARGIN.top + MARGIN.bottom;
+  const legendItems = groups.length ? groups.map((group, i) => ({
+    id: group.id,
+    name: group.name,
+    color: seriesColor(i, group.color),
+    shape: "square",
+    hidden: state.isHidden(group.id)
+  })) : [];
+  const sortedAll = [...items].sort((a, b) => +a.start - +b.start);
+  const rowName = (id) => rows.find((row) => row.id === id)?.label ?? id;
+  const groupName = (id) => groups.find((group) => group.id === id)?.name ?? "";
+  return /* @__PURE__ */ jsx(
+    ChartFrame,
+    {
+      height: heightMode === "fill" ? "fill" : Math.max(totalHeight, 120),
+      aspectRatio,
+      labels,
+      loading,
+      empty: items.length === 0 || rows.length === 0,
+      skeleton: "bars",
+      legend: (legend ?? groups.length > 1) && legendItems.length ? /* @__PURE__ */ jsx(
+        ChartLegend,
+        {
+          items: legendItems,
+          onToggle: state.toggle,
+          onHighlight: state.setHighlighted
+        }
+      ) : null,
+      className,
+      table: /* @__PURE__ */ jsx(
+        ChartDataTable,
+        {
+          caption: description ? `${title}. ${description}` : title,
+          categoryHeader: labels.category,
+          categories: sortedAll.map((item) => item.label ?? item.id),
+          columns: [
+            { id: "row", name: texts.row, values: sortedAll.map((item) => rowName(item.rowId)) },
+            {
+              id: "group",
+              name: texts.group,
+              values: sortedAll.map((item) => groupName(item.group))
+            },
+            {
+              id: "time",
+              name: texts.time,
+              values: sortedAll.map(
+                (item) => `${formatClock(item.start)} - ${formatClock(item.end)}`
+              )
+            },
+            {
+              id: "duration",
+              name: texts.duration,
+              values: sortedAll.map((item) => duration(+item.end - +item.start, texts))
+            }
+          ]
+        }
+      ),
+      children: (width, measuredHeight) => /* @__PURE__ */ jsx(
+        TimelinePlot,
+        {
+          width,
+          height: heightMode === "fill" || aspectRatio ? measuredHeight : totalHeight,
+          stretch: heightMode === "fill" || aspectRatio != null,
+          rows,
+          layout,
+          nowValue,
+          laneHeight,
+          grid,
+          tooltip,
+          animate,
+          highlighted: state.highlighted,
+          texts,
+          groupName,
+          rowName,
+          labels,
+          title
+        }
+      )
+    }
+  );
+}
+function TimelinePlot({
+  width,
+  height,
+  rows,
+  layout,
+  nowValue,
+  laneHeight: baseLaneHeight,
+  stretch,
+  grid,
+  tooltip,
+  animate,
+  highlighted,
+  texts,
+  groupName,
+  rowName,
+  labels,
+  title
+}) {
+  const svgRef = useRef(null);
+  const [active, setActive] = useState(null);
+  const { placed, start, end } = layout;
+  const laneHeight = stretch ? fitLaneHeight({
+    counts: layout.bands.map((band) => band.count),
+    available: height - MARGIN.top - MARGIN.bottom,
+    gap: GAP,
+    rowPad: ROW_PAD
+  }) : baseLaneHeight;
+  const { bands, plotHeight } = useMemo(() => {
+    if (!stretch) return { bands: layout.bands, plotHeight: layout.plotHeight };
+    let top = 0;
+    const next = layout.bands.map((band) => {
+      const bandHeight = band.count * (laneHeight + GAP) - GAP + ROW_PAD * 2;
+      const placedBand = { ...band, top, height: bandHeight };
+      top += bandHeight;
+      return placedBand;
+    });
+    return { bands: next, plotHeight: top };
+  }, [layout.bands, layout.plotHeight, laneHeight, stretch]);
+  const narrow = width < 440;
+  const left = Math.min(
+    narrow ? 78 : 132,
+    Math.max(64, Math.max(...rows.map((r) => estimateTextWidth(r.label, 12)), 0) + 18)
+  );
+  const innerWidth = Math.max(60, width - left - MARGIN.right);
+  const x = useCallback(
+    (t) => (t - start) / (end - start || 1) * innerWidth,
+    [start, end, innerWidth]
+  );
+  const ticks = useMemo(
+    () => clockTicks(start, end, Math.max(2, Math.floor(innerWidth / 62))).map((tick) => ({
+      key: tick.value,
+      position: x(tick.value),
+      label: tick.label
+    })),
+    [start, end, x, innerWidth]
+  );
+  useEntryAnimation(
+    svgRef,
+    (root) => {
+      const list = root.querySelectorAll("[data-bar]");
+      const per = Math.min(24, 500 / Math.max(1, list.length));
+      list.forEach((bar, i) => {
+        bar.animate(
+          [
+            { transform: "scaleX(0)", opacity: 0 },
+            { transform: "scaleX(1)", opacity: 1 }
+          ],
+          {
+            duration: 520,
+            delay: i * per,
+            easing: EASE_OUT,
+            fill: "backwards"
+          }
+        );
+      });
+      for (const node of root.querySelectorAll("[data-fade]")) fadeIn(node, 360, 400);
+    },
+    { disabled: !animate }
+  );
+  const geometry = useMemo(
+    () => placed.map((entry) => {
+      const band = bands[entry.row];
+      const x0 = x(entry.start);
+      const x1 = x(entry.end);
+      return {
+        entry,
+        x: x0,
+        y: band.top + ROW_PAD + entry.lane * (laneHeight + GAP),
+        w: Math.max(3, x1 - x0)
+      };
+    }),
+    [placed, bands, laneHeight, x]
+  );
+  const current = active != null ? geometry[active] : void 0;
+  const valueText = current ? `${current.entry.item.label ?? current.entry.item.id}. ${rowName(current.entry.item.rowId)}. ${formatClock(
+    current.entry.start
+  )} - ${formatClock(current.entry.end)}${groupName(current.entry.item.group) ? `. ${groupName(current.entry.item.group)}` : ""}` : labels.explore;
+  const rowOf = (index) => geometry[index].entry.row;
+  const stepRow = (delta) => {
+    if (active == null) return false;
+    const from = geometry[active];
+    let best = -1;
+    let bestGap = Number.POSITIVE_INFINITY;
+    let target = rowOf(active) + delta;
+    while (best < 0 && target >= 0 && target < bands.length) {
+      geometry.forEach((g, i) => {
+        if (g.entry.row !== target) return;
+        const gap = Math.abs(g.entry.start - from.entry.start);
+        if (gap < bestGap) {
+          best = i;
+          bestGap = gap;
+        }
+      });
+      target += delta;
+    }
+    if (best >= 0) setActive(best);
+    return true;
+  };
+  return /* @__PURE__ */ jsxs("div", { className: "relative", style: { width }, children: [
+    /* @__PURE__ */ jsx(
+      "svg",
+      {
+        ref: svgRef,
+        role: "img",
+        "aria-label": title,
+        width,
+        height,
+        className: "block overflow-visible",
+        children: /* @__PURE__ */ jsxs("g", { transform: `translate(${left},${MARGIN.top})`, children: [
+          grid ? /* @__PURE__ */ jsx(GridLines, { ticks, direction: "vertical", length: plotHeight }) : null,
+          bands.map((band, i) => /* @__PURE__ */ jsxs("g", { children: [
+            i % 2 === 0 ? /* @__PURE__ */ jsx(
+              "rect",
+              {
+                x: -left + 4,
+                y: band.top,
+                width: left + innerWidth + MARGIN.right - 8,
+                height: band.height,
+                rx: 10,
+                style: { fill: "var(--surface-2)", fillOpacity: 0.45 }
+              }
+            ) : null,
+            /* @__PURE__ */ jsx(
+              "text",
+              {
+                x: -10,
+                y: band.top + band.height / 2,
+                dy: "0.34em",
+                textAnchor: "end",
+                className: "font-semibold text-[12px]",
+                style: { fill: "var(--ink-2)" },
+                children: fitText(band.row.label, left - 18, 12)
+              }
+            )
+          ] }, band.row.id)),
+          /* @__PURE__ */ jsx(AxisBottom, { ticks, offset: plotHeight }),
+          geometry.map((g, i) => /* @__PURE__ */ jsx(
+            BarMark,
+            {
+              x: g.x,
+              y: g.y,
+              width: g.w,
+              height: laneHeight,
+              color: g.entry.color,
+              active: active === i,
+              muted: active != null && active !== i || highlighted != null && highlighted !== g.entry.group,
+              text: g.w > 44 ? fitText(g.entry.item.label ?? "", g.w - 14) : ""
+            },
+            g.entry.item.id
+          )),
+          nowValue != null && nowValue >= start && nowValue <= end ? /* @__PURE__ */ jsxs("g", { "data-fade": "", className: "pointer-events-none", children: [
+            /* @__PURE__ */ jsx(
+              "line",
+              {
+                x1: x(nowValue),
+                x2: x(nowValue),
+                y1: -6,
+                y2: plotHeight,
+                strokeWidth: 1.5,
+                style: { stroke: "var(--danger)" }
+              }
+            ),
+            /* @__PURE__ */ jsx(
+              "rect",
+              {
+                x: x(nowValue) - 20,
+                y: -MARGIN.top + 2,
+                width: 40,
+                height: 16,
+                rx: 8,
+                style: { fill: "var(--danger)" }
+              }
+            ),
+            /* @__PURE__ */ jsx(
+              "text",
+              {
+                x: x(nowValue),
+                y: -MARGIN.top + 10,
+                dy: "0.34em",
+                textAnchor: "middle",
+                className: "font-bold text-[10px]",
+                style: { fill: "var(--surface)" },
+                children: texts.now
+              }
+            )
+          ] }) : null
+        ] })
+      }
+    ),
+    /* @__PURE__ */ jsx(
+      PlotOverlay,
+      {
+        left,
+        top: MARGIN.top,
+        width: innerWidth,
+        height: plotHeight,
+        label: labels.explore,
+        count: geometry.length,
+        active,
+        valueText,
+        onActiveChange: setActive,
+        keys: "horizontal",
+        indexAt: ({ x: px, y: py }) => {
+          const hit = geometry.findIndex(
+            (g) => px >= g.x && px <= g.x + g.w && py >= g.y && py <= g.y + laneHeight
+          );
+          return hit >= 0 ? hit : null;
+        },
+        onKey: (event) => {
+          if (event.key === "ArrowUp") return stepRow(-1);
+          if (event.key === "ArrowDown") return stepRow(1);
+          return false;
+        }
+      }
+    ),
+    tooltip && current ? /* @__PURE__ */ jsx(
+      ChartTooltip,
+      {
+        x: left + current.x + current.w / 2,
+        y: MARGIN.top + current.y + laneHeight / 2,
+        containerWidth: width,
+        title: current.entry.item.label ?? current.entry.item.id,
+        rows: [
+          ...groupName(current.entry.item.group) ? [
+            {
+              id: "group",
+              name: texts.group,
+              value: groupName(current.entry.item.group),
+              color: current.entry.color,
+              shape: "square"
+            }
+          ] : [],
+          {
+            id: "row",
+            name: texts.row,
+            value: rowName(current.entry.item.rowId),
+            color: "var(--ink-3)",
+            shape: "dot"
+          },
+          {
+            id: "time",
+            name: texts.time,
+            value: `${formatClock(current.entry.start)} - ${formatClock(current.entry.end)}`,
+            color: "var(--ink-3)",
+            shape: "dot"
+          },
+          {
+            id: "duration",
+            name: texts.duration,
+            value: duration(current.entry.end - current.entry.start, texts),
+            color: "var(--ink-3)",
+            shape: "dot"
+          },
+          ...current.entry.item.detail ? [{ id: "detail", name: current.entry.item.detail, value: "", color: "transparent" }] : []
+        ]
+      }
+    ) : null
+  ] });
+}
+export {
+  TimelineChart
+};

package/dist/charts/timeline-chart/timeline-lanes.d.ts

@@ -0,0 +1,43 @@
+export interface Interval {
+    start: number;
+    end: number;
+}
+export interface LaneAssignment {
+    /** Lane index per input item, same order as the input. */
+    lanes: number[];
+    /** Number of lanes used (0 when there are no items). */
+    count: number;
+}
+/**
+ * Packs overlapping intervals into the fewest lanes: items are placed in
+ * start order into the first lane that is already free. Intervals that only
+ * touch (one ends when the next starts) share a lane.
+ */
+export declare function assignLanes(items: ReadonlyArray<Interval>): LaneAssignment;
+/** "09:30" in 24-hour time. */
+export declare function formatClock(value: number | Date): string;
+export interface ClockTick {
+    value: number;
+    label: string;
+}
+/**
+ * Round clock ticks (every 15 min ... 1 day, aligned to local midnight) for a
+ * span of hours, at most about `count` of them.
+ */
+export declare function clockTicks(start: number, end: number, count?: number): ClockTick[];
+export interface FitLaneInput {
+    /** Lanes per row. */
+    counts: readonly number[];
+    /** Height available for all the rows together (axis margins already removed). */
+    available: number;
+    gap: number;
+    rowPad: number;
+    min?: number;
+    max?: number;
+}
+/**
+ * Lane height that makes the rows fill `available` exactly:
+ * `sum(count * (lane + gap) - gap + 2 * rowPad) = available`, clamped to
+ * `[min, max]`.
+ */
+export declare function fitLaneHeight({ counts, available, gap, rowPad, min, max, }: FitLaneInput): number;

package/dist/charts/timeline-chart/timeline-lanes.js

@@ -0,0 +1,65 @@
+import { shortMonth } from "../core/scales/time.js";
+function assignLanes(items) {
+  const order = items.map((_, index) => index).sort(
+    (a, b) => items[a].start - items[b].start || items[a].end - items[b].end || a - b
+  );
+  const laneEnds = [];
+  const lanes = new Array(items.length).fill(0);
+  for (const index of order) {
+    const item = items[index];
+    let lane = laneEnds.findIndex((end) => end <= item.start);
+    if (lane < 0) {
+      lane = laneEnds.length;
+      laneEnds.push(item.end);
+    } else {
+      laneEnds[lane] = item.end;
+    }
+    lanes[index] = lane;
+  }
+  return { lanes, count: laneEnds.length };
+}
+const MINUTE = 6e4;
+const STEPS = [15, 30, 60, 120, 180, 360, 720, 1440].map((m) => m * MINUTE);
+const clock = new Intl.DateTimeFormat("es-PE", {
+  hour: "2-digit",
+  minute: "2-digit",
+  hour12: false
+});
+function formatClock(value) {
+  return clock.format(value);
+}
+function clockTicks(start, end, count = 8) {
+  const span = Math.max(1, end - start);
+  const step = STEPS.find((candidate) => span / candidate <= count) ?? STEPS[STEPS.length - 1] ?? 1440 * MINUTE;
+  const origin = new Date(start);
+  origin.setHours(0, 0, 0, 0);
+  const first = origin.getTime() + Math.ceil((start - origin.getTime()) / step) * step;
+  const out = [];
+  for (let t = first; t <= end && out.length < 200; t += step) {
+    const date = new Date(t);
+    out.push({
+      value: t,
+      label: step >= 1440 * MINUTE ? `${date.getDate()} ${shortMonth(date)}` : formatClock(date)
+    });
+  }
+  return out;
+}
+function fitLaneHeight({
+  counts,
+  available,
+  gap,
+  rowPad,
+  min = 14,
+  max = 72
+}) {
+  const lanes = counts.reduce((sum, count) => sum + count, 0);
+  if (lanes <= 0) return min;
+  const fixed = counts.length * (2 * rowPad - gap) + lanes * gap;
+  return Math.min(max, Math.max(min, (available - fixed) / lanes));
+}
+export {
+  assignLanes,
+  clockTicks,
+  fitLaneHeight,
+  formatClock
+};

package/dist/charts/tree-chart/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./tree-card.js";
+export * from "./tree-chart.js";
+export * from "./tree-model.js";

package/dist/charts/tree-chart/index.js

@@ -0,0 +1,3 @@
+export * from "./tree-card.js";
+export * from "./tree-chart.js";
+export * from "./tree-model.js";

package/dist/charts/tree-chart/tree-card.d.ts

@@ -0,0 +1,37 @@
+import { type TreeChartNode } from "./tree-model.js";
+/** State of a node passed to the card template. */
+export interface TreeNodeState {
+    /** On the highlighted path (hover or keyboard) from the root. */
+    highlighted: boolean;
+    /** Something else is highlighted: the card may fade back. */
+    dimmed: boolean;
+    /** Keyboard cursor. */
+    active: boolean;
+    /** Children are hidden. */
+    collapsed: boolean;
+    hasChildren: boolean;
+    /** Nodes below this one, at any depth. */
+    descendants: number;
+    /** `showCounts` is on: the template should display `descendants`. */
+    showCount: boolean;
+    /** Children are being fetched. */
+    loading: boolean;
+    /** Matches the search box. */
+    matched: boolean;
+    /** Chosen with a click or the search box; its path to the root stays lit. */
+    selected: boolean;
+}
+export interface TreeCardProps {
+    node: TreeChartNode;
+    state: TreeNodeState;
+}
+/**
+ * Default node template: a card with a color rail, an avatar (image or
+ * initials), the name, a subtitle and an optional badge. Fills its box.
+ */
+export declare function TreeCard({ node, state }: TreeCardProps): import("react").JSX.Element;
+/**
+ * Compact node template for the radial and dendrogram layouts: a pill with a
+ * color dot, the name and, optionally, the descendant count.
+ */
+export declare function TreeChip({ node, state }: TreeCardProps): import("react").JSX.Element;