@djangocfg/ui-core 2.1.412 → 2.1.413

package/src/components/select/multi-select-pro-async.tsx

@@ -542,16 +542,25 @@ export const MultiSelectProAsync = React.forwardRef<MultiSelectProAsyncRef, Mult
               </div>
               <div className="flex items-center gap-1 ml-2">
                 {selectedValues.length > 0 && !disabled && (
-                  <button
+                  <span
+                    role="button"
+                    tabIndex={0}
                     onClick={(e) => {
                       e.stopPropagation()
                       handleClearAll()
                     }}
+                    onKeyDown={(e) => {
+                      if (e.key === 'Enter' || e.key === ' ') {
+                        e.preventDefault()
+                        e.stopPropagation()
+                        handleClearAll()
+                      }
+                    }}
                     className="rounded-full hover:bg-muted-foreground/20 focus:outline-none focus:ring-2 focus:ring-ring"
                     aria-label={translations.clearAll}
                   >
                     <XCircle className="h-4 w-4 shrink-0 opacity-50" />
-                  </button>
+                  </span>
                 )}
                 <ChevronsUpDown className="h-4 w-4 shrink-0 opacity-50" />
               </div>

package/src/components/select/multi-select-pro.tsx

@@ -559,16 +559,25 @@ export const MultiSelectPro = React.forwardRef<MultiSelectProRef, MultiSelectPro
               </div>
               <div className="flex items-center gap-1 ml-2">
                 {selectedValues.length > 0 && !disabled && (
-                  <button
+                  <span
+                    role="button"
+                    tabIndex={0}
                     onClick={(e) => {
                       e.stopPropagation()
                       handleClearAll()
                     }}
+                    onKeyDown={(e) => {
+                      if (e.key === 'Enter' || e.key === ' ') {
+                        e.preventDefault()
+                        e.stopPropagation()
+                        handleClearAll()
+                      }
+                    }}
                     className="rounded-full hover:bg-muted-foreground/20 focus:outline-none focus:ring-2 focus:ring-ring"
                     aria-label={translations.clearAll}
                   >
                     <XCircle className="h-4 w-4 shrink-0 opacity-50" />
-                  </button>
+                  </span>
                 )}
                 <ChevronsUpDown className="h-4 w-4 shrink-0 opacity-50" />
               </div>

package/src/components/specialized/presence/index.tsx

@@ -0,0 +1,181 @@
+"use client";
+
+import * as React from "react";
+import { useLayoutEffect } from "../../../hooks/dom/useLayoutEffect";
+import { useStateMachine } from "../../../hooks/state/useStateMachine";
+import { useComposedRefs } from "../../../lib/compose-refs";
+import { getElementRef } from "../../../lib/get-element-ref";
+
+interface PresenceProps {
+  children:
+    | React.ReactElement
+    | ((props: { present: boolean }) => React.ReactElement);
+  present: boolean;
+}
+
+const Presence: React.FC<PresenceProps> = (props) => {
+  const { present, children } = props;
+  const presence = usePresence(present);
+
+  const child = (
+    typeof children === "function"
+      ? children({ present: presence.isPresent })
+      : React.Children.only(children)
+  ) as React.ReactElement<{ ref?: React.Ref<HTMLElement> }>;
+
+  const ref = useComposedRefs(presence.ref, getElementRef(child));
+  const forceMount = typeof children === "function";
+  return forceMount || presence.isPresent
+    ? React.cloneElement(child, { ref })
+    : null;
+};
+
+Presence.displayName = "Presence";
+
+function usePresence(present: boolean) {
+  const [node, setNode] = React.useState<HTMLElement>();
+  const stylesRef = React.useRef<CSSStyleDeclaration>(
+    {} as unknown as CSSStyleDeclaration,
+  );
+  const prevPresentRef = React.useRef(present);
+  const prevAnimationNameRef = React.useRef<string>("none");
+  const initialState = present ? "mounted" : "unmounted";
+  const [state, send] = useStateMachine({
+    initial: initialState,
+    states: {
+      mounted: {
+        UNMOUNT: "unmounted",
+        ANIMATION_OUT: "unmountSuspended",
+      },
+      unmountSuspended: {
+        MOUNT: "mounted",
+        ANIMATION_END: "unmounted",
+      },
+      unmounted: {
+        MOUNT: "mounted",
+      },
+    },
+  });
+
+  React.useEffect(() => {
+    const currentAnimationName = getAnimationName(stylesRef.current);
+    prevAnimationNameRef.current =
+      state === "mounted" ? currentAnimationName : "none";
+  }, [state]);
+
+  useLayoutEffect(() => {
+    const styles = stylesRef.current;
+    const wasPresent = prevPresentRef.current;
+    const hasPresentChanged = wasPresent !== present;
+
+    if (hasPresentChanged) {
+      const prevAnimationName = prevAnimationNameRef.current;
+      const currentAnimationName = getAnimationName(styles);
+
+      if (present) {
+        send("MOUNT");
+      } else if (
+        currentAnimationName === "none" ||
+        styles?.display === "none"
+      ) {
+        // If there is no exit animation or the element is hidden, animations won't run
+        // so we unmount instantly
+        send("UNMOUNT");
+      } else {
+        /**
+         * When `present` changes to `false`, we check changes to animation-name to
+         * determine whether an animation has started. We chose this approach (reading
+         * computed styles) because there is no `animationrun` event and `animationstart`
+         * fires after `animation-delay` has expired which would be too late.
+         */
+        const isAnimating = prevAnimationName !== currentAnimationName;
+
+        if (wasPresent && isAnimating) {
+          send("ANIMATION_OUT");
+        } else {
+          send("UNMOUNT");
+        }
+      }
+
+      prevPresentRef.current = present;
+    }
+  }, [present, send]);
+
+  useLayoutEffect(() => {
+    if (node) {
+      let timeoutId: number;
+      const ownerWindow = node.ownerDocument.defaultView ?? window;
+      /**
+       * Triggering an ANIMATION_OUT during an ANIMATION_IN will fire an `animationcancel`
+       * event for ANIMATION_IN after we have entered `unmountSuspended` state. So, we
+       * make sure we only trigger ANIMATION_END for the currently active animation.
+       */
+      function onAnimationEnd(event: AnimationEvent) {
+        const currentAnimationName = getAnimationName(stylesRef.current);
+        const isCurrentAnimation = currentAnimationName.includes(
+          event.animationName,
+        );
+        if (event.target === node && isCurrentAnimation) {
+          // With React 18 concurrency this update is applied a frame after the
+          // animation ends, creating a flash of visible content. By setting the
+          // animation fill mode to "forwards", we force the node to keep the
+          // styles of the last keyframe, removing the flash.
+          //
+          // Previously we flushed the update via ReactDom.flushSync, but with
+          // exit animations this resulted in the node being removed from the
+          // DOM before the synthetic animationEnd event was dispatched, meaning
+          // user-provided event handlers would not be called.
+          // https://github.com/radix-ui/primitives/pull/1849
+          send("ANIMATION_END");
+          if (!prevPresentRef.current) {
+            const currentFillMode = node.style.animationFillMode;
+            node.style.animationFillMode = "forwards";
+            // Reset the style after the node had time to unmount (for cases
+            // where the component chooses not to unmount). Doing this any
+            // sooner than `setTimeout` (e.g. with `requestAnimationFrame`)
+            // still causes a flash.
+            timeoutId = ownerWindow.setTimeout(() => {
+              if (node.style.animationFillMode === "forwards") {
+                node.style.animationFillMode = currentFillMode;
+              }
+            });
+          }
+        }
+      }
+      function onAnimationStart(event: AnimationEvent) {
+        if (event.target === node) {
+          // if animation occurred, store its name as the previous animation.
+          prevAnimationNameRef.current = getAnimationName(stylesRef.current);
+        }
+      }
+      node.addEventListener("animationstart", onAnimationStart);
+      node.addEventListener("animationcancel", onAnimationEnd);
+      node.addEventListener("animationend", onAnimationEnd);
+      return () => {
+        ownerWindow.clearTimeout(timeoutId);
+        node.removeEventListener("animationstart", onAnimationStart);
+        node.removeEventListener("animationcancel", onAnimationEnd);
+        node.removeEventListener("animationend", onAnimationEnd);
+      };
+    }
+
+    // Transition to the unmounted state if the node is removed prematurely.
+    // We avoid doing so during cleanup as the node may change but still exist.
+    send("ANIMATION_END");
+  }, [node, send]);
+
+  return {
+    isPresent: ["mounted", "unmountSuspended"].includes(state),
+    ref: React.useCallback((node: HTMLElement) => {
+      if (node) stylesRef.current = getComputedStyle(node);
+      setNode(node);
+    }, []),
+  };
+}
+
+function getAnimationName(styles?: CSSStyleDeclaration) {
+  return styles?.animationName ?? "none";
+}
+
+export type { PresenceProps };
+export { Presence };

package/src/components/specialized/primitive/index.tsx

@@ -0,0 +1,83 @@
+"use client";
+
+import * as React from "react";
+import * as ReactDOM from "react-dom";
+import { Slot } from "@radix-ui/react-slot";
+
+type IntrinsicElementsKeys = keyof React.JSX.IntrinsicElements;
+
+type PrimitivePropsWithRef<E extends IntrinsicElementsKeys> = Omit<
+  React.JSX.IntrinsicElements[E],
+  "ref"
+> & {
+  /** Whether to render the wrapped component and merge their props. */
+  asChild?: boolean;
+  ref?: React.Ref<React.ElementRef<E>>;
+};
+
+type PrimitiveForwardRefComponent<E extends IntrinsicElementsKeys> =
+  React.ForwardRefExoticComponent<PrimitivePropsWithRef<E>>;
+
+function createPrimitive<E extends IntrinsicElementsKeys>(
+  element: E,
+): PrimitiveForwardRefComponent<E> {
+  const Primitive = React.forwardRef<
+    React.ElementRef<E>,
+    PrimitivePropsWithRef<E>
+  >((props, forwardedRef) => {
+    const { asChild, ...primitiveProps } = props;
+
+    if (asChild) {
+      return React.createElement(Slot, {
+        ...primitiveProps,
+        ref: forwardedRef as React.Ref<HTMLElement>,
+      });
+    }
+
+    return React.createElement(element, {
+      ...primitiveProps,
+      ref: forwardedRef,
+    });
+  });
+
+  Primitive.displayName = `Primitive.${String(element)}`;
+  return Primitive as PrimitiveForwardRefComponent<E>;
+}
+
+type Primitives = {
+  [E in IntrinsicElementsKeys]: PrimitiveForwardRefComponent<E>;
+};
+
+const cache = new Map<
+  IntrinsicElementsKeys,
+  PrimitiveForwardRefComponent<IntrinsicElementsKeys>
+>();
+
+const Primitive = new Proxy(
+  {},
+  {
+    get: (_, element: PropertyKey) => {
+      const key = element as IntrinsicElementsKeys;
+      if (!cache.has(key)) {
+        cache.set(key, createPrimitive(key));
+      }
+      return cache.get(key);
+    },
+  },
+) as Primitives;
+
+/**
+ * Flush custom event dispatch for React 18 batching
+ * @see https://github.com/facebook/react/blob/a8a4742f1c54493df00da648a3f9d26e3db9c8b5/packages/react-dom/src/events/ReactDOMEventListener.js#L294-L350
+ */
+function dispatchDiscreteCustomEvent<E extends CustomEvent>(
+  target: E["target"],
+  event: E,
+) {
+  if (!target) return;
+
+  ReactDOM.flushSync(() => target.dispatchEvent(event));
+}
+
+export type { PrimitivePropsWithRef };
+export { dispatchDiscreteCustomEvent, Primitive };

package/src/components/specialized/visually-hidden/index.tsx

@@ -0,0 +1,19 @@
+"use client";
+
+import * as React from "react";
+import { visuallyHidden } from "../../../lib/styles";
+
+const VisuallyHidden = React.forwardRef<
+  HTMLSpanElement,
+  React.ComponentPropsWithoutRef<"span">
+>((props, ref) => (
+  <span
+    ref={ref}
+    style={visuallyHidden}
+    {...props}
+  />
+));
+
+VisuallyHidden.displayName = "VisuallyHidden";
+
+export { VisuallyHidden };

package/src/components/specialized/visually-hidden-input/index.tsx

@@ -0,0 +1,99 @@
+"use client";
+
+import * as React from "react";
+import { usePrevious } from "../../../hooks/state/usePrevious";
+import { useSize } from "../../../hooks/dom/useSize";
+import { useFormReset } from "../../../hooks/dom/useFormReset";
+import { visuallyHidden } from "../../../lib/styles";
+
+type InputValue = string[] | string;
+
+interface VisuallyHiddenInputProps<T = InputValue>
+  extends Omit<
+    React.InputHTMLAttributes<HTMLInputElement>,
+    "value" | "checked" | "onReset"
+  > {
+  value?: T;
+  checked?: boolean;
+  control: HTMLElement | null;
+  bubbles?: boolean;
+  onReset?: (value: T) => void;
+}
+
+function VisuallyHiddenInput<T = InputValue>(
+  props: VisuallyHiddenInputProps<T>,
+) {
+  const {
+    control,
+    value,
+    checked,
+    bubbles = true,
+    type = "hidden",
+    onReset,
+    style,
+    ...inputProps
+  } = props;
+
+  const isCheckInput =
+    type === "checkbox" || type === "radio" || type === "switch";
+  const inputRef = React.useRef<HTMLInputElement>(null);
+  const prevValue = usePrevious(type === "hidden" ? value : checked);
+  const controlSize = useSize(control);
+
+  // Bubble value/checked change to parents
+  React.useEffect(() => {
+    const input = inputRef.current;
+    if (!input) return;
+    const inputProto = window.HTMLInputElement.prototype;
+
+    const propertyKey = isCheckInput ? "checked" : "value";
+    const eventType = isCheckInput ? "click" : "input";
+    const currentValue = isCheckInput ? checked : JSON.stringify(value);
+
+    const descriptor = Object.getOwnPropertyDescriptor(
+      inputProto,
+      propertyKey,
+    ) as PropertyDescriptor;
+    const setter = descriptor.set;
+
+    if (prevValue !== currentValue && setter) {
+      const event = new Event(eventType, { bubbles });
+      setter.call(input, currentValue);
+      input.dispatchEvent(event);
+    }
+  }, [prevValue, value, checked, bubbles, isCheckInput]);
+
+  // Trigger on onReset callback when form is reset
+  useFormReset({
+    form: inputRef.current?.form ?? null,
+    defaultValue: isCheckInput ? (checked as T) : value,
+    onReset: (resetValue: T) => {
+      onReset?.(resetValue);
+    },
+  });
+
+  const composedStyle = React.useMemo<React.CSSProperties>(() => {
+    return {
+      ...style,
+      ...(controlSize?.width !== undefined && controlSize?.height !== undefined
+        ? controlSize
+        : {}),
+      ...visuallyHidden,
+    };
+  }, [style, controlSize]);
+
+  return (
+    <input
+      type={type}
+      {...inputProps}
+      ref={inputRef}
+      aria-hidden={isCheckInput}
+      tabIndex={-1}
+      defaultChecked={isCheckInput ? checked : undefined}
+      style={composedStyle}
+    />
+  );
+}
+
+export type { VisuallyHiddenInputProps, InputValue };
+export { VisuallyHiddenInput };

package/src/hooks/dom/index.ts

@@ -10,3 +10,7 @@ export {
   useIsScrolling,
 } from './useScroll';
 export type { ScrollSnapshot, ScrollDirection, ScrollTarget } from './useScroll';
+export { useLayoutEffect } from './useLayoutEffect';
+export { useSize } from './useSize';
+export { useFormReset } from './useFormReset';
+export type { UseFormResetParams } from './useFormReset';

package/src/hooks/dom/useFormReset.ts

@@ -0,0 +1,49 @@
+"use client";
+
+import * as React from "react";
+import { useCallbackRef } from "../state/useCallbackRef";
+
+interface UseFormResetParams<T> {
+  /**
+   * The form element to attach reset handler to.
+   */
+  form?: HTMLFormElement | null;
+
+  /**
+   * The default value to reset to.
+   */
+  defaultValue?: T;
+
+  /**
+   * Callback fired when form is reset.
+   */
+  onReset?: (value: T) => void;
+}
+
+/**
+ * A hook to handle form reset events.
+ * Can be triggered by onReset callback or by form reset event.
+ */
+function useFormReset<T>({
+  form,
+  defaultValue,
+  onReset,
+}: UseFormResetParams<T>) {
+  const onResetCallback = useCallbackRef(onReset);
+
+  React.useEffect(() => {
+    if (!form) return;
+
+    function onFormReset() {
+      if (defaultValue !== undefined) {
+        onResetCallback?.(defaultValue);
+      }
+    }
+
+    form.addEventListener("reset", onFormReset);
+    return () => form.removeEventListener("reset", onFormReset);
+  }, [form, defaultValue, onResetCallback]);
+}
+
+export { useFormReset };
+export type { UseFormResetParams };

package/src/hooks/dom/useLayoutEffect.ts

@@ -0,0 +1,16 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * On the server, React emits a warning when calling `useLayoutEffect`.
+ * This is because neither `useLayoutEffect` nor `useEffect` run on the server.
+ * We use this safe version which suppresses the warning by replacing it with a noop on the server.
+ *
+ * @see https://react.dev/reference/react/useLayoutEffect
+ */
+const useLayoutEffect = globalThis?.document
+  ? React.useLayoutEffect
+  : () => {};
+
+export { useLayoutEffect };

package/src/hooks/dom/useSize.ts

@@ -0,0 +1,57 @@
+"use client";
+
+import * as React from "react";
+import { useLayoutEffect } from "./useLayoutEffect";
+
+function useSize(element: HTMLElement | null) {
+  const [size, setSize] = React.useState<
+    { width: number; height: number } | undefined
+  >(undefined);
+
+  useLayoutEffect(() => {
+    if (element) {
+      // Provide size as early as possible
+      setSize({ width: element.offsetWidth, height: element.offsetHeight });
+
+      const resizeObserver = new ResizeObserver((entries) => {
+        if (!Array.isArray(entries)) return;
+
+        // Since we only observe the one element, we don't need to loop over the array
+        if (!entries.length) return;
+
+        const entry = entries[0];
+        let width: number;
+        let height: number;
+
+        if (entry && "borderBoxSize" in entry) {
+          const borderSizeEntry = entry.borderBoxSize;
+          // iron out differences between browsers
+          const borderSize = Array.isArray(borderSizeEntry)
+            ? borderSizeEntry[0]
+            : borderSizeEntry;
+          width = borderSize.inlineSize;
+          height = borderSize.blockSize;
+        } else {
+          // For browsers that don't support `borderBoxSize`
+          // we calculate it ourselves to get the correct border box.
+          width = element.offsetWidth;
+          height = element.offsetHeight;
+        }
+
+        setSize({ width, height });
+      });
+
+      resizeObserver.observe(element, { box: "border-box" });
+
+      return () => resizeObserver.unobserve(element);
+    }
+
+    // We only want to reset to `undefined` when the element becomes `null`,
+    // not if it changes to another element.
+    setSize(undefined);
+  }, [element]);
+
+  return size;
+}
+
+export { useSize };

package/src/hooks/state/index.ts

@@ -15,3 +15,7 @@ export type {
   UseStoredValueReturn,
   StorageType,
 } from './useStoredValue';
+export { useStateMachine } from './useStateMachine';
+export type { StateMachineConfig } from './useStateMachine';
+export { useCallbackRef } from './useCallbackRef';
+export { usePrevious } from './usePrevious';

package/src/hooks/state/useCallbackRef.ts

@@ -0,0 +1,25 @@
+"use client";
+
+import * as React from "react";
+
+/**
+ * A custom hook that converts a callback to a ref to avoid triggering re-renders when passed as a
+ * prop or avoid re-executing effects when passed as a dependency
+ */
+function useCallbackRef<T extends (...args: never[]) => unknown>(
+  callback: T | undefined,
+): T {
+  const callbackRef = React.useRef(callback);
+
+  React.useEffect(() => {
+    callbackRef.current = callback;
+  });
+
+  // https://github.com/facebook/react/issues/19240
+  return React.useMemo(
+    () => ((...args) => callbackRef.current?.(...args)) as T,
+    [],
+  );
+}
+
+export { useCallbackRef };

package/src/hooks/state/usePrevious.ts

@@ -0,0 +1,20 @@
+"use client";
+
+import * as React from "react";
+
+function usePrevious<T>(value: T) {
+  const ref = React.useRef({ value, previous: value });
+
+  // We compare values before making an update to ensure that
+  // a change has been made. This ensures the previous value is
+  // persisted correctly between renders.
+  return React.useMemo(() => {
+    if (ref.current.value !== value) {
+      ref.current.previous = ref.current.value;
+      ref.current.value = value;
+    }
+    return ref.current.previous;
+  }, [value]);
+}
+
+export { usePrevious };

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 };