@proyecto-viviana/ui 0.5.0 → 0.6.0

package/src/picker/index.tsx

@@ -0,0 +1,1250 @@
+// @ts-nocheck
+import {
+  type JSX,
+  createContext,
+  createEffect,
+  createSignal,
+  createUniqueId,
+  mergeProps,
+  onCleanup,
+  Show,
+  splitProps,
+  useContext,
+} from "solid-js";
+import {
+  Select as HeadlessSelect,
+  SelectContext as HeadlessSelectContext,
+  SelectTrigger as HeadlessSelectTrigger,
+  SelectValue as HeadlessSelectValue,
+  SelectListBox as HeadlessSelectListBox,
+  SelectOption as HeadlessSelectOption,
+  ListBoxSection as HeadlessListBoxSection,
+  FieldError as HeadlessFieldError,
+  Popover as HeadlessPopover,
+  type ListBoxSectionProps as HeadlessListBoxSectionProps,
+  type SelectProps as HeadlessSelectProps,
+  type SelectRenderProps,
+  type SelectTriggerRenderProps,
+  type SelectValueRenderProps,
+  type SelectListBoxRenderProps,
+  type SelectOptionProps as HeadlessSelectOptionProps,
+  type SelectOptionRenderProps,
+} from "@proyecto-viviana/solidaria-components";
+import type { Key } from "@proyecto-viviana/solid-stately";
+import type { StyleString } from "../style";
+import {
+  baseColor,
+  css,
+  focusRing,
+  fontRelative,
+  lightDark,
+  setColorScheme,
+  space,
+  style,
+} from "../style" with { type: "macro" };
+import { edgeToText } from "../style/spectrum-theme" with { type: "macro" };
+import {
+  control,
+  controlBorderRadius,
+  controlFont,
+  controlSize,
+  field,
+  fieldInput,
+  fieldLabel,
+  getAllowedOverrides,
+} from "../s2-internal/style-utils" with { type: "macro" };
+import { CenterBaseline } from "../icon/center-baseline";
+import AlertTriangleIcon from "../icon/s2wf-icons/AlertTriangleIcon";
+import AsteriskIcon from "../icon/ui-icons/Asterisk";
+import CheckmarkIcon from "../icon/ui-icons/Checkmark";
+import ChevronIcon from "../icon/ui-icons/Chevron";
+import { pressScale } from "../pressScale";
+import { ProgressCircle } from "../progress/ProgressCircle";
+import { useProviderProps, useTheme } from "../provider";
+import { Divider } from "../divider";
+import { getSlottedContextProps, type SpectrumContextValue } from "../button/spectrum-context";
+
+export type PickerSize = "S" | "M" | "L" | "XL";
+type S2PickerSize = "S" | "M" | "L" | "XL";
+export type PickerLabelPosition = "top" | "side";
+export type PickerLabelAlign = "start" | "end";
+export type PickerNecessityIndicator = "icon" | "label";
+export type PickerDirection = "bottom" | "top";
+export type PickerAlign = "start" | "end";
+export type PickerLoadingState =
+  | "idle"
+  | "loading"
+  | "loadingMore"
+  | "sorting"
+  | "filtering"
+  | "error";
+
+export interface PickerProps<T> extends Omit<
+  HeadlessSelectProps<T>,
+  "class" | "style" | "children"
+> {
+  size?: PickerSize;
+  isQuiet?: boolean;
+  styles?: StyleString;
+  UNSAFE_className?: string;
+  UNSAFE_style?: JSX.CSSProperties;
+  class?: string;
+  label?: JSX.Element;
+  description?: JSX.Element;
+  errorMessage?: JSX.Element;
+  isInvalid?: boolean;
+  labelPosition?: PickerLabelPosition;
+  labelAlign?: PickerLabelAlign;
+  necessityIndicator?: PickerNecessityIndicator;
+  contextualHelp?: JSX.Element;
+  direction?: PickerDirection;
+  align?: PickerAlign;
+  menuWidth?: number;
+  shouldFlip?: boolean;
+  loadingState?: PickerLoadingState;
+  onLoadMore?: () => void | Promise<void>;
+  renderValue?: (selectedItems: T[]) => JSX.Element;
+  children?: JSX.Element | ((item: T) => JSX.Element);
+}
+
+export interface PickerItemProps<T> extends Omit<
+  HeadlessSelectOptionProps<T>,
+  "class" | "style" | "children"
+> {
+  children?: JSX.Element;
+  styles?: StyleString;
+  UNSAFE_className?: string;
+  UNSAFE_style?: JSX.CSSProperties;
+  class?: string;
+}
+
+interface PickerStyleProps extends SelectRenderProps {
+  size?: S2PickerSize;
+  labelPosition?: PickerLabelPosition;
+  labelAlign?: PickerLabelAlign;
+  isFocusWithin?: boolean;
+  isQuiet?: boolean;
+  isInvalid?: boolean;
+  isInForm?: boolean;
+}
+
+interface PickerTriggerStyleProps extends SelectTriggerRenderProps {
+  size?: S2PickerSize;
+  isQuiet?: boolean;
+  isInvalid?: boolean;
+}
+
+interface PickerValueStyleProps extends SelectValueRenderProps<unknown> {
+  isQuiet?: boolean;
+}
+
+interface PickerOptionStyleProps extends SelectOptionRenderProps {
+  size?: S2PickerSize;
+}
+
+const PickerSizeContext = createContext<S2PickerSize>("M");
+
+// Mirrors upstream S2 `Picker`'s `InsideSelectValueContext` (Picker.tsx:315).
+// True while rendering a selected option's content inside the trigger's
+// `SelectValue`. `PickerItem` reads it to render only its slotted content
+// (icon/avatar/label) — no option row, checkmark, or press-scale — so the
+// trigger mirrors the full selected node, not just its text.
+const InsidePickerValueContext = createContext<boolean>(false);
+
+// Mirrors React S2's `PickerContext`: slotted props injected by an ancestor
+// provider. No-op by default (`getSlottedContextProps(null, …)` returns null).
+export const PickerContext = createContext<SpectrumContextValue<PickerProps<any>>>(null);
+
+const pickerRoot = style<PickerStyleProps>(
+  {
+    ...field(),
+    position: "relative",
+  },
+  getAllowedOverrides(),
+);
+
+const pickerLabelWrapper = style<PickerStyleProps>({
+  gridArea: "label",
+  display: "inline-flex",
+  alignItems: "baseline",
+  gap: "text-to-visual",
+  textAlign: {
+    labelAlign: {
+      start: "start",
+      end: "end",
+    },
+  },
+  paddingBottom: {
+    labelPosition: {
+      top: "--field-gap",
+    },
+  },
+  contain: {
+    labelPosition: {
+      top: "inline-size",
+    },
+  },
+});
+
+const pickerLabel = style<PickerStyleProps>({
+  ...fieldLabel(),
+});
+
+const pickerTrigger = style<PickerTriggerStyleProps>({
+  ...focusRing(),
+  ...control({ shape: "default", icon: true, register: "matte" }),
+  ...fieldInput(),
+  outlineStyle: {
+    default: "none",
+    isFocusVisible: "solid",
+    isQuiet: "none",
+  },
+  position: "relative",
+  textAlign: "start",
+  // These three keys DUPLICATE what `control({ register: "matte" })` spreads in
+  // above (see the `if (register === "matte")` branch in
+  // ../s2-internal/style-utils.ts, which sets borderWidth/borderStyle/borderColor/
+  // backgroundColor). In a JS object literal the later key wins OUTRIGHT — it does
+  // not merge — so whatever is written here IS the whole value, and the spread's
+  // `solid` / `well-border` / `well` never survived to the macro. That is how the
+  // closed trigger ended up a borderless gray-100 slab next to a ComboBox field
+  // group that renders correctly: `comboBoxFieldGroup` (combobox/index.tsx:196-223)
+  // spreads the identical `control()` and RESTATES the register values instead of
+  // silently erasing them.
+  //
+  // Each key below therefore restates the resting matte field — 1px solid
+  // var(--well-border) over var(--surface-well) (the handoff's `Well`,
+  // TerminalGlassLab.tsx:269-283) — and only then layers on per-component state.
+  // `default: "solid"` is load-bearing: dropping it would leave borderStyle with no
+  // default, which computes to `none` and keeps the border invisible even though
+  // borderWidth survives the spread. `isQuiet: "none"` is equally load-bearing —
+  // without it the quiet variant would newly grow a border it never had.
+  borderStyle: {
+    default: "solid",
+    isQuiet: "none",
+    forcedColors: "solid",
+  },
+  borderColor: {
+    default: "well-border",
+    forcedColors: {
+      default: "ButtonText",
+      isDisabled: "GrayText",
+    },
+  },
+  transition: "default",
+  paddingX: {
+    default: "edge-to-text",
+    isQuiet: 0,
+  },
+  // `isOpen: "gray-200"` is deliberately dropped rather than retinted: the handoff
+  // gives the well no open state, and --surface-well has no ramp to step to. The
+  // popover appearing plus focusRing() carry the feedback, as they already do on
+  // the ComboBox. `forcedColors: "Field"` mirrors comboBoxFieldGroup.
+  backgroundColor: {
+    default: "well",
+    isDisabled: "disabled",
+    isQuiet: "transparent",
+    forcedColors: "Field",
+  },
+  color: {
+    default: baseColor("neutral"),
+    isDisabled: "disabled",
+  },
+  maxWidth: {
+    isQuiet: "max",
+  },
+  cursor: "default",
+  disableTapHighlight: true,
+});
+
+const pickerInvalidBorder = style<PickerTriggerStyleProps>({
+  ...controlBorderRadius(),
+  position: "absolute",
+  top: 0,
+  left: 0,
+  bottom: 0,
+  right: 0,
+  pointerEvents: "none",
+  borderStyle: "solid",
+  borderWidth: 1,
+  borderColor: baseColor("negative"),
+  transition: "default",
+});
+
+const quietFocusLine = style({
+  width: "full",
+  height: "[2px]",
+  position: "absolute",
+  bottom: 0,
+  borderRadius: "full",
+  backgroundColor: {
+    default: "blue-800",
+    forcedColors: "Highlight",
+  },
+});
+
+const pickerValue = style<PickerValueStyleProps>({
+  flexGrow: {
+    default: 1,
+    isQuiet: 0,
+  },
+  truncate: true,
+  display: "flex",
+  alignItems: "center",
+  height: "100%",
+  color: {
+    default: "inherit",
+    ":is([data-placeholder])": "neutral-subdued",
+  },
+});
+
+// Faithful to upstream S2 `Picker`: the selected value text is mirrored from the
+// option's rendered content, and `PickerItem` wraps a string child in
+// `<Text slot="label">` (Picker.tsx:854). Inside `SelectValue` the `TextContext`
+// `label` slot styles that span `display: block; flex-grow: 1; truncate`
+// (Picker.tsx:718-731). Our port renders `selectedText` as a plain string, so we
+// wrap it in the equivalent label-slot span — otherwise the value text sits
+// directly on the flex `pickerValue` container and inherits its
+// `display: flex; align-items: center; height: 100%` instead of the block
+// text-height the `label` slot paints.
+const pickerValueText = style({
+  display: "block",
+  flexGrow: 1,
+  truncate: true,
+});
+
+// Faithful to upstream S2 `Picker` (Picker.tsx:668-670): when no custom
+// `renderValue` is supplied, the trigger mirrors the selected option's full
+// content but hides anything that is NOT an icon/avatar/label slot (e.g. an
+// option `description`), so the trigger shows only the meaningful value slots.
+const pickerValueContents = css(
+  "&> :not([slot=icon], [slot=avatar], [slot=label], [data-slot=label]) {display: none;}",
+);
+
+const pickerChevron = style<{ size?: S2PickerSize; isLoading?: boolean }>({
+  size: {
+    size: {
+      S: 10,
+      M: 10,
+      L: 12,
+      XL: 14,
+    },
+  },
+  flexShrink: 0,
+  rotate: 90,
+  "--iconPrimary": {
+    type: "fill",
+    value: "currentColor",
+  },
+  color: {
+    isLoading: "disabled",
+  },
+});
+
+const pickerLoadingWrapper = style({
+  gridColumnStart: 1,
+  gridColumnEnd: -1,
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "center",
+  marginY: 8,
+});
+
+const pickerProgressCircle = style<{ size?: S2PickerSize }>({
+  size: {
+    size: {
+      S: 16,
+      M: 20,
+      L: 22,
+      XL: 26,
+    },
+  },
+});
+
+const pickerHelpText = style<PickerStyleProps>({
+  gridArea: "helptext",
+  display: "flex",
+  margin: 0,
+  alignItems: "baseline",
+  gap: "text-to-visual",
+  font: controlFont(),
+  color: {
+    default: "neutral-subdued",
+    isInvalid: {
+      default: "negative",
+      forcedColors: "Mark",
+    },
+    isDisabled: {
+      default: "disabled",
+      forcedColors: "GrayText",
+    },
+  },
+  contain: "inline-size",
+  paddingTop: "--field-gap",
+});
+
+const pickerListBox = style<SelectListBoxRenderProps & { size?: S2PickerSize }>({
+  width: "full",
+  boxSizing: "border-box",
+  maxHeight: "[inherit]",
+  overflowY: "auto",
+  overflowX: "hidden",
+  fontFamily: "sans",
+  fontSize: controlFont(),
+  outlineStyle: "none",
+  margin: 0,
+  listStyleType: "none",
+  padding: 8,
+});
+
+const pickerPopover = style({
+  ...setColorScheme(),
+  "--s2-container-bg": {
+    type: "backgroundColor",
+    value: {
+      default: "layer-2",
+      forcedColors: "Background",
+    },
+  },
+  backgroundColor: "--s2-container-bg",
+  // Glasselated: frost the scene behind the surface — the container bg is the
+  // translucent `--surface-card`; the blur is what makes it read as glass.
+  backdropFilter: "var(--blur-card)",
+  boxShadow: "elevated",
+  borderRadius: "panel",
+  display: "flex",
+  padding: 0,
+  minHeight: 0,
+  overflow: "visible",
+  boxSizing: "border-box",
+  isolation: "isolate",
+  outlineStyle: "solid",
+  outlineWidth: 1,
+  outlineColor: {
+    default: lightDark("transparent-white-25", "gray-200"),
+    forcedColors: "ButtonBorder",
+  },
+});
+
+const pickerListBoxFrame = style({
+  display: "flex",
+  width: "full",
+  height: "full",
+});
+
+const pickerOption = style<PickerOptionStyleProps>({
+  ...focusRing(),
+  ...control({ shape: "default", wrap: true, icon: true, register: "row" }),
+  columnGap: 0,
+  paddingX: 0,
+  paddingBottom: "--labelPadding",
+  // Glasselated: a register row is NEVER painted. The handoff's row primitive is
+  // `.tgl-nav`, shared by the nav and the list rows, and all five of its rules are
+  // ink or mark-opacity only (design-handoff-v2.css:434, :441, :445, :449, :453) —
+  // there is no background-color in any of rest / hover / selected. The row
+  // elements carry none inline either (TerminalGlassLab.tsx:593-602 nav rows,
+  // :1020-1030 list rows: display/gap/padding/border-radius/cursor/--nav-fg only).
+  // `baseColor("gray-100").isFocusVisible` baked an opaque ramp stop the register
+  // never draws, so state moves to ink below. Keyboard focus additionally keeps the
+  // outline from focusRing() above; `pickerListBox`'s `padding: 8` leaves room for
+  // its 2px width at 2px offset, so the ring is not clipped by that scroller's
+  // `overflowX: hidden`. No forced-colors branch is needed: this option sets no
+  // `forcedColorAdjust`, so high-contrast mode still paints its own highlight.
+  backgroundColor: "transparent",
+  color: {
+    default: baseColor("neutral"),
+    // Full-strength `accent`, NOT the handoff's literal hover value
+    // `color-mix(in srgb, var(--accent-primary) 55%, var(--text-tertiary))`
+    // (design-handoff-v2.css:454). Two deliberate deviations. The mix is calibrated
+    // for a nav row resting at `--text-tertiary` (NAV_ITEMS, TerminalGlassLab.tsx:67-69);
+    // an option here rests at full-strength neutral, so the mix would DIM the label
+    // on highlight. And full accent is the handoff's SELECTED-row ink
+    // (NAV_ITEMS[0], :66), so borrowing it for highlight collapses a distinction the
+    // nav draws — acceptable here only because a Picker option carries persistent
+    // selection in the checkmark (`pickerCheckmark` below), not in its label color.
+    isFocused: "accent",
+    isDisabled: {
+      default: "disabled",
+      forcedColors: "GrayText",
+    },
+  },
+  position: "relative",
+  gridColumnStart: 1,
+  gridColumnEnd: -1,
+  display: "grid",
+  gridTemplateAreas: [". checkmark icon label .", ". . . description ."],
+  gridTemplateColumns: {
+    size: {
+      S: [edgeToText(24), "auto", "auto", "minmax(0, 1fr)", edgeToText(24)],
+      M: [edgeToText(32), "auto", "auto", "minmax(0, 1fr)", edgeToText(32)],
+      L: [edgeToText(40), "auto", "auto", "minmax(0, 1fr)", edgeToText(40)],
+      XL: [edgeToText(48), "auto", "auto", "minmax(0, 1fr)", edgeToText(48)],
+    },
+  },
+  gridTemplateRows: {
+    default: "auto minmax(0, min-content)",
+    ":has([slot=description])": "auto auto",
+  },
+  rowGap: {
+    ":has([slot=description])": space(1),
+  },
+  alignItems: "baseline",
+  minHeight: controlSize(),
+  height: "min",
+  textDecoration: "none",
+  cursor: {
+    default: "default",
+    isDisabled: "default",
+  },
+  // Upstream `menuitem` (shared by Picker options) uses `transition: 'transform'`
+  // (transform-scoped, paired with `pressScale`), NOT the broad `'default'` set.
+  transition: "transform",
+});
+
+const pickerOptionLabel = style<{ size?: S2PickerSize }>({
+  gridArea: "label",
+  display: "block",
+  flexGrow: 1,
+  font: controlFont(),
+  color: "inherit",
+  fontWeight: "medium",
+  marginTop: "--labelPadding",
+  truncate: true,
+});
+
+const pickerCheckmark = style<PickerOptionStyleProps>({
+  gridArea: "checkmark",
+  visibility: {
+    default: "hidden",
+    isSelected: "visible",
+  },
+  color: baseColor("accent"),
+  marginEnd: "text-to-control",
+  aspectRatio: "square",
+  flexShrink: 0,
+  "--iconPrimary": {
+    type: "fill",
+    value: {
+      default: "currentColor",
+      forcedColors: {
+        default: "Highlight",
+        isFocused: "HighlightText",
+      },
+    },
+  },
+});
+
+const fieldErrorIcon = style({
+  size: fontRelative(20),
+  marginStart: "text-to-visual",
+  marginEnd: fontRelative(-2),
+  flexShrink: 0,
+  "--iconPrimary": {
+    type: "fill",
+    value: {
+      default: "negative",
+      forcedColors: "Mark",
+    },
+  },
+});
+
+const requiredIcon = style({
+  "--iconPrimary": {
+    type: "fill",
+    value: "currentColor",
+  },
+});
+
+const noWrap = style({
+  whiteSpace: "nowrap",
+});
+
+function isPrimitiveText(value: unknown): value is string | number {
+  return typeof value === "string" || typeof value === "number";
+}
+
+function isTextOnlyChildren(value: unknown): boolean {
+  return isPrimitiveText(value) || (Array.isArray(value) && value.every(isPrimitiveText));
+}
+
+function normalizePickerSize(size: PickerSize | undefined): S2PickerSize {
+  switch (size) {
+    case "S":
+    case "M":
+    case "L":
+    case "XL":
+      return size;
+    default:
+      return "M";
+  }
+}
+
+function requiredIconStyle(size: S2PickerSize): JSX.CSSProperties {
+  const pixelSize = size === "L" || size === "XL" ? 10 : 8;
+  return {
+    width: `${pixelSize}px`,
+    height: `${pixelSize}px`,
+  };
+}
+
+function pickerCheckmarkIconStyle(size: S2PickerSize): JSX.CSSProperties {
+  const pixelSize = size === "XL" ? 14 : size === "L" ? 12 : 10;
+  return {
+    width: `${pixelSize}px`,
+    height: `${pixelSize}px`,
+  };
+}
+
+function pickerMenuOffset(size: S2PickerSize): number {
+  switch (size) {
+    case "S":
+    case "M":
+      return 6;
+    case "L":
+      return 7;
+    case "XL":
+      return 8;
+  }
+}
+
+function PickerListBoxPopover(props: {
+  size: () => S2PickerSize;
+  isQuiet: () => boolean;
+  direction: () => PickerDirection;
+  align: () => PickerAlign;
+  menuWidth: () => number | undefined;
+  shouldFlip: () => boolean;
+  children: JSX.Element;
+}) {
+  const theme = useTheme();
+  const selectContext = useContext(HeadlessSelectContext) as {
+    state?: { close?: () => void };
+    isOpen?: () => boolean;
+    triggerRef?: () => HTMLElement | null;
+    rootRef?: () => HTMLElement | null;
+  } | null;
+  const triggerRef = () =>
+    selectContext?.triggerRef?.() ??
+    selectContext?.rootRef?.()?.querySelector<HTMLElement>("button[aria-haspopup='listbox']") ??
+    null;
+  const [triggerWidth, setTriggerWidth] = createSignal<string | undefined>();
+
+  const updateTriggerWidth = () => {
+    const trigger = triggerRef();
+    if (trigger) {
+      setTriggerWidth(`${trigger.getBoundingClientRect().width}px`);
+    }
+  };
+
+  createEffect(() => {
+    const trigger = triggerRef();
+    if (!trigger) {
+      setTriggerWidth(undefined);
+      return;
+    }
+
+    updateTriggerWidth();
+    if (typeof ResizeObserver === "undefined") {
+      return;
+    }
+
+    const resizeObserver = new ResizeObserver(updateTriggerWidth);
+    resizeObserver.observe(trigger);
+    onCleanup(() => resizeObserver.disconnect());
+  });
+
+  const resolvedTriggerWidth = () => {
+    const explicitMenuWidth = props.menuWidth();
+    if (explicitMenuWidth != null) {
+      return `${explicitMenuWidth}px`;
+    }
+
+    const measuredWidth = triggerWidth();
+    if (measuredWidth) {
+      return measuredWidth;
+    }
+
+    const trigger = triggerRef();
+    return trigger ? `${trigger.getBoundingClientRect().width}px` : undefined;
+  };
+
+  return (
+    <HeadlessPopover
+      trigger="Select"
+      triggerRef={triggerRef}
+      isOpen={selectContext?.isOpen?.() ?? false}
+      onOpenChange={(open) => {
+        if (!open) {
+          selectContext?.state?.close?.();
+        }
+      }}
+      placement={`${props.direction()} ${props.align()}`}
+      offset={pickerMenuOffset(props.size())}
+      crossOffset={props.isQuiet() ? -12 : undefined}
+      shouldFlip={props.shouldFlip()}
+      autoFocus={false}
+      class={(renderProps) =>
+        pickerPopover({
+          ...renderProps,
+          colorScheme: theme.colorScheme,
+          isArrowShown: false,
+          isSubmenu: false,
+        })
+      }
+      style={() => ({
+        "--trigger-width": resolvedTriggerWidth(),
+        minWidth: props.isQuiet() ? "192px" : "var(--trigger-width)",
+        width: props.isQuiet() ? "calc(var(--trigger-width) - 24px)" : "var(--trigger-width)",
+      })}
+    >
+      <div class={pickerListBoxFrame}>{props.children}</div>
+    </HeadlessPopover>
+  );
+}
+
+function PickerLabel(props: {
+  id?: string;
+  label: JSX.Element;
+  size: S2PickerSize;
+  isDisabled: boolean;
+  isRequired: boolean;
+  labelPosition: PickerLabelPosition;
+  labelAlign: PickerLabelAlign;
+  necessityIndicator: PickerNecessityIndicator;
+  contextualHelp?: JSX.Element;
+}) {
+  return (
+    <span
+      class={pickerLabelWrapper({
+        size: props.size,
+        isDisabled: props.isDisabled,
+        isRequired: props.isRequired,
+        labelPosition: props.labelPosition,
+        labelAlign: props.labelAlign,
+        isStaticColor: false,
+      })}
+    >
+      <span
+        id={props.id}
+        class={pickerLabel({
+          size: props.size,
+          isDisabled: props.isDisabled,
+          isRequired: props.isRequired,
+          labelPosition: props.labelPosition,
+          labelAlign: props.labelAlign,
+          isStaticColor: false,
+        })}
+      >
+        {props.label}
+        <Show when={props.isRequired || props.necessityIndicator === "label"}>
+          <span class={noWrap}>
+            &nbsp;
+            <Show
+              when={props.necessityIndicator === "icon"}
+              fallback={
+                <span aria-hidden={props.isRequired ? true : undefined}>
+                  {props.isRequired ? "(required)" : "(optional)"}
+                </span>
+              }
+            >
+              <AsteriskIcon
+                size={props.size === "S" ? "M" : props.size}
+                styles={requiredIcon}
+                style={requiredIconStyle(props.size)}
+                aria-hidden="true"
+              />
+            </Show>
+          </span>
+        </Show>
+      </span>
+      <Show when={props.contextualHelp}>
+        <span data-slot="contextualHelp">{props.contextualHelp}</span>
+      </Show>
+    </span>
+  );
+}
+
+function selectedValues<T>(valueProps: SelectValueRenderProps<T>): T[] {
+  return valueProps.selectedItems
+    .map((item) => item.value ?? (item as unknown as T))
+    .filter((item): item is T => item != null);
+}
+
+function pickerValueContent<T>(
+  valueProps: SelectValueRenderProps<T>,
+  renderValue: ((selectedItems: T[]) => JSX.Element) | undefined,
+  renderItem: (item: T) => JSX.Element,
+) {
+  // Upstream wraps a custom `renderValue` in `<div style={{display:'contents'}}>`
+  // (Picker.tsx:743) so it lays out transparently in the flex value container.
+  // `InsidePickerValueContext` lets any `PickerItem` inside a custom `renderValue`
+  // back off its option chrome (checkmark/press-scale), matching upstream's
+  // `InsideSelectValueContext`/`DefaultProvider` handshake (Picker.tsx:864-880).
+  if (valueProps.selectedItems.length > 0 && renderValue) {
+    return (
+      <InsidePickerValueContext.Provider value={true}>
+        <div style={{ display: "contents" }}>{renderValue(selectedValues(valueProps))}</div>
+      </InsidePickerValueContext.Provider>
+    );
+  }
+
+  // Multiple selection collapses to an "N selected" summary (Picker.tsx:677-682),
+  // rendered in the label slot so the trigger's slot-hiding css keeps it.
+  if (valueProps.selectedItems.length > 1) {
+    return (
+      <span slot="label" class={pickerValueText}>
+        {`${valueProps.selectedItems.length} selected`}
+      </span>
+    );
+  }
+
+  // Single selection mirrors the option's FULL rendered content (icon/avatar +
+  // label), not just its text — upstream's `defaultChildren` is `rendered[0]` =
+  // the selected item's children (Picker.tsx:374-392). We reconstruct that by
+  // re-rendering the item through the same render function the listbox uses,
+  // inside `InsidePickerValueContext` so `PickerItem` emits content-only.
+  const selected = valueProps.selectedItems[0];
+  if (selected != null && selected.value != null) {
+    return (
+      <InsidePickerValueContext.Provider value={true}>
+        {renderItem(selected.value as T)}
+      </InsidePickerValueContext.Provider>
+    );
+  }
+
+  // No selection: the placeholder text (block, flex-grow:1, truncate). Slotted so
+  // the trigger's slot-hiding css keeps it visible; `pickerValue`'s
+  // `[data-placeholder]` selector still paints the muted placeholder color.
+  return (
+    <span slot="label" class={pickerValueText}>
+      {valueProps.placeholder ?? ""}
+    </span>
+  );
+}
+
+function loadingSpinnerLabel(loadingState: PickerLoadingState | undefined) {
+  return loadingState === "loadingMore" ? "Loading more" : "Loading";
+}
+
+function PickerProgressCircle(props: {
+  size: S2PickerSize;
+  loadingState: PickerLoadingState | undefined;
+}) {
+  return (
+    <ProgressCircle
+      aria-label={loadingSpinnerLabel(props.loadingState)}
+      isIndeterminate
+      size="S"
+      styles={pickerProgressCircle({ size: props.size })}
+    />
+  );
+}
+
+export function Picker<T>(props: PickerProps<T>): JSX.Element {
+  const defaultProps: Partial<PickerProps<T>> = {
+    labelPosition: "top",
+    labelAlign: "start",
+    necessityIndicator: "icon",
+    direction: "bottom",
+    align: "start",
+    shouldFlip: true,
+  };
+  const contextProps = getSlottedContextProps(useContext(PickerContext), props.slot);
+  const mergedProps = mergeProps(defaultProps, useProviderProps(props), contextProps ?? {}, props);
+  const [local, headlessProps] = splitProps(mergedProps, [
+    "size",
+    "isQuiet",
+    "styles",
+    "UNSAFE_className",
+    "UNSAFE_style",
+    "class",
+    "label",
+    "description",
+    "errorMessage",
+    "isInvalid",
+    "labelPosition",
+    "labelAlign",
+    "necessityIndicator",
+    "contextualHelp",
+    "direction",
+    "align",
+    "menuWidth",
+    "shouldFlip",
+    "loadingState",
+    "onLoadMore",
+    "renderValue",
+    "children",
+  ]);
+
+  const size = () => normalizePickerSize(local.size);
+  const labelPosition = () => local.labelPosition ?? "top";
+  const labelAlign = () => local.labelAlign ?? "start";
+  const necessityIndicator = () => local.necessityIndicator ?? "icon";
+  const direction = () => local.direction ?? "bottom";
+  const align = () => local.align ?? "start";
+  const shouldFlip = () => local.shouldFlip ?? true;
+  const isQuiet = () => local.isQuiet === true;
+  const isInvalid = () => local.isInvalid === true;
+  const isTriggerLoading = () => local.loadingState === "loading";
+  const isLoadingMore = () => local.loadingState === "loadingMore";
+  const propsRecord = () => headlessProps as Record<string, unknown>;
+  const isMultiple = () => propsRecord().selectionMode === "multiple";
+  const selectedKey = () => propsRecord().selectedKey as Key | null | undefined;
+  const defaultSelectedKey = () => propsRecord().defaultSelectedKey as Key | null | undefined;
+  const selectedKeys = () => propsRecord().selectedKeys as "all" | Iterable<Key> | undefined;
+  const defaultSelectedKeys = () =>
+    propsRecord().defaultSelectedKeys as "all" | Iterable<Key> | undefined;
+  const onSelectionChange = () =>
+    propsRecord().onSelectionChange as ((key: Key | null) => void) | undefined;
+  const onSelectionChangeKeys = () =>
+    propsRecord().onSelectionChangeKeys as ((keys: "all" | Set<Key>) => void) | undefined;
+  const selectProps = mergeProps(headlessProps, {
+    get selectedKey() {
+      return isMultiple() ? undefined : selectedKey();
+    },
+    get defaultSelectedKey() {
+      return isMultiple() ? undefined : defaultSelectedKey();
+    },
+    get selectedKeys() {
+      return isMultiple() ? selectedKeys() : propsRecord().selectedKeys;
+    },
+    get defaultSelectedKeys() {
+      return isMultiple() ? defaultSelectedKeys() : propsRecord().defaultSelectedKeys;
+    },
+    get onSelectionChange() {
+      return isMultiple() ? undefined : onSelectionChange();
+    },
+    get onSelectionChangeKeys() {
+      return isMultiple() ? onSelectionChangeKeys() : undefined;
+    },
+  });
+  const descriptionId = createUniqueId();
+  const labelId = createUniqueId();
+  const [triggerEl, setTriggerEl] = createSignal<HTMLButtonElement | null>(null);
+  const selectDescribedBy = () => {
+    const explicitDescribedBy = (headlessProps as Record<string, unknown>)["aria-describedby"] as
+      | string
+      | undefined;
+    const ids = [explicitDescribedBy, local.description && !isInvalid() ? descriptionId : undefined]
+      .filter(Boolean)
+      .join(" ")
+      .split(" ")
+      .filter(Boolean);
+    return ids.length ? Array.from(new Set(ids)).join(" ") : undefined;
+  };
+
+  const rootClass = (renderProps: SelectRenderProps) =>
+    [
+      local.UNSAFE_className,
+      local.class,
+      pickerRoot(
+        {
+          ...renderProps,
+          size: size(),
+          labelPosition: labelPosition(),
+          isQuiet: isQuiet(),
+          isInvalid: isInvalid(),
+          isInForm: false,
+        },
+        local.styles,
+      ),
+    ]
+      .filter(Boolean)
+      .join(" ");
+
+  const labelContent = (renderProps: SelectRenderProps) =>
+    local.label ? (
+      <PickerLabel
+        id={labelId}
+        label={local.label}
+        size={size()}
+        isDisabled={renderProps.isDisabled}
+        isRequired={renderProps.isRequired}
+        labelPosition={labelPosition()}
+        labelAlign={labelAlign()}
+        necessityIndicator={necessityIndicator()}
+        contextualHelp={local.contextualHelp}
+      />
+    ) : undefined;
+
+  const helpClass = (renderProps: SelectRenderProps) =>
+    pickerHelpText({
+      isDisabled: renderProps.isDisabled,
+      isRequired: renderProps.isRequired,
+      isSelected: renderProps.isSelected,
+      size: size(),
+      isInvalid: isInvalid(),
+    });
+  // Labelling mirrors upstream `useSelect`: a REAL visible label is associated by
+  // id (`aria-labelledby` → `labelId`), letting the headless hook fold the value
+  // into the trigger name ("Pro Plan") while the listbox is named by the label
+  // alone ("Plan"). We only synthesize an `aria-label` when there is NO visible
+  // label (nothing to point at) — using the caller's explicit `aria-label` if
+  // given. Previously the port ALWAYS synthesized "value + label" as an
+  // `aria-label`, which leaked the selected value onto the listbox name.
+  const ariaLabel = () => {
+    const propsRecord = headlessProps as Record<string, unknown>;
+    const explicitLabel = propsRecord["aria-label"];
+    if (typeof explicitLabel === "string") {
+      return explicitLabel;
+    }
+    return undefined;
+  };
+  const ariaLabelledBy = () => {
+    const explicitLabelledBy = (headlessProps as Record<string, unknown>)["aria-labelledby"] as
+      | string
+      | undefined;
+    if (!local.label) {
+      return explicitLabelledBy;
+    }
+    return [explicitLabelledBy, labelId].filter(Boolean).join(" ") || undefined;
+  };
+
+  const listBoxChildren = (item: T) => {
+    if (typeof local.children === "function") {
+      return local.children(item);
+    }
+
+    const propsRecord = headlessProps as Record<string, unknown>;
+    const getKey = propsRecord.getKey as ((item: T) => Key) | undefined;
+    const getTextValue = propsRecord.getTextValue as ((item: T) => string) | undefined;
+    const itemRecord = item as Record<string, unknown>;
+    const key = (getKey?.(item) ?? itemRecord.key ?? itemRecord.id ?? String(item)) as Key;
+    const textValue = String(
+      getTextValue?.(item) ?? itemRecord.textValue ?? itemRecord.label ?? item,
+    );
+    const label = (itemRecord.label ?? textValue) as JSX.Element;
+    return (
+      <PickerItem id={key} item={item} textValue={textValue}>
+        {label}
+      </PickerItem>
+    );
+  };
+
+  return (
+    <PickerSizeContext.Provider value={size()}>
+      <HeadlessSelect
+        {...selectProps}
+        aria-label={ariaLabel()}
+        aria-labelledby={ariaLabelledBy()}
+        aria-describedby={selectDescribedBy()}
+        isInvalid={isInvalid()}
+        class={rootClass}
+        style={local.UNSAFE_style}
+        children={(renderProps) => (
+          <>
+            <Show when={local.label}>{labelContent(renderProps)}</Show>
+            <HeadlessSelectTrigger
+              ref={setTriggerEl}
+              class={(triggerProps) =>
+                pickerTrigger({
+                  ...triggerProps,
+                  size: size(),
+                  isQuiet: isQuiet(),
+                  isInvalid: isInvalid(),
+                })
+              }
+              // Faithful to upstream S2 `Picker` (`style={pressScale(buttonRef)}`):
+              // the trigger carries the Spectrum press-scale effect, which also
+              // emits the resting `will-change: transform` hint.
+              style={(triggerProps) => pressScale(() => triggerEl())(triggerProps)}
+            >
+              {(triggerProps) => (
+                <>
+                  <HeadlessSelectValue
+                    class={(valueProps) =>
+                      pickerValue({
+                        ...valueProps,
+                        isQuiet: isQuiet(),
+                      }) + (local.renderValue ? "" : " " + pickerValueContents)
+                    }
+                  >
+                    {(valueProps) =>
+                      pickerValueContent(valueProps, local.renderValue, listBoxChildren)
+                    }
+                  </HeadlessSelectValue>
+                  <Show when={isInvalid() && !triggerProps.isDisabled}>
+                    <CenterBaseline>
+                      <AlertTriangleIcon styles={fieldErrorIcon} />
+                    </CenterBaseline>
+                  </Show>
+                  <Show when={isTriggerLoading() && !triggerProps.isOpen}>
+                    <CenterBaseline>
+                      <PickerProgressCircle size={size()} loadingState={local.loadingState} />
+                    </CenterBaseline>
+                  </Show>
+                  {/* Faithful to upstream S2 `Picker.tsx` (the ChevronIcon carries
+                      NO `aria-hidden`), the trigger chevron is exposed as an `img`
+                      in the AX tree — mirroring the selected-option checkmark. */}
+                  <ChevronIcon
+                    size={size()}
+                    styles={pickerChevron({ size: size(), isLoading: isTriggerLoading() })}
+                    data-open={triggerProps.isOpen ? "true" : undefined}
+                  />
+                  <Show when={triggerProps.isFocusVisible && isQuiet()}>
+                    <span class={quietFocusLine} />
+                  </Show>
+                  <Show when={isInvalid() && !triggerProps.isDisabled && !isQuiet()}>
+                    <div
+                      class={pickerInvalidBorder({
+                        ...triggerProps,
+                        size: size(),
+                        isQuiet: isQuiet(),
+                        isInvalid: isInvalid(),
+                      })}
+                    />
+                  </Show>
+                </>
+              )}
+            </HeadlessSelectTrigger>
+            <Show when={local.description && !isInvalid()}>
+              <p id={descriptionId} class={helpClass(renderProps)}>
+                {local.description}
+              </p>
+            </Show>
+            <Show when={local.errorMessage && isInvalid()}>
+              <HeadlessFieldError class={helpClass(renderProps)}>
+                {local.errorMessage}
+              </HeadlessFieldError>
+            </Show>
+            <PickerListBoxPopover
+              size={size}
+              isQuiet={isQuiet}
+              direction={direction}
+              align={align}
+              menuWidth={() => local.menuWidth}
+              shouldFlip={shouldFlip}
+            >
+              <HeadlessSelectListBox
+                isInPopover
+                class={(listBoxProps) => pickerListBox({ ...listBoxProps, size: size() })}
+                onLoadMore={local.onLoadMore}
+                isLoading={isLoadingMore()}
+                loadMoreClass={pickerLoadingWrapper}
+                renderLoadMore={() =>
+                  isLoadingMore() ? (
+                    <PickerProgressCircle size={size()} loadingState={local.loadingState} />
+                  ) : undefined
+                }
+              >
+                {listBoxChildren}
+              </HeadlessSelectListBox>
+            </PickerListBoxPopover>
+          </>
+        )}
+      />
+    </PickerSizeContext.Provider>
+  );
+}
+
+export function PickerItem<T>(props: PickerItemProps<T>): JSX.Element {
+  const [local, headlessProps] = splitProps(props, [
+    "UNSAFE_className",
+    "UNSAFE_style",
+    "class",
+    "styles",
+    "children",
+  ]);
+  const size = useContext(PickerSizeContext);
+  const insideValue = useContext(InsidePickerValueContext);
+  const [optionEl, setOptionEl] = createSignal<HTMLDivElement | null>(null);
+
+  // Trigger/value mode: mirror upstream, where `SelectValue`'s default children
+  // are the selected item's *content* (`item.props.children`), not a rendered
+  // option row. Emit only the slotted content — no `HeadlessSelectOption`
+  // wrapper, checkmark, or press-scale — so the trigger shows icon/avatar/label.
+  // A bare text child is wrapped in the label slot (block/flex-grow/truncate),
+  // matching upstream's `<Text slot="label">` (Picker.tsx:854 → TextContext).
+  if (insideValue) {
+    return (
+      <>
+        {isTextOnlyChildren(local.children) ? (
+          <span slot="label" class={pickerValueText} data-rsp-slot="text">
+            {local.children}
+          </span>
+        ) : (
+          local.children
+        )}
+      </>
+    );
+  }
+
+  const optionClass = (renderProps: SelectOptionRenderProps) =>
+    [
+      local.UNSAFE_className,
+      local.class,
+      pickerOption(
+        {
+          ...renderProps,
+          size,
+        },
+        local.styles,
+      ),
+    ]
+      .filter(Boolean)
+      .join(" ");
+
+  return (
+    <HeadlessSelectOption
+      {...headlessProps}
+      ref={setOptionEl}
+      class={optionClass}
+      // Faithful to upstream S2 `Picker` (`style={pressScale(ref, props.UNSAFE_style)}`):
+      // options carry the press-scale effect + resting `will-change: transform`.
+      style={pressScale(() => optionEl(), local.UNSAFE_style)}
+    >
+      {(renderProps) => (
+        <>
+          <CheckmarkIcon
+            size={size === "S" ? "XS" : size}
+            // Mirror upstream S2 `Picker` (Picker.tsx): the checkmark style is
+            // applied via `className`, NOT the icon `styles` override. The icon
+            // `styles` path filters overrides through `iconAllowedOverrides`,
+            // which (faithfully) omits `visibility` — routing the checkmark
+            // through it silently strips the `visibility: { default: hidden,
+            // isSelected: visible }` atom, leaving the checkmark visible on
+            // every option. Upstream's hand-written ui-icon Checkmark applies
+            // the caller's `className` raw; our `class` prop is the raw path.
+            class={pickerCheckmark({ ...renderProps, size })}
+            style={pickerCheckmarkIconStyle(size)}
+            // No `aria-hidden`: upstream S2 `Picker` renders the selected-option
+            // checkmark as a bare `<CheckmarkIcon>` with NO `aria-hidden`, so the
+            // selected row exposes the checkmark as an `img` node in the AX tree
+            // (D6). Unselected rows' checkmarks are `visibility: hidden`, so they
+            // are pruned from the tree automatically — matching the React oracle.
+          />
+          {isTextOnlyChildren(local.children) ? (
+            <span slot="label" class={pickerOptionLabel({ size })} data-rsp-slot="text">
+              {local.children}
+            </span>
+          ) : (
+            local.children
+          )}
+        </>
+      )}
+    </HeadlessSelectOption>
+  );
+}
+
+export interface PickerSectionProps<T> extends Omit<
+  HeadlessListBoxSectionProps,
+  "style" | "class" | "render"
+> {}
+
+/**
+ * A section within a `<Picker>`, mirroring React S2's `PickerSection`. Renders a
+ * headless list-box section followed by a size-matched `<Divider>`; the size is
+ * read from the internal picker context.
+ */
+export function PickerSection<T>(props: PickerSectionProps<T>): JSX.Element {
+  const size = useContext(PickerSizeContext);
+  return (
+    <>
+      <HeadlessListBoxSection {...props}>{props.children}</HeadlessListBoxSection>
+      <Divider size={size} />
+    </>
+  );
+}
+
+export const Item = PickerItem;
+export type { Key };