@djangocfg/ui-tools 2.1.417 → 2.1.419

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

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

@@ -0,0 +1,63 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+import type * as React from 'react';
+
+/**
+ * Display format for the copied / rendered color value.
+ *
+ * - `hex` — `#0989aa` (default). Canvas2D / SVG friendly.
+ * - `rgb` — `rgb(9, 137, 170)`.
+ * - `hsl` — `hsl(192, 90%, 35%)`.
+ */
+export type ColorFormat = 'hex' | 'rgb' | 'hsl';
+
+/**
+ * A single color entry rendered as one swatch.
+ *
+ * `value` is always a hex string (`#rrggbb`). Resolve theme tokens
+ * to hex via `useThemeColor(...)` before passing them in.
+ */
+export interface ColorEntry {
+  /** Display name (e.g. "Primary", "Success", "brand-accent"). */
+  name: string;
+  /** Hex color value, e.g. `#0989aa`. */
+  value: string;
+  /** Optional usage note. */
+  description?: string;
+}
+
+/**
+ * Source of swatches.
+ *
+ * - `theme` — semantic tokens from `useThemePalette()` (background,
+ *   foreground, primary, secondary, muted, accent, destructive, …).
+ * - `preset` — status preset family from `useStylePresets()`
+ *   (primary, success, warning, danger, info, chart3-5).
+ * - `custom` — caller-provided `colors` array.
+ */
+export type ColorPaletteMode = 'theme' | 'preset' | 'custom';
+
+export interface ColorPaletteProps
+  extends Omit<React.ComponentProps<'div'>, 'children'> {
+  /**
+   * Where swatches come from. Defaults to `'custom'` when `colors` is
+   * provided, otherwise `'theme'`.
+   */
+  mode?: ColorPaletteMode;
+  /**
+   * Explicit list of swatches (required when `mode === 'custom'`).
+   * Ignored for `'theme'` / `'preset'`.
+   */
+  colors?: ColorEntry[];
+  /** Grid column count. @default 4 */
+  columns?: number;
+  /**
+   * Format of the copied value AND the rendered value text.
+   * @default 'hex'
+   */
+  copyFormat?: ColorFormat;
+  /** Show the color name label below the swatch. @default true */
+  showName?: boolean;
+  /** Show the color value string below the swatch. @default true */
+  showValue?: boolean;
+}

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

@@ -0,0 +1,83 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+import type { ColorFormat } from './types';
+
+/**
+ * Parse a `#rrggbb` / `#rgb` hex string into `{ r, g, b }` (0–255).
+ * Returns `null` for malformed input.
+ */
+function parseHex(hex: string): { r: number; g: number; b: number } | null {
+  const cleaned = hex.trim().replace(/^#/, '');
+  if (cleaned.length === 3) {
+    const r = parseInt(cleaned[0] + cleaned[0], 16);
+    const g = parseInt(cleaned[1] + cleaned[1], 16);
+    const b = parseInt(cleaned[2] + cleaned[2], 16);
+    if ([r, g, b].some(Number.isNaN)) return null;
+    return { r, g, b };
+  }
+  if (cleaned.length === 6) {
+    const r = parseInt(cleaned.slice(0, 2), 16);
+    const g = parseInt(cleaned.slice(2, 4), 16);
+    const b = parseInt(cleaned.slice(4, 6), 16);
+    if ([r, g, b].some(Number.isNaN)) return null;
+    return { r, g, b };
+  }
+  return null;
+}
+
+function rgbToHsl(
+  r: number,
+  g: number,
+  b: number,
+): { h: number; s: number; l: number } {
+  const rn = r / 255;
+  const gn = g / 255;
+  const bn = b / 255;
+  const max = Math.max(rn, gn, bn);
+  const min = Math.min(rn, gn, bn);
+  const l = (max + min) / 2;
+  let h = 0;
+  let s = 0;
+  if (max !== min) {
+    const d = max - min;
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    switch (max) {
+      case rn:
+        h = (gn - bn) / d + (gn < bn ? 6 : 0);
+        break;
+      case gn:
+        h = (bn - rn) / d + 2;
+        break;
+      case bn:
+        h = (rn - gn) / d + 4;
+        break;
+    }
+    h /= 6;
+  }
+  return { h: Math.round(h * 360), s: Math.round(s * 100), l: Math.round(l * 100) };
+}
+
+/**
+ * Format a hex color into the requested {@link ColorFormat}. Falls
+ * back to the original string when the hex is unparseable.
+ */
+export function formatColor(hex: string, format: ColorFormat): string {
+  if (format === 'hex') return hex.toLowerCase();
+  const rgb = parseHex(hex);
+  if (!rgb) return hex;
+  if (format === 'rgb') return `rgb(${rgb.r}, ${rgb.g}, ${rgb.b})`;
+  const { h, s, l } = rgbToHsl(rgb.r, rgb.g, rgb.b);
+  return `hsl(${h}, ${s}%, ${l}%)`;
+}
+
+/**
+ * Return `'light'` when the hex color is bright enough that black
+ * text reads better against it, otherwise `'dark'`. Uses standard
+ * Rec. 601 luminance (`0.299·R + 0.587·G + 0.114·B`).
+ */
+export function getReadableContrast(hex: string): 'light' | 'dark' {
+  const rgb = parseHex(hex);
+  if (!rgb) return 'dark';
+  const luminance = (0.299 * rgb.r + 0.587 * rgb.g + 0.114 * rgb.b) / 255;
+  return luminance > 0.6 ? 'light' : 'dark';
+}

package/src/tools/visual/{ColorPicker → design/ColorPicker}/lazy.tsx

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

package/src/tools/visual/{FileIcon → design/FileIcon}/treeAdapter.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import type { TreeNode, TreeRowSlot } from '../../data/Tree/types';
+import type { TreeNode, TreeRowSlot } from '../../../data/Tree/types';
 import { FileIcon, type FileIconSize } from './FileIcon';
 import type { FolderIconOverrides } from './specialFolders';
 

package/src/tools/visual/{Fps → indicators/Fps}/lazy.tsx

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

package/src/tools/visual/{Rating → indicators/Rating}/lazy.tsx

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

package/src/tools/visual/indicators/StatusIndicator/README.md

@@ -0,0 +1,28 @@
+# StatusIndicator
+
+Compact operational-status pill (dot + label). Maps `Status` → semantic `StatusTone` (success / warning / destructive / info / muted) via `STATUS_CONFIG`.
+
+This component is the **golden sample** for the jalcoui port — it demonstrates all CONTRACT rules (semantic tokens, CVA variants, no nested providers, attribution).
+
+```tsx
+import { StatusIndicator } from '@djangocfg/ui-tools/status-indicator';
+
+<StatusIndicator status="operational" />
+<StatusIndicator status="degraded" size="lg" />
+<StatusIndicator status="incident" label="Custom label" />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `status` | `Status` | — | `'operational' \| 'degraded' \| 'partial-outage' \| 'major-outage' \| 'maintenance' \| 'incident' \| 'unknown'`. |
+| `tone` | `StatusTone` | from `STATUS_CONFIG` | Override the semantic tone. |
+| `label` | `string` | from `STATUS_CONFIG` | Override the visible label. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Pill scale. |
+
+Storybook: `apps/storybook/stories/ui-tools/visual/StatusIndicator.stories.tsx`
+
+---
+
+Adapted from jalcoui (MIT).