@sixthshift/design-system 0.4.0 → 0.6.0

package/src/components/DateTimeRangePicker/DateTimeRangePicker.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { autoUpdate, FloatingPortal, flip, offset, shift, useClick, useDismiss, useFloating, useInteractions } from "@floating-ui/react";
 import { useControllableState } from "@sixthshift/design-system/hooks";
 import { cn } from "@sixthshift/design-system/utils";
@@ -16,8 +18,8 @@ import {
   toISOInstant,
   toISOInstantRange,
 } from "../../date-time";
-
 import { PickerField } from "../../internal";
+import { useEscapeLayer } from "../../internal/escapeLayers";
 import { Button } from "../Button";
 import { CalendarView } from "../Calendar/CalendarView";
 import { isDateDisabled } from "../Calendar/calendar.hooks";
@@ -412,6 +414,10 @@ export const DateTimeRangePicker = React.forwardRef<HTMLDivElement, DateTimeRang
 
   const click = useClick(context);
   const dismiss = useDismiss(context);
+
+  // While open, an Escape press closes this picker's popover and must not
+  // also close a Modal/Sheet it is rendered inside.
+  useEscapeLayer(open);
   const { getReferenceProps, getFloatingProps } = useInteractions([click, dismiss]);
 
   // IDs for accessibility

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,3 +1,5 @@
+"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";

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

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

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

@@ -1,3 +1,5 @@
+"use client";
+
 import { createContext, useContext } from "react";
 
 export type HoverCardContextValue = {

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

package/src/components/Modal/Modal.tsx

@@ -1,7 +1,10 @@
-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 { hasOpenEscapeLayer, useEscapeDialog } from "../../internal/escapeLayers";
 import { ModalBody, ModalContext, ModalFooter, ModalHeader } from "./components";
 
 // =============================================================================
@@ -21,9 +24,11 @@ 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 */
@@ -66,6 +71,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);
@@ -84,8 +92,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 +105,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 +133,63 @@ 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}
+              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 +217,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,10 @@
+"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 { useEscapeLayer } from "../../internal/escapeLayers";
 import { PopoverBody } from "./components/PopoverBody";
 import { PopoverClose } from "./components/PopoverClose";
 import { PopoverContext } from "./components/PopoverContext";
@@ -42,6 +45,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

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

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

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 = {

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

package/src/components/RadioButtonGroup/RadioButtonGroup.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { useControllableState } from "@sixthshift/design-system/hooks";
 import { RadioButton } from "@sixthshift/design-system/radio-button";
 import { cn } from "@sixthshift/design-system/utils";

package/src/components/SearchInput/SearchInput.tsx

@@ -1,11 +1,14 @@
+"use client";
+
 import { Input } from "@sixthshift/design-system/input";
 import { cn } from "@sixthshift/design-system/utils";
 import { Search, X } from "lucide-react";
 import * as React from "react";
 
-export type SearchInputProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" | "onChange"> & {
+export type SearchInputProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, "type"> & {
   value: string;
-  onChange: (value: string) => void;
+  /** Called with the input's string value on every change. The native `onChange(event)` also fires, unchanged. */
+  onValueChange: (value: string) => void;
   onClear?: () => void;
   /** Accessible name for the clear button — it is icon-only. */
   clearLabel?: string;
@@ -17,17 +20,18 @@ export type SearchInputProps = Omit<React.InputHTMLAttributes<HTMLInputElement>,
  *
  * Wraps `Input`, using its `iconLeft`/`iconRight` slots, rather than
  * reimplementing the field. Always controlled — `value` is required and
- * there is no `defaultValue`/uncontrolled mode. `onChange` receives the
- * string value directly, not the change event. Clearing calls `onClear` if
- * provided, otherwise calls `onChange("")`.
+ * there is no `defaultValue`/uncontrolled mode. `onValueChange` receives the
+ * string value directly; the native `onChange` keeps its event signature and
+ * fires too if passed. Clearing calls `onClear` if provided, otherwise calls
+ * `onValueChange("")` — note a programmatic clear dispatches no native event.
  */
 const SearchInput = React.forwardRef<HTMLInputElement, SearchInputProps>(
-  ({ className, value, onChange, onClear, clearLabel = "Clear search", ...props }, ref) => {
+  ({ className, value, onValueChange, onChange, onClear, clearLabel = "Clear search", ...props }, ref) => {
     const handleClear = () => {
       if (onClear) {
         onClear();
       } else {
-        onChange("");
+        onValueChange("");
       }
     };
 
@@ -36,7 +40,10 @@ const SearchInput = React.forwardRef<HTMLInputElement, SearchInputProps>(
         ref={ref}
         type="text"
         value={value}
-        onChange={(e) => onChange(e.target.value)}
+        onChange={(e) => {
+          onValueChange(e.target.value);
+          onChange?.(e);
+        }}
         iconLeft={<Search />}
         iconRight={
           value ? (

package/src/components/Select/Select.tsx

@@ -1,6 +1,9 @@
+"use client";
+
 import { autoUpdate, flip, offset, shift, size, useFloating } from "@floating-ui/react";
 import { useControllableState } from "@sixthshift/design-system/hooks";
 import { forwardRef, type HTMLAttributes, type ReactElement, type Ref, useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+import { useEscapeLayer } from "../../internal/escapeLayers";
 import { SelectDropdown, selectOptionId } from "./SelectDropdown";
 import { SelectTriggerButton, SelectTriggerSearch } from "./SelectTrigger";
 import { useSelectKeyboard } from "./useSelectKeyboard";
@@ -19,6 +22,12 @@ type SelectBaseProps<T extends string = string> = Omit<HTMLAttributes<HTMLElemen
   placeholder?: string;
   searchable?: boolean;
   clearable?: boolean;
+  /** Input name for native form submission. Selected value(s) are mirrored into hidden `<input>`s, `${name}[]` in multiple mode. */
+  name?: string;
+  /** The `form` attribute for the hidden input(s), for a Select rendered outside its `<form>`. */
+  form?: string;
+  /** Marks the combobox `aria-required`. Constraint validation is the caller's job — the mirrored inputs are hidden. */
+  required?: boolean;
 };
 
 type SelectSingleProps<T extends string = string> = SelectBaseProps<T> & {
@@ -54,6 +63,9 @@ const SelectRoot = forwardRef(function SelectRoot<T extends string = string>(pro
     placeholder = "Select...",
     searchable = false,
     clearable = false,
+    name,
+    form,
+    required = false,
     ...restProps
   } = props;
 
@@ -244,6 +256,10 @@ const SelectRoot = forwardRef(function SelectRoot<T extends string = string>(pro
     }
   }, [highlightedIndex, open]);
 
+  // While open, an Escape press closes the dropdown and must not also close
+  // a Modal/Sheet this Select is rendered inside.
+  useEscapeLayer(open);
+
   // Close on outside click
   useEffect(() => {
     if (!open) return;
@@ -266,7 +282,8 @@ const SelectRoot = forwardRef(function SelectRoot<T extends string = string>(pro
   const activeOptionId = open && highlightedIndex >= 0 && highlightedIndex < filteredOptions.length ? selectOptionId(listboxId, highlightedIndex) : undefined;
 
   // Strip mode from DOM props
-  const { mode: _, value: _v, defaultValue: _dv, onValueChange: _oc, ...htmlProps } = restProps as Record<string, unknown>;
+  const { mode: _, value: _v, defaultValue: _dv, onValueChange: _oc, ...strippedProps } = restProps as Record<string, unknown>;
+  const htmlProps = required ? { "aria-required": true, ...strippedProps } : strippedProps;
 
   // `role="listbox"` requires an accessible name of its own, and the trigger
   // can't supply one: its label is the current *value*, and in searchable mode
@@ -311,6 +328,12 @@ const SelectRoot = forwardRef(function SelectRoot<T extends string = string>(pro
         />
       )}
 
+      {/* Hidden inputs mirror the selection for native form submission — same
+          contract as DatePicker: rendered inline (not portalled) so they sit
+          inside the surrounding <form> unless `form` points elsewhere. */}
+      {name && !isMultiple && singleValue && <input type="hidden" name={name} value={singleValue} {...(form ? { form } : {})} />}
+      {name && isMultiple && multiValue.map((v) => <input key={v} type="hidden" name={`${name}[]`} value={v} {...(form ? { form } : {})} />)}
+
       {open && !collapsed && (
         <SelectDropdown
           setFloating={refs.setFloating}

package/src/components/Select/SelectDropdown.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { FloatingPortal } from "@floating-ui/react";
 import { cn } from "@sixthshift/design-system/utils";
 import { Check } from "lucide-react";

package/src/components/Select/SelectTrigger.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { cn } from "@sixthshift/design-system/utils";
 import { ChevronDown, X } from "lucide-react";
 import type { HTMLAttributes, Ref } from "react";
@@ -55,6 +57,9 @@ export const SelectTriggerButton = ({
           className
         )}
         title={collapsed ? displayLabel : undefined}
+        // The APG select-only combobox: a button-behaving element announced as
+        // a combobox, which also admits aria-required — a plain button doesn't.
+        role="combobox"
         aria-haspopup="listbox"
         aria-expanded={open}
         // The listbox unmounts when closed, so only reference it while it exists.