@djangocfg/ui-core 2.1.411 → 2.1.413

package/src/hooks/state/useStateMachine.ts

@@ -0,0 +1,29 @@
+"use client";
+
+import * as React from "react";
+
+interface StateMachineConfig<TState extends string, TEvent extends string> {
+  initial: TState;
+  states: Record<TState, Partial<Record<TEvent, TState>>>;
+}
+
+function useStateMachine<TState extends string, TEvent extends string>(
+  config: StateMachineConfig<TState, TEvent>,
+) {
+  const [state, setState] = React.useState<TState>(config.initial);
+
+  const send = React.useCallback(
+    (event: TEvent) => {
+      setState((currentState) => {
+        const transition = config.states[currentState]?.[event];
+        return transition ?? currentState;
+      });
+    },
+    [config.states],
+  );
+
+  return [state, send] as const;
+}
+
+export { useStateMachine };
+export type { StateMachineConfig };

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

@@ -0,0 +1,22 @@
+"use client";
+
+function composeEventHandlers<E>(
+  originalEventHandler?: (event: E) => void,
+  ourEventHandler?: (event: E) => void,
+  { checkForDefaultPrevented = true } = {},
+) {
+  return function handleEvent(event: E) {
+    originalEventHandler?.(event);
+
+    if (
+      checkForDefaultPrevented &&
+      (event as unknown as Event).defaultPrevented
+    ) {
+      return;
+    }
+
+    ourEventHandler?.(event);
+  };
+}
+
+export { composeEventHandlers };

package/src/lib/compose-refs.ts

@@ -0,0 +1,65 @@
+"use client";
+
+import * as React from "react";
+
+type PossibleRef<T> = React.Ref<T> | undefined;
+
+/**
+ * Set a given ref to a given value.
+ * This utility takes care of different types of refs: callback refs and RefObject(s).
+ */
+function setRef<T>(ref: PossibleRef<T>, value: T) {
+  if (typeof ref === "function") {
+    return ref(value);
+  }
+
+  if (ref !== null && ref !== undefined) {
+    ref.current = value;
+  }
+}
+
+/**
+ * A utility to compose multiple refs together.
+ * Accepts callback refs and RefObject(s).
+ */
+function composeRefs<T>(...refs: PossibleRef<T>[]): React.RefCallback<T> {
+  return (node) => {
+    let hasCleanup = false;
+    const cleanups = refs.map((ref) => {
+      const cleanup = setRef(ref, node);
+      if (!hasCleanup && typeof cleanup === "function") {
+        hasCleanup = true;
+      }
+      return cleanup;
+    });
+
+    // React <19 will log an error to the console if a callback ref returns a
+    // value. We don't use ref cleanups internally so this will only happen if a
+    // user's ref callback returns a value, which we only expect if they are
+    // using the cleanup functionality added in React 19.
+    if (hasCleanup) {
+      return () => {
+        for (let i = 0; i < cleanups.length; i++) {
+          const cleanup = cleanups[i];
+          if (typeof cleanup === "function") {
+            cleanup();
+          } else {
+            setRef(refs[i], null);
+          }
+        }
+      };
+    }
+  };
+}
+
+/**
+ * A custom hook that composes multiple refs.
+ * Accepts callback refs and RefObject(s).
+ */
+function useComposedRefs<T>(...refs: PossibleRef<T>[]): React.RefCallback<T> {
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  return React.useCallback(composeRefs(...refs), refs);
+}
+
+export { composeRefs, useComposedRefs };
+export type { PossibleRef };

package/src/lib/create-context.tsx

@@ -0,0 +1,62 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * Creates a type-safe context and provider with automatic error handling
+ * @template T The type of the context value
+ * @param name The name of the root component for error messages
+ * @param defaultValue Optional default value for the context
+ */
+function createContext<T extends object | null>(
+  rootComponentName: string,
+  defaultValue?: T,
+) {
+  const Context = React.createContext<T | undefined>(defaultValue);
+  Context.displayName = rootComponentName;
+
+  function Provider(props: T & { children: React.ReactNode }) {
+    const { children, ...contextValue } = props;
+
+    // Memoize the context value by its values
+    const value = React.useMemo(
+      () => contextValue,
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      Object.values(contextValue),
+    ) as T;
+
+    return <Context.Provider value={value}>{children}</Context.Provider>;
+  }
+
+  Provider.displayName = `${rootComponentName}Provider`;
+
+  type ContextReturn<Optional extends boolean> = Optional extends true
+    ? T | undefined
+    : T;
+
+  /**
+   * @param consumerName The name of the component that is consuming the context
+   * @param optional Whether the context is optional (defaults to false)
+   */
+  function useContext<Optional extends boolean = false>(
+    consumerName: string,
+    optional?: Optional,
+  ): ContextReturn<Optional> {
+    const context = React.useContext(Context);
+
+    if (!context && !optional) {
+      throw new Error(
+        `\`${consumerName}\` must be used within \`${rootComponentName}\``,
+      );
+    }
+
+    if (context) return context;
+    if (defaultValue !== undefined) return defaultValue;
+
+    return undefined as ContextReturn<Optional>;
+  }
+
+  return [Provider, useContext] as const;
+}
+
+export { createContext };

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

@@ -0,0 +1,33 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * Get the ref from a React element without throwing warnings.
+ */
+function getElementRef(element: React.ReactElement) {
+  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;
+  }
+
+  // React 19 in DEV
+  getter = Object.getOwnPropertyDescriptor(element, "ref")?.get;
+  mayWarn = getter && "isReactWarning" in getter && getter.isReactWarning;
+  if (mayWarn) {
+    return (element.props as { ref?: React.Ref<unknown> }).ref;
+  }
+
+  // Not DEV
+  return (
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (element.props as { ref?: React.Ref<unknown> }).ref || (element as any).ref
+  );
+}
+
+export { getElementRef };

package/src/lib/index.ts

@@ -10,3 +10,8 @@ export type {
   CustomJsonUiGroup,
   CustomJsonUiDisabledWhenRule,
 } from "./configurator-schema";
+export * from "./styles";
+export * from "./compose-refs";
+export * from "./get-element-ref";
+export * from "./compose-event-handlers";
+export { createContext } from "./create-context";

package/src/lib/styles.ts

@@ -0,0 +1,103 @@
+import type * as React from "react";
+
+/**
+ * CSS style object that visually hides content while keeping it accessible to screen readers.
+ * This follows accessibility best practices for visually hidden content.
+ */
+const visuallyHidden: React.CSSProperties = {
+  border: 0,
+  clip: "rect(0 0 0 0)",
+  clipPath: "inset(50%)",
+  height: "1px",
+  margin: "-1px",
+  overflow: "hidden",
+  padding: 0,
+  position: "absolute",
+  whiteSpace: "nowrap",
+  width: "1px",
+} as const;
+
+/**
+ * CSS style object for a full-screen overlay backdrop.
+ * Useful for modals, dialogs, and other overlay components.
+ */
+const overlay: React.CSSProperties = {
+  position: "fixed",
+  inset: 0,
+  backgroundColor: "rgba(0, 0, 0, 0.4)",
+  backdropFilter: "blur(2px)",
+  zIndex: 50,
+} as const;
+
+/**
+ * CSS style object for text truncation with ellipsis.
+ * Ensures text fits within its container.
+ */
+const truncate: React.CSSProperties = {
+  overflow: "hidden",
+  textOverflow: "ellipsis",
+  whiteSpace: "nowrap",
+} as const;
+
+/**
+ * CSS style object for a custom focus ring style.
+ * Provides a consistent, accessible focus indicator.
+ */
+const focusRing: React.CSSProperties = {
+  outline: "none",
+  boxShadow: "0 0 0 2px rgba(66, 153, 225, 0.6)",
+  borderRadius: "0.25rem",
+} as const;
+
+/**
+ * CSS style object to create a scrollable container that hides scrollbars.
+ * Note: For webkit browsers, you'll need to add additional CSS for ::-webkit-scrollbar
+ */
+const scrollableHidden: React.CSSProperties = {
+  overflow: "auto",
+  scrollbarWidth: "none",
+  msOverflowStyle: "none",
+} as const;
+
+/**
+ * CSS style object for absolutely positioning an element to fill its container.
+ * Useful for overlays, backgrounds, and full-size children.
+ */
+const fullSize: React.CSSProperties = {
+  position: "absolute",
+  top: 0,
+  right: 0,
+  bottom: 0,
+  left: 0,
+} as const;
+
+/**
+ * CSS style object for centering content both vertically and horizontally.
+ * Uses flexbox for better browser support.
+ */
+const center: React.CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "center",
+} as const;
+
+/**
+ * CSS style object to prevent text selection.
+ * Useful for interactive elements like buttons.
+ */
+const noSelect: React.CSSProperties = {
+  userSelect: "none",
+  WebkitUserSelect: "none",
+  msUserSelect: "none",
+} as const;
+
+export {
+  center,
+  focusRing,
+  fullSize,
+  noSelect,
+  overlay,
+  scrollableHidden,
+  truncate,
+  visuallyHidden,
+};

package/src/styles/README.md

@@ -175,6 +175,49 @@ In your consuming app's `globals.css`:
 
 Tailwind v4 doesn't scan across npm packages automatically. Each consumer needs either a `@source` directive or to import a `sources.css` from the package — `@djangocfg/ui-core/styles` already chains its own `sources.css`, so importing `…/styles` is enough.
 
+### Wiring a custom display font (consumer recipe)
+
+`ui-core` ships `.font-display` and a display type ramp (`.text-display-xl` / `.text-display-lg` / `.text-display`) that read from a `--font-display` CSS variable. The variable itself is **not** set — apps pick the font.
+
+In a Next.js app with `next/font`:
+
+```tsx
+// app/layout.tsx
+import { Plus_Jakarta_Sans } from 'next/font/google';
+
+const display = Plus_Jakarta_Sans({
+  subsets: ['latin'],
+  weight: ['700', '800'],
+  variable: '--font-display',  // exposes as CSS var
+  display: 'swap',
+});
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" className={display.variable}>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+Then in `globals.css` register it as a Tailwind token so the `font-display` utility class works:
+
+```css
+@theme {
+  --font-display: var(--font-display), ui-sans-serif, system-ui, sans-serif;
+}
+```
+
+Now any of these work:
+
+```tsx
+<h1 className="text-7xl text-display-xl">Hero title</h1>
+<h2 className="text-4xl text-display-lg">Section title</h2>
+<h3 className="text-xl text-display">Card title</h3>
+<span className="font-display">Plain display family</span>
+```
+
 ## Theme Showcase story
 
 The `UI Core/Theme Showcase` story in djangocfg storybook renders every base token, status surface, button variant, card, form control, glass utility, and opacity sanity-check on one page. Switch the `preset` control to flip across all 8 themes; flip light/dark from the toolbar.

package/src/styles/palette/utils.ts

@@ -4,15 +4,25 @@
  */
 
 /**
- * Parse HSL string from CSS variable (e.g., "192 90% 35%" for light `--primary`) to components
+ * Parse HSL string from CSS variable to components.
+ * Accepts either the raw triplet form `"192 90% 35%"` or the wrapped
+ * form `"hsl(192 90% 35%)"` / `"hsl(192, 90%, 35%)"`. `getComputedStyle`
+ * returns the wrapped form when the CSS variable is declared as
+ * `--primary: hsl(...)` rather than `--primary: 192 90% 35%`.
  */
 function parseHslString(hsl: string): { h: number; s: number; l: number } | null {
-  const match = hsl.trim().match(/^(\d+)\s+(\d+)%\s+(\d+)%$/);
+  const stripped = hsl
+    .trim()
+    .replace(/^hsla?\(/i, '')
+    .replace(/\)$/, '')
+    .replace(/,/g, ' ')
+    .replace(/\s*\/\s*[\d.]+%?$/, ''); // drop optional `/ alpha`
+  const match = stripped.match(/^(-?\d+(?:\.\d+)?)\s+(\d+(?:\.\d+)?)%\s+(\d+(?:\.\d+)?)%$/);
   if (!match) return null;
   return {
-    h: parseInt(match[1], 10),
-    s: parseInt(match[2], 10),
-    l: parseInt(match[3], 10),
+    h: parseFloat(match[1]),
+    s: parseFloat(match[2]),
+    l: parseFloat(match[3]),
   };
 }
 

package/src/styles/utilities/animations.css

@@ -0,0 +1,135 @@
+/* ============================================================================
+ * MultiSelectPro Animation Classes
+ * ============================================================================ */
+
+@keyframes wiggle {
+  0%, 100% { transform: rotate(-3deg); }
+  50% { transform: rotate(3deg); }
+}
+
+.animate-wiggle {
+  animation: wiggle 0.5s ease-in-out;
+}
+
+@keyframes fadeIn {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+.animate-fadeIn {
+  animation: fadeIn 0.3s ease-in-out;
+}
+
+@keyframes slideIn {
+  from {
+    opacity: 0;
+    transform: translateY(-10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.animate-slideIn {
+  animation: slideIn 0.3s ease-out;
+}
+
+@keyframes scaleIn {
+  from {
+    opacity: 0;
+    transform: scale(0.95);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+
+.animate-scaleIn {
+  animation: scaleIn 0.2s ease-out;
+}
+
+@keyframes scaleOut {
+  from {
+    opacity: 1;
+    transform: scale(1);
+  }
+  to {
+    opacity: 0;
+    transform: scale(0.95);
+  }
+}
+
+.animate-scaleOut {
+  animation: scaleOut 0.2s ease-in;
+}
+
+@keyframes slideDown {
+  from {
+    opacity: 0;
+    transform: translateY(-10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.animate-slideDown {
+  animation: slideDown 0.3s ease-out;
+}
+
+@keyframes slideUp {
+  from {
+    opacity: 1;
+    transform: translateY(0);
+  }
+  to {
+    opacity: 0;
+    transform: translateY(-10px);
+  }
+}
+
+.animate-slideUp {
+  animation: slideUp 0.3s ease-in;
+}
+
+@keyframes fadeOut {
+  from { opacity: 1; }
+  to { opacity: 0; }
+}
+
+.animate-fadeOut {
+  animation: fadeOut 0.2s ease-in;
+}
+
+@keyframes flipIn {
+  from {
+    opacity: 0;
+    transform: rotateX(-90deg);
+  }
+  to {
+    opacity: 1;
+    transform: rotateX(0);
+  }
+}
+
+.animate-flipIn {
+  animation: flipIn 0.3s ease-out;
+}
+
+@keyframes flipOut {
+  from {
+    opacity: 1;
+    transform: rotateX(0);
+  }
+  to {
+    opacity: 0;
+    transform: rotateX(90deg);
+  }
+}
+
+.animate-flipOut {
+  animation: flipOut 0.3s ease-in;
+}

package/src/styles/utilities/display.css

@@ -0,0 +1,62 @@
+/**
+ * Display font utility — for marketing headlines and large numeric stats.
+ *
+ * The font itself is NOT shipped here. Apps pick their own display font and
+ * expose it as `--font-display` on <html> (via `next/font`, `@font-face`, or
+ * equivalent). If the variable is missing, falls back to the system UI stack.
+ */
+.font-display {
+  font-family: var(--font-display), system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+  font-feature-settings: 'ss01', 'ss03';
+  letter-spacing: -0.035em;
+  padding-bottom: 0.08em;
+}
+
+/**
+ * Display type ramp — opinionated headline presets that pair with
+ * `--font-display`. Use these instead of `.font-display` when you also
+ * want a tuned weight + tracking + line-height + balanced wrapping for
+ * a specific role:
+ *
+ *   .text-display-xl   hero (text-5xl / 6xl / 7xl)        — 800, very tight
+ *   .text-display-lg   section title (text-3xl / 4xl)     — 800, tight
+ *   .text-display      card / feature title (text-lg / xl) — 700, mild
+ *
+ * Size is intentionally NOT set here — pair with Tailwind `text-*`.
+ */
+.text-display-xl {
+  font-family: var(--font-display), system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+  font-weight: 800;
+  letter-spacing: -0.035em;
+  line-height: 1.02;
+  text-wrap: balance;
+}
+.text-display-lg {
+  font-family: var(--font-display), system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+  font-weight: 800;
+  letter-spacing: -0.025em;
+  line-height: 1.05;
+  text-wrap: balance;
+}
+.text-display {
+  font-family: var(--font-display), system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+  font-weight: 700;
+  letter-spacing: -0.015em;
+  line-height: 1.1;
+}
+
+/**
+ * Screen Reader Only
+ * Hides content visually but keeps it accessible to screen readers
+ */
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border-width: 0;
+}

package/src/styles/utilities/glass.css

@@ -0,0 +1,57 @@
+/**
+ * Glass surface utilities — OS-native translucency effects.
+ * Apply to panels/sidebars that sit over a blurred background.
+ * Requires `isolation: isolate` and a background image/color on a parent.
+ */
+
+/**
+ * macOS Vibrancy / Liquid Glass — strong blur + high saturation over a
+ * 72% translucent base. The blur+saturate combo is the Apple-standard
+ * recipe (Sequoia / Tahoe 26 use the same values). 72% opacity keeps
+ * enough background bleed-through to read content underneath.
+ *
+ * Use on: sidebars, popovers, sheet headers, command palette overlays.
+ * Requires: container parent must be non-transparent (otherwise nothing
+ * to blur). Avoid stacking multiple `.glass-macos` — blur compounds.
+ */
+.glass-macos {
+  backdrop-filter: blur(20px) saturate(180%);
+  -webkit-backdrop-filter: blur(20px) saturate(180%);
+  background-color: color-mix(in oklab, var(--background) 72%, transparent);
+}
+
+/**
+ * Windows 11 Mica / Acrylic — wider/softer blur over an 85% base.
+ * Mica = wallpaper-tinted material; Acrylic = stronger blur on top.
+ * This recipe targets Acrylic (the closer-to-Apple flavour).
+ */
+.glass-win11 {
+  backdrop-filter: blur(60px) saturate(125%);
+  -webkit-backdrop-filter: blur(60px) saturate(125%);
+  background-color: color-mix(in oklab, var(--background) 85%, transparent);
+}
+
+/**
+ * Liquid Glass variants — Apple's macOS 26 / iOS 26 design language.
+ * Thinner blur, brighter base, subtle inner highlight via box-shadow.
+ * Designed for floating chrome (Dock, navbar, FAB chips).
+ */
+.glass-liquid {
+  backdrop-filter: blur(12px) saturate(180%);
+  -webkit-backdrop-filter: blur(12px) saturate(180%);
+  background-color: color-mix(in oklab, var(--card) 60%, transparent);
+  border: 1px solid color-mix(in oklab, var(--foreground) 8%, transparent);
+  box-shadow:
+    0 8px 32px color-mix(in oklab, var(--foreground) 12%, transparent),
+    inset 0 1px 0 color-mix(in oklab, var(--foreground) 6%, transparent);
+}
+
+/**
+ * Lighter glass for headers / status bars where strong blur would be
+ * too heavy. 8px blur is the macOS NavBar / TitleBar default.
+ */
+.glass-header {
+  backdrop-filter: blur(8px) saturate(160%);
+  -webkit-backdrop-filter: blur(8px) saturate(160%);
+  background-color: color-mix(in oklab, var(--background) 80%, transparent);
+}