@djangocfg/ui-core 2.1.381 → 2.1.383

package/src/hooks/hotkey/useHotkeyChord.ts

@@ -0,0 +1,96 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+
+export interface UseHotkeyChordOptions {
+  /** Whether the chord is active. @default true */
+  enabled?: boolean;
+  /** Max delay between consecutive keys, in ms. @default 800 */
+  window?: number;
+  /**
+   * Fire even when focus is inside an input / textarea / contenteditable.
+   * @default false — chord sequences shouldn't hijack typing
+   */
+  enableOnFormTags?: boolean;
+  /** Prevent default browser behaviour on each key. @default false */
+  preventDefault?: boolean;
+}
+
+const FORM_TAGS = new Set(['INPUT', 'TEXTAREA', 'SELECT']);
+
+function isEditableTarget(el: EventTarget | null): boolean {
+  if (!(el instanceof HTMLElement)) return false;
+  if (FORM_TAGS.has(el.tagName)) return true;
+  if (el.isContentEditable) return true;
+  return false;
+}
+
+/**
+ * Linear-style chord shortcuts — fire `callback` when the user presses
+ * a sequence of bare keys within a time window.
+ *
+ * @example
+ * ```tsx
+ * useHotkeyChord(['g', 't'], () => navigate('/tasks'));
+ * useHotkeyChord(['g', 'i'], () => navigate('/inbox'), { window: 1200 });
+ * ```
+ *
+ * Each step is a single bare key (no modifiers). Pressing any
+ * non-sequence key resets progress, so partially-typed sequences don't
+ * fire accidentally.
+ */
+export function useHotkeyChord(
+  keys: readonly string[],
+  callback: (event: KeyboardEvent) => void,
+  options: UseHotkeyChordOptions = {},
+): void {
+  const { enabled = true, window: chordWindow = 800, enableOnFormTags = false, preventDefault = false } = options;
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+
+  useEffect(() => {
+    if (!enabled) return;
+    if (typeof window === 'undefined') return;
+    if (!keys.length) return;
+
+    const sequence = keys.map((k) => k.toLowerCase());
+    let progress = 0;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+
+    const reset = () => {
+      progress = 0;
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    };
+
+    const onKey = (e: KeyboardEvent) => {
+      if (!enableOnFormTags && isEditableTarget(e.target)) return;
+      // Chords don't carry modifiers.
+      if (e.metaKey || e.ctrlKey || e.altKey) return reset();
+
+      const expected = sequence[progress];
+      if (!expected) return;
+      const pressed = e.key.toLowerCase();
+      if (pressed !== expected) return reset();
+
+      if (preventDefault) e.preventDefault();
+      progress++;
+      if (progress >= sequence.length) {
+        callbackRef.current(e);
+        reset();
+        return;
+      }
+
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(reset, chordWindow);
+    };
+
+    window.addEventListener('keydown', onKey);
+    return () => {
+      window.removeEventListener('keydown', onKey);
+      if (timer) clearTimeout(timer);
+    };
+  }, [keys.join('|'), enabled, chordWindow, enableOnFormTags, preventDefault]);
+}

package/src/hooks/hotkey/useHotkeyHelp.ts

@@ -0,0 +1,68 @@
+'use client';
+
+import { useEffect, useSyncExternalStore } from 'react';
+
+/**
+ * Module-level store of every hotkey that registered itself with a
+ * `description`. Lets you render a `?` cheat-sheet without prop-drilling.
+ */
+export interface RegisteredHotkey {
+  /** Key combo (raw string passed to `useHotkey` — format with `formatHotkey()` for display). */
+  combo: string;
+  /** Human-readable purpose. */
+  description: string;
+  /** Optional scope label for grouping (e.g. `'chat'`, `'global'`). */
+  scope?: string;
+}
+
+const registry = new Map<symbol, RegisteredHotkey>();
+const listeners = new Set<() => void>();
+
+function notify() {
+  for (const cb of listeners) cb();
+}
+
+/**
+ * Register a hotkey entry while a component is mounted. Internal —
+ * called by `useHotkey` when a `description` is provided.
+ */
+export function registerHotkey(entry: RegisteredHotkey): () => void {
+  const key = Symbol(entry.combo);
+  registry.set(key, entry);
+  notify();
+  return () => {
+    registry.delete(key);
+    notify();
+  };
+}
+
+/** Read the live list of registered hotkeys. SSR-safe. */
+export function useHotkeyHelp(): RegisteredHotkey[] {
+  return useSyncExternalStore(
+    (cb) => {
+      listeners.add(cb);
+      return () => {
+        listeners.delete(cb);
+      };
+    },
+    () => Array.from(registry.values()),
+    () => [],
+  );
+}
+
+/** Imperative read for non-React consumers (debug panels, etc.). */
+export function getRegisteredHotkeys(): RegisteredHotkey[] {
+  return Array.from(registry.values());
+}
+
+/**
+ * Hook variant — call alongside `useHotkey` when the binding lives
+ * outside the hook (e.g. raw `window.addEventListener` consumers that
+ * still want to appear in the cheat sheet).
+ */
+export function useRegisterHotkey(entry: RegisteredHotkey | null): void {
+  useEffect(() => {
+    if (!entry) return;
+    return registerHotkey(entry);
+  }, [entry?.combo, entry?.description, entry?.scope]);
+}

package/src/hooks/index.ts

@@ -19,6 +19,7 @@ export * from './theme';
 export * from './time';
 export * from './events';
 export * from './hotkey';
+export * from './audio';
 export * from './debug';
 
 // ----------------------------------------------------------------------------

package/src/components/boundary/boundary.story.tsx

@@ -1,109 +0,0 @@
-import { defineStory, useSelect } from '@djangocfg/playground';
-import { useState } from 'react';
-
-import { Button } from '../forms/button';
-import { Boundary } from '.';
-import type { BoundaryVariant } from '.';
-
-export default defineStory({
-  title: 'Core/Boundary',
-  component: Boundary,
-  description:
-    'React error boundary with multiple visual variants. Wrap untrusted subtrees (widgets, third-party iframes, dynamic renderers) so a single render error does not crash the whole page.',
-});
-
-function BoomButton({ label = 'Throw error' }: { label?: string }) {
-  const [boom, setBoom] = useState(false);
-  if (boom) throw new Error('Demo crash from BoomButton');
-  return (
-    <Button variant="outline" size="sm" onClick={() => setBoom(true)}>
-      {label}
-    </Button>
-  );
-}
-
-export const Interactive = () => {
-  const [variant] = useSelect('variant', {
-    options: ['silent', 'inline', 'card', 'fullscreen'] as const,
-    defaultValue: 'card',
-    label: 'Variant',
-    description: 'Fallback visual style',
-  });
-
-  return (
-    <div className="max-w-lg space-y-3">
-      <p className="text-sm text-muted-foreground">
-        Click the button to throw — the surrounding page stays alive, only this block swaps to the fallback.
-      </p>
-      <Boundary variant={variant as BoundaryVariant} name="story">
-        <div className="rounded-md border p-4">
-          <BoomButton />
-        </div>
-      </Boundary>
-    </div>
-  );
-};
-
-export const Silent = () => (
-  <div className="max-w-lg space-y-2">
-    <p className="text-sm text-muted-foreground">
-      variant=&quot;silent&quot; renders nothing on error. Use for non-critical widgets (chat launcher, embeds).
-    </p>
-    <Boundary variant="silent" name="silent-demo">
-      <BoomButton label="Crash silently" />
-    </Boundary>
-    <p className="text-xs text-muted-foreground">↑ button disappears after click. Page is fine.</p>
-  </div>
-);
-
-export const Inline = () => (
-  <div className="max-w-lg">
-    <Boundary variant="inline" name="inline-demo">
-      <BoomButton />
-    </Boundary>
-  </div>
-);
-
-export const Card = () => (
-  <div className="max-w-lg">
-    <Boundary variant="card" name="card-demo">
-      <BoomButton />
-    </Boundary>
-  </div>
-);
-
-export const CustomFallback = () => (
-  <div className="max-w-lg">
-    <Boundary
-      fallback={({ error, reset }) => (
-        <div className="rounded-md border-2 border-dashed border-amber-500 bg-amber-500/5 p-4">
-          <p className="text-sm font-semibold text-amber-700">Custom fallback</p>
-          <p className="mt-1 text-xs text-amber-700/80">{error.message}</p>
-          <Button size="sm" variant="outline" className="mt-2" onClick={reset}>
-            Reset boundary
-          </Button>
-        </div>
-      )}
-    >
-      <BoomButton />
-    </Boundary>
-  </div>
-);
-
-export const ResetKeys = () => {
-  const [key, setKey] = useState(0);
-  return (
-    <div className="max-w-lg space-y-3">
-      <p className="text-sm text-muted-foreground">
-        Pass <code className="text-xs">resetKeys</code> — when any value in the array changes, the boundary auto-resets.
-        Good for clearing errors on route change.
-      </p>
-      <Button size="sm" onClick={() => setKey((k) => k + 1)}>
-        Bump resetKey ({key})
-      </Button>
-      <Boundary variant="card" resetKeys={[key]} name="resetkeys-demo">
-        <BoomButton />
-      </Boundary>
-    </div>
-  );
-};

package/src/components/data/avatar/avatar.story.tsx

@@ -1,115 +0,0 @@
-import { defineStory, useSelect } from '@djangocfg/playground';
-import { Avatar, AvatarImage, AvatarFallback } from '.';
-
-export default defineStory({
-  title: 'Core/Avatar',
-  component: Avatar,
-  description: 'User avatar with image and fallback support.',
-});
-
-const AVATARS = [
-  { src: 'https://github.com/shadcn.png', fallback: 'CN' },
-  { src: 'https://github.com/vercel.png', fallback: 'VC' },
-  { src: 'https://github.com/radix-ui.png', fallback: 'RX' },
-];
-
-export const Interactive = () => {
-  const [size] = useSelect('size', {
-    options: ['sm', 'md', 'lg'] as const,
-    defaultValue: 'md',
-    label: 'Size',
-    description: 'Avatar size',
-  });
-
-  const sizeClasses = {
-    sm: 'h-8 w-8',
-    md: 'h-10 w-10',
-    lg: 'h-14 w-14',
-  };
-
-  return (
-    <Avatar className={sizeClasses[size]}>
-      <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
-      <AvatarFallback>CN</AvatarFallback>
-    </Avatar>
-  );
-};
-
-export const Default = () => (
-  <Avatar>
-    <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
-    <AvatarFallback>CN</AvatarFallback>
-  </Avatar>
-);
-
-export const Fallback = () => (
-  <Avatar>
-    <AvatarImage src="/broken-image.jpg" alt="User" />
-    <AvatarFallback>JD</AvatarFallback>
-  </Avatar>
-);
-
-export const Sizes = () => (
-  <div className="flex items-center gap-4">
-    <Avatar className="h-6 w-6">
-      <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
-      <AvatarFallback className="text-xs">CN</AvatarFallback>
-    </Avatar>
-    <Avatar className="h-8 w-8">
-      <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
-      <AvatarFallback>CN</AvatarFallback>
-    </Avatar>
-    <Avatar className="h-10 w-10">
-      <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
-      <AvatarFallback>CN</AvatarFallback>
-    </Avatar>
-    <Avatar className="h-14 w-14">
-      <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
-      <AvatarFallback>CN</AvatarFallback>
-    </Avatar>
-    <Avatar className="h-20 w-20">
-      <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
-      <AvatarFallback className="text-xl">CN</AvatarFallback>
-    </Avatar>
-  </div>
-);
-
-export const Group = () => (
-  <div className="flex -space-x-4">
-    {AVATARS.map((avatar, i) => (
-      <Avatar key={i} className="border-2 border-background">
-        <AvatarImage src={avatar.src} />
-        <AvatarFallback>{avatar.fallback}</AvatarFallback>
-      </Avatar>
-    ))}
-    <Avatar className="border-2 border-background">
-      <AvatarFallback>+5</AvatarFallback>
-    </Avatar>
-  </div>
-);
-
-export const WithStatus = () => (
-  <div className="flex gap-4">
-    <div className="relative">
-      <Avatar>
-        <AvatarImage src="https://github.com/shadcn.png" />
-        <AvatarFallback>CN</AvatarFallback>
-      </Avatar>
-      <span className="absolute bottom-0 right-0 h-3 w-3 rounded-full bg-green-500 border-2 border-background" />
-    </div>
-    <div className="relative">
-      <Avatar>
-        <AvatarImage src="https://github.com/vercel.png" />
-        <AvatarFallback>VC</AvatarFallback>
-      </Avatar>
-      <span className="absolute bottom-0 right-0 h-3 w-3 rounded-full bg-yellow-500 border-2 border-background" />
-    </div>
-    <div className="relative">
-      <Avatar>
-        <AvatarImage src="https://github.com/radix-ui.png" />
-        <AvatarFallback>RX</AvatarFallback>
-      </Avatar>
-      <span className="absolute bottom-0 right-0 h-3 w-3 rounded-full bg-gray-400 border-2 border-background" />
-    </div>
-  </div>
-);

package/src/components/data/badge/badge.story.tsx

@@ -1,56 +0,0 @@
-import { defineStory, useSelect } from '@djangocfg/playground';
-import { Badge } from '.';
-
-export default defineStory({
-  title: 'Core/Badge',
-  component: Badge,
-  description: 'Small status indicators and labels.',
-});
-
-export const Interactive = () => {
-  const [variant] = useSelect('variant', {
-    options: ['default', 'secondary', 'destructive', 'outline'] as const,
-    defaultValue: 'default',
-    label: 'Variant',
-    description: 'Badge style variant',
-  });
-
-  return (
-    <div className="flex gap-4">
-      <Badge variant={variant}>Badge</Badge>
-    </div>
-  );
-};
-
-export const Variants = () => (
-  <div className="flex flex-wrap gap-4">
-    <Badge variant="default">Default</Badge>
-    <Badge variant="secondary">Secondary</Badge>
-    <Badge variant="destructive">Destructive</Badge>
-    <Badge variant="outline">Outline</Badge>
-  </div>
-);
-
-export const StatusBadges = () => (
-  <div className="flex flex-wrap gap-4">
-    <Badge variant="default">Active</Badge>
-    <Badge variant="secondary">Pending</Badge>
-    <Badge variant="destructive">Expired</Badge>
-    <Badge variant="outline">Draft</Badge>
-  </div>
-);
-
-export const InContext = () => (
-  <div className="space-y-4">
-    <div className="flex items-center gap-2">
-      <span className="font-medium">Status:</span>
-      <Badge variant="default">Published</Badge>
-    </div>
-    <div className="flex items-center gap-2">
-      <span className="font-medium">Tags:</span>
-      <Badge variant="secondary">React</Badge>
-      <Badge variant="secondary">TypeScript</Badge>
-      <Badge variant="secondary">UI</Badge>
-    </div>
-  </div>
-);

package/src/components/data/calendar/calendar.story.tsx

@@ -1,127 +0,0 @@
-import { useState } from 'react';
-import { defineStory } from '@djangocfg/playground';
-import { Calendar } from '.';
-import { DatePicker, DateRangePicker, type DateRange } from './date-picker';
-
-export default defineStory({
-  title: 'Core/Calendar',
-  component: Calendar,
-  description: 'Calendar and date picker components.',
-});
-
-export const Default = () => {
-  const [date, setDate] = useState<Date | undefined>(new Date());
-
-  return (
-    <Calendar
-      mode="single"
-      selected={date}
-      onSelect={setDate}
-      className="rounded-md border"
-    />
-  );
-};
-
-export const Range = () => {
-  const [range, setRange] = useState<DateRange | undefined>({
-    from: new Date(),
-    to: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
-  });
-
-  return (
-    <Calendar
-      mode="range"
-      selected={range}
-      onSelect={setRange}
-      className="rounded-md border"
-      numberOfMonths={2}
-    />
-  );
-};
-
-export const Multiple = () => {
-  const [dates, setDates] = useState<Date[] | undefined>([]);
-
-  return (
-    <Calendar
-      mode="multiple"
-      selected={dates}
-      onSelect={setDates}
-      className="rounded-md border"
-    />
-  );
-};
-
-export const Picker = () => {
-  const [date, setDate] = useState<Date>();
-
-  return (
-    <div className="max-w-xs">
-      <DatePicker
-        value={date}
-        onChange={setDate}
-        placeholder="Pick a date"
-      />
-    </div>
-  );
-};
-
-export const PickerWithLabel = () => {
-  const [date, setDate] = useState<Date>();
-
-  return (
-    <div className="max-w-xs space-y-2">
-      <label className="text-sm font-medium">Date of birth</label>
-      <DatePicker
-        value={date}
-        onChange={setDate}
-        placeholder="Select your birth date"
-      />
-    </div>
-  );
-};
-
-export const RangePicker = () => {
-  const [range, setRange] = useState<DateRange>();
-
-  return (
-    <div className="max-w-sm">
-      <DateRangePicker
-        value={range}
-        onChange={setRange}
-        placeholder="Select date range"
-      />
-    </div>
-  );
-};
-
-export const RangePickerWithPresets = () => {
-  const [range, setRange] = useState<DateRange>();
-
-  return (
-    <div className="max-w-sm space-y-2">
-      <label className="text-sm font-medium">Booking dates</label>
-      <DateRangePicker
-        value={range}
-        onChange={setRange}
-        placeholder="Check-in — Check-out"
-        numberOfMonths={2}
-      />
-    </div>
-  );
-};
-
-export const Disabled = () => {
-  const [date, setDate] = useState<Date>();
-
-  return (
-    <div className="max-w-xs">
-      <DatePicker
-        value={date}
-        onChange={setDate}
-        placeholder="Pick a date"
-        disabled
-      />
-    </div>
-  );
-};