@djangocfg/ui-tools 2.1.417 → 2.1.419

package/src/tools/media/VideoPlayer/parts/volume.tsx

@@ -1,32 +1,251 @@
 'use client';
 
-import { MediaMuteButton, MediaVolumeRange } from 'media-chrome/react';
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type ButtonHTMLAttributes,
+  type ReactNode,
+} from 'react';
+import { Volume2, VolumeX, Volume1 } from 'lucide-react';
 import { cn } from '@djangocfg/ui-core/lib';
-import type { ComponentProps } from 'react';
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+  Slider,
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '@djangocfg/ui-core/components';
 
 export interface VolumeProps {
   readonly className?: string;
+  /**
+   * Reserved for backwards compatibility. The control is always a single
+   * icon button that opens a popover with a vertical slider on hover/focus,
+   * so this flag is now a no-op. Kept so existing consumers
+   * (`<Volume iconOnly />`) don't break.
+   */
   readonly iconOnly?: boolean;
-  readonly muteProps?: ComponentProps<typeof MediaMuteButton>;
-  readonly rangeProps?: ComponentProps<typeof MediaVolumeRange>;
+  /** Mute-button tooltip copy. Defaults to `"Volume"`. Pass `false` to opt out. */
+  readonly muteLabel?: ReactNode | false;
 }
 
-export function Volume({ className, iconOnly, muteProps, rangeProps }: VolumeProps) {
+// Hide the popover slider on iOS Safari — `video.volume` is read-only
+// there (controlled by hardware buttons), so a JS slider does nothing.
+// The trigger still toggles mute, which iOS *does* honour.
+function isIosSafari(): boolean {
+  if (typeof navigator === 'undefined') return false;
+  const ua = navigator.userAgent;
+  const iOS =
+    /iPad|iPhone|iPod/.test(ua) ||
+    (navigator.platform === 'MacIntel' &&
+      (navigator as { maxTouchPoints?: number }).maxTouchPoints! > 1);
+  return iOS;
+}
+
+// media-chrome request event names. Dispatched on any descendant of
+// `<media-controller>`; the controller catches them and updates its
+// internal store, which then propagates state back via attributes.
+const MEDIA_VOLUME_REQUEST = 'mediavolumerequest';
+const MEDIA_MUTE_REQUEST = 'mediamuterequest';
+const MEDIA_UNMUTE_REQUEST = 'mediaunmuterequest';
+
+/**
+ * Click-style trigger that visually matches the rest of the VideoPlayer
+ * control bar. Mirrors `.video-player__control` styling from
+ * `styles/video-player.css` so it slots in next to `<MediaPlayButton>` &
+ * friends without standing out.
+ */
+const TriggerButton = forwardRef<
+  HTMLButtonElement,
+  ButtonHTMLAttributes<HTMLButtonElement>
+>(function TriggerButton({ className, children, ...rest }, ref) {
   return (
-    <div className={cn('flex items-center', className)}>
-      <MediaMuteButton
-        {...muteProps}
-        className={cn(
-          'media-control-square video-player__control h-8 w-8',
-          muteProps?.className,
-        )}
-      />
-      {!iconOnly && (
-        <MediaVolumeRange
-          {...rangeProps}
-          className={cn('h-8 w-20', rangeProps?.className)}
-        />
+    <button
+      ref={ref}
+      type="button"
+      className={cn(
+        'video-player__control',
+        'grid h-8 w-8 place-items-center rounded-md',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/60',
+        className,
       )}
+      {...rest}
+    >
+      {children}
+    </button>
+  );
+});
+
+/**
+ * VideoPlayer volume control.
+ *
+ * - **Click** the trigger → mute / unmute toggle (dispatches a
+ *   `mediamuterequest` / `mediaunmuterequest` so media-chrome's store
+ *   stays the single source of truth — no parallel state machine).
+ * - **Hover / keyboard focus** → opens a popover containing a vertical
+ *   `<Slider>` (0..100). Drag = volume change via `mediavolumerequest`.
+ * - Icon reflects level (mute / low / high) and mirrors `media.muted`.
+ *
+ * State is read directly off the underlying `HTMLMediaElement` (located
+ * via the closest `<media-controller>`'s `.media` accessor); we never
+ * shadow media-chrome's store.
+ */
+export function Volume({ className, muteLabel }: VolumeProps) {
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+  const [volume, setVolume] = useState(1);
+  const [muted, setMuted] = useState(false);
+  const [open, setOpen] = useState(false);
+  const [iosSafari] = useState(isIosSafari);
+
+  // Resolve & track the underlying HTMLMediaElement so we can read live
+  // volume / muted. media-chrome fires `mediaelementchange` on the
+  // controller whenever the slotted media element swaps (e.g. source
+  // change), so we re-bind listeners on each swap.
+  useEffect(() => {
+    const trigger = triggerRef.current;
+    if (!trigger) return;
+    const controller = trigger.closest('media-controller') as
+      | (HTMLElement & { media?: HTMLMediaElement | null })
+      | null;
+    if (!controller) return;
+
+    let media: HTMLMediaElement | null = controller.media ?? null;
+    const sync = () => {
+      if (!media) return;
+      setVolume(media.volume);
+      setMuted(media.muted);
+    };
+    const bind = (el: HTMLMediaElement | null) => {
+      if (!el) return;
+      el.addEventListener('volumechange', sync);
+      sync();
+    };
+    const unbind = (el: HTMLMediaElement | null) => {
+      if (!el) return;
+      el.removeEventListener('volumechange', sync);
+    };
+
+    bind(media);
+
+    const onMediaChange = (e: Event) => {
+      unbind(media);
+      const detail = (e as CustomEvent).detail as HTMLMediaElement | null;
+      media = detail ?? controller.media ?? null;
+      bind(media);
+    };
+    controller.addEventListener('mediaelementchange', onMediaChange);
+
+    return () => {
+      unbind(media);
+      controller.removeEventListener('mediaelementchange', onMediaChange);
+    };
+  }, []);
+
+  const dispatch = useCallback((name: string, detail?: number) => {
+    const trigger = triggerRef.current;
+    if (!trigger) return;
+    trigger.dispatchEvent(
+      new CustomEvent(name, { detail, bubbles: true, composed: true }),
+    );
+  }, []);
+
+  const toggleMute = useCallback(() => {
+    dispatch(muted ? MEDIA_UNMUTE_REQUEST : MEDIA_MUTE_REQUEST);
+  }, [dispatch, muted]);
+
+  const onSlider = useCallback(
+    (value: number) => {
+      dispatch(MEDIA_VOLUME_REQUEST, value);
+      // If the user nudges the slider above zero, treat that as an
+      // implicit unmute — matches what the native HTML5 volume slider does.
+      if (value > 0 && muted) dispatch(MEDIA_UNMUTE_REQUEST);
+    },
+    [dispatch, muted],
+  );
+
+  const effectiveVolume = muted ? 0 : volume;
+  const Icon =
+    muted || volume === 0 ? VolumeX : volume < 0.5 ? Volume1 : Volume2;
+
+  const trigger = (
+    <TriggerButton
+      ref={triggerRef}
+      aria-label={muted ? 'Unmute' : 'Mute'}
+      aria-pressed={muted}
+      onClick={toggleMute}
+    >
+      <Icon className="h-4 w-4" strokeWidth={1.75} />
+    </TriggerButton>
+  );
+
+  // On iOS Safari volume is hardware-only — skip the popover entirely
+  // and let the trigger work as a plain mute/unmute button.
+  if (iosSafari) {
+    if (muteLabel === false) return <div className={cn('flex', className)}>{trigger}</div>;
+    return (
+      <div className={cn('flex items-center', className)}>
+        <Tooltip>
+          <TooltipTrigger asChild>{trigger}</TooltipTrigger>
+          <TooltipContent side="top">{muteLabel ?? 'Mute / unmute'}</TooltipContent>
+        </Tooltip>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className={cn('flex items-center', className)}
+      // Hover-driven open: opening on pointerenter of the wrapper (not
+      // just the button) gives the user a forgiving hit-area when their
+      // cursor drifts between trigger and popover. The popover itself
+      // also catches pointerenter via Radix portal — so once it's open,
+      // moving into it keeps it open.
+      onPointerEnter={() => setOpen(true)}
+      onPointerLeave={() => setOpen(false)}
+      onFocus={() => setOpen(true)}
+      onBlur={(e) => {
+        // Don't close when focus moves between the trigger and the
+        // popover content (both live in this wrapper / its portal).
+        if (!e.currentTarget.contains(e.relatedTarget as Node | null)) {
+          setOpen(false);
+        }
+      }}
+    >
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverTrigger asChild>{trigger}</PopoverTrigger>
+        <PopoverContent
+          side="top"
+          align="center"
+          sideOffset={8}
+          // Keep focus on the trigger so click-to-mute still works while
+          // the popover is visible; the slider remains keyboard-reachable
+          // via Tab once a user explicitly tabs into it.
+          onOpenAutoFocus={(e) => e.preventDefault()}
+          onCloseAutoFocus={(e) => e.preventDefault()}
+          onPointerEnter={() => setOpen(true)}
+          onPointerLeave={() => setOpen(false)}
+          className="flex w-12 flex-col items-center gap-2 p-3"
+        >
+          <span className="w-full text-center text-[10px] tabular-nums text-muted-foreground">
+            {Math.round(effectiveVolume * 100)}
+          </span>
+          <Slider
+            orientation="vertical"
+            min={0}
+            max={1}
+            step={0.01}
+            value={[effectiveVolume]}
+            onValueChange={([v]) => onSlider(v)}
+            aria-label="Volume"
+            className="h-24"
+          />
+        </PopoverContent>
+      </Popover>
     </div>
   );
 }

package/src/tools/media/VideoPlayer/styles/video-player.css

@@ -42,11 +42,6 @@ media-controller {
   --media-range-thumb-opacity: 0;
   --media-range-thumb-transition: opacity 0.15s ease;
 
-  /* Tooltip */
-  --media-tooltip-background: var(--popover);
-  --media-tooltip-color: var(--popover-foreground);
-  --media-tooltip-border-radius: 6px;
-
   /* Font */
   --media-font-family: inherit;
   --media-font-size: 12px;
@@ -87,6 +82,29 @@ media-control-bar {
   background: transparent;
 }
 
+/*
+ * Suppress media-chrome's built-in tooltips. They are sticky elements
+ * slotted under each control button's shadow root (exposed via
+ * `part="tooltip"`) and paint a permanent "Play" / "Mute" / "Enter
+ * fullscreen" label below the bar. We wrap each control with our own
+ * Radix-backed <Tooltip> from @djangocfg/ui-core, which fires only on
+ * hover/focus and matches the rest of the platform. Reach into the
+ * shadow DOM via ::part(tooltip) — a global `media-tooltip` selector
+ * cannot pierce the boundary.
+ */
+media-play-button::part(tooltip),
+media-mute-button::part(tooltip),
+media-fullscreen-button::part(tooltip),
+media-pip-button::part(tooltip),
+media-playback-rate-button::part(tooltip),
+media-captions-button::part(tooltip),
+media-airplay-button::part(tooltip),
+media-cast-button::part(tooltip),
+media-seek-forward-button::part(tooltip),
+media-seek-backward-button::part(tooltip) {
+  display: none !important;
+}
+
 /*
  * Auto-hide. media-chrome flags inactivity by setting `userinactive` on
  * the <media-controller>; it only does so while playback is running, and
@@ -120,17 +138,79 @@ media-time-range {
   --media-preview-background: var(--popover);
   --media-preview-border-radius: 6px;
   --media-text-color: var(--popover-foreground);
+
+  /* Kill media-chrome's default blue focus rectangle on the range track.
+     media-chrome paints a `box-shadow: inset 0 0 0 2px rgb(27 127 204 / .9)`
+     via `--media-focus-box-shadow` whenever the inner `<input type=range>`
+     matches `:focus-visible`, which wraps the entire seek-bar in a big
+     blue rectangle on click/Tab. We opt out of the track-wide ring and
+     surface focus on the thumb instead (see :focus-visible below). */
+  --media-focus-box-shadow: none;
 }
 
-/* Reveal the accent thumb only while hovering / scrubbing the rail. */
-media-time-range:hover {
+/* Reveal the accent thumb only while hovering / scrubbing the rail, OR
+   when the rail is keyboard-focused so a11y keyboard users still see
+   where focus lives. */
+media-time-range:hover,
+media-time-range:focus-within {
   --media-range-thumb-opacity: 1;
 }
 
+/* Keyboard focus indicator: a ring around the thumb (not the track).
+   Uses the platform `--ring` semantic token so it matches every other
+   focusable surface. */
+media-time-range:focus-within {
+  --media-range-thumb-box-shadow: 0 0 0 2px var(--ring);
+}
+
 media-time-range::part(preview-box) {
   display: none;
 }
 
+/*
+ * YouTube iframe bleed-through suppression.
+ *
+ * YouTube's IFrame embed ToS requires showing some chrome that cannot be
+ * hidden via player params: the title bar at the top, the large pause
+ * button on the pause screen, and the bottom branding/share tray on
+ * hover/pause. We can't remove them, but we CAN make them non-interactive
+ * — so the user never triggers YouTube's hover-state, never gets a
+ * "More videos" overlay, and clicks never reach the YT iframe.
+ *
+ * The <youtube-video> custom element renders an inner <iframe>; disable
+ * pointer events on it (and on the wrapper itself, just in case the
+ * element later swaps layout). The companion `.vp-yt-click-shield` div
+ * inside <media-controller> absorbs clicks and converts them into
+ * media-chrome play/pause requests — so click-to-toggle still works.
+ *
+ * Our control bar lives above the shield and re-enables pointer events
+ * for the slot, so the controls stay clickable.
+ */
+youtube-video,
+youtube-video iframe {
+  pointer-events: none;
+}
+
+.vp-yt-click-shield {
+  position: absolute;
+  inset: 0;
+  cursor: pointer;
+  background: transparent;
+  pointer-events: auto;
+  /* Sit above the iframe but below the slotted control bar. */
+  z-index: 1;
+}
+
+/* media-chrome slots its control surfaces directly under
+   <media-controller>; raise them above the click-shield and restore
+   pointer events so buttons remain interactive. */
+media-controller > media-control-bar,
+media-controller > [slot='centered-chrome'],
+media-controller > [slot='top-chrome'] {
+  z-index: 2;
+  pointer-events: auto;
+}
+
 media-time-range::part(current-box) {
   padding: 2px 6px;
   border-radius: 6px;

package/src/tools/media/VideoPlayer/types.ts

@@ -79,4 +79,8 @@ export interface VideoPlayerProps extends VideoPlayerSettings {
   readonly className?: string;
   /** Custom children replace the default control bar entirely. */
   readonly children?: ReactNode;
+  /** Focus the player container on mount so media-chrome keyboard shortcuts
+   *  (space=play/pause, f=fullscreen, arrows=seek/volume) are active
+   *  immediately. Pair with `key={src}` upstream for per-source focus reset. */
+  readonly autoFocus?: boolean;
 }

package/src/tools/overlay/ResponsiveDialog/lazy.tsx

@@ -10,7 +10,7 @@
  * import { LazyResponsiveDialog, LazyResponsiveDialogContent } from '@djangocfg/ui-tools/responsive-dialog';
  */
 
-import { createLazyComponent, LoadingFallback } from '../../../components/lazy-wrapper';
+import { createLazyComponent, LoadingFallback } from '../../../common/lazy-wrapper';
 import type {
   ResponsiveDialogProps,
   ResponsiveDialogContentProps,

package/src/tools/overlay/ScrollSpy/lazy.tsx

@@ -4,7 +4,7 @@
  * Lazy-loaded ScrollSpy Component
  */
 
-import { createLazyComponent, LoadingFallback } from '../../../components/lazy-wrapper';
+import { createLazyComponent, LoadingFallback } from '../../../common/lazy-wrapper';
 import type {
   ScrollSpyProps,
   ScrollSpyNavProps,

package/src/tools/overlay/SelectionToolbar/lazy.tsx

@@ -4,7 +4,7 @@
  * Lazy-loaded SelectionToolbar Component
  */
 
-import { createLazyComponent, LoadingFallback } from '../../../components/lazy-wrapper';
+import { createLazyComponent, LoadingFallback } from '../../../common/lazy-wrapper';
 import type {
   SelectionToolbarProps,
   SelectionToolbarContentProps,

package/src/tools/overlay/Tour/lazy.tsx

@@ -4,7 +4,7 @@
  * Lazy-loaded Tour Component
  */
 
-import { createLazyComponent, LoadingFallback } from '../../../components/lazy-wrapper';
+import { createLazyComponent, LoadingFallback } from '../../../common/lazy-wrapper';
 import type {
   TourProps,
   TourPopoverProps,

package/src/tools/visual/Marquee/lazy.tsx

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

package/src/tools/visual/QRCode/lazy.tsx

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

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).