@djangocfg/ui-tools 2.1.418 → 2.1.419

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

package/src/tools/visual/indicators/StatusIndicator/StatusIndicator.tsx

@@ -0,0 +1,83 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+//
+// Operational status badge with colored dot and label for dashboards,
+// status pages, and header bars.
+//
+// Golden sample — see CONTRACT.md. Demonstrates:
+//   - semantic tokens only (no raw color scales)
+//   - Tailwind `animate-ping` for pulse (no framer-motion)
+//   - attribution header
+//   - no nested providers
+//   - decomposed types in `./types`, lazy in `./lazy`
+
+'use client';
+
+import * as React from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+import {
+  STATUS_CONFIG,
+  TONE_CLASSES,
+  statusIndicatorVariants,
+  type StatusIndicatorProps,
+  type StatusTone,
+} from './types';
+
+const LIVE_STATUSES = new Set<string>([
+  'incident',
+  'major-outage',
+  'partial-outage',
+  'degraded',
+]);
+
+export function StatusIndicator({
+  status,
+  label,
+  tone: toneProp,
+  pulse: pulseProp,
+  size,
+  className,
+  ...props
+}: StatusIndicatorProps) {
+  const config = STATUS_CONFIG[status];
+  const tone: StatusTone = toneProp ?? config.tone;
+  const displayLabel = label ?? config.label;
+  const pulse = pulseProp ?? LIVE_STATUSES.has(status);
+
+  const toneClasses = TONE_CLASSES[tone];
+
+  return (
+    <span
+      data-slot="status-indicator"
+      data-status={status}
+      data-tone={tone}
+      role="status"
+      aria-label={displayLabel}
+      className={cn(
+        statusIndicatorVariants({ size }),
+        'border-border/60 shadow-xs',
+        toneClasses.pill,
+        className,
+      )}
+      {...props}
+    >
+      <span
+        data-slot="status-dot"
+        className={cn('relative shrink-0 rounded-full', toneClasses.dot)}
+        aria-hidden="true"
+      >
+        {pulse && (
+          <span
+            data-slot="status-dot-pulse"
+            className={cn(
+              'absolute inset-0 rounded-full opacity-60 animate-ping',
+              toneClasses.dot,
+            )}
+          />
+        )}
+      </span>
+      <span className={cn('whitespace-nowrap', toneClasses.text)}>
+        {displayLabel}
+      </span>
+    </span>
+  );
+}

package/src/tools/visual/indicators/StatusIndicator/index.ts

@@ -0,0 +1,14 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+export { StatusIndicator } from './StatusIndicator';
+export {
+  STATUS_CONFIG,
+  TONE_CLASSES,
+  statusIndicatorVariants,
+} from './types';
+export type {
+  Status,
+  StatusTone,
+  StatusIndicatorSize,
+  StatusIndicatorProps,
+} from './types';

package/src/tools/visual/indicators/StatusIndicator/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 { StatusIndicatorProps } from './types';
+
+export const LazyStatusIndicator = createLazyComponent<StatusIndicatorProps>(
+  () => import('./StatusIndicator').then((mod) => ({ default: mod.StatusIndicator })),
+  {
+    displayName: 'LazyStatusIndicator',
+    fallback: (
+      <span
+        data-slot="status-indicator-skeleton"
+        className="inline-flex h-7 w-24 animate-pulse rounded-full bg-muted"
+      />
+    ),
+  },
+);
+
+export type { StatusIndicatorProps } from './types';

package/src/tools/visual/indicators/StatusIndicator/types.ts

@@ -0,0 +1,133 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+import type * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+
+/**
+ * Operational status of a service or component.
+ *
+ * Each value maps to a semantic tone defined in {@link STATUS_TONE}. Custom
+ * statuses can be passed by extending {@link STATUS_TONE} at the call site
+ * (see `<StatusIndicator tone="..." />` escape hatch).
+ */
+export type Status =
+  | 'operational'
+  | 'degraded'
+  | 'partial-outage'
+  | 'major-outage'
+  | 'maintenance'
+  | 'incident'
+  | 'unknown';
+
+/**
+ * Semantic tone used to colorize the dot and label.
+ *
+ * Maps 1:1 to status-surface tokens in `ui-core/styles` (success / warning /
+ * destructive / info / muted). Themes / presets override these tokens —
+ * never reference raw scales like `emerald-500`.
+ */
+export type StatusTone = 'success' | 'warning' | 'destructive' | 'info' | 'muted';
+
+/**
+ * Default Status → tone + label mapping. Override per-instance via the
+ * `tone` and `label` props.
+ */
+export const STATUS_CONFIG: Record<Status, { label: string; tone: StatusTone }> = {
+  operational: { label: 'Operational', tone: 'success' },
+  degraded: { label: 'Degraded', tone: 'warning' },
+  'partial-outage': { label: 'Partial Outage', tone: 'warning' },
+  'major-outage': { label: 'Major Outage', tone: 'destructive' },
+  maintenance: { label: 'Maintenance', tone: 'info' },
+  incident: { label: 'Incident', tone: 'destructive' },
+  unknown: { label: 'Unknown', tone: 'muted' },
+};
+
+/**
+ * Tailwind classes per tone. All classes resolve to semantic tokens; no raw
+ * color scales.
+ *
+ * The whole pill (background) uses the status-surface `bg-*-background`
+ * token paired with the readable `text-*-foreground` token — that pair
+ * is the one `ui-core/styles` specifically tunes for banner/pill use
+ * (low-saturation surface + dark accent text). Stacking a red-on-pale-red
+ * label over a `bg-card` pill, as the previous version did, dropped
+ * contrast under 3:1 on light theme.
+ *
+ * The dot stays at the saturated accent color (`bg-*`) so it visually
+ * pops against the muted surface.
+ *
+ * `destructive` has no `--destructive-foreground` tuned for surface use
+ * (the existing token is the white-on-red filled-button text), so we use
+ * the accent color itself — dark red on the pale-red surface still meets
+ * AA contrast in both light and dark themes.
+ */
+export const TONE_CLASSES: Record<
+  StatusTone,
+  { dot: string; text: string; pill: string }
+> = {
+  success: {
+    dot: 'bg-success',
+    text: 'text-success-foreground',
+    pill: 'bg-success-background',
+  },
+  warning: {
+    dot: 'bg-warning',
+    text: 'text-warning-foreground',
+    pill: 'bg-warning-background',
+  },
+  destructive: {
+    dot: 'bg-destructive',
+    text: 'text-destructive',
+    pill: 'bg-destructive-background',
+  },
+  info: {
+    dot: 'bg-info',
+    text: 'text-info-foreground',
+    pill: 'bg-info-background',
+  },
+  muted: {
+    dot: 'bg-muted-foreground/60',
+    text: 'text-muted-foreground',
+    pill: 'bg-muted',
+  },
+};
+
+export const statusIndicatorVariants = cva(
+  'inline-flex items-center gap-2 rounded-full border font-medium',
+  {
+    variants: {
+      size: {
+        sm: 'h-6 px-2.5 text-[11px] [&>[data-slot=status-dot]]:size-1.5',
+        md: 'h-7 px-3 text-xs [&>[data-slot=status-dot]]:size-2',
+        lg: 'h-8 px-3.5 text-sm [&>[data-slot=status-dot]]:size-2.5',
+      },
+    },
+    defaultVariants: {
+      size: 'md',
+    },
+  },
+);
+
+export type StatusIndicatorSize = NonNullable<
+  VariantProps<typeof statusIndicatorVariants>['size']
+>;
+
+export interface StatusIndicatorProps
+  extends Omit<React.ComponentProps<'span'>, 'children'>,
+    VariantProps<typeof statusIndicatorVariants> {
+  /** Current operational status. */
+  status: Status;
+  /** Custom label text. Auto-generated from status when omitted. */
+  label?: string;
+  /**
+   * Override the tone (semantic color) used for dot + label. Defaults to
+   * {@link STATUS_CONFIG}`[status].tone`.
+   */
+  tone?: StatusTone;
+  /**
+   * Enable the pulsing halo around the dot. Defaults to `true` for live
+   * statuses (`incident`, `major-outage`, `partial-outage`, `degraded`)
+   * and `false` for steady states.
+   */
+  pulse?: boolean;
+}

package/src/components/FloatingToolbar/actions/CopyAction.tsx

@@ -1,22 +0,0 @@
-'use client';
-
-import React from 'react';
-import { CopyButton } from '@djangocfg/ui-core/components';
-
-interface CopyActionProps {
-  value: string;
-  title?: string;
-}
-
-const BUTTON_CLASS = 'h-6 w-6 rounded-sm bg-muted/80 hover:bg-muted border border-border/50 backdrop-blur-sm';
-
-export const CopyAction: React.FC<CopyActionProps> = ({ value, title = 'Copy' }) => (
-  <CopyButton
-    value={value}
-    variant="ghost"
-    size="icon"
-    className={BUTTON_CLASS}
-    iconClassName="h-3 w-3"
-    title={title}
-  />
-);

package/src/components/FloatingToolbar/actions/ExpandAction.tsx

@@ -1,25 +0,0 @@
-'use client';
-
-import { ChevronDown, ChevronUp } from 'lucide-react';
-import React from 'react';
-
-import { Button } from '@djangocfg/ui-core/components';
-
-interface ExpandActionProps {
-  isExpanded: boolean;
-  onToggle: () => void;
-}
-
-const BUTTON_CLASS = 'h-6 w-6 rounded-sm bg-muted/80 hover:bg-muted border border-border/50 backdrop-blur-sm';
-
-export const ExpandAction: React.FC<ExpandActionProps> = ({ isExpanded, onToggle }) => (
-  <Button
-    variant="ghost"
-    size="icon"
-    onClick={onToggle}
-    className={BUTTON_CLASS}
-    title={isExpanded ? 'Collapse All' : 'Expand All'}
-  >
-    {isExpanded ? <ChevronUp className="h-3 w-3" /> : <ChevronDown className="h-3 w-3" />}
-  </Button>
-);

package/src/components/FloatingToolbar/actions/FullscreenAction.tsx

@@ -1,30 +0,0 @@
-'use client';
-
-import { Maximize2, Minimize2 } from 'lucide-react';
-import React from 'react';
-
-import { Button } from '@djangocfg/ui-core/components';
-
-interface FullscreenActionProps {
-  isFullscreen?: boolean;
-  onToggle: () => void;
-  title?: string;
-}
-
-const BUTTON_CLASS = 'h-6 w-6 rounded-sm bg-muted/80 hover:bg-muted border border-border/50 backdrop-blur-sm';
-
-export const FullscreenAction: React.FC<FullscreenActionProps> = ({
-  isFullscreen = false,
-  onToggle,
-  title,
-}) => (
-  <Button
-    variant="ghost"
-    size="icon"
-    onClick={onToggle}
-    className={BUTTON_CLASS}
-    title={title ?? (isFullscreen ? 'Exit fullscreen' : 'Fullscreen')}
-  >
-    {isFullscreen ? <Minimize2 className="h-3 w-3" /> : <Maximize2 className="h-3 w-3" />}
-  </Button>
-);