@djangocfg/ui-core 2.1.540 → 2.1.542

package/src/hooks/events/useEventsBus.ts

@@ -2,7 +2,7 @@
 
 import { useEffect, useRef } from 'react';
 
-export type FormEvent<T extends string = string, P = any> = {
+export type FormEvent<T extends string = string, P = unknown> = {
     type: T;
     payload?: P;
     timestamp?: number;
@@ -11,7 +11,9 @@ export type FormEvent<T extends string = string, P = any> = {
 type EventListener<T extends FormEvent> = (event: T) => void;
 
 class EventBus {
-    private listeners: Set<EventListener<any>> = new Set();
+    // Subscribers each declare their own event type; the bus only ever hands
+    // them a FormEvent, so it stores the widest listener it can actually call.
+    private listeners: Set<EventListener<FormEvent>> = new Set();
 
     publish<T extends FormEvent>(event: T) {
         this.listeners.forEach(listener => listener({
@@ -20,7 +22,10 @@ class EventBus {
         }));
     }
 
-    subscribe<T extends FormEvent>(listener: EventListener<T>) {
+    // Not generic on purpose: the bus broadcasts EVERY event to EVERY listener,
+    // so a listener declaring a narrower event type would be handed events that
+    // do not match it. Filtering by `type` is the subscriber's job.
+    subscribe(listener: EventListener<FormEvent>) {
         this.listeners.add(listener);
         return () => {
             this.listeners.delete(listener);
@@ -30,9 +35,18 @@ class EventBus {
 
 export const events = new EventBus();
 
-export function useEventListener<T extends string, P>(
+/**
+ * Subscribe to one event type on the bus.
+ *
+ * The payload arrives from an untyped publisher, so it is delivered as
+ * `unknown`: this is the boundary, and the handler narrows it. Callers that
+ * know the publisher's shape should narrow with a type guard rather than
+ * declaring the shape and hoping — nothing at runtime enforces the pairing of
+ * `eventType` and payload.
+ */
+export function useEventListener<T extends string>(
     eventType: T,
-    handler: (payload: P) => void
+    handler: (payload: unknown) => void
 ) {
     const savedHandler = useRef(handler);
 

package/src/hooks/hotkey/useHotkeyChord.ts

@@ -48,12 +48,19 @@ export function useHotkeyChord(
   const callbackRef = useRef(callback);
   callbackRef.current = callback;
 
+  // The listener is rebound on the chord's CONTENTS, not the array's identity:
+  // callers write `useHotkeyChord(['g', 't'], …)` with a fresh literal each
+  // render, which would otherwise tear down and re-add the keydown listener
+  // continuously and reset any chord in progress.
+  const keysKey = keys.join('|');
+  const keysRef = useRef(keys);
+  keysRef.current = keys;
+
   useEffect(() => {
     if (!enabled) return;
     if (typeof window === 'undefined') return;
-    if (!keys.length) return;
-
-    const sequence = keys.map((k) => k.toLowerCase());
+    const sequence = keysRef.current.map((k) => k.toLowerCase());
+    if (!sequence.length) return;
     let progress = 0;
     let timer: ReturnType<typeof setTimeout> | null = null;
 
@@ -92,5 +99,5 @@ export function useHotkeyChord(
       window.removeEventListener('keydown', onKey);
       if (timer) clearTimeout(timer);
     };
-  }, [keys.join('|'), enabled, chordWindow, enableOnFormTags, preventDefault]);
+  }, [keysKey, enabled, chordWindow, enableOnFormTags, preventDefault]);
 }

package/src/hooks/hotkey/useHotkeyHelp.ts

@@ -61,8 +61,13 @@ export function getRegisteredHotkeys(): RegisteredHotkey[] {
  * still want to appear in the cheat sheet).
  */
 export function useRegisterHotkey(entry: RegisteredHotkey | null): void {
+  // Registration is keyed on the entry's FIELDS, not its identity: callers pass
+  // an inline object, so depending on `entry` would unregister and re-register
+  // on every render and notify every cheat-sheet subscriber each time.
+  const { combo, description, scope } = entry ?? {};
+
   useEffect(() => {
-    if (!entry) return;
-    return registerHotkey(entry);
-  }, [entry?.combo, entry?.description, entry?.scope]);
+    if (!combo || !description) return;
+    return registerHotkey({ combo, description, scope });
+  }, [combo, description, scope]);
 }

package/src/hooks/router/adapter.tsx

@@ -113,7 +113,9 @@ export const defaultAdapter: RouterAdapter = Object.freeze({
 // every hook reads another — falling back to the History API, which changes the
 // URL without telling the host router.
 const CONTEXT_KEY = Symbol.for('@djangocfg/ui-core.RouterAdapterContext');
-const globalScope = globalThis as unknown as Record<symbol, unknown>;
+// `typeof globalThis` carries no index signature, but the object genuinely
+// accepts symbol keys — this asserts a property the runtime has.
+const globalScope = globalThis as Record<symbol, unknown>;
 
 export const RouterAdapterContext =
   (globalScope[CONTEXT_KEY] as ReturnType<typeof createContext<RouterAdapter | null>> | undefined) ??

package/src/hooks/state/storage-quota.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared quota detection for the localStorage / sessionStorage hooks.
+ *
+ * Internal — not exported from the package entry point.
+ */
+
+/**
+ * Is this thrown value the browser's "storage is full" signal?
+ *
+ * Boundary: a `catch` binding is `unknown`, and browsers disagree on how they
+ * report a full quota — Chrome/Safari throw `QuotaExceededError`, older engines
+ * use the legacy DOMException code 22, and some report it only in the message.
+ * Each field is therefore probed rather than assumed to exist.
+ */
+export function isQuotaExceededError(error: unknown): boolean {
+  if (typeof error !== 'object' || error === null) return false;
+
+  const { name, code, message } = error as {
+    name?: unknown;
+    code?: unknown;
+    message?: unknown;
+  };
+
+  if (name === 'QuotaExceededError') return true;
+  if (code === 22) return true;
+  return typeof message === 'string' && message.includes('quota');
+}

package/src/hooks/state/useDebouncedCallback.ts

@@ -1,6 +1,6 @@
 'use client';
 
-import { useCallback, useEffect, useRef } from 'react';
+import { useCallback, useEffect, useMemo, useRef } from 'react';
 
 /**
  * Creates a debounced version of a callback function.
@@ -9,10 +9,15 @@ import { useCallback, useEffect, useRef } from 'react';
  * @param delay The debounce delay in milliseconds.
  * @returns A debounced callback function.
  */
-export function useDebouncedCallback<T extends (...args: any[]) => any>(
+/** The debounced function, plus the `cancel` handle this hook attaches to it. */
+export type DebouncedCallback<T extends (...args: never[]) => unknown> = ((
+    ...args: Parameters<T>
+) => void) & { cancel: () => void };
+
+export function useDebouncedCallback<T extends (...args: never[]) => unknown>(
     callback: T,
     delay: number
-): (...args: Parameters<T>) => void {
+): DebouncedCallback<T> {
     const callbackRef = useRef(callback);
     const timeoutRef = useRef<NodeJS.Timeout | null>(null);
 
@@ -30,29 +35,30 @@ export function useDebouncedCallback<T extends (...args: any[]) => any>(
         };
     }, []);
 
-    const debouncedCallback = useCallback(
-        (...args: Parameters<T>) => {
-            if (timeoutRef.current) {
-                clearTimeout(timeoutRef.current);
-            }
-
-            timeoutRef.current = setTimeout(() => {
-                callbackRef.current(...args);
-            }, delay);
-        },
-        [delay]
-    );
-
-    // Add a cancel method to the debounced function
-    // We attach it directly to the function object
-    (debouncedCallback as any).cancel = useCallback(() => {
+    const cancel = useCallback(() => {
         if (timeoutRef.current) {
             clearTimeout(timeoutRef.current);
             timeoutRef.current = null;
         }
     }, []);
 
-    return debouncedCallback;
+    // `cancel` is part of the returned type, so it is assembled with the
+    // function rather than bolted on afterwards.
+    return useMemo(() => {
+        const debounced: DebouncedCallback<T> = Object.assign(
+            (...args: Parameters<T>) => {
+                if (timeoutRef.current) {
+                    clearTimeout(timeoutRef.current);
+                }
+
+                timeoutRef.current = setTimeout(() => {
+                    callbackRef.current(...args);
+                }, delay);
+            },
+            { cancel }
+        );
+        return debounced;
+    }, [delay, cancel]);
 }
 
 export default useDebouncedCallback; 

package/src/hooks/state/useLocalStorage.ts

@@ -2,6 +2,8 @@
 
 import { useCallback, useEffect, useRef, useState } from 'react';
 
+import { isQuotaExceededError } from './storage-quota';
+
 /**
  * Storage wrapper format with metadata
  * Used when TTL is specified
@@ -254,7 +256,7 @@ export function useLocalStorage<T>(
   }, [key, parseRaw]);
 
   // Check data size and limit
-  const checkDataSize = (data: any): boolean => {
+  const checkDataSize = (data: unknown): boolean => {
     try {
       const jsonString = JSON.stringify(data);
       const sizeInBytes = new Blob([jsonString]).size;
@@ -338,12 +340,8 @@ export function useLocalStorage<T>(
     (dataToStore: string): void => {
       try {
         window.localStorage.setItem(key, dataToStore);
-      } catch (storageError: any) {
-        if (
-          storageError.name === 'QuotaExceededError' ||
-          storageError.code === 22 ||
-          storageError.message?.includes('quota')
-        ) {
+      } catch (storageError) {
+        if (isQuotaExceededError(storageError)) {
           console.warn('localStorage quota exceeded, clearing old data...');
           clearOldData();
           try {
@@ -481,12 +479,8 @@ export function useLocalStorage<T>(
       if (typeof window !== 'undefined') {
         try {
           window.localStorage.removeItem(key);
-        } catch (removeError: any) {
-          if (
-            removeError.name === 'QuotaExceededError' ||
-            removeError.code === 22 ||
-            removeError.message?.includes('quota')
-          ) {
+        } catch (removeError) {
+          if (isQuotaExceededError(removeError)) {
             console.warn('localStorage quota exceeded during removal, clearing old data...');
             clearOldData();
             try {

package/src/hooks/state/useSessionStorage.ts

@@ -2,6 +2,8 @@
 
 import { useState } from 'react';
 
+import { isQuotaExceededError } from './storage-quota';
+
 /**
  * Storage wrapper format with metadata
  * Used when TTL is specified
@@ -131,7 +133,7 @@ export function useSessionStorage<T>(
   });
 
   // Check data size and limit
-  const checkDataSize = (data: any): boolean => {
+  const checkDataSize = (data: unknown): boolean => {
     try {
       const jsonString = JSON.stringify(data);
       const sizeInBytes = new Blob([jsonString]).size;
@@ -236,11 +238,9 @@ export function useSessionStorage<T>(
         // Try to set the value
         try {
           window.sessionStorage.setItem(key, dataToStore);
-        } catch (storageError: any) {
+        } catch (storageError) {
           // If quota exceeded, clear old data and try again
-          if (storageError.name === 'QuotaExceededError' ||
-              storageError.code === 22 ||
-              storageError.message?.includes('quota')) {
+          if (isQuotaExceededError(storageError)) {
             console.warn('sessionStorage quota exceeded, clearing old data...');
             clearOldData();
 
@@ -279,11 +279,9 @@ export function useSessionStorage<T>(
       if (typeof window !== 'undefined') {
         try {
           window.sessionStorage.removeItem(key);
-        } catch (removeError: any) {
+        } catch (removeError) {
           // If removal fails due to quota, try to clear some data first
-          if (removeError.name === 'QuotaExceededError' ||
-              removeError.code === 22 ||
-              removeError.message?.includes('quota')) {
+          if (isQuotaExceededError(removeError)) {
             console.warn('sessionStorage quota exceeded during removal, clearing old data...');
             clearOldData();
 

package/src/lib/compose-event-handlers.ts

@@ -1,6 +1,9 @@
 "use client";
 
-function composeEventHandlers<E>(
+// Constrained to values that actually carry `defaultPrevented` — both DOM
+// events and React synthetic events qualify. Without it the guard below reads a
+// property the type never promised.
+function composeEventHandlers<E extends { defaultPrevented: boolean }>(
   originalEventHandler?: (event: E) => void,
   ourEventHandler?: (event: E) => void,
   { checkForDefaultPrevented = true } = {},
@@ -8,10 +11,7 @@ function composeEventHandlers<E>(
   return function handleEvent(event: E) {
     originalEventHandler?.(event);
 
-    if (
-      checkForDefaultPrevented &&
-      (event as unknown as Event).defaultPrevented
-    ) {
+    if (checkForDefaultPrevented && event.defaultPrevented) {
       return;
     }
 

package/src/lib/dialog-service/getDialog.ts

@@ -30,7 +30,7 @@ export function getDialog(): DialogAPI | null {
   if (!api) {
     if (process.env.NODE_ENV !== 'production' && !warnedMissing) {
       warnedMissing = true;
-      // eslint-disable-next-line no-console
+       
       console.warn(
         '[getDialog] window.dialog is not available — mount <DialogProvider /> at the app root.',
       );

package/src/lib/get-element-ref.ts

@@ -3,17 +3,21 @@
 import * as React from "react";
 
 /**
- * Get the ref from a React element without throwing warnings.
+ * React 18 exposed `ref` on the element itself; React 19 moved it into `props`.
+ * Neither placement is in `ReactElement`'s public type, so the legacy one is
+ * declared here rather than asserted away.
  */
-function getElementRef(element: React.ReactElement) {
+type ElementWithLegacyRef = React.ReactElement & { ref?: React.Ref<unknown> };
+
+/** Get the ref from a React element without throwing warnings. */
+function getElementRef(element: ElementWithLegacyRef) {
   if (!React.isValidElement(element)) return undefined;
 
   // React <=18 in DEV
   let getter = Object.getOwnPropertyDescriptor(element.props, "ref")?.get;
   let mayWarn = getter && "isReactWarning" in getter && getter.isReactWarning;
   if (mayWarn) {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    return (element as any).ref;
+    return element.ref;
   }
 
   // React 19 in DEV
@@ -25,8 +29,7 @@ function getElementRef(element: React.ReactElement) {
 
   // Not DEV
   return (
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    (element.props as { ref?: React.Ref<unknown> }).ref || (element as any).ref
+    (element.props as { ref?: React.Ref<unknown> }).ref || element.ref
   );
 }
 

package/src/lib/pretext/pretext.types.ts

@@ -1,72 +1,27 @@
 // Adapted from jalcoui (MIT) — github.com/jal-co/ui
 //
-// Local mirror of the @chenglou/pretext public API. The runtime dependency
-// is declared `optional` (see ui-tools/package.json), so consumers that
-// never use BalancedText / pretext-powered tools don't pay for it. To keep
-// `pnpm check` green without the dependency installed, we redeclare just
-// the types we touch — no `import type from '@chenglou/pretext'`.
-//
-// Mirrors the public surface as of @chenglou/pretext 0.0.7. If the upstream
-// types drift, update here.
-
-export interface PrepareOptions {
-  whiteSpace?: 'normal' | 'pre' | 'pre-wrap' | 'pre-line';
-}
-
-// Opaque handles — internal shape doesn't matter to consumers of the hooks.
-// We brand them so the two flavours don't get accidentally swapped.
-export interface PreparedText {
-  readonly __brand: 'PreparedText';
-}
-
-export interface PreparedTextWithSegments {
-  readonly __brand: 'PreparedTextWithSegments';
-}
-
-export interface LayoutResult {
-  lineCount: number;
-  height: number;
-}
-
-export interface LayoutLine {
-  text: string;
-  width: number;
-  start: number;
-  end: number;
-}
-
-export interface LayoutLinesResult {
-  lineCount: number;
-  height: number;
-  lines: LayoutLine[];
-}
-
-export interface WalkLineRange {
-  width: number;
-  start: number;
-  end: number;
-}
-
-export interface PretextModule {
-  prepare(text: string, font: string, options?: PrepareOptions): PreparedText;
-  prepareWithSegments(
-    text: string,
-    font: string,
-    options?: PrepareOptions,
-  ): PreparedTextWithSegments;
-  layout(
-    prepared: PreparedText,
-    maxWidth: number,
-    lineHeight: number,
-  ): LayoutResult;
-  layoutWithLines(
-    prepared: PreparedTextWithSegments,
-    maxWidth: number,
-    lineHeight: number,
-  ): LayoutLinesResult;
-  walkLineRanges(
-    prepared: PreparedTextWithSegments,
-    maxWidth: number,
-    visit: (line: WalkLineRange) => void,
-  ): void;
-}
+// Re-export of the @chenglou/pretext public types. A hand-written mirror used
+// to live here to keep `pnpm check` green while the runtime was an optional
+// dependency; it is a hard `dependencies` entry now, and the mirror had already
+// drifted — it declared `LayoutLine.start/end` as `number` where upstream
+// returns a `{ segmentIndex, graphemeIndex }` cursor, so every consumer of
+// `usePretextLines` was typed against a shape the runtime never produces.
+
+export type {
+  PrepareOptions,
+  PreparedText,
+  PreparedTextWithSegments,
+  LayoutResult,
+  LayoutLine,
+  LayoutLineRange,
+  LayoutLinesResult,
+  LayoutCursor,
+} from '@chenglou/pretext';
+
+import type * as pretext from '@chenglou/pretext';
+
+/** The subset of the module surface the hooks in this folder call. */
+export type PretextModule = Pick<
+  typeof pretext,
+  'prepare' | 'prepareWithSegments' | 'layout' | 'layoutWithLines' | 'walkLineRanges'
+>;

package/src/lib/pretext/use-pretext.ts

@@ -6,15 +6,16 @@
 //
 // Powered by Pretext by Cheng Lou — github.com/chenglou/pretext
 //
-// `@chenglou/pretext` is declared as an optionalDependency in
-// `packages/ui-tools/package.json` — consumers that never use BalancedText
-// (or other pretext-based tools) can install ui-tools without it. The
-// `getPretext()` helper uses a CommonJS `require()` so the optional
-// dependency is resolved lazily at first use; if it is missing, the
-// `require` throws at call site, never at module-load.
+// `@chenglou/pretext` is imported statically because it is ESM-only
+// (`"type": "module"`, and its `exports` map offers only an `import`
+// condition). The previous lazy `require('@chenglou/pretext')` could not
+// resolve it in any runtime: under Vite/ESM `require` is not defined at all,
+// so the first render of `BalancedText` threw `require is not defined`
+// rather than degrading gracefully.
 
 'use client';
 
+import * as pretext from '@chenglou/pretext';
 import * as React from 'react';
 import type {
   PreparedText,
@@ -35,13 +36,8 @@ export type {
 
 const isBrowser = typeof window !== 'undefined';
 
-let cachedPretext: PretextModule | null = null;
-
 function getPretext(): PretextModule {
-  if (cachedPretext) return cachedPretext;
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  cachedPretext = require('@chenglou/pretext') as PretextModule;
-  return cachedPretext;
+  return pretext;
 }
 
 const EMPTY_LAYOUT: LayoutResult = { lineCount: 0, height: 0 };

package/src/snippets/LazyComponent.tsx

@@ -7,7 +7,7 @@
 
 'use client';
 
-import React, { Suspense, ReactNode, ComponentType, lazy } from 'react';
+import React, { Suspense, ReactNode, ComponentType, LazyExoticComponent, lazy } from 'react';
 
 // Default loading spinner
 export const DefaultLoader = () => (
@@ -67,13 +67,13 @@ export function LazyWrapper({ children, fallback }: LazyWrapperProps) {
  * <HeavyComponent someProps={value} />
  * ```
  */
-export function createLazyComponent<T extends ComponentType<any>>(
-  importFn: () => Promise<{ default: T }>,
+export function createLazyComponent<P extends object>(
+  importFn: () => Promise<{ default: ComponentType<P> }>,
   fallback?: ReactNode
 ) {
   const LazyComponent = lazy(importFn);
 
-  return function WrappedLazyComponent(props: React.ComponentProps<T>) {
+  return function WrappedLazyComponent(props: P) {
     return (
       <Suspense fallback={fallback ?? <DefaultLoader />}>
         <LazyComponent {...props} />
@@ -95,18 +95,18 @@ export function createLazyComponent<T extends ComponentType<any>>(
  * ```
  */
 export function createLazyNamedComponent<
-  T extends Record<string, ComponentType<any>>,
-  K extends keyof T
+  P extends object,
+  K extends string = string
 >(
-  importFn: () => Promise<T>,
+  importFn: () => Promise<Record<K, ComponentType<P>>>,
   exportName: K,
   fallback?: ReactNode
 ) {
-  const LazyComponent = lazy(() =>
+  const LazyComponent: LazyExoticComponent<ComponentType<P>> = lazy(() =>
     importFn().then((mod) => ({ default: mod[exportName] }))
   );
 
-  return function WrappedLazyComponent(props: React.ComponentProps<T[K]>) {
+  return function WrappedLazyComponent(props: P) {
     return (
       <Suspense fallback={fallback ?? <DefaultLoader />}>
         <LazyComponent {...props} />

package/src/styles/palette/useThemePalette.ts

@@ -101,6 +101,13 @@ export function useThemePalette(): ThemePalette {
   const theme = useResolvedTheme();
 
   return useMemo(() => {
+    // `theme` is read here so the dependency is real to the linter as well as to
+    // us: every getCssColorAsHex call below resolves against the live DOM, whose
+    // values change when the theme flips, but nothing in that call chain
+    // mentions `theme`. Without this read the memo looks free of it and would be
+    // cached across a theme change, returning the previous theme's colors.
+    void theme;
+
     return {
       // Base colors
       background: getCssColorAsHex('background'),