@sixthshift/design-system 0.5.0 → 0.7.0

package/src/components/FormField/FormField.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { Label } from "@sixthshift/design-system/label";
 import { Message } from "@sixthshift/design-system/message";
 import { Muted } from "@sixthshift/design-system/muted";
@@ -10,61 +12,111 @@ export type FormFieldFeedback = {
 };
 
 export type FormFieldProps = React.HTMLAttributes<HTMLDivElement> & {
-  label: string;
-  description?: string;
+  label: React.ReactNode;
+  description?: React.ReactNode;
   feedback?: FormFieldFeedback;
   required?: boolean;
 };
 
+/** What FormField knows about the control it wraps — see `useFormField`. */
+export type FormFieldContextValue = {
+  /** The id the control should carry, and the label's `htmlFor` target. */
+  id: string;
+  /** Space-separated ids of the description/feedback texts, for `aria-describedby`. `undefined` when there are none. */
+  describedBy: string | undefined;
+  /** True when `feedback.intent` is `"danger"` — the control should set `aria-invalid`. */
+  invalid: boolean;
+  /** Mirrors the `required` prop, for `aria-required`/`required` on the control. */
+  required: boolean;
+};
+
+const FormFieldContext = React.createContext<FormFieldContextValue | null>(null);
+
+/**
+ * The wiring `FormField` provides to whatever control it wraps: `id`,
+ * `describedBy`, `invalid`, `required`. Direct element children get these
+ * cloned on automatically; a control nested deeper — inside a wrapper div, a
+ * render prop, a custom composite — can call this instead and apply them
+ * itself. Returns `null` outside a `FormField`.
+ */
+export const useFormField = () => React.useContext(FormFieldContext);
+
 /**
  * Wraps a form control with a label, optional description, and optional
  * validation feedback — the composition point for `Input`, `Textarea`,
  * `Select` and similar controls inside a form.
  *
- * Generates an `id` (or uses the one passed in) and clones it, plus
- * `aria-describedby` (pointing at the description and/or feedback text) and
- * `aria-invalid` (when `feedback.intent` is `"danger"`), onto its child —
- * so the wrapped control does not need those wired by hand. It expects a
- * single child control: the same id and aria attributes get cloned onto
- * every child if more than one is passed.
+ * Generates an `id` (or uses the one passed in) and wires it, plus
+ * `aria-describedby` (pointing at the description and/or feedback text),
+ * `aria-invalid` (when `feedback.intent` is `"danger"`) and `aria-required`
+ * (when `required`), onto the first element child. A child's own attributes
+ * win: an explicit `id` is kept (and becomes the label's `htmlFor` target),
+ * an existing `aria-describedby` is merged with FormField's rather than
+ * replaced. Controls that aren't the first element child can self-wire via
+ * `useFormField`.
  *
  * Distinct from `Field`, which displays a read-only label/value pair rather
  * than wrapping an interactive control.
  */
-const FormField = React.forwardRef<HTMLDivElement, FormFieldProps>(({ className, label, description, feedback, required, children, id, ...props }, ref) => {
-  const generatedId = React.useId();
-  const fieldId = id ?? generatedId;
-  const descriptionId = description ? `${fieldId}-description` : undefined;
-  const feedbackId = feedback ? `${fieldId}-feedback` : undefined;
-
-  return (
-    <div ref={ref} className={cn("flex flex-col gap-1.5", className)} {...props}>
-      <Label htmlFor={fieldId}>
-        {label}
-        {required && <span className="ml-0.5 text-fg-danger">*</span>}
-      </Label>
-
-      {description && <Muted id={descriptionId}>{description}</Muted>}
-
-      {React.Children.map(children, (child) => {
-        if (React.isValidElement(child)) {
-          return React.cloneElement(child, {
-            id: fieldId,
-            "aria-describedby": cn(descriptionId, feedbackId) || undefined,
-            "aria-invalid": feedback?.intent === "danger" ? true : undefined,
-          } as React.HTMLAttributes<HTMLElement>);
-        }
-        return child;
-      })}
-
-      {feedback && (
-        <Message id={feedbackId} intent={feedback.intent} size="sm">
-          {feedback.message}
-        </Message>
-      )}
-    </div>
-  );
-});
+const FormField = React.forwardRef<HTMLDivElement, FormFieldProps>(
+  ({ className, label, description, feedback, required = false, children, id, ...props }, ref) => {
+    const generatedId = React.useId();
+    const fieldId = id ?? generatedId;
+
+    // The label must point at the id the control actually carries: when the
+    // (first element) child brings its own id, that id wins over ours.
+    const childArray = React.Children.toArray(children);
+    const firstElementIndex = childArray.findIndex((child) => React.isValidElement(child));
+    const firstElement = firstElementIndex === -1 ? null : (childArray[firstElementIndex] as React.ReactElement<React.HTMLAttributes<HTMLElement>>);
+    const controlId = firstElement?.props.id ?? fieldId;
+
+    const descriptionId = description ? `${fieldId}-description` : undefined;
+    const feedbackId = feedback ? `${fieldId}-feedback` : undefined;
+    const invalid = feedback?.intent === "danger";
+
+    const contextValue = React.useMemo<FormFieldContextValue>(
+      () => ({
+        id: controlId,
+        describedBy: cn(descriptionId, feedbackId) || undefined,
+        invalid,
+        required,
+      }),
+      [controlId, descriptionId, feedbackId, invalid, required]
+    );
+
+    const wiredChildren = childArray.map((child, index) => {
+      if (index !== firstElementIndex || !React.isValidElement(child)) return child;
+      const childProps = child.props as React.HTMLAttributes<HTMLElement>;
+      return React.cloneElement(child, {
+        id: controlId,
+        // The child's own describedby (a tooltip, an external hint) is kept and
+        // FormField's ids are appended, rather than overwritten.
+        "aria-describedby": cn(childProps["aria-describedby"], descriptionId, feedbackId) || undefined,
+        "aria-invalid": childProps["aria-invalid"] ?? (invalid ? true : undefined),
+        "aria-required": childProps["aria-required"] ?? (required ? true : undefined),
+      } as React.HTMLAttributes<HTMLElement>);
+    });
+
+    return (
+      <div ref={ref} className={cn("flex flex-col gap-1.5", className)} {...props}>
+        <Label htmlFor={controlId}>
+          {label}
+          {required && <span className="ml-0.5 text-fg-danger">*</span>}
+        </Label>
+
+        {description && <Muted id={descriptionId}>{description}</Muted>}
+
+        <FormFieldContext.Provider value={contextValue}>{wiredChildren}</FormFieldContext.Provider>
+
+        {feedback && (
+          <Message id={feedbackId} intent={feedback.intent} size="sm">
+            {feedback.message}
+          </Message>
+        )}
+      </div>
+    );
+  }
+);
 FormField.displayName = "FormField";
 
 export { FormField };

package/src/components/FormField/index.ts

@@ -1,2 +1,2 @@
-export type { FormFieldFeedback, FormFieldProps } from "./FormField";
-export { FormField } from "./FormField";
+export type { FormFieldContextValue, FormFieldFeedback, FormFieldProps } from "./FormField";
+export { FormField, useFormField } from "./FormField";

package/src/components/HoverCard/HoverCard.tsx

@@ -1,6 +1,9 @@
+"use client";
+
 import { autoUpdate, flip, offset, type Placement, safePolygon, shift, useDismiss, useFloating, useFocus, useHover, useInteractions } from "@floating-ui/react";
 import { useControllableState } from "@sixthshift/design-system/hooks";
 import type * as React from "react";
+import { closestBrand } from "../../internal/brandScope";
 import { HoverCardContent } from "./components/HoverCardContent";
 import { HoverCardContext } from "./components/HoverCardContext";
 import { HoverCardTrigger } from "./components/HoverCardTrigger";
@@ -65,6 +68,8 @@ const HoverCardRoot = ({
       setFloating: refs.setFloating,
     },
     floatingStyles,
+    // Read at render: `domReference` is state, so this updates once the trigger mounts.
+    inheritedBrand: closestBrand(context.elements.domReference),
     getReferenceProps,
     getFloatingProps,
   };

package/src/components/HoverCard/components/HoverCardContent.tsx

@@ -1,12 +1,21 @@
+"use client";
+
 import { FloatingPortal } from "@floating-ui/react";
 import { cn } from "@sixthshift/design-system/utils";
 import * as React from "react";
 import { useHoverCardContext } from "./HoverCardContext";
 
-export type HoverCardContentProps = React.HTMLAttributes<HTMLDivElement>;
+export type HoverCardContentProps = React.HTMLAttributes<HTMLDivElement> & {
+  /**
+   * Name of a brand the theme defines, rendered as `data-brand`. Omitted, the
+   * body copies the brand scope of its trigger, which the portal would
+   * otherwise leave behind.
+   */
+  brand?: string | undefined;
+};
 
-export const HoverCardContent = React.forwardRef<HTMLDivElement, HoverCardContentProps>(({ className, children, ...props }, forwardedRef) => {
-  const { open, refs, floatingStyles, getFloatingProps } = useHoverCardContext();
+export const HoverCardContent = React.forwardRef<HTMLDivElement, HoverCardContentProps>(({ className, brand, children, ...props }, forwardedRef) => {
+  const { open, refs, floatingStyles, inheritedBrand, getFloatingProps } = useHoverCardContext();
 
   if (!open) return null;
 
@@ -19,6 +28,7 @@ export const HoverCardContent = React.forwardRef<HTMLDivElement, HoverCardConten
           else if (forwardedRef) forwardedRef.current = node;
         }}
         style={floatingStyles}
+        data-brand={brand ?? inheritedBrand}
         className={cn("z-popover w-80 rounded-lg border border-border-normal bg-bg-normal p-4 shadow-lg", className)}
         {...getFloatingProps(props)}
       >

package/src/components/HoverCard/components/HoverCardContext.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { createContext, useContext } from "react";
 
 export type HoverCardContextValue = {
@@ -7,6 +9,8 @@ export type HoverCardContextValue = {
     setFloating: (node: HTMLElement | null) => void;
   };
   floatingStyles: React.CSSProperties;
+  /** The trigger's brand scope, re-stamped on the portalled body. */
+  inheritedBrand: string | undefined;
   getReferenceProps: (props?: React.HTMLProps<HTMLElement>) => Record<string, unknown>;
   getFloatingProps: (props?: React.HTMLProps<HTMLElement>) => Record<string, unknown>;
 };

package/src/components/HoverCard/components/HoverCardTrigger.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import * as React from "react";
 import { Slot } from "../../../internal/Slot";
 import type { WritableRefObject } from "../../../internal/types";

package/src/components/Message/Message.tsx

@@ -10,7 +10,7 @@ import { MessageTitle } from "./components/MessageTitle";
  * Geometry only, plus the three `--message-*` component tokens.
  *
  * Every colour reads a `--message-*` component token whose value is decided by
- * src/theme/recipes/message.css. That file is the mapping from `intent` to a
+ * src/components/Message/message.recipe.css. That file is the mapping from `intent` to a
  * semantic token — the layer that used to be the `intent` entry in `variants`
  * here, compiled into class-name literals and unreachable from outside.
  * `size` stays here: it is pure geometry (padding, gap, font-size), not
@@ -48,6 +48,8 @@ export type MessageIntent = Loose<MessageIntentName>;
 export type MessageProps = React.HTMLAttributes<HTMLDivElement> &
   VariantProps<typeof messageVariants> & {
     intent?: MessageIntent | undefined;
+    /** Name of a brand the theme defines, rendered as `data-brand`. Omitted, the message follows the nearest `data-brand` ancestor. */
+    brand?: string | undefined;
     /** Simple API: Optional title displayed above children */
     title?: React.ReactNode;
     /** Simple API: Optional icon displayed on the left */
@@ -99,27 +101,29 @@ function intentRole(intent: MessageIntent): "status" | "alert" {
  * simple API can't express. Message detects which one is in use by
  * inspecting its children, so the two aren't meant to be mixed.
  */
-export const Message = React.forwardRef<HTMLDivElement, MessageProps>(({ className, intent = "neutral", size, title, icon, children, ...props }, ref) => {
-  const hasCompoundChildren = React.Children.toArray(children).some(
-    (child) =>
-      React.isValidElement(child) &&
-      (child.type === MessageIcon || child.type === MessageBody || child.type === MessageTitle || child.type === MessageDescription)
-  );
+export const Message = React.forwardRef<HTMLDivElement, MessageProps>(
+  ({ className, intent = "neutral", brand, size, title, icon, children, ...props }, ref) => {
+    const hasCompoundChildren = React.Children.toArray(children).some(
+      (child) =>
+        React.isValidElement(child) &&
+        (child.type === MessageIcon || child.type === MessageBody || child.type === MessageTitle || child.type === MessageDescription)
+    );
 
-  return (
-    <div ref={ref} role={intentRole(intent)} data-intent={intent} className={cn(messageVariants({ size, className }))} {...props}>
-      {hasCompoundChildren ? (
-        children
-      ) : (
-        <>
-          {icon && <MessageIcon>{icon}</MessageIcon>}
-          <MessageBody>
-            {title && <MessageTitle>{title}</MessageTitle>}
-            <MessageDescription>{children}</MessageDescription>
-          </MessageBody>
-        </>
-      )}
-    </div>
-  );
-});
+    return (
+      <div ref={ref} role={intentRole(intent)} data-intent={intent} data-brand={brand} className={cn(messageVariants({ size, className }))} {...props}>
+        {hasCompoundChildren ? (
+          children
+        ) : (
+          <>
+            {icon && <MessageIcon>{icon}</MessageIcon>}
+            <MessageBody>
+              {title && <MessageTitle>{title}</MessageTitle>}
+              <MessageDescription>{children}</MessageDescription>
+            </MessageBody>
+          </>
+        )}
+      </div>
+    );
+  }
+);
 Message.displayName = "Message";

package/src/components/Modal/Modal.tsx

@@ -1,7 +1,11 @@
-import { FloatingFocusManager, FloatingOverlay, useDismiss, useFloating, useInteractions, useRole } from "@floating-ui/react";
+"use client";
+
+import { FloatingFocusManager, FloatingOverlay, FloatingPortal, useDismiss, useFloating, useInteractions, useRole } from "@floating-ui/react";
 import { useMergedFloatingRef, usePresence } from "@sixthshift/design-system/hooks";
 import { cn } from "@sixthshift/design-system/utils";
 import { forwardRef, type HTMLAttributes, type ReactNode, useCallback, useContext, useEffect, useId, useMemo, useState } from "react";
+import { useOpenerBrand } from "../../internal/brandScope";
+import { hasOpenEscapeLayer, useEscapeDialog } from "../../internal/escapeLayers";
 import { ModalBody, ModalContext, ModalFooter, ModalHeader } from "./components";
 
 // =============================================================================
@@ -21,15 +25,23 @@ export type ModalProps = Pick<HTMLAttributes<HTMLDivElement>, "className" | "sty
   /** Children - use Modal.Header, Modal.Body, Modal.Footer */
   children: ReactNode;
   /**
-   * When true (default), clicking outside closes the modal.
+   * When true (default), clicking outside — and, for a directly-mounted
+   * modal, pressing Escape — closes the modal.
    * When false, the modal can only be closed programmatically.
-   * Note: Escape key is handled by OverlayContext for proper stack ordering.
+   * Note: for modals opened via `useModal()`, Escape is handled by
+   * OverlayContext for proper stack ordering.
    */
   dismissable?: boolean;
   /** When true, shows a close (X) button in the modal header */
   closable?: boolean;
   /** Vertical alignment on desktop. "center" (default) or "top" (anchored near top, content grows down) */
   align?: "center" | "top";
+  /**
+   * Name of a brand the theme defines, rendered as `data-brand` on the dialog.
+   * Omitted, the modal takes the brand scope of the control that opened it
+   * (whatever held focus), since the portal leaves the trigger's scope behind.
+   */
+  brand?: string | undefined;
 };
 
 // =============================================================================
@@ -58,6 +70,7 @@ const ModalRoot = forwardRef<HTMLDivElement, ModalProps>(
       dismissable = true,
       closable,
       align = "center",
+      brand,
       "aria-label": ariaLabel,
       "aria-labelledby": ariaLabelledBy,
       "aria-describedby": ariaDescribedBy,
@@ -66,6 +79,9 @@ const ModalRoot = forwardRef<HTMLDivElement, ModalProps>(
   ) => {
     // Prefer explicit prop over context (context is set by useModal's overlay system)
     const contextValue = useContext(ModalContext);
+    // A context means useModal's stack owns this modal — and with it, Escape
+    // ordering. Without one the modal is mounted directly and handles its own.
+    const isStackManaged = contextValue != null;
     // Context provides a parameterless onClose for programmatic modals; adapt to the boolean shape.
     const handleDismiss = useCallback(() => {
       if (onOpenChange) onOpenChange(false);
@@ -73,6 +89,8 @@ const ModalRoot = forwardRef<HTMLDivElement, ModalProps>(
     }, [onOpenChange, contextValue]);
 
     const { ref: presenceRef, state, isMounted, show, hide } = usePresence();
+    // Mount-driven, so the modal is open for as long as it exists.
+    const openerBrand = useOpenerBrand(true);
 
     useEffect(() => {
       show();
@@ -84,8 +102,12 @@ const ModalRoot = forwardRef<HTMLDivElement, ModalProps>(
 
     const { refs, context } = useFloating({
       open: true,
-      onOpenChange: (nextOpen) => {
-        if (!nextOpen) handleClose();
+      onOpenChange: (nextOpen, _event, reason) => {
+        if (nextOpen) return;
+        // A transient overlay (Select dropdown, Popover, picker) open above
+        // this modal consumes the Escape itself — don't also close the modal.
+        if (reason === "escape-key" && hasOpenEscapeLayer()) return;
+        handleClose();
       },
     });
 
@@ -93,8 +115,10 @@ const ModalRoot = forwardRef<HTMLDivElement, ModalProps>(
 
     const dismiss = useDismiss(context, {
       enabled: dismissable,
-      // OverlayContext handles escape key for proper stack ordering
-      escapeKey: false,
+      // Stack-managed modals leave Escape to OverlayContext, which closes
+      // topmost-first. A directly-mounted modal has no stack above it and
+      // handles its own Escape here.
+      escapeKey: !isStackManaged,
       outsidePress: true,
       outsidePressEvent: "mousedown",
     });
@@ -119,52 +143,64 @@ const ModalRoot = forwardRef<HTMLDivElement, ModalProps>(
 
     const modalContextValue = useMemo(() => ({ onClose: handleClose, closable, titleId, registerTitle }), [closable, handleClose, titleId, registerTitle]);
 
+    // While mounted (exit animation included), a non-modal Sheet underneath
+    // must leave Escape to this dialog.
+    useEscapeDialog(isMounted);
+
     if (!isMounted) return null;
 
     const isEntering = state === "entering";
     const isExiting = state === "exiting";
 
     return (
-      <FloatingFocusManager context={context} modal>
-        <FloatingOverlay
-          lockScroll
-          className={cn("modal-overlay fixed inset-0 z-modal bg-(--modal-overlay-bg)", isEntering && "animate-fade-in", isExiting && "animate-fade-out")}
-        >
-          <div
-            ref={mergedRef}
-            role="dialog"
-            aria-modal="true"
-            aria-label={ariaLabel}
-            aria-labelledby={labelledBy}
-            aria-describedby={ariaDescribedBy}
-            tabIndex={-1}
-            data-state={state}
-            className={cn(
-              "modal fixed flex flex-col overflow-hidden outline-hidden",
-              "border-(color:--modal-border) rounded-xl border bg-(--modal-bg)",
-              // Size
-              sizeClasses[size],
-              // Cap height so ModalBody scrolls instead of overflowing the viewport
-              "max-h-[95%]",
-              // Mobile: slide up from bottom, full width
-              "max-sm:inset-x-0 max-sm:bottom-0 max-sm:rounded-b-none",
-              isEntering && "max-sm:animate-slide-up-in",
-              isExiting && "max-sm:animate-slide-up-out",
-              // Desktop: horizontal center + vertical alignment
-              "sm:left-1/2 sm:-translate-x-1/2",
-              align === "center" && "sm:top-1/2 sm:-translate-y-1/2",
-              align === "top" && "sm:top-[15vh]",
-              isEntering && "sm:animate-fade-in",
-              isExiting && "sm:animate-fade-out",
-              className
-            )}
-            style={style}
-            {...getFloatingProps({})}
+      // Self-portalled: `position: fixed` resolves against the nearest
+      // transformed/filtered ancestor, so a modal rendered in place inside a
+      // `transform` container would be positioned (and clipped) by it. Nested
+      // FloatingPortals attach to the parent portal's node, so a stack-managed
+      // modal stays inside the `OverlayProvider`'s custom `modal` root.
+      <FloatingPortal>
+        <FloatingFocusManager context={context} modal>
+          <FloatingOverlay
+            lockScroll
+            className={cn("modal-overlay fixed inset-0 z-modal bg-(--modal-overlay-bg)", isEntering && "animate-fade-in", isExiting && "animate-fade-out")}
           >
-            <ModalContext.Provider value={modalContextValue}>{children}</ModalContext.Provider>
-          </div>
-        </FloatingOverlay>
-      </FloatingFocusManager>
+            <div
+              ref={mergedRef}
+              role="dialog"
+              aria-modal="true"
+              aria-label={ariaLabel}
+              aria-labelledby={labelledBy}
+              aria-describedby={ariaDescribedBy}
+              tabIndex={-1}
+              data-state={state}
+              data-brand={brand ?? openerBrand}
+              className={cn(
+                "modal fixed flex flex-col overflow-hidden outline-hidden",
+                "border-(color:--modal-border) rounded-xl border bg-(--modal-bg)",
+                // Size
+                sizeClasses[size],
+                // Cap height so ModalBody scrolls instead of overflowing the viewport
+                "max-h-[95%]",
+                // Mobile: slide up from bottom, full width
+                "max-sm:inset-x-0 max-sm:bottom-0 max-sm:rounded-b-none",
+                isEntering && "max-sm:animate-slide-up-in",
+                isExiting && "max-sm:animate-slide-up-out",
+                // Desktop: horizontal center + vertical alignment
+                "sm:left-1/2 sm:-translate-x-1/2",
+                align === "center" && "sm:top-1/2 sm:-translate-y-1/2",
+                align === "top" && "sm:top-[15vh]",
+                isEntering && "sm:animate-fade-in",
+                isExiting && "sm:animate-fade-out",
+                className
+              )}
+              style={style}
+              {...getFloatingProps({})}
+            >
+              <ModalContext.Provider value={modalContextValue}>{children}</ModalContext.Provider>
+            </div>
+          </FloatingOverlay>
+        </FloatingFocusManager>
+      </FloatingPortal>
     );
   }
 );
@@ -192,11 +228,12 @@ ModalRoot.displayName = "Modal";
  * Modal is mount-driven — a parent (or `useModal`'s stack) decides whether it
  * renders at all, so there's no `open` prop. `onOpenChange` still exists,
  * firing only with `false` on dismissal, so every overlay in this library
- * shares one open/close shape. Escape is *not* wired inside Modal itself:
- * `OverlayProvider` owns it globally so a stack of modals closes
- * topmost-first. That means Escape only closes a Modal opened through
- * `useModal()` — one a parent mounts directly from its own boolean state
- * won't respond to Escape unless the app wires that separately.
+ * shares one open/close shape. Escape closes the modal: a directly-mounted
+ * Modal handles it itself (via `useDismiss`, so `dismissable={false}` turns
+ * it off along with outside-press), while one opened through `useModal()`
+ * defers to `OverlayProvider`, which closes a stack of modals topmost-first.
+ * Either way, an Escape pressed while a transient overlay (Select dropdown,
+ * Popover, picker) is open above the modal closes only that overlay.
  *
  * Focus moves into the modal on mount and is trapped there
  * (`FloatingFocusManager modal`) until it unmounts, then returns to whatever

package/src/components/Modal/components/ModalContext.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { createContext, type PropsWithChildren, useContext, useMemo } from "react";
 
 /**

package/src/components/Modal/components/ModalHeader.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { cn } from "@sixthshift/design-system/utils";
 import { X } from "lucide-react";
 import * as React from "react";

package/src/components/Popover/Popover.tsx

@@ -1,7 +1,11 @@
+"use client";
+
 import { autoUpdate, flip, offset, type Placement, shift, useClick, useDismiss, useFloating, useInteractions } from "@floating-ui/react";
 import { useControllableState } from "@sixthshift/design-system/hooks";
 import type * as React from "react";
 import { useId } from "react";
+import { closestBrand } from "../../internal/brandScope";
+import { useEscapeLayer } from "../../internal/escapeLayers";
 import { PopoverBody } from "./components/PopoverBody";
 import { PopoverClose } from "./components/PopoverClose";
 import { PopoverContext } from "./components/PopoverContext";
@@ -42,6 +46,10 @@ const PopoverRoot = ({ open: controlledOpen, onOpenChange, defaultOpen = false,
   const dismiss = useDismiss(context);
   const { getReferenceProps, getFloatingProps } = useInteractions([click, dismiss]);
 
+  // While open, an Escape press dismisses this popover and must not also
+  // close a Modal/Sheet underneath it.
+  useEscapeLayer(open);
+
   const id = useId();
   const contentId = `popover-content-${id}`;
   // `Popover.Body` is a `role="dialog"`, and a dialog with no accessible name is
@@ -59,6 +67,8 @@ const PopoverRoot = ({ open: controlledOpen, onOpenChange, defaultOpen = false,
       setFloating: refs.setFloating,
     },
     floatingStyles,
+    // Read at render: `domReference` is state, so this updates once the trigger mounts.
+    inheritedBrand: closestBrand(context.elements.domReference),
     getReferenceProps,
     getFloatingProps,
     contentId,

package/src/components/Popover/components/PopoverBody.tsx

@@ -1,12 +1,21 @@
+"use client";
+
 import { FloatingPortal } from "@floating-ui/react";
 import { cn } from "@sixthshift/design-system/utils";
 import * as React from "react";
 import { usePopoverContext } from "./PopoverContext";
 
-export type PopoverBodyProps = React.HTMLAttributes<HTMLDivElement>;
+export type PopoverBodyProps = React.HTMLAttributes<HTMLDivElement> & {
+  /**
+   * Name of a brand the theme defines, rendered as `data-brand`. Omitted, the
+   * body copies the brand scope of its trigger, which the portal would
+   * otherwise leave behind.
+   */
+  brand?: string | undefined;
+};
 
-export const PopoverBody = React.forwardRef<HTMLDivElement, PopoverBodyProps>(({ className, children, ...props }, forwardedRef) => {
-  const { open, refs, floatingStyles, getFloatingProps, contentId, triggerId } = usePopoverContext();
+export const PopoverBody = React.forwardRef<HTMLDivElement, PopoverBodyProps>(({ className, brand, children, ...props }, forwardedRef) => {
+  const { open, refs, floatingStyles, inheritedBrand, getFloatingProps, contentId, triggerId } = usePopoverContext();
 
   // `aria-labelledby` outranks `aria-label` in the name computation, so the
   // trigger only names the dialog when the caller hasn't named it themselves.
@@ -26,6 +35,7 @@ export const PopoverBody = React.forwardRef<HTMLDivElement, PopoverBodyProps>(({
         role="dialog"
         aria-labelledby={hasOwnLabel ? undefined : triggerId}
         style={floatingStyles}
+        data-brand={brand ?? inheritedBrand}
         className={cn("z-popover rounded-lg border border-border-normal bg-bg-normal p-4 shadow-lg", className)}
         {...getFloatingProps(props)}
       >

package/src/components/Popover/components/PopoverClose.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import * as React from "react";
 import { Slot } from "../../../internal/Slot";
 import { usePopoverContext } from "./PopoverContext";

package/src/components/Popover/components/PopoverContext.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { createContext, useContext } from "react";
 
 export type PopoverContextValue = {
@@ -8,6 +10,8 @@ export type PopoverContextValue = {
     setFloating: (node: HTMLElement | null) => void;
   };
   floatingStyles: React.CSSProperties;
+  /** The trigger's brand scope, re-stamped on the portalled body. */
+  inheritedBrand: string | undefined;
   getReferenceProps: (props?: React.HTMLProps<HTMLElement>) => Record<string, unknown>;
   getFloatingProps: (props?: React.HTMLProps<HTMLElement>) => Record<string, unknown>;
   contentId: string;

package/src/components/Popover/components/PopoverTrigger.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import * as React from "react";
 import { Slot } from "../../../internal/Slot";
 import { usePopoverContext } from "./PopoverContext";

package/src/components/RadioButton/RadioButton.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { Label } from "@sixthshift/design-system/label";
 import { cn } from "@sixthshift/design-system/utils";
 import * as React from "react";