@jcsoftdev/ui 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,531 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { memo, useMemo, useRef, useState } from "react";
+import { AxisBottom, AxisLeft, estimateTextWidth, GridLines } from "../core/axes.js";
+import { ChartFrame } from "../core/chart-frame.js";
+import { ChartDataTable } from "../core/data-table.js";
+import { resolveAxisFormat, resolveFormat } from "../core/format.js";
+import { ChartLegend } from "../core/legend.js";
+import { EASE_OUT, fadeIn, useEntryAnimation } from "../core/motion.js";
+import { DIRECTION_COLORS } from "../core/palette.js";
+import { roundedRectPath } from "../core/path.js";
+import { PlotOverlay } from "../core/plot-overlay.js";
+import { bandScale } from "../core/scales/band.js";
+import { linearScale } from "../core/scales/linear.js";
+import { ChartTooltip } from "../core/tooltip.js";
+import { resolveLabels } from "../core/types.js";
+import {
+  pickLabels,
+  waterfallLayout
+} from "./waterfall-layout.js";
+const MARGIN = { top: 22, right: 14, bottom: 30 };
+const FILL = {
+  increase: DIRECTION_COLORS.up,
+  decrease: DIRECTION_COLORS.down,
+  start: DIRECTION_COLORS.flat,
+  subtotal: DIRECTION_COLORS.flat,
+  total: DIRECTION_COLORS.flat
+};
+const Bar = memo(function Bar2({
+  path,
+  kind,
+  active,
+  muted,
+  horizontal = false
+}) {
+  return /* @__PURE__ */ jsx(
+    "path",
+    {
+      "data-bar": "",
+      d: path,
+      className: "motion-safe:transition-[fill-opacity] motion-safe:duration-150",
+      style: {
+        fill: FILL[kind],
+        fillOpacity: muted ? 0.4 : kind === "subtotal" ? 0.62 : active ? 1 : 0.9,
+        transformBox: "fill-box",
+        transformOrigin: horizontal ? "left center" : "center bottom"
+      }
+    }
+  );
+});
+function truncate(text, maxChars) {
+  return text.length <= maxChars ? text : `${text.slice(0, Math.max(1, maxChars - 1)).trimEnd()}\u2026`;
+}
+function WaterfallChart({
+  steps,
+  title,
+  description,
+  height = 320,
+  aspectRatio,
+  valueFormat,
+  yAxis,
+  orientation = "vertical",
+  connectors = true,
+  dataLabels = true,
+  grid = true,
+  legend = true,
+  tooltip = true,
+  loading,
+  animate = true,
+  increaseLabel = "Increase",
+  decreaseLabel = "Decrease",
+  totalLabel = "Total",
+  runningLabel = "Running total",
+  labels: labelOverrides,
+  className
+}) {
+  const labels = resolveLabels(labelOverrides);
+  const fmt = useMemo(() => resolveFormat(valueFormat), [valueFormat]);
+  const layout = useMemo(() => waterfallLayout(steps), [steps]);
+  const signed = (bar) => bar.kind === "increase" ? `+${fmt(bar.value)}` : fmt(bar.value);
+  const kindName = (kind) => kind === "increase" ? increaseLabel : kind === "decrease" ? decreaseLabel : totalLabel;
+  return /* @__PURE__ */ jsx(
+    ChartFrame,
+    {
+      height,
+      aspectRatio,
+      labels,
+      loading,
+      empty: steps.length === 0,
+      skeleton: "bars",
+      legend: legend ? /* @__PURE__ */ jsx(
+        ChartLegend,
+        {
+          items: [
+            { id: "up", name: increaseLabel, color: DIRECTION_COLORS.up, shape: "square" },
+            { id: "down", name: decreaseLabel, color: DIRECTION_COLORS.down, shape: "square" },
+            { id: "total", name: totalLabel, color: DIRECTION_COLORS.flat, shape: "square" }
+          ]
+        }
+      ) : null,
+      className,
+      table: /* @__PURE__ */ jsx(
+        ChartDataTable,
+        {
+          caption: description ? `${title}. ${description}` : title,
+          categoryHeader: labels.category,
+          categories: layout.bars.map((bar) => bar.label),
+          columns: [
+            {
+              id: "value",
+              name: labels.total,
+              values: layout.bars.map((bar) => `${kindName(bar.kind)}: ${signed(bar)}`)
+            },
+            { id: "running", name: runningLabel, values: layout.bars.map((bar) => fmt(bar.to)) }
+          ]
+        }
+      ),
+      children: (width, measuredHeight) => {
+        const Plot = orientation === "horizontal" ? HorizontalWaterfallPlot : WaterfallPlot;
+        return /* @__PURE__ */ jsx(
+          Plot,
+          {
+            width,
+            height: measuredHeight,
+            bars: layout.bars,
+            min: layout.min,
+            max: layout.max,
+            fmt,
+            valueFormat,
+            yAxis,
+            connectors,
+            dataLabels,
+            grid,
+            tooltip,
+            animate,
+            signed,
+            kindName,
+            runningLabel,
+            labels,
+            title
+          }
+        );
+      }
+    }
+  );
+}
+function WaterfallPlot({
+  width,
+  height,
+  bars,
+  min,
+  max,
+  fmt,
+  valueFormat,
+  yAxis,
+  connectors,
+  dataLabels,
+  grid,
+  tooltip,
+  animate,
+  signed,
+  kindName,
+  runningLabel,
+  labels,
+  title
+}) {
+  const svgRef = useRef(null);
+  const [active, setActive] = useState(null);
+  const innerHeight = height - MARGIN.top - MARGIN.bottom;
+  const model = useMemo(() => {
+    const y2 = linearScale({
+      domain: [yAxis?.min ?? min, yAxis?.max ?? max],
+      range: [innerHeight, 0],
+      tickCount: yAxis?.tickCount ?? Math.max(3, Math.round(innerHeight / 56))
+    });
+    const axisFormat = resolveAxisFormat(yAxis?.format ?? valueFormat);
+    const yTicks2 = y2.ticks().map((tick) => ({ key: tick, position: y2.map(tick), label: axisFormat(tick) }));
+    const left2 = Math.max(...yTicks2.map((tick) => estimateTextWidth(tick.label)), 16) + 18;
+    const innerWidth2 = Math.max(40, width - left2 - MARGIN.right);
+    const x2 = bandScale({
+      count: bars.length,
+      range: [0, innerWidth2],
+      paddingInner: 0.32,
+      paddingOuter: 0.16
+    });
+    const maxChars = Math.max(3, Math.floor(x2.step / 6.4));
+    const xTicks2 = bars.map((bar, i) => ({
+      key: bar.id,
+      position: x2.center(i),
+      label: truncate(bar.label, maxChars)
+    }));
+    const shapes2 = bars.map((bar, i) => {
+      const top = y2.map(Math.max(bar.from, bar.to));
+      const bottom = y2.map(Math.min(bar.from, bar.to));
+      const h = Math.max(1.5, bottom - top);
+      return {
+        bar,
+        x: x2.start(i),
+        top,
+        bottom,
+        path: roundedRectPath(x2.start(i), top, x2.bandwidth, h, { tl: 4, tr: 4, br: 4, bl: 4 })
+      };
+    });
+    return { y: y2, yTicks: yTicks2, left: left2, innerWidth: innerWidth2, x: x2, xTicks: xTicks2, shapes: shapes2 };
+  }, [bars, min, max, innerHeight, width, yAxis, valueFormat]);
+  const { y, yTicks, left, innerWidth, x, xTicks, shapes } = model;
+  useEntryAnimation(
+    svgRef,
+    (root) => {
+      const list = root.querySelectorAll("[data-bar]");
+      const per = Math.min(60, 520 / Math.max(1, list.length));
+      list.forEach((bar, i) => {
+        bar.animate([{ transform: "scaleY(0)" }, { transform: "scaleY(1)" }], {
+          duration: 560,
+          delay: i * per,
+          easing: EASE_OUT,
+          fill: "backwards"
+        });
+      });
+      for (const node of root.querySelectorAll("[data-fade]")) fadeIn(node, 360, 520);
+    },
+    { disabled: !animate }
+  );
+  const current = active != null ? bars[active] : null;
+  const valueText = current ? `${current.label}. ${kindName(current.kind)} ${signed(current)}. ${runningLabel} ${fmt(current.to)}` : labels.explore;
+  const zero = y.map(0);
+  const shownLabels = pickLabels(
+    shapes.map((shape) => ({
+      center: shape.x + x.bandwidth / 2,
+      width: estimateTextWidth(signed(shape.bar), 11),
+      y: shape.top - 6
+    }))
+  );
+  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: yTicks, direction: "horizontal", length: innerWidth, zero }) : null,
+          /* @__PURE__ */ jsx(AxisLeft, { ticks: yTicks, offset: 0, title: yAxis?.title }),
+          /* @__PURE__ */ jsx(AxisBottom, { ticks: xTicks, offset: innerHeight }),
+          connectors ? shapes.slice(0, -1).map((shape, i) => {
+            const next = shapes[i + 1];
+            if (!next) return null;
+            const level = y.map(shape.bar.to);
+            return /* @__PURE__ */ jsx(
+              "line",
+              {
+                "data-fade": "",
+                x1: shape.x + x.bandwidth,
+                x2: next.x,
+                y1: level,
+                y2: level,
+                strokeDasharray: "3 3",
+                shapeRendering: "crispEdges",
+                style: { stroke: "var(--ink-3)", strokeOpacity: 0.7 }
+              },
+              shape.bar.id
+            );
+          }) : null,
+          shapes.map((shape, i) => /* @__PURE__ */ jsx(
+            Bar,
+            {
+              path: shape.path,
+              kind: shape.bar.kind,
+              active: active === i,
+              muted: active != null && active !== i
+            },
+            shape.bar.id
+          )),
+          dataLabels ? shapes.map(
+            (shape, i) => !shownLabels[i] ? null : /* @__PURE__ */ jsx(
+              "text",
+              {
+                "data-fade": "",
+                x: shape.x + x.bandwidth / 2,
+                y: shape.top - 6,
+                textAnchor: "middle",
+                className: "font-bold text-[11px] tabular-nums",
+                style: {
+                  fill: shape.bar.kind === "increase" ? DIRECTION_COLORS.up : shape.bar.kind === "decrease" ? DIRECTION_COLORS.down : "var(--ink)",
+                  opacity: active != null && active !== i ? 0.45 : 1
+                },
+                children: signed(shape.bar)
+              },
+              shape.bar.id
+            )
+          ) : null
+        ] })
+      }
+    ),
+    /* @__PURE__ */ jsx(
+      PlotOverlay,
+      {
+        left,
+        top: 0,
+        width: innerWidth,
+        height,
+        label: labels.explore,
+        count: bars.length,
+        active,
+        valueText,
+        onActiveChange: setActive,
+        indexAt: ({ x: px }) => bars.length ? x.indexAt(px) : null
+      }
+    ),
+    tooltip && current && active != null ? /* @__PURE__ */ jsx(
+      ChartTooltip,
+      {
+        x: left + x.center(active),
+        y: MARGIN.top + shapes[active].top,
+        containerWidth: width,
+        title: current.label,
+        rows: [
+          {
+            id: "value",
+            name: kindName(current.kind),
+            value: signed(current),
+            color: FILL[current.kind],
+            shape: "square"
+          },
+          {
+            id: "running",
+            name: runningLabel,
+            value: fmt(current.to),
+            color: "var(--ink-3)",
+            shape: "dot"
+          }
+        ]
+      }
+    ) : null
+  ] });
+}
+const H_MARGIN = { top: 8, right: 56, bottom: 30 };
+function HorizontalWaterfallPlot({
+  width,
+  height,
+  bars,
+  min,
+  max,
+  fmt,
+  valueFormat,
+  yAxis,
+  connectors,
+  dataLabels,
+  grid,
+  tooltip,
+  animate,
+  signed,
+  kindName,
+  runningLabel,
+  labels,
+  title
+}) {
+  const svgRef = useRef(null);
+  const [active, setActive] = useState(null);
+  const innerHeight = Math.max(40, height - H_MARGIN.top - H_MARGIN.bottom);
+  const model = useMemo(() => {
+    const left2 = Math.min(
+      width * 0.36,
+      Math.max(48, ...bars.map((bar) => estimateTextWidth(bar.label, 12))) + 14
+    );
+    const innerWidth2 = Math.max(40, width - left2 - (dataLabels ? H_MARGIN.right : 12));
+    const x2 = linearScale({
+      domain: [yAxis?.min ?? min, yAxis?.max ?? max],
+      range: [0, innerWidth2],
+      tickCount: yAxis?.tickCount ?? Math.max(2, Math.round(innerWidth2 / 130))
+    });
+    const axisFormat = resolveAxisFormat(yAxis?.format ?? valueFormat);
+    const xTicks2 = x2.ticks().map((tick) => ({ key: tick, position: x2.map(tick), label: axisFormat(tick) }));
+    const band2 = bandScale({
+      count: bars.length,
+      range: [0, innerHeight],
+      paddingInner: 0.3,
+      paddingOuter: 0.1
+    });
+    const maxChars = Math.max(3, Math.floor((left2 - 14) / 6.6));
+    const yTicks2 = bars.map((bar, i) => ({
+      key: bar.id,
+      position: band2.center(i),
+      label: truncate(bar.label, maxChars)
+    }));
+    const shapes2 = bars.map((bar, i) => {
+      const a = x2.map(Math.min(bar.from, bar.to));
+      const b = x2.map(Math.max(bar.from, bar.to));
+      const w = Math.max(1.5, b - a);
+      return {
+        bar,
+        y: band2.start(i),
+        left: a,
+        right: a + w,
+        path: roundedRectPath(a, band2.start(i), w, band2.bandwidth, { tl: 4, tr: 4, br: 4, bl: 4 })
+      };
+    });
+    return { x: x2, xTicks: xTicks2, yTicks: yTicks2, left: left2, innerWidth: innerWidth2, band: band2, shapes: shapes2 };
+  }, [bars, min, max, innerHeight, width, yAxis, valueFormat, dataLabels]);
+  const { x, xTicks, yTicks, left, innerWidth, band, shapes } = model;
+  useEntryAnimation(
+    svgRef,
+    (root) => {
+      const list = root.querySelectorAll("[data-bar]");
+      const per = Math.min(60, 520 / Math.max(1, list.length));
+      list.forEach((bar, i) => {
+        bar.animate([{ transform: "scaleX(0)" }, { transform: "scaleX(1)" }], {
+          duration: 560,
+          delay: i * per,
+          easing: EASE_OUT,
+          fill: "backwards"
+        });
+      });
+      for (const node of root.querySelectorAll("[data-fade]")) fadeIn(node, 360, 520);
+    },
+    { disabled: !animate }
+  );
+  const current = active != null ? bars[active] : null;
+  const valueText = current ? `${current.label}. ${kindName(current.kind)} ${signed(current)}. ${runningLabel} ${fmt(current.to)}` : labels.explore;
+  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},${H_MARGIN.top})`, children: [
+          grid ? /* @__PURE__ */ jsx(GridLines, { ticks: xTicks, direction: "vertical", length: innerHeight, zero: x.map(0) }) : null,
+          /* @__PURE__ */ jsx(AxisLeft, { ticks: yTicks, offset: 0 }),
+          /* @__PURE__ */ jsx(AxisBottom, { ticks: xTicks, offset: innerHeight }),
+          connectors ? shapes.slice(0, -1).map((shape, i) => {
+            const next = shapes[i + 1];
+            if (!next) return null;
+            const level = x.map(shape.bar.to);
+            return /* @__PURE__ */ jsx(
+              "line",
+              {
+                "data-fade": "",
+                x1: level,
+                x2: level,
+                y1: shape.y + band.bandwidth,
+                y2: next.y,
+                strokeDasharray: "3 3",
+                shapeRendering: "crispEdges",
+                style: { stroke: "var(--ink-3)", strokeOpacity: 0.7 }
+              },
+              shape.bar.id
+            );
+          }) : null,
+          shapes.map((shape, i) => /* @__PURE__ */ jsx(
+            Bar,
+            {
+              path: shape.path,
+              kind: shape.bar.kind,
+              horizontal: true,
+              active: active === i,
+              muted: active != null && active !== i
+            },
+            shape.bar.id
+          )),
+          dataLabels ? shapes.map((shape, i) => /* @__PURE__ */ jsx(
+            "text",
+            {
+              "data-fade": "",
+              x: shape.right + 6,
+              y: shape.y + band.bandwidth / 2,
+              dy: "0.34em",
+              className: "font-bold text-[11px] tabular-nums",
+              style: {
+                fill: shape.bar.kind === "increase" ? DIRECTION_COLORS.up : shape.bar.kind === "decrease" ? DIRECTION_COLORS.down : "var(--ink)",
+                opacity: active != null && active !== i ? 0.45 : 1
+              },
+              children: signed(shape.bar)
+            },
+            shape.bar.id
+          )) : null
+        ] })
+      }
+    ),
+    /* @__PURE__ */ jsx(
+      PlotOverlay,
+      {
+        left: 0,
+        top: H_MARGIN.top,
+        width: left + innerWidth,
+        height: innerHeight,
+        label: labels.explore,
+        count: bars.length,
+        active,
+        valueText,
+        onActiveChange: setActive,
+        keys: "vertical",
+        indexAt: ({ y }) => bars.length ? band.indexAt(y) : null
+      }
+    ),
+    tooltip && current && active != null ? /* @__PURE__ */ jsx(
+      ChartTooltip,
+      {
+        x: left + shapes[active].right,
+        y: H_MARGIN.top + band.center(active),
+        containerWidth: width,
+        title: current.label,
+        rows: [
+          {
+            id: "value",
+            name: kindName(current.kind),
+            value: signed(current),
+            color: FILL[current.kind],
+            shape: "square"
+          },
+          {
+            id: "running",
+            name: runningLabel,
+            value: fmt(current.to),
+            color: "var(--ink-3)",
+            shape: "dot"
+          }
+        ]
+      }
+    ) : null
+  ] });
+}
+export {
+  WaterfallChart
+};

package/dist/charts/waterfall-chart/waterfall-layout.d.ts

@@ -0,0 +1,51 @@
+/**
+ * - `start`: opening balance, an absolute bar from 0 that sets the running total.
+ * - `delta`: an increase (positive) or a decrease (negative) applied to the running total.
+ * - `subtotal`: a bar from 0 to the running total so far (its `value` is ignored).
+ * - `total`: the same as a subtotal, drawn as the closing bar.
+ */
+export type WaterfallStepType = "start" | "delta" | "subtotal" | "total";
+export interface WaterfallStep {
+    id?: string;
+    label: string;
+    value?: number;
+    /** Defaults to "delta". */
+    type?: WaterfallStepType;
+}
+export type WaterfallKind = "increase" | "decrease" | "start" | "subtotal" | "total";
+export interface WaterfallBar {
+    index: number;
+    id: string;
+    label: string;
+    kind: WaterfallKind;
+    /** Delta for increases and decreases, absolute amount for start, subtotal and total. */
+    value: number;
+    /** Where the bar begins on the value axis. */
+    from: number;
+    /** Where the bar ends; also the running total after this step. */
+    to: number;
+}
+export interface WaterfallLayout {
+    bars: WaterfallBar[];
+    /** Lowest and highest value any bar reaches, always including 0. */
+    min: number;
+    max: number;
+    /** Running total after the last step. */
+    final: number;
+}
+/** Running totals for a list of steps. Missing values count as 0. */
+export declare function waterfallLayout(steps: ReadonlyArray<WaterfallStep>): WaterfallLayout;
+export interface WaterfallLabelBox {
+    /** Horizontal centre of the label. */
+    center: number;
+    width: number;
+    /** Baseline of the label. */
+    y: number;
+}
+/**
+ * Which labels to draw: left to right, a label is kept unless it overlaps an
+ * already kept one horizontally while sitting less than `lineHeight` away
+ * vertically. Labels wider than their bar still show whenever the neighbours
+ * are far enough above or below, or the gap between them is wide enough.
+ */
+export declare function pickLabels(boxes: readonly WaterfallLabelBox[], gap?: number, lineHeight?: number): boolean[];

package/dist/charts/waterfall-chart/waterfall-layout.js

@@ -0,0 +1,54 @@
+function waterfallLayout(steps) {
+  let running = 0;
+  let min = 0;
+  let max = 0;
+  const bars = steps.map((step, index) => {
+    const type = step.type ?? "delta";
+    const value = step.value ?? 0;
+    let kind;
+    let from;
+    let to;
+    let shown = value;
+    if (type === "start") {
+      kind = "start";
+      from = 0;
+      to = value;
+    } else if (type === "subtotal" || type === "total") {
+      kind = type;
+      from = 0;
+      to = running;
+      shown = running;
+    } else {
+      kind = value >= 0 ? "increase" : "decrease";
+      from = running;
+      to = running + value;
+    }
+    running = to;
+    min = Math.min(min, from, to);
+    max = Math.max(max, from, to);
+    return {
+      index,
+      id: step.id ?? `${index}-${step.label}`,
+      label: step.label,
+      kind,
+      value: shown,
+      from,
+      to
+    };
+  });
+  return { bars, min, max, final: running };
+}
+function pickLabels(boxes, gap = 4, lineHeight = 13) {
+  const kept = [];
+  return boxes.map((box) => {
+    const clash = kept.some(
+      (other) => Math.abs(other.center - box.center) < (other.width + box.width) / 2 + gap && Math.abs(other.y - box.y) < lineHeight
+    );
+    if (!clash) kept.push(box);
+    return !clash;
+  });
+}
+export {
+  pickLabels,
+  waterfallLayout
+};

package/dist/containers/action-bar/action-bar.d.ts

@@ -0,0 +1,18 @@
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+export interface ActionBarProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
+    /** Number of selected items. The bar renders nothing while it is 0. */
+    selectedCount: number;
+    /** Singular and plural noun for the live count, e.g. ["cita", "citas"]. */
+    noun?: [singular: string, plural: string];
+    /** Clears the selection (close button and Escape). */
+    onClear?: () => void;
+    /** Bulk actions, usually Buttons. */
+    children?: ReactNode;
+    /**
+     * `fixed` floats over the viewport; `absolute` floats inside the nearest positioned
+     * ancestor (a card, a table wrapper); `static` renders inline.
+     */
+    position?: "fixed" | "absolute" | "static";
+}
+/** Floating toolbar for bulk actions on a selection. Announces the count politely. */
+export declare function ActionBar({ selectedCount, noun, onClear, children, position, className, onKeyDown, ...props }: ActionBarProps): import("react").JSX.Element | null;