@djangocfg/ui-tools 2.1.418 → 2.1.419

package/src/tools/visual/charts/CommitGraph/components/CommitRow.tsx

@@ -0,0 +1,122 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+/* eslint-disable @next/next/no-img-element */
+
+import * as React from 'react';
+import { alpha } from '@djangocfg/ui-core/styles/palette';
+import { ROW_HEIGHT, type GraphRow } from '../types';
+import { formatRelativeDate, initials } from '../utils';
+import { CommitDetail } from './CommitDetail';
+import { Rails } from './Rails';
+
+interface CommitRowProps {
+  row: GraphRow;
+  prevRow: GraphRow | null;
+  railWidth: number;
+  maxRails: number;
+  truncateHash: number;
+  laneColors: string[];
+  railColor: string;
+}
+
+/**
+ * Single commit row: rails column, refs, message, hash + author + time.
+ * Wrapped in a {@link CommitDetail} popover.
+ */
+export function CommitRow({
+  row,
+  prevRow,
+  railWidth,
+  maxRails,
+  truncateHash,
+  laneColors,
+  railColor,
+}: CommitRowProps) {
+  const svgWidth = maxRails * railWidth;
+  const refStyle = {
+    borderColor: alpha(railColor, 0.25),
+    backgroundColor: alpha(railColor, 0.0625),
+    color: railColor,
+  };
+  const tagStyle = {
+    backgroundColor: alpha(railColor, 0.125),
+    color: railColor,
+  };
+  const initialsLabel = initials(row.commit.author.name);
+  const shortHash = row.commit.hash.slice(0, truncateHash);
+  const relativeDate = formatRelativeDate(row.commit.date);
+
+  return (
+    <CommitDetail commit={row.commit} hashLength={truncateHash} railColor={railColor}>
+      <button
+        type="button"
+        data-slot="commit-entry"
+        className="flex w-full items-center gap-0 border-b border-border/30 transition-colors hover:bg-muted/30 focus-visible:bg-muted/30 focus-visible:outline-none last:border-b-0"
+        style={{ height: ROW_HEIGHT }}
+      >
+        {/* Rails */}
+        <div style={{ width: svgWidth }} className="shrink-0">
+          <Rails
+            row={row}
+            prevRow={prevRow}
+            railWidth={railWidth}
+            maxRails={maxRails}
+            laneColors={laneColors}
+          />
+        </div>
+
+        {/* Refs + tag */}
+        <div className="flex shrink-0 items-center gap-1 px-2">
+          {row.commit.refs?.map((ref) => (
+            <span
+              key={ref}
+              className="inline-flex items-center gap-1 rounded-md border px-1.5 py-0.5 text-[10px] font-semibold leading-none"
+              style={refStyle}
+            >
+              {ref}
+            </span>
+          ))}
+          {row.commit.tag && (
+            <span
+              className="inline-flex items-center rounded-md px-1.5 py-0.5 text-[10px] font-semibold leading-none"
+              style={tagStyle}
+            >
+              {row.commit.tag}
+            </span>
+          )}
+        </div>
+
+        {/* Message */}
+        <p className="min-w-0 flex-1 truncate px-2 text-left text-sm text-foreground/80">
+          {row.commit.message}
+        </p>
+
+        {/* Meta */}
+        <div className="flex shrink-0 items-center gap-3 px-3">
+          <code className="font-mono text-[11px] text-muted-foreground/60">
+            {shortHash}
+          </code>
+          <span className="inline-flex items-center gap-1.5 text-xs text-muted-foreground">
+            {row.commit.author.avatarUrl ? (
+              <img
+                src={row.commit.author.avatarUrl}
+                alt=""
+                width={16}
+                height={16}
+                className="size-4 rounded-full border border-border/60 bg-muted"
+              />
+            ) : (
+              <span className="flex size-4 items-center justify-center rounded-full bg-muted text-[8px] font-bold text-muted-foreground">
+                {initialsLabel}
+              </span>
+            )}
+            <span className="hidden sm:inline">{row.commit.author.name}</span>
+          </span>
+          <span className="text-[11px] text-muted-foreground/50">{relativeDate}</span>
+        </div>
+      </button>
+    </CommitDetail>
+  );
+}

package/src/tools/visual/charts/CommitGraph/components/Rails.tsx

@@ -0,0 +1,171 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import * as React from 'react';
+import { useThemeColor } from '@djangocfg/ui-core/styles/palette';
+import { ROW_HEIGHT, type GraphRow } from '../types';
+import { pickLaneColor } from '../hooks/useLaneColors';
+
+interface RailsProps {
+  row: GraphRow;
+  prevRow: GraphRow | null;
+  railWidth: number;
+  maxRails: number;
+  laneColors: string[];
+}
+
+/**
+ * SVG renderer for the rail column of a single commit row.
+ *
+ * Draws four classes of geometry:
+ *   1. Pass-through rails — straight vertical line top→bottom for any rail
+ *      that is active above *and* below this row and is not the commit rail.
+ *   2. Commit rail incoming/outgoing — half-height verticals on the commit's
+ *      own rail, depending on whether the rail was active above/below.
+ *   3. Fork-out curves — bezier from the commit's rail down to a freshly
+ *      allocated rail (a new branch coming off this commit).
+ *   4. Merge curves — bezier from a source rail into the commit dot
+ *      (or from the dot down to a target rail).
+ *
+ * SVG fill/stroke values are hex strings resolved via the theme palette;
+ * raw Tailwind classes do not work inside `stroke=`.
+ */
+export function Rails({ row, prevRow, railWidth, maxRails, laneColors }: RailsProps) {
+  // Background color for the commit dot ring — matches the surface the row
+  // is mounted on so the dot reads as "popped out" on every preset.
+  const background = useThemeColor('background');
+
+  const w = maxRails * railWidth;
+  const h = ROW_HEIGHT;
+  const cy = h / 2;
+  const rx = (rail: number) => rail * railWidth + railWidth / 2;
+  const color = (rail: number) => pickLaneColor(laneColors, rail);
+
+  const commitX = rx(row.rail);
+
+  const activeAbove = new Set<number>();
+  if (prevRow) {
+    for (let r = 0; r < prevRow.rails.length; r++) {
+      if (prevRow.rails[r] !== null) activeAbove.add(r);
+    }
+  }
+  const activeBelow = new Set<number>();
+  for (let r = 0; r < row.rails.length; r++) {
+    if (row.rails[r] !== null) activeBelow.add(r);
+  }
+
+  const passThroughRails = Array.from(activeAbove).filter(
+    (r) => r !== row.rail && activeBelow.has(r),
+  );
+  const endingRails = Array.from(activeAbove).filter(
+    (r) => r !== row.rail && !activeBelow.has(r),
+  );
+  const forkEdges = row.edges.filter((e) => e.type === 'fork-out');
+  const mergeEdges = row.edges.filter((e) => e.type === 'merge-in');
+
+  return (
+    <svg
+      width={w}
+      height={h}
+      viewBox={`0 0 ${w} ${h}`}
+      className="shrink-0"
+      aria-hidden="true"
+    >
+      {passThroughRails.map((r) => {
+        const x = rx(r);
+        return (
+          <line
+            key={`pt-${r}`}
+            x1={x}
+            y1={0}
+            x2={x}
+            y2={h}
+            stroke={color(r)}
+            strokeWidth={2}
+            strokeOpacity={0.6}
+          />
+        );
+      })}
+
+      {activeAbove.has(row.rail) && (
+        <line
+          x1={commitX}
+          y1={0}
+          x2={commitX}
+          y2={cy}
+          stroke={color(row.rail)}
+          strokeWidth={2}
+          strokeOpacity={0.6}
+        />
+      )}
+
+      {activeBelow.has(row.rail) && (
+        <line
+          x1={commitX}
+          y1={cy}
+          x2={commitX}
+          y2={h}
+          stroke={color(row.rail)}
+          strokeWidth={2}
+          strokeOpacity={0.6}
+        />
+      )}
+
+      {forkEdges.map((edge, i) => (
+        <path
+          key={`f-${i}`}
+          d={`M${rx(edge.fromRail)},${cy} C${rx(edge.fromRail)},${h} ${rx(edge.toRail)},${cy} ${rx(edge.toRail)},${h}`}
+          stroke={edge.color}
+          strokeWidth={2}
+          strokeOpacity={0.6}
+          fill="none"
+        />
+      ))}
+
+      {mergeEdges.map((edge, i) => {
+        const isOutgoing = edge.fromRail === row.rail;
+        const x1 = rx(edge.fromRail);
+        const x2 = rx(edge.toRail);
+        const d = isOutgoing
+          ? `M${x1},${cy} C${x1},${h} ${x2},${cy} ${x2},${h}`
+          : `M${x1},${0} C${x1},${cy} ${x2},${0} ${x2},${cy}`;
+        return (
+          <path
+            key={`m-${i}`}
+            d={d}
+            stroke={edge.color}
+            strokeWidth={2}
+            strokeOpacity={0.6}
+            fill="none"
+          />
+        );
+      })}
+
+      {endingRails.map((r) => {
+        const x = rx(r);
+        return (
+          <line
+            key={`end-${r}`}
+            x1={x}
+            y1={0}
+            x2={x}
+            y2={cy}
+            stroke={color(r)}
+            strokeWidth={2}
+            strokeOpacity={0.6}
+          />
+        );
+      })}
+
+      <circle
+        cx={commitX}
+        cy={cy}
+        r={5}
+        fill={color(row.rail)}
+        stroke={background}
+        strokeWidth={2}
+      />
+    </svg>
+  );
+}

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>(