@djangocfg/ui-tools 2.1.417 → 2.1.419

package/src/tools/visual/charts/CommitGraph/hooks/useGraphLayout.ts

@@ -0,0 +1,169 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import { useMemo } from 'react';
+import type { Commit, Edge, GraphRow } from '../types';
+import { pickLaneColor } from './useLaneColors';
+
+/**
+ * Topological layout pass for the commit graph.
+ *
+ * Walks the commit list in order (newest first) and tracks active rails —
+ * each slot holds the hash of the parent the rail is "waiting for". The
+ * algorithm produces:
+ *
+ *  - The rail a commit's dot occupies.
+ *  - The rails state after the row (for the next iteration).
+ *  - Edges to draw on this row (pass-throughs, merge curves, fork curves).
+ *
+ * Rail colors are looked up at layout time so the rendered SVG can use raw
+ * hex `stroke=` values — Canvas2D/SVG won't parse Tailwind classes.
+ */
+function computeLayout(commits: Commit[], laneColors: string[]): GraphRow[] {
+  const rows: GraphRow[] = [];
+  const rails: (string | null)[] = [];
+  const color = (rail: number) => pickLaneColor(laneColors, rail);
+
+  for (const commit of commits) {
+    const hash = commit.hash;
+
+    // Find which rail this commit occupies (if any rail is waiting for it).
+    let commitRail = rails.indexOf(hash);
+
+    if (commitRail === -1) {
+      // New branch — find first empty slot or append.
+      const emptySlot = rails.indexOf(null);
+      if (emptySlot !== -1) {
+        commitRail = emptySlot;
+        rails[commitRail] = hash;
+      } else {
+        commitRail = rails.length;
+        rails.push(hash);
+      }
+    }
+
+    const commitColor = color(commitRail);
+    const edges: Edge[] = [];
+
+    // Pass-through rails (everything not on the commit rail).
+    for (let r = 0; r < rails.length; r++) {
+      if (r !== commitRail && rails[r] !== null) {
+        edges.push({ fromRail: r, toRail: r, color: color(r), type: 'straight' });
+      }
+    }
+
+    // Clear this rail — the commit has been rendered.
+    rails[commitRail] = null;
+
+    // First parent continues on the commit's rail unless already expected
+    // elsewhere (merge of two existing branches).
+    const parents = commit.parents;
+    if (parents.length >= 1) {
+      const firstParent = parents[0];
+      const existingRail = rails.indexOf(firstParent);
+      if (existingRail !== -1) {
+        edges.push({
+          fromRail: commitRail,
+          toRail: existingRail,
+          color: commitColor,
+          type: 'merge-in',
+        });
+      } else {
+        rails[commitRail] = firstParent;
+        edges.push({
+          fromRail: commitRail,
+          toRail: commitRail,
+          color: commitColor,
+          type: 'straight',
+        });
+      }
+    }
+
+    // Second+ parents (merge sources / forks).
+    for (let p = 1; p < parents.length; p++) {
+      const parentHash = parents[p];
+      const existingRail = rails.indexOf(parentHash);
+      if (existingRail !== -1) {
+        edges.push({
+          fromRail: existingRail,
+          toRail: commitRail,
+          color: color(existingRail),
+          type: 'merge-in',
+        });
+      } else {
+        const emptySlot = rails.indexOf(null);
+        const newRail = emptySlot !== -1 ? emptySlot : rails.length;
+        if (newRail >= rails.length) rails.push(null);
+        rails[newRail] = parentHash;
+        edges.push({
+          fromRail: commitRail,
+          toRail: newRail,
+          color: color(newRail),
+          type: 'fork-out',
+        });
+      }
+    }
+
+    // Trim trailing nulls so `maxRails` stays accurate.
+    while (rails.length > 0 && rails[rails.length - 1] === null) {
+      rails.pop();
+    }
+
+    rows.push({
+      commit,
+      rail: commitRail,
+      rails: [...rails],
+      edges,
+    });
+  }
+
+  return rows;
+}
+
+/**
+ * Auto-infer a linear topology when no commit declares parents — the
+ * jalcoui examples ship a flat list and rely on the component to chain
+ * them.
+ */
+function ensureTopology(commits: Commit[]): Commit[] {
+  const hasTopology = commits.some((c) => c.parents && c.parents.length > 0);
+  if (hasTopology) return commits;
+  return commits.map((c, i) => ({
+    ...c,
+    parents: i < commits.length - 1 ? [commits[i + 1].hash] : [],
+  }));
+}
+
+export interface GraphLayout {
+  rows: GraphRow[];
+  maxRails: number;
+}
+
+/**
+ * React-friendly wrapper around {@link computeLayout}. Memoizes on
+ * `commits` + `laneColors` identity so theme switches re-color but do not
+ * reshuffle topology.
+ */
+export function useGraphLayout(
+  commits: Commit[],
+  laneColors: string[],
+): GraphLayout {
+  return useMemo(() => {
+    const resolved = ensureTopology(commits);
+    if (resolved.length === 0) {
+      return { rows: [], maxRails: 0 };
+    }
+    const rows = computeLayout(resolved, laneColors);
+    const maxRails = Math.max(
+      ...rows.map((r) =>
+        Math.max(
+          r.rail + 1,
+          r.rails.length,
+          ...r.edges.map((e) => Math.max(e.fromRail, e.toRail) + 1),
+        ),
+      ),
+    );
+    return { rows, maxRails };
+  }, [commits, laneColors]);
+}

package/src/tools/visual/charts/CommitGraph/hooks/useLaneColors.ts

@@ -0,0 +1,45 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import { useMemo } from 'react';
+import { useStylePresets } from '@djangocfg/ui-core/styles/palette';
+
+/**
+ * Hook returning the categorical lane palette as an array of hex strings.
+ *
+ * jalcoui hard-codes 8 raw colors (`#3b82f6`, `#22c55e`, …) — that would
+ * break every non-default theme preset. We instead derive the palette from
+ * {@link useStylePresets}: 8 distinguishable categorical fills that already
+ * respect the active theme. Branches beyond index 7 cycle modulo the
+ * palette length.
+ *
+ * Order is chosen for maximum perceptual distance between adjacent rails:
+ * primary → success → warning → danger → info → chart3 → chart4 → chart5.
+ */
+export function useLaneColors(): string[] {
+  const presets = useStylePresets();
+
+  return useMemo(
+    () => [
+      presets.primary.fill,
+      presets.success.fill,
+      presets.warning.fill,
+      presets.danger.fill,
+      presets.info.fill,
+      presets.chart3.fill,
+      presets.chart4.fill,
+      presets.chart5.fill,
+    ],
+    [presets],
+  );
+}
+
+/**
+ * Pick the color for a rail index, cycling when there are more rails than
+ * palette entries.
+ */
+export function pickLaneColor(colors: string[], rail: number): string {
+  if (colors.length === 0) return '#000000';
+  return colors[((rail % colors.length) + colors.length) % colors.length];
+}

package/src/tools/visual/charts/CommitGraph/index.ts

@@ -0,0 +1,14 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+export { CommitGraph } from './CommitGraph';
+export { useLaneColors, pickLaneColor } from './hooks/useLaneColors';
+export { useGraphLayout } from './hooks/useGraphLayout';
+export { ROW_HEIGHT } from './types';
+export type {
+  Commit,
+  CommitAuthor,
+  CommitGraphProps,
+  Edge,
+  EdgeType,
+  GraphRow,
+} from './types';

package/src/tools/visual/charts/CommitGraph/lazy.tsx

@@ -0,0 +1,25 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import { createLazyComponent } from '../../../../common/lazy-wrapper';
+import type { CommitGraphProps } from './types';
+
+export const LazyCommitGraph = createLazyComponent<CommitGraphProps>(
+  () => import('./CommitGraph').then((mod) => ({ default: mod.CommitGraph })),
+  {
+    displayName: 'LazyCommitGraph',
+    fallback: (
+      <div
+        data-slot="commit-graph-skeleton"
+        className="h-40 w-full animate-pulse rounded-xl bg-muted"
+      />
+    ),
+  },
+);
+
+export type {
+  CommitGraphProps,
+  Commit,
+  CommitAuthor,
+} from './types';

package/src/tools/visual/charts/CommitGraph/types.ts

@@ -0,0 +1,85 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+import type * as React from 'react';
+
+/**
+ * Author metadata rendered next to each commit row and inside the detail
+ * popover. Avatar URLs are optional — when omitted, the initials of
+ * {@link CommitAuthor.name} are shown instead.
+ */
+export interface CommitAuthor {
+  name: string;
+  avatarUrl?: string;
+}
+
+/**
+ * Single commit node fed into {@link CommitGraph}. Commits must be passed in
+ * topological order (newest first). The `parents` array drives the rail
+ * topology — empty for root commits, one entry for normal commits, two or
+ * more for merges.
+ */
+export interface Commit {
+  /** Commit hash (full or abbreviated). */
+  hash: string;
+  /** Commit message (first line). */
+  message: string;
+  /** Commit author. */
+  author: CommitAuthor;
+  /** ISO date string or Date object. */
+  date: string | Date;
+  /** Parent commit hashes. Empty for root commits. Two parents = merge commit. */
+  parents: string[];
+  /** Branch or ref labels (e.g. `"main"`, `"feat/auth"`). */
+  refs?: string[];
+  /** Tag label (e.g. `"v1.0.0"`). */
+  tag?: string;
+}
+
+/**
+ * Props for {@link CommitGraph}.
+ */
+export interface CommitGraphProps
+  extends Omit<React.ComponentProps<'div'>, 'children'> {
+  /** Commits in topological order (newest first). */
+  commits: Commit[];
+  /** Number of hash characters to display. @default 7 */
+  truncateHash?: number;
+  /** Pixel width per rail column. @default 24 */
+  railWidth?: number;
+}
+
+/**
+ * Type of edge a rail segment renders inside a row. The layout pass tags
+ * every drawn segment with one of these — the SVG renderer only needs to
+ * pick the geometry per type.
+ */
+export type EdgeType = 'straight' | 'merge-in' | 'fork-out';
+
+/**
+ * A single edge inside a {@link GraphRow}. Indices refer to rail slots
+ * (left-to-right) and `color` is a hex string already resolved through the
+ * theme palette — never a raw scale.
+ */
+export interface Edge {
+  fromRail: number;
+  toRail: number;
+  color: string;
+  type: EdgeType;
+}
+
+/**
+ * Output of {@link computeLayout}. One row per commit, with the rail
+ * topology snapshot needed to draw rails + edges.
+ */
+export interface GraphRow {
+  commit: Commit;
+  /** Rail index this commit's dot occupies. */
+  rail: number;
+  /** Rails state after this row (`null` = empty slot). */
+  rails: (string | null)[];
+  /** Edges to draw between the previous row and this row. */
+  edges: Edge[];
+}
+
+/** Pixel height of a single commit row. */
+export const ROW_HEIGHT = 40;

package/src/tools/visual/charts/CommitGraph/utils.ts

@@ -0,0 +1,53 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+/**
+ * Author initials fallback for the avatar slot. Returns up to 2 uppercase
+ * characters drawn from the first letter of each whitespace-separated word.
+ */
+export function initials(name: string): string {
+  return name
+    .split(/\s+/)
+    .map((w) => w[0] ?? '')
+    .join('')
+    .toUpperCase()
+    .slice(0, 2);
+}
+
+/**
+ * Relative "x ago" formatter used on each commit row. Falls back to a
+ * locale-formatted date once the gap exceeds a week.
+ */
+export function formatRelativeDate(date: string | Date): string {
+  const d = typeof date === 'string' ? new Date(date) : date;
+  const now = new Date();
+  const diffMs = now.getTime() - d.getTime();
+  const diffMins = Math.floor(diffMs / 60_000);
+  const diffHours = Math.floor(diffMs / 3_600_000);
+  const diffDays = Math.floor(diffMs / 86_400_000);
+
+  if (diffMins < 1) return 'just now';
+  if (diffMins < 60) return `${diffMins}m ago`;
+  if (diffHours < 24) return `${diffHours}h ago`;
+  if (diffDays < 7) return `${diffDays}d ago`;
+
+  return d.toLocaleDateString('en-US', {
+    month: 'short',
+    day: 'numeric',
+    year: d.getFullYear() !== now.getFullYear() ? 'numeric' : undefined,
+  });
+}
+
+/**
+ * Fully-qualified date shown inside the commit detail popover.
+ */
+export function formatFullDate(date: string | Date): string {
+  const d = typeof date === 'string' ? new Date(date) : date;
+  return d.toLocaleDateString('en-US', {
+    weekday: 'short',
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit',
+  });
+}

package/src/tools/visual/{Gauge → charts/Gauge}/lazy.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { createLazyComponent } from '../../../components/lazy-wrapper';
+import { createLazyComponent } from '../../../../common/lazy-wrapper';
 import type { GaugeProps } from './types';
 
 export const LazyGauge = createLazyComponent<GaugeProps>(

package/src/tools/visual/charts/Sparkline/README.md

@@ -0,0 +1,29 @@
+# Sparkline
+
+Compact inline trend chart (line / area / bar). Resolves stroke + fill via `useThemeColor(color)` — semantic tokens only, no raw scales.
+
+```tsx
+import { Sparkline } from '@djangocfg/ui-tools/sparkline';
+
+<Sparkline data={[3, 5, 4, 7, 9, 8, 12]} variant="area" color="success" />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `data` | `SparklineDatum[]` | — | `number` or `{ value, label? }`. Empty array renders nothing. |
+| `variant` | `'line' \| 'area' \| 'bar'` | `'line'` | Visual style. |
+| `color` | `'primary' \| 'success' \| 'warning' \| 'destructive' \| 'info'` | `'primary'` | Semantic theme color. |
+| `width` | `number` | `120` | SVG width. |
+| `height` | `number` | `32` | SVG height. |
+| `strokeWidth` | `number` | `1.5` | Line stroke (ignored for `bar`). |
+| `showEndpoint` | `boolean` | `true` | Filled dot at latest point. |
+| `showBaseline` | `boolean` | `false` | Dashed average line. |
+| `ariaLabel` | `string` | — | Accessible label. |
+
+Storybook: `apps/storybook/stories/ui-tools/visual/Sparkline.stories.tsx`
+
+---
+
+Adapted from jalcoui (MIT).

package/src/tools/visual/charts/Sparkline/Sparkline.tsx

@@ -0,0 +1,217 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+//
+// Generic inline SVG sparkline. Pure SVG, no charting deps. Color resolves
+// through the theme palette (semantic token → hex), so the stroke and area
+// fill follow the active preset.
+//
+// Requires <UiProviders> mounted by the host app (no nested providers here).
+
+'use client';
+
+import * as React from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+import { useThemeColor, alpha } from '@djangocfg/ui-core/styles/palette';
+import type { SparklineDatum, SparklineProps } from './types';
+
+function toValue(d: SparklineDatum): number {
+  return typeof d === 'number' ? d : d.value;
+}
+
+interface Stats {
+  values: number[];
+  min: number;
+  max: number;
+  range: number;
+  avg: number;
+}
+
+function computeStats(data: SparklineDatum[]): Stats {
+  const values = data.map(toValue);
+  const max = Math.max(...values, 1);
+  const min = Math.min(...values);
+  const range = max - min || 1;
+  const total = values.reduce((s, v) => s + v, 0);
+  const avg = values.length > 0 ? total / values.length : 0;
+  return { values, min, max, range, avg };
+}
+
+function buildLinePath(
+  values: number[],
+  width: number,
+  height: number,
+  padding: number,
+  min: number,
+  range: number,
+): string {
+  if (values.length === 0) return '';
+  const drawHeight = height - padding * 2;
+  const drawWidth = width - padding * 2;
+  const denom = values.length - 1 || 1;
+
+  return values
+    .map((v, i) => {
+      const x = padding + (i / denom) * drawWidth;
+      const y = padding + drawHeight - ((v - min) / range) * drawHeight;
+      return `${i === 0 ? 'M' : 'L'} ${x.toFixed(2)} ${y.toFixed(2)}`;
+    })
+    .join(' ');
+}
+
+function buildAreaPath(
+  linePath: string,
+  width: number,
+  height: number,
+  padding: number,
+): string {
+  if (!linePath) return '';
+  const lastX = width - padding;
+  const firstX = padding;
+  const bottom = height - padding;
+  return `${linePath} L ${lastX.toFixed(2)} ${bottom.toFixed(2)} L ${firstX.toFixed(2)} ${bottom.toFixed(2)} Z`;
+}
+
+function getEndpoint(
+  values: number[],
+  width: number,
+  height: number,
+  padding: number,
+  min: number,
+  range: number,
+): { x: number; y: number } | null {
+  if (values.length === 0) return null;
+  const drawHeight = height - padding * 2;
+  const lastV = values[values.length - 1];
+  return {
+    x: width - padding,
+    y: padding + drawHeight - ((lastV - min) / range) * drawHeight,
+  };
+}
+
+function getBaselineY(
+  avg: number,
+  height: number,
+  padding: number,
+  min: number,
+  range: number,
+): number {
+  const drawHeight = height - padding * 2;
+  return padding + drawHeight - ((avg - min) / range) * drawHeight;
+}
+
+export function Sparkline({
+  data,
+  variant = 'line',
+  color = 'primary',
+  width = 120,
+  height = 32,
+  strokeWidth = 1.5,
+  showEndpoint = true,
+  showBaseline = false,
+  ariaLabel,
+  className,
+  ...rest
+}: SparklineProps) {
+  const stroke = useThemeColor(color);
+  const fill = alpha(stroke, 0.15);
+  const baselineStroke = alpha(stroke, 0.4);
+
+  if (data.length === 0) return null;
+
+  const stats = computeStats(data);
+  const padding = variant === 'bar' ? 2 : 2 + strokeWidth;
+  const linePath =
+    variant !== 'bar'
+      ? buildLinePath(stats.values, width, height, padding, stats.min, stats.range)
+      : '';
+  const areaPath = variant === 'area' ? buildAreaPath(linePath, width, height, padding) : '';
+  const endpoint =
+    showEndpoint && variant !== 'bar'
+      ? getEndpoint(stats.values, width, height, padding, stats.min, stats.range)
+      : null;
+  const baselineY = showBaseline
+    ? getBaselineY(stats.avg, height, padding, stats.min, stats.range)
+    : null;
+
+  return (
+    <div
+      data-slot="sparkline"
+      data-variant={variant}
+      data-color={color}
+      className={cn('inline-flex items-center', className)}
+      {...rest}
+    >
+      <svg
+        viewBox={`0 0 ${width} ${height}`}
+        width={width}
+        height={height}
+        fill="none"
+        role="img"
+        aria-label={ariaLabel}
+        aria-hidden={ariaLabel ? undefined : true}
+        className="block"
+      >
+        {baselineY != null && (
+          <line
+            x1={padding}
+            y1={baselineY}
+            x2={width - padding}
+            y2={baselineY}
+            stroke={baselineStroke}
+            strokeWidth={0.75}
+            strokeDasharray="3 3"
+          />
+        )}
+
+        {variant === 'bar' && (() => {
+          const drawHeight = height - padding * 2;
+          const drawWidth = width - padding * 2;
+          const gap = 1;
+          const barWidth = Math.max(
+            1,
+            (drawWidth - gap * (stats.values.length - 1)) / stats.values.length,
+          );
+          const denom = stats.values.length - 1 || 1;
+          return stats.values.map((v, i) => {
+            const barHeight = Math.max(1, ((v - stats.min) / stats.range) * drawHeight);
+            const x = padding + i * (barWidth + gap);
+            const y = padding + drawHeight - barHeight;
+            return (
+              <rect
+                key={i}
+                x={x}
+                y={y}
+                width={barWidth}
+                height={barHeight}
+                rx={Math.min(barWidth / 2, 1)}
+                fill={stroke}
+                opacity={0.7 + 0.3 * (i / denom)}
+              />
+            );
+          });
+        })()}
+
+        {variant === 'area' && areaPath && <path d={areaPath} fill={fill} />}
+
+        {variant !== 'bar' && linePath && (
+          <path
+            d={linePath}
+            stroke={stroke}
+            strokeWidth={strokeWidth}
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            fill="none"
+          />
+        )}
+
+        {endpoint && (
+          <circle
+            cx={endpoint.x}
+            cy={endpoint.y}
+            r={strokeWidth + 0.5}
+            fill={stroke}
+          />
+        )}
+      </svg>
+    </div>
+  );
+}

package/src/tools/visual/charts/Sparkline/index.ts

@@ -0,0 +1,9 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+export { Sparkline } from './Sparkline';
+export type {
+  SparklineProps,
+  SparklineColor,
+  SparklineVariant,
+  SparklineDatum,
+} from './types';

package/src/tools/visual/charts/Sparkline/lazy.tsx

@@ -0,0 +1,26 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import { createLazyComponent } from '../../../../common/lazy-wrapper';
+import type { SparklineProps } from './types';
+
+export const LazySparkline = createLazyComponent<SparklineProps>(
+  () => import('./Sparkline').then((mod) => ({ default: mod.Sparkline })),
+  {
+    displayName: 'LazySparkline',
+    fallback: (
+      <span
+        data-slot="sparkline-skeleton"
+        className="inline-block h-8 w-[120px] animate-pulse rounded bg-muted"
+      />
+    ),
+  },
+);
+
+export type {
+  SparklineProps,
+  SparklineColor,
+  SparklineVariant,
+  SparklineDatum,
+} from './types';