@djangocfg/ui-tools 2.1.418 → 2.1.419

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

@@ -0,0 +1,195 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+//
+// GitHub-style activity heatmap that visualizes daily counts as a
+// color-intensity grid. Auto-sizes blocks to fit the container by default.
+//
+// Port notes:
+//   - Cell colors resolve through `useThemeColor('primary')` + `alpha(...)`,
+//     not raw `bg-emerald-*` (CONTRACT §2, AUDIT §1). The five emerald
+//     stops in the original collapse to five opacity stops on the active
+//     theme's `primary` token, which means the heatmap follows the theme
+//     preset automatically.
+//   - Intensity bucketing routed through `getIntensity` from
+//     `@djangocfg/ui-core/lib` (CONTRACT shared util added in Phase 0).
+//   - Container sizing routed through `useResizeObserver` from
+//     `@djangocfg/ui-core/hooks` (shared RO from Phase 0), replacing the
+//     local `ResizeObserver` instance in the source.
+//   - Tooltips: the original wrapped every cell in its own Radix
+//     `Tooltip.Provider`. Mounting a provider per cell violates CONTRACT
+//     §5 ("no nested providers") and explodes to 365 portals on a default
+//     52-week graph. The port uses the native `title` attribute on each
+//     cell instead — accessible, no provider dependency, no portal.
+
+'use client';
+
+import * as React from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+import { getIntensity } from '@djangocfg/ui-core/lib';
+import { useResizeObserver } from '@djangocfg/ui-core/hooks';
+import { useThemeColor, alpha } from '@djangocfg/ui-core/styles/palette';
+
+import {
+  DAY_LABEL_INDICES,
+  DAY_LABEL_WIDTH,
+  DAY_LABELS,
+  DEFAULT_INTENSITY_OPACITY,
+  DEFAULT_INTENSITY_THRESHOLDS,
+  GAP,
+  MONTH_LABEL_HEIGHT,
+  type ActivityGraphProps,
+} from './types';
+import { buildWeeks, formatDate, getMonthLabels } from './utils';
+
+export function ActivityGraph({
+  data,
+  intensityOpacity = DEFAULT_INTENSITY_OPACITY,
+  blockSize: fixedBlockSize,
+  blockRadius = 2,
+  weeks: weekCount = 52,
+  className,
+  ...props
+}: ActivityGraphProps) {
+  const containerRef = React.useRef<HTMLDivElement>(null);
+  const { width: containerWidth } = useResizeObserver(containerRef);
+
+  const isAutoFit = fixedBlockSize == null;
+
+  // Auto-fit cell size based on container width. Falls back to a small
+  // default until the first measurement lands (consistent with original).
+  const autoSize = React.useMemo(() => {
+    if (!isAutoFit || containerWidth <= 0) return null;
+    const available = containerWidth - DAY_LABEL_WIDTH;
+    const size = (available - GAP * (weekCount - 1)) / weekCount;
+    return Math.max(4, Math.floor(size));
+  }, [isAutoFit, containerWidth, weekCount]);
+
+  const blockSize = fixedBlockSize ?? autoSize ?? 10;
+  const showGraph = !isAutoFit || autoSize != null;
+
+  // Resolve the theme color once; map each intensity bucket to an
+  // opacity stop applied to that color (see CONTRACT §3 — never raw
+  // Tailwind class for parametric colors).
+  const primary = useThemeColor('primary');
+  const intensityColors = React.useMemo(
+    () => intensityOpacity.map((op) => alpha(primary, op)),
+    [primary, intensityOpacity],
+  );
+
+  const weeks = React.useMemo(() => buildWeeks(data, weekCount), [data, weekCount]);
+  const maxCount = React.useMemo(
+    () => data.reduce((m, d) => (d.count > m ? d.count : m), 0),
+    [data],
+  );
+  const monthLabels = React.useMemo(
+    () => getMonthLabels(weeks, blockSize),
+    [weeks, blockSize],
+  );
+
+  const gridWidth = weeks.length * (blockSize + GAP) - GAP;
+  const gridHeight = 7 * (blockSize + GAP) - GAP;
+  const totalWidth = DAY_LABEL_WIDTH + gridWidth;
+
+  return (
+    <div
+      ref={containerRef}
+      className={cn(isAutoFit ? 'w-full' : 'overflow-x-auto', className)}
+      role="img"
+      aria-label="Activity graph"
+      data-slot="activity-graph"
+      {...props}
+    >
+      {showGraph && (
+        <div
+          className="flex flex-col gap-2"
+          style={{ minWidth: isAutoFit ? undefined : totalWidth }}
+        >
+          <div
+            className="relative"
+            style={{
+              width: isAutoFit ? '100%' : totalWidth,
+              height: MONTH_LABEL_HEIGHT + gridHeight,
+            }}
+          >
+            {monthLabels.map((m, i) => (
+              <span
+                key={`${m.label}-${i}`}
+                className="absolute text-[10px] leading-none text-muted-foreground"
+                style={{ left: DAY_LABEL_WIDTH + m.offset, top: 0 }}
+              >
+                {m.label}
+              </span>
+            ))}
+
+            {DAY_LABELS.map((label, i) => (
+              <span
+                key={label}
+                className="absolute text-[10px] leading-none text-muted-foreground"
+                style={{
+                  left: 0,
+                  top:
+                    MONTH_LABEL_HEIGHT +
+                    DAY_LABEL_INDICES[i] * (blockSize + GAP) +
+                    blockSize / 2 -
+                    4,
+                }}
+              >
+                {label}
+              </span>
+            ))}
+
+            <div
+              className="absolute"
+              style={{
+                left: DAY_LABEL_WIDTH,
+                top: MONTH_LABEL_HEIGHT,
+                display: 'flex',
+                gap: GAP,
+              }}
+            >
+              {weeks.map((week, wi) => (
+                <div key={wi} style={{ display: 'flex', flexDirection: 'column', gap: GAP }}>
+                  {week.map((day, di) => {
+                    const ratio = maxCount > 0 ? day.count / maxCount : 0;
+                    const intensity = getIntensity(ratio, [...DEFAULT_INTENSITY_THRESHOLDS]);
+                    const title = `${day.count} contribution${day.count === 1 ? '' : 's'} — ${formatDate(day.date)}`;
+                    return (
+                      <div
+                        key={di}
+                        data-slot="activity-graph-cell"
+                        data-intensity={intensity}
+                        className="transition-colors"
+                        title={title}
+                        style={{
+                          width: blockSize,
+                          height: blockSize,
+                          borderRadius: blockRadius,
+                          backgroundColor: intensityColors[intensity],
+                        }}
+                      />
+                    );
+                  })}
+                </div>
+              ))}
+            </div>
+          </div>
+
+          <div className="flex items-center gap-1.5 self-end text-[10px] text-muted-foreground">
+            <span>Less</span>
+            {intensityColors.map((color, i) => (
+              <div
+                key={i}
+                style={{
+                  width: blockSize,
+                  height: blockSize,
+                  borderRadius: blockRadius,
+                  backgroundColor: color,
+                }}
+              />
+            ))}
+            <span>More</span>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,28 @@
+# ActivityGraph
+
+GitHub-style contribution heatmap. Maps daily counts to opacity stops of the active theme `primary` color via `useThemeColor` + `useResizeObserver`.
+
+```tsx
+import { ActivityGraph } from '@djangocfg/ui-tools/activity-graph';
+
+<ActivityGraph
+  data={[{ date: '2025-01-12', count: 4 }, { date: '2025-01-13', count: 0 }]}
+  weeks={52}
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `data` | `ActivityEntry[]` | — | Daily entries `{ date, count }`. Duplicate dates are summed. |
+| `weeks` | `number` | `52` | Trailing week count. |
+| `blockSize` | `number` | auto | Cell size in px. When omitted, auto-fits the container. |
+| `blockRadius` | `number` | `2` | Cell border-radius in px. |
+| `intensityOpacity` | `[number,number,number,number,number]` | `[0.08, 0.18, 0.35, 0.6, 0.95]` | Opacity stops applied to the theme `primary` color (intensity 0–4). |
+
+Storybook: `apps/storybook/stories/ui-tools/visual/ActivityGraph.stories.tsx`
+
+---
+
+Adapted from jalcoui (MIT).

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