@djangocfg/ui-tools 2.1.418 → 2.1.419

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';

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

@@ -0,0 +1,58 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+import type * as React from 'react';
+
+/**
+ * Semantic color token name used for the sparkline stroke / area fill.
+ *
+ * Resolves at runtime via `useThemeColor(color)` from
+ * `@djangocfg/ui-core/styles/palette`, so it follows the active theme preset
+ * — never reference raw Tailwind scales (`emerald-500`, `sky-400`, …).
+ */
+export type SparklineColor =
+  | 'primary'
+  | 'success'
+  | 'warning'
+  | 'destructive'
+  | 'info';
+
+/**
+ * Sparkline chart variant.
+ *
+ *  - `line` — just the stroke.
+ *  - `area` — stroke + alpha-filled area underneath.
+ *  - `bar`  — discrete bars per data point.
+ */
+export type SparklineVariant = 'line' | 'area' | 'bar';
+
+/**
+ * A datum is either a bare number or an `{ value, label? }` object. The
+ * optional `label` is used for `aria-label` enrichment only — it never renders
+ * inside the SVG.
+ */
+export type SparklineDatum = number | { value: number; label?: string };
+
+export interface SparklineProps
+  extends Omit<React.ComponentProps<'div'>, 'children'> {
+  /** Data points. Empty array renders nothing. */
+  data: SparklineDatum[];
+  /** Sparkline chart variant. @default 'line' */
+  variant?: SparklineVariant;
+  /**
+   * Semantic color token. Resolved via `useThemeColor()` — respects the
+   * active theme preset. @default 'primary'
+   */
+  color?: SparklineColor;
+  /** SVG width in pixels. @default 120 */
+  width?: number;
+  /** SVG height in pixels. @default 32 */
+  height?: number;
+  /** Line stroke width (ignored for `bar`). @default 1.5 */
+  strokeWidth?: number;
+  /** Show a filled dot at the latest data point. @default true */
+  showEndpoint?: boolean;
+  /** Show a faint dashed line at the average value. @default false */
+  showBaseline?: boolean;
+  /** Optional accessible label for the chart. */
+  ariaLabel?: string;
+}

package/src/tools/visual/design/ColorPalette/ColorPalette.tsx

@@ -0,0 +1,129 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+//
+// Grid of color swatches with click-to-copy in hex / rgb / hsl.
+// Pulls colors from one of three sources via `mode`:
+//   - 'theme'  → useThemePalette() (semantic tokens of the active theme)
+//   - 'preset' → useStylePresets() (status preset families)
+//   - 'custom' → caller-provided `colors` array
+//
+// Chrome (frame, value label) uses semantic Tailwind tokens; the swatch
+// background uses inline `style={{ backgroundColor: hex }}` so it stays
+// honest regardless of the active theme. See CONTRACT.md §2/§3.
+
+'use client';
+
+import * as React from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+import { useThemePalette, useStylePresets } from '@djangocfg/ui-core/styles/palette';
+import { Swatch } from './components/Swatch';
+import type { ColorEntry, ColorPaletteMode, ColorPaletteProps } from './types';
+
+function resolveMode(
+  mode: ColorPaletteMode | undefined,
+  colors: ColorEntry[] | undefined,
+): ColorPaletteMode {
+  if (mode) return mode;
+  return colors && colors.length > 0 ? 'custom' : 'theme';
+}
+
+/**
+ * Build the swatch list for `mode === 'theme'` — semantic tokens of the
+ * current theme. Includes the foreground/background pair plus brand and
+ * status families so a docs page can show "what does this preset look
+ * like" at a glance.
+ */
+function useThemeEntries(): ColorEntry[] {
+  const palette = useThemePalette();
+  return React.useMemo<ColorEntry[]>(
+    () => [
+      { name: 'Background', value: palette.background },
+      { name: 'Foreground', value: palette.foreground },
+      { name: 'Card', value: palette.card },
+      { name: 'Muted', value: palette.muted },
+      { name: 'Muted Foreground', value: palette.mutedForeground },
+      { name: 'Border', value: palette.border },
+      { name: 'Primary', value: palette.primary },
+      { name: 'Secondary', value: palette.secondary },
+      { name: 'Accent', value: palette.accent },
+      { name: 'Destructive', value: palette.destructive },
+      { name: 'Success', value: palette.success },
+      { name: 'Warning', value: palette.warning },
+      { name: 'Info', value: palette.info },
+    ],
+    [palette],
+  );
+}
+
+/**
+ * Build the swatch list for `mode === 'preset'` — the status / brand
+ * families exposed by `useStylePresets()`. Renders the `fill` color
+ * for each preset; consumers needing stroke/foreground should query
+ * the preset hooks directly.
+ */
+function usePresetEntries(): ColorEntry[] {
+  const presets = useStylePresets();
+  return React.useMemo<ColorEntry[]>(
+    () => [
+      { name: 'Primary', value: presets.primary.fill },
+      { name: 'Success', value: presets.success.fill },
+      { name: 'Warning', value: presets.warning.fill },
+      { name: 'Danger', value: presets.danger.fill },
+      { name: 'Info', value: presets.info.fill },
+      { name: 'Chart 3', value: presets.chart3.fill },
+      { name: 'Chart 4', value: presets.chart4.fill },
+      { name: 'Chart 5', value: presets.chart5.fill },
+    ],
+    [presets],
+  );
+}
+
+export function ColorPalette({
+  mode,
+  colors,
+  columns = 4,
+  copyFormat = 'hex',
+  showName = true,
+  showValue = true,
+  className,
+  style,
+  ...rest
+}: ColorPaletteProps) {
+  // Always call both hooks so React keeps a stable order regardless of `mode`.
+  const themeEntries = useThemeEntries();
+  const presetEntries = usePresetEntries();
+
+  const resolvedMode = resolveMode(mode, colors);
+  const entries = React.useMemo<ColorEntry[]>(() => {
+    if (resolvedMode === 'theme') return themeEntries;
+    if (resolvedMode === 'preset') return presetEntries;
+    return colors ?? [];
+  }, [resolvedMode, themeEntries, presetEntries, colors]);
+
+  const gridStyle = React.useMemo<React.CSSProperties>(
+    () => ({
+      ...style,
+      gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`,
+    }),
+    [style, columns],
+  );
+
+  return (
+    <div
+      data-slot="color-palette"
+      data-mode={resolvedMode}
+      className={cn('grid gap-3', className)}
+      style={gridStyle}
+      {...rest}
+    >
+      {entries.map((color) => (
+        <Swatch
+          key={`${color.name}-${color.value}`}
+          color={color}
+          copyFormat={copyFormat}
+          showName={showName}
+          showValue={showValue}
+        />
+      ))}
+    </div>
+  );
+}

package/src/tools/visual/design/ColorPalette/README.md

@@ -0,0 +1,34 @@
+# ColorPalette
+
+Grid of color swatches with copy-on-click. Source can be the active theme, a status preset family, or a custom list.
+
+```tsx
+import { ColorPalette } from '@djangocfg/ui-tools/color-palette';
+
+// Render the current theme tokens
+<ColorPalette mode="theme" columns={4} />
+
+// Custom swatches
+<ColorPalette
+  mode="custom"
+  colors={[{ name: 'Brand', value: '#0989aa' }]}
+  copyFormat="hex"
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `mode` | `'theme' \| 'preset' \| 'custom'` | `'custom'` if `colors` provided, else `'theme'` | Where swatches come from. |
+| `colors` | `ColorEntry[]` | — | Required when `mode === 'custom'`. |
+| `columns` | `number` | `4` | Grid columns. |
+| `copyFormat` | `'hex' \| 'rgb' \| 'hsl'` | `'hex'` | Format of the copied + rendered value. |
+| `showName` | `boolean` | `true` | Show the color label. |
+| `showValue` | `boolean` | `true` | Show the color value string. |
+
+Storybook: `apps/storybook/stories/ui-tools/visual/ColorPalette.stories.tsx`
+
+---
+
+Adapted from jalcoui (MIT).

package/src/tools/visual/design/ColorPalette/components/Swatch.tsx

@@ -0,0 +1,102 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import * as React from 'react';
+import { Check, Copy } from 'lucide-react';
+import { cn } from '@djangocfg/ui-core/lib';
+import { useCopyToClipboard } from '../hooks/useCopyToClipboard';
+import { formatColor, getReadableContrast } from '../utils';
+import type { ColorEntry, ColorFormat } from '../types';
+
+export interface SwatchProps {
+  color: ColorEntry;
+  copyFormat: ColorFormat;
+  showName: boolean;
+  showValue: boolean;
+}
+
+/**
+ * Single color swatch — colored block on top, optional `name` +
+ * formatted `value` row below. Click anywhere copies the value in
+ * the configured {@link ColorFormat}.
+ *
+ * Background uses inline `style={{ backgroundColor }}` (hex) so the
+ * color is rendered verbatim — not via Tailwind's color tokens.
+ * Chrome (border, value text) flows through semantic tokens so the
+ * frame still respects the active theme preset.
+ */
+export function Swatch({ color, copyFormat, showName, showValue }: SwatchProps) {
+  const { copied, copy } = useCopyToClipboard();
+  const formattedValue = React.useMemo(
+    () => formatColor(color.value, copyFormat),
+    [color.value, copyFormat],
+  );
+  const contrast = React.useMemo(
+    () => getReadableContrast(color.value),
+    [color.value],
+  );
+
+  const handleCopy = React.useCallback(() => {
+    void copy(formattedValue);
+  }, [copy, formattedValue]);
+
+  const iconColor = contrast === 'light' ? 'rgba(0, 0, 0, 0.7)' : 'rgba(255, 255, 255, 0.85)';
+
+  return (
+    <button
+      type="button"
+      onClick={handleCopy}
+      data-slot="color-swatch"
+      data-copied={copied || undefined}
+      aria-label={`Copy ${color.name}: ${formattedValue}`}
+      title={color.description ?? `${color.name} — ${formattedValue}`}
+      className={cn(
+        'group relative flex flex-col overflow-hidden rounded-lg border border-border/60 bg-card text-left shadow-xs outline-none transition-colors',
+        'hover:border-border focus-visible:ring-[3px] focus-visible:ring-ring/50',
+      )}
+    >
+      <div
+        className="relative flex h-20 items-center justify-center sm:h-24"
+        style={{ backgroundColor: color.value }}
+      >
+        {/* Copy / Check icon — hex color resolved in JS, theme tokens skipped on purpose
+            because the swatch background is the user-supplied hex, not a token. */}
+        <span
+          className={cn(
+            'inline-flex items-center justify-center rounded-full p-1.5 transition-opacity',
+            copied ? 'opacity-100' : 'opacity-0 group-hover:opacity-100 group-focus-visible:opacity-100',
+          )}
+          style={{ color: iconColor }}
+          aria-hidden="true"
+        >
+          {copied ? <Check className="size-4" /> : <Copy className="size-4" />}
+        </span>
+
+        {copied && (
+          <span
+            data-slot="color-swatch-toast"
+            className="absolute bottom-1.5 right-1.5 rounded-md bg-card/90 px-1.5 py-0.5 text-[10px] font-medium text-foreground shadow-sm backdrop-blur"
+          >
+            Copied!
+          </span>
+        )}
+      </div>
+
+      {(showName || showValue) && (
+        <div className="flex flex-col gap-0.5 bg-card px-3 py-2">
+          {showName && (
+            <span className="truncate text-xs font-medium text-foreground">
+              {color.name}
+            </span>
+          )}
+          {showValue && (
+            <span className="truncate font-mono text-[11px] text-muted-foreground">
+              {formattedValue}
+            </span>
+          )}
+        </div>
+      )}
+    </button>
+  );
+}

package/src/tools/visual/design/ColorPalette/hooks/useCopyToClipboard.ts

@@ -0,0 +1,41 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import * as React from 'react';
+
+/**
+ * Copy a string to the clipboard and flash a `copied` flag for
+ * `resetMs` (default 1500ms). Safe to call on browsers without
+ * `navigator.clipboard` — returns silently.
+ */
+export function useCopyToClipboard(resetMs = 1500): {
+  copied: boolean;
+  copy: (text: string) => Promise<void>;
+} {
+  const [copied, setCopied] = React.useState(false);
+  const timerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  React.useEffect(() => {
+    return () => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+    };
+  }, []);
+
+  const copy = React.useCallback(
+    async (text: string) => {
+      try {
+        if (typeof navigator === 'undefined' || !navigator.clipboard) return;
+        await navigator.clipboard.writeText(text);
+        setCopied(true);
+        if (timerRef.current) clearTimeout(timerRef.current);
+        timerRef.current = setTimeout(() => setCopied(false), resetMs);
+      } catch {
+        // Clipboard API not available / permission denied — ignore.
+      }
+    },
+    [resetMs],
+  );
+
+  return { copied, copy };
+}

package/src/tools/visual/design/ColorPalette/index.ts

@@ -0,0 +1,12 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+export { ColorPalette } from './ColorPalette';
+export { Swatch as ColorPaletteSwatch } from './components/Swatch';
+export { useCopyToClipboard } from './hooks/useCopyToClipboard';
+export { formatColor, getReadableContrast } from './utils';
+export type {
+  ColorEntry,
+  ColorFormat,
+  ColorPaletteMode,
+  ColorPaletteProps,
+} from './types';

package/src/tools/visual/design/ColorPalette/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 { ColorPaletteProps } from './types';
+
+export const LazyColorPalette = createLazyComponent<ColorPaletteProps>(
+  () => import('./ColorPalette').then((m) => ({ default: m.ColorPalette })),
+  {
+    displayName: 'LazyColorPalette',
+    fallback: (
+      <div
+        data-slot="color-palette-skeleton"
+        className="grid h-32 animate-pulse gap-3 rounded-lg bg-muted"
+      />
+    ),
+  },
+);
+
+export type { ColorPaletteProps } from './types';