@djangocfg/widget-visual 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Reforms.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# @djangocfg/widget-visual
+
+Presentation pieces: colour, motion, a code symbol, and two ways to show media
+that are not a viewer.
+
+## Install
+
+```bash
+pnpm add @djangocfg/widget-visual @djangocfg/ui-core @djangocfg/i18n
+```
+
+| Subpath | What |
+|---|---|
+| `./color-picker` | a colour picker |
+| `./color-palette` | a palette built from one seed |
+| `./marquee` | a continuous scroll |
+| `./qr-code` | a QR code; the encoder is a dynamic import |
+| `./gallery` | an image grid, carousel, thumbnails and lightbox |
+| `./lottie-player` | a Lottie animation |
+
+## What is NOT here
+
+This is the residue of ui-tools' `visual/` and `media/` folders after the parts
+with a real home left, and knowing where they went is half the package:
+
+| Looking for | It is in |
+|---|---|
+| an image viewer with zoom and pan | `@djangocfg/widget-media` |
+| an audio or video player | `@djangocfg/widget-player` |
+| a chart or an indicator | `@djangocfg/widget-charts` |
+| a dialog, tour or scroll spy | `@djangocfg/widget-overlay` |
+| a file icon | `@djangocfg/widget-data` |
+
+What remains genuinely belongs together: each puts something on screen for its
+own sake, and none owns state a host has to drive.
+
+## Verify
+
+```bash
+pnpm --filter @djangocfg/widget-visual check-types test
+```

package/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "@djangocfg/widget-visual",
+  "version": "0.1.1",
+  "description": "Presentation pieces: a colour picker and palette, a marquee, a QR code, an image gallery and a Lottie player",
+  "keywords": [
+    "color-picker",
+    "palette",
+    "marquee",
+    "qrcode",
+    "gallery",
+    "lottie",
+    "react",
+    "typescript"
+  ],
+  "author": {
+    "name": "DjangoCFG",
+    "url": "https://djangocfg.com"
+  },
+  "homepage": "https://djangocfg.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/markolofsen/django-cfg.git",
+    "directory": "widgets/visual"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./color-picker": {
+      "types": "./src/design/ColorPicker/index.ts",
+      "default": "./src/design/ColorPicker/index.ts"
+    },
+    "./color-palette": {
+      "types": "./src/design/ColorPalette/index.ts",
+      "default": "./src/design/ColorPalette/index.ts"
+    },
+    "./marquee": {
+      "types": "./src/marquee/index.ts",
+      "default": "./src/marquee/index.ts"
+    },
+    "./qr-code": {
+      "types": "./src/qrcode/index.ts",
+      "default": "./src/qrcode/index.ts"
+    },
+    "./gallery": {
+      "types": "./src/gallery/index.ts",
+      "default": "./src/gallery/index.ts"
+    },
+    "./lottie-player": {
+      "types": "./src/lottie/index.ts",
+      "default": "./src/lottie/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@djangocfg/widget-kit": "^0.1.1",
+    "@radix-ui/react-direction": "^1.1.2",
+    "@radix-ui/react-slot": "^1.3.0",
+    "class-variance-authority": "^0.7.1",
+    "qrcode": "^1.5.4",
+    "react-lottie-player": "^2.1.0"
+  },
+  "peerDependencies": {
+    "@djangocfg/i18n": "^2.1.542",
+    "@djangocfg/ui-core": "^2.1.542",
+    "lucide-react": "^0.545.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@djangocfg/i18n": "^2.1.542",
+    "@djangocfg/typescript-config": "^2.1.542",
+    "@djangocfg/ui-core": "^2.1.542",
+    "@storybook/react-vite": "^10.5.0",
+    "@types/node": "^25.9.5",
+    "@types/qrcode": "^1.5.6",
+    "@types/react": "19.2.15",
+    "@types/react-dom": "19.2.3",
+    "lucide-react": "0.545.0",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "storybook": "^10.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/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/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/design/ColorPalette/color-palette.stories.tsx

@@ -0,0 +1,95 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  ColorPalette,
+  type ColorEntry as ColorPaletteEntry,
+  type ColorFormat as ColorPaletteFormat,
+} from '.';
+
+const CUSTOM_COLORS: ColorPaletteEntry[] = [
+  { name: 'Brand Aqua', value: '#0989aa' },
+  { name: 'Brand Lime', value: '#22c55e' },
+  { name: 'Brand Coral', value: '#ef4444' },
+  { name: 'Brand Gold', value: '#f59e0b' },
+  { name: 'Brand Slate', value: '#1e293b' },
+  { name: 'Brand Cloud', value: '#f8fafc' },
+  { name: 'Brand Plum', value: '#8b5cf6' },
+  { name: 'Brand Rose', value: '#ec4899' },
+];
+
+const FORMATS: ColorPaletteFormat[] = ['hex', 'rgb', 'hsl'];
+
+const meta = {
+  title: 'Widgets/Visual/ColorPalette',
+  component: ColorPalette,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Grid of color swatches with click-to-copy. Source colors come from the active theme (`mode="theme"`), the status preset family (`mode="preset"`), or a custom array. Copy format toggles between hex / rgb / hsl. Swatch chrome (frame, value label) uses semantic Tailwind tokens; the swatch background is rendered from the raw hex so the displayed color matches the copied value.',
+      },
+    },
+  },
+  argTypes: {
+    mode: { control: 'select', options: ['theme', 'preset', 'custom'] },
+    columns: { control: { type: 'number', min: 1, max: 8, step: 1 } },
+    copyFormat: { control: 'select', options: FORMATS },
+    showName: { control: 'boolean' },
+    showValue: { control: 'boolean' },
+  },
+} satisfies Meta<typeof ColorPalette>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const ThemeColors: Story = {
+  args: { mode: 'theme', columns: 4, copyFormat: 'hex' },
+};
+
+export const StatusPresets: Story = {
+  args: { mode: 'preset', columns: 4, copyFormat: 'hex' },
+};
+
+export const CustomColors: Story = {
+  args: {
+    mode: 'custom',
+    colors: CUSTOM_COLORS,
+    columns: 4,
+    copyFormat: 'hex',
+  },
+};
+
+export const AllFormats: Story = {
+  args: {
+    mode: 'custom',
+    colors: CUSTOM_COLORS,
+    columns: 4,
+    copyFormat: 'hex',
+  },
+  render: () => (
+    <div className="flex flex-col gap-6">
+      {FORMATS.map((fmt) => (
+        <div key={fmt} className="flex flex-col gap-2">
+          <h3 className="text-sm font-medium uppercase tracking-wide text-muted-foreground">
+            copyFormat = &quot;{fmt}&quot;
+          </h3>
+          <ColorPalette
+            mode="custom"
+            colors={CUSTOM_COLORS}
+            columns={4}
+            copyFormat={fmt}
+          />
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+export const CompactGrid: Story = {
+  args: {
+    mode: 'theme',
+    columns: 6,
+    copyFormat: 'hex',
+    showValue: false,
+  },
+};

package/src/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/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/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/design/ColorPalette/lazy.tsx

@@ -0,0 +1,21 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import { createLazyComponent } from '@djangocfg/widget-kit/lazy';
+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/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;
+}