@djangocfg/ui-tools 2.1.417 → 2.1.419

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

@@ -0,0 +1,8 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+export { ActivityGraph } from './ActivityGraph';
+export {
+  DEFAULT_INTENSITY_OPACITY,
+  DEFAULT_INTENSITY_THRESHOLDS,
+} from './types';
+export type { ActivityGraphProps, ActivityEntry } from './types';

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

@@ -0,0 +1,21 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import { createLazyComponent } from '../../../../common/lazy-wrapper';
+import type { ActivityGraphProps } from './types';
+
+export const LazyActivityGraph = createLazyComponent<ActivityGraphProps>(
+  () => import('./ActivityGraph').then((mod) => ({ default: mod.ActivityGraph })),
+  {
+    displayName: 'LazyActivityGraph',
+    fallback: (
+      <div
+        data-slot="activity-graph-skeleton"
+        className="h-[120px] w-full animate-pulse rounded-md bg-muted"
+      />
+    ),
+  },
+);
+
+export type { ActivityGraphProps, ActivityEntry } from './types';

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

@@ -0,0 +1,59 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+import type * as React from 'react';
+
+/**
+ * Single day entry in the contribution heatmap.
+ */
+export interface ActivityEntry {
+  /** ISO date string (YYYY-MM-DD). */
+  date: string;
+  /** Activity count for this date. */
+  count: number;
+}
+
+/**
+ * Five opacity stops applied to the resolved theme `primary` color for
+ * intensity levels 0–4. Level 0 is the empty / no-activity surface and is
+ * intentionally low (almost equal to `bg-muted`).
+ *
+ * Audit notes (AUDIT.md §1) collapse the full emerald scale to
+ * `alpha(primary, …)`, so the same five stops cover light and dark themes.
+ */
+export const DEFAULT_INTENSITY_OPACITY: readonly [number, number, number, number, number] = [
+  0.08, 0.18, 0.35, 0.6, 0.95,
+] as const;
+
+/**
+ * Thresholds (ratios of `value / max`) that map a normalized count into
+ * one of four non-zero intensity buckets. Combined with the empty bucket
+ * for `count === 0` they yield the 5 levels expected by the heatmap.
+ *
+ * Mirrors the original jalcoui `getIntensity` (`<=0.25 / 0.5 / 0.75`).
+ */
+export const DEFAULT_INTENSITY_THRESHOLDS: readonly [number, number, number] = [0.25, 0.5, 0.75];
+
+export interface ActivityGraphProps extends Omit<React.ComponentProps<'div'>, 'children'> {
+  /** Activity data entries. Duplicates with the same `date` are summed. */
+  data: ActivityEntry[];
+  /**
+   * Override the 5 opacity stops applied to the active theme `primary`
+   * color. Index 0 is the empty surface; index 4 is the peak.
+   */
+  intensityOpacity?: readonly [number, number, number, number, number];
+  /**
+   * Fixed cell size in pixels. When omitted the component auto-sizes
+   * blocks to fill the available container width via `useResizeObserver`.
+   */
+  blockSize?: number;
+  /** Cell border radius in pixels. @default 2 */
+  blockRadius?: number;
+  /** Number of trailing weeks to display. @default 52 */
+  weeks?: number;
+}
+
+export const GAP = 2;
+export const DAY_LABEL_WIDTH = 28;
+export const MONTH_LABEL_HEIGHT = 16;
+export const DAY_LABELS = ['Mon', 'Wed', 'Fri'] as const;
+export const DAY_LABEL_INDICES = [1, 3, 5] as const;

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

@@ -0,0 +1,88 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+import type { ActivityEntry } from './types';
+import { GAP } from './types';
+
+export interface WeekDay {
+  date: Date;
+  count: number;
+}
+
+/**
+ * Bucket the supplied entries into a fixed-size grid that ends on the
+ * current week and spans `weekCount` weeks. Missing dates fill with 0.
+ */
+export function buildWeeks(data: ActivityEntry[], weekCount: number): WeekDay[][] {
+  const countMap = new Map<string, number>();
+  for (const entry of data) {
+    countMap.set(entry.date, (countMap.get(entry.date) ?? 0) + entry.count);
+  }
+
+  const today = new Date();
+  today.setHours(0, 0, 0, 0);
+  const todayDay = today.getDay();
+
+  const endOfWeek = new Date(today);
+  endOfWeek.setDate(today.getDate() + (6 - todayDay));
+
+  const totalDays = weekCount * 7;
+  const startDate = new Date(endOfWeek);
+  startDate.setDate(endOfWeek.getDate() - totalDays + 1);
+
+  const weeks: WeekDay[][] = [];
+  let currentWeek: WeekDay[] = [];
+
+  for (let i = 0; i < totalDays; i++) {
+    const d = new Date(startDate);
+    d.setDate(startDate.getDate() + i);
+    const key = d.toISOString().slice(0, 10);
+    currentWeek.push({ date: d, count: countMap.get(key) ?? 0 });
+
+    if (currentWeek.length === 7) {
+      weeks.push(currentWeek);
+      currentWeek = [];
+    }
+  }
+
+  if (currentWeek.length > 0) {
+    weeks.push(currentWeek);
+  }
+
+  return weeks;
+}
+
+/**
+ * Find the column offset for the first week of every new month. Used to
+ * lay month labels along the top of the grid.
+ */
+export function getMonthLabels(
+  weeks: WeekDay[][],
+  blockSize: number,
+): { label: string; offset: number }[] {
+  const months: { label: string; offset: number }[] = [];
+  let lastKey = '';
+
+  for (let w = 0; w < weeks.length; w++) {
+    const firstDay = weeks[w][0];
+    const key = `${firstDay.date.getFullYear()}-${firstDay.date.getMonth()}`;
+
+    if (key !== lastKey) {
+      months.push({
+        label: firstDay.date.toLocaleString('en-US', { month: 'short' }),
+        offset: w * (blockSize + GAP),
+      });
+      lastKey = key;
+    }
+  }
+
+  return months;
+}
+
+export function formatDate(date: Date): string {
+  return date.toLocaleDateString('en-US', {
+    weekday: 'short',
+    month: 'short',
+    day: 'numeric',
+    year: 'numeric',
+  });
+}

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

@@ -0,0 +1,80 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+//
+// Topological git graph with rail lines showing branch forks, merges, and
+// commit ancestry. Renders the same visual as GitKraken / Fork / Tower.
+//
+// Composer only — heavy lifting lives in:
+//   - hooks/useGraphLayout.ts    topology pass
+//   - hooks/useLaneColors.ts     theme-aware categorical palette
+//   - components/Rails.tsx       SVG rails + dot
+//   - components/CommitRow.tsx   row body (refs, message, meta)
+//   - components/CommitDetail.tsx popover detail
+//
+// Project rules exercised here: semantic tokens for chrome (no raw scales),
+// theme-derived hex colors for SVG strokes (no Tailwind classes inside
+// `stroke=`), no nested overlay providers, attribution header, lazy entry.
+
+'use client';
+
+import * as React from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+import type { CommitGraphProps } from './types';
+import { useGraphLayout } from './hooks/useGraphLayout';
+import { useLaneColors, pickLaneColor } from './hooks/useLaneColors';
+import { CommitRow } from './components/CommitRow';
+
+function CommitGraph({
+  commits,
+  truncateHash = 7,
+  railWidth = 24,
+  className,
+  ...props
+}: CommitGraphProps) {
+  const laneColors = useLaneColors();
+  const { rows, maxRails } = useGraphLayout(commits, laneColors);
+  const svgWidth = maxRails * railWidth;
+
+  if (rows.length === 0) {
+    return (
+      <div
+        data-slot="commit-graph"
+        className={cn(
+          'flex items-center justify-center rounded-xl border border-border/60 bg-card py-10 text-sm text-muted-foreground shadow-sm',
+          className,
+        )}
+        {...props}
+      >
+        No commits.
+      </div>
+    );
+  }
+
+  return (
+    <div
+      data-slot="commit-graph"
+      className={cn(
+        'overflow-hidden rounded-xl border border-border/60 bg-card shadow-sm',
+        className,
+      )}
+      style={{ ['--commit-graph-rail-width' as string]: `${svgWidth}px` }}
+      {...props}
+    >
+      <div className="overflow-x-auto">
+        {rows.map((row, i) => (
+          <CommitRow
+            key={`${row.commit.hash}-${i}`}
+            row={row}
+            prevRow={i > 0 ? rows[i - 1] : null}
+            railWidth={railWidth}
+            maxRails={maxRails}
+            truncateHash={truncateHash}
+            laneColors={laneColors}
+            railColor={pickLaneColor(laneColors, row.rail)}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export { CommitGraph };

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

@@ -0,0 +1,28 @@
+# CommitGraph
+
+Git-style commit rail visualisation. Computes rail topology from `parents` and renders SVG rails + edges. Lane colors come from `useStylePresets()` so every theme preset re-skins consistently.
+
+```tsx
+import { CommitGraph } from '@djangocfg/ui-tools/commit-graph';
+
+<CommitGraph
+  commits={[
+    { hash: 'a1b2c3d', message: 'init', author: { name: 'Mark' }, date: '2025-01-01', parents: [] },
+    { hash: 'd4e5f6g', message: 'feat: auth', author: { name: 'Mark' }, date: '2025-01-02', parents: ['a1b2c3d'] },
+  ]}
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `commits` | `Commit[]` | — | Commits in topological order (newest first). Merge = two+ `parents`. |
+| `truncateHash` | `number` | `7` | Number of hash characters to display. |
+| `railWidth` | `number` | `24` | Pixel width per rail column. |
+
+Storybook: `apps/storybook/stories/ui-tools/visual/CommitGraph.stories.tsx`
+
+---
+
+Adapted from jalcoui (MIT).

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

@@ -0,0 +1,107 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+/* eslint-disable @next/next/no-img-element */
+
+import * as React from 'react';
+import { Popover, PopoverContent, PopoverTrigger } from '@djangocfg/ui-core';
+import { alpha } from '@djangocfg/ui-core/styles/palette';
+import type { Commit } from '../types';
+import { formatFullDate, initials } from '../utils';
+
+interface CommitDetailProps {
+  commit: Commit;
+  hashLength: number;
+  railColor: string;
+  children: React.ReactNode;
+}
+
+/**
+ * Popover with the full commit message, refs, tag and parent hashes. The
+ * trigger is the row button — the parent component owns the row markup and
+ * passes it through `children`.
+ *
+ * Requires the host app to mount `<UiProviders>` at the root (we do not
+ * remount a Popover provider here — see CONTRACT §5).
+ */
+export function CommitDetail({
+  commit,
+  hashLength,
+  railColor,
+  children,
+}: CommitDetailProps) {
+  // Pre-compute style strings outside JSX (per project rule: hoist derived
+  // values into named consts before `return (...)`).
+  const tagStyle = {
+    backgroundColor: alpha(railColor, 0.125),
+    color: railColor,
+  };
+  const initialsLabel = initials(commit.author.name);
+
+  return (
+    <Popover>
+      <PopoverTrigger asChild>{children}</PopoverTrigger>
+      <PopoverContent side="right" sideOffset={8} className="w-80 p-3">
+        <div className="flex flex-col gap-2">
+          <p className="text-sm font-medium leading-snug">{commit.message}</p>
+
+          <div className="flex flex-wrap items-center gap-2 text-xs text-muted-foreground">
+            <span className="inline-flex items-center gap-1.5">
+              {commit.author.avatarUrl ? (
+                <img
+                  src={commit.author.avatarUrl}
+                  alt=""
+                  width={14}
+                  height={14}
+                  className="size-3.5 rounded-full border border-border/60 bg-muted"
+                />
+              ) : (
+                <span className="flex size-3.5 items-center justify-center rounded-full bg-muted text-[7px] font-bold">
+                  {initialsLabel}
+                </span>
+              )}
+              {commit.author.name}
+            </span>
+            <span className="text-border">·</span>
+            <code className="rounded bg-muted px-1 py-0.5 font-mono text-[10px]">
+              {commit.hash.slice(0, hashLength)}
+            </code>
+          </div>
+
+          <div className="text-[11px] text-muted-foreground">
+            {formatFullDate(commit.date)}
+          </div>
+
+          {(commit.refs || commit.tag) && (
+            <div className="flex flex-wrap gap-1">
+              {commit.refs?.map((ref) => (
+                <span
+                  key={ref}
+                  className="inline-flex items-center gap-1 rounded-md border border-border/60 bg-muted/50 px-1.5 py-0.5 text-[10px] font-medium text-muted-foreground"
+                >
+                  {ref}
+                </span>
+              ))}
+              {commit.tag && (
+                <span
+                  className="inline-flex items-center rounded-md px-1.5 py-0.5 text-[10px] font-medium"
+                  style={tagStyle}
+                >
+                  {commit.tag}
+                </span>
+              )}
+            </div>
+          )}
+
+          {commit.parents.length > 0 && (
+            <div className="text-[10px] text-muted-foreground/60">
+              {commit.parents.length === 1 ? 'Parent' : 'Parents'}:{' '}
+              {commit.parents.map((p) => p.slice(0, hashLength)).join(', ')}
+            </div>
+          )}
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+}

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>
+  );
+}