feat(ui): Add phone input

.changeset/calm-combs-search.md

@@ -0,0 +1,2 @@
+---
+---

.changeset/warm-taxis-call.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/popover/popover-positioner.tsx

@@ -6,11 +6,14 @@ import React from 'react';
 import { type ComponentProps, type DefaultProps, isKeyboardOpen, mergeProps, useRender } from '../../utils';
 import { usePopoverContext } from './popover-context';
 
-export type PopoverPositionerProps = ComponentProps<'div'>;
+export interface PopoverPositionerProps extends ComponentProps<'div'> {
+  /** Positions against this element instead of the trigger. */
+  anchor?: HTMLElement | null;
+}
 
 export const PopoverPositioner = React.forwardRef<HTMLDivElement, PopoverPositionerProps>(
   function PopoverPositioner(props, ref) {
-    const { render, ...otherProps } = props;
+    const { anchor, render, ...otherProps } = props;
     const {
       mounted,
       floatingContext,
@@ -27,6 +30,14 @@ export const PopoverPositioner = React.forwardRef<HTMLDivElement, PopoverPositio
       hasDescription,
     } = usePopoverContext();
 
+    React.useLayoutEffect(() => {
+      if (!anchor) {
+        return;
+      }
+      refs.setPositionReference(anchor);
+      return () => refs.setPositionReference(refs.domReference.current);
+    }, [anchor, refs]);
+
     const side = placement.split('-')[0];
 
     const ownProps = {

packages/swingset/src/components/DocsViewer.tsx

@@ -46,8 +46,10 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
     banner: dynamic(() => import('../stories/banner.mdx')),
     button: dynamic(() => import('../stories/button.mdx')),
     card: dynamic(() => import('../stories/card.component.mdx')),
+    combobox: dynamic(() => import('../stories/combobox.mdx')),
     input: dynamic(() => import('../stories/input.mdx')),
     'input-group': dynamic(() => import('../stories/input-group.mdx')),
+    'phone-input': dynamic(() => import('../stories/phone-input.mdx')),
     item: dynamic(() => import('../stories/item.mdx')),
     dialog: dynamic(() => import('../stories/dialog.component.mdx')),
     drawer: dynamic(() => import('../stories/drawer.component.mdx')),

packages/swingset/src/lib/registry.ts

@@ -26,6 +26,11 @@ import { Disabled, meta as buttonMeta, Primary, Sizes } from '../stories/button.
 import { Default as CardDefault, meta as cardComponentMeta } from '../stories/card.component.stories';
 import { meta as collapsibleMeta } from '../stories/collapsible.stories';
 import { meta as comboboxPrimitiveMeta } from '../stories/combobox.primitive.stories';
+import {
+  Default as ComboboxDefault,
+  meta as comboboxMeta,
+  Scrolling as ComboboxScrolling,
+} from '../stories/combobox.stories';
 import {
   Default as DestructiveDefault,
   meta as destructiveMeta,
@@ -100,6 +105,14 @@ import {
   Success as OtpComponentSuccess,
 } from '../stories/otp.component.stories';
 import { meta as otpMeta } from '../stories/otp.stories';
+import {
+  Default as PhoneInputDefault,
+  Disabled as PhoneInputDisabled,
+  Invalid as PhoneInputInvalid,
+  meta as phoneInputMeta,
+  Prefilled as PhoneInputPrefilled,
+  Sizes as PhoneInputSizes,
+} from '../stories/phone-input.stories';
 import {
   Alignment as PopoverComponentAlignment,
   Default as PopoverComponentDefault,
@@ -266,6 +279,12 @@ const drawerComponentModule: StoryModule = {
 
 const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault };
 
+const comboboxModule: StoryModule = {
+  meta: comboboxMeta,
+  Default: ComboboxDefault,
+  Scrolling: ComboboxScrolling,
+};
+
 const avatarModule: StoryModule = {
   meta: avatarMeta,
   Primary: AvatarPrimary,
@@ -309,6 +328,15 @@ const inputGroupModule: StoryModule = {
   Invalid: InputGroupInvalid,
 };
 
+const phoneInputModule: StoryModule = {
+  meta: phoneInputMeta,
+  Default: PhoneInputDefault,
+  Sizes: PhoneInputSizes,
+  Prefilled: PhoneInputPrefilled,
+  Disabled: PhoneInputDisabled,
+  Invalid: PhoneInputInvalid,
+};
+
 const popoverComponentModule: StoryModule = {
   meta: popoverComponentMeta,
   Default: PopoverComponentDefault,
@@ -556,9 +584,11 @@ export const registry: StoryModule[] = [
   bannerModule,
   buttonModule,
   cardComponentModule,
+  comboboxModule,
   flowComponentModule,
   inputModule,
   inputGroupModule,
+  phoneInputModule,
   itemModule,
   dialogComponentModule,
   drawerComponentModule,

packages/swingset/src/stories/combobox.mdx

@@ -0,0 +1,57 @@
+import * as ComboboxStories from './combobox.stories';
+
+# Combobox
+
+## Example
+
+<Story
+  name='Default'
+  storyModule={ComboboxStories}
+/>
+
+`value` is the selected option; `inputValue` is the search text. Clearing the input clears the selection.
+
+## Inline lists
+
+Use `List` inside an existing popover. Set `inline` and bind the root's open state to that popover
+so closing resets the search, not the selection.
+
+```tsx
+<Combobox.Root inline open={open} onOpenChange={setOpen} value={country} onValueChange={setCountry}>
+  <InputGroup.Root>
+    <InputGroup.Start>
+      <Icon name='search' aria-hidden='true' />
+    </InputGroup.Start>
+    <Combobox.Input aria-label='Search countries' />
+  </InputGroup.Root>
+  <Combobox.List>
+    <Combobox.Collection items={countries} itemToStringLabel={country => country.name}>
+      {country => (
+        <Combobox.Option key={country.iso} value={country.iso} label={country.name}>
+          {country.name}
+        </Combobox.Option>
+      )}
+    </Combobox.Collection>
+  </Combobox.List>
+</Combobox.Root>
+```
+
+## Scrolling
+
+<Story
+  name='Scrolling'
+  storyModule={ComboboxStories}
+/>
+
+## Parts
+
+| Part                  | Description                                                                 |
+| --------------------- | --------------------------------------------------------------------------- |
+| `Combobox.Root`       | Owns input, selection, open state, and keyboard navigation.                 |
+| `Combobox.Input`      | Search input; renders Mosaic `Input` unless composed through another input. |
+| `Combobox.Trigger`    | Opens and closes the option list while keeping focus on the input.          |
+| `Combobox.Popup`      | Portals, positions, surfaces, and scrolls a floating option list.           |
+| `Combobox.List`       | Scrollable inline listbox.                                                  |
+| `Combobox.Collection` | Filters items and renders each option, with an optional empty state.        |
+| `Combobox.Option`     | Selectable option with active, selected, and disabled states.               |
+| `Combobox.Empty`      | Empty result message.                                                       |

packages/swingset/src/stories/combobox.stories.tsx

@@ -0,0 +1,108 @@
+'use client';
+
+import { Button } from '@clerk/ui/mosaic/components/button';
+import { Combobox } from '@clerk/ui/mosaic/components/combobox';
+import { Field } from '@clerk/ui/mosaic/components/field';
+import { Icon } from '@clerk/ui/mosaic/components/icon';
+import { InputGroup } from '@clerk/ui/mosaic/components/input-group';
+
+import type { StoryMeta } from '@/lib/types';
+
+export { default as __source } from './combobox.stories?raw';
+
+export const meta: StoryMeta = {
+  group: 'Components',
+  status: 'wip',
+  title: 'Combobox',
+  source: 'packages/ui/src/mosaic/components/combobox/combobox.tsx',
+};
+
+export function Default() {
+  const options = ['Apple', 'Apricot', 'Banana', 'Blackberry', 'Cherry', 'Fig', 'Grape', 'Pear', 'Plum'];
+
+  return (
+    <Combobox.Root>
+      <Field.Root style={{ width: 320 }}>
+        <Field.Label>Fruit</Field.Label>
+        <InputGroup.Root>
+          <Combobox.Input placeholder='Search fruit…' />
+          <InputGroup.End>
+            <Combobox.Trigger
+              aria-label='Toggle fruit options'
+              render={<Button />}
+            >
+              <Icon
+                name='chevron-down'
+                size='sm'
+                aria-hidden='true'
+              />
+            </Combobox.Trigger>
+          </InputGroup.End>
+        </InputGroup.Root>
+      </Field.Root>
+      <Combobox.Popup>
+        <Combobox.Collection
+          items={options}
+          itemToStringLabel={option => option}
+          empty={<Combobox.Empty>No fruit found</Combobox.Empty>}
+        >
+          {option => (
+            <Combobox.Option
+              key={option}
+              value={option.toLowerCase()}
+              label={option}
+            >
+              {option}
+              <Combobox.OptionIndicator />
+            </Combobox.Option>
+          )}
+        </Combobox.Collection>
+      </Combobox.Popup>
+    </Combobox.Root>
+  );
+}
+
+export function Scrolling() {
+  const options = Array.from({ length: 40 }, (_, index) => `Fruit ${index + 1}`);
+
+  return (
+    <Combobox.Root>
+      <Field.Root style={{ width: 320 }}>
+        <Field.Label>Fruit</Field.Label>
+        <InputGroup.Root>
+          <Combobox.Input placeholder='Search fruit…' />
+          <InputGroup.End>
+            <Combobox.Trigger
+              aria-label='Toggle fruit options'
+              render={<Button />}
+            >
+              <Icon
+                name='chevron-down'
+                size='sm'
+                aria-hidden='true'
+              />
+            </Combobox.Trigger>
+          </InputGroup.End>
+        </InputGroup.Root>
+      </Field.Root>
+      <Combobox.Popup>
+        <Combobox.Collection
+          items={options}
+          itemToStringLabel={option => option}
+          empty={<Combobox.Empty>No fruit found</Combobox.Empty>}
+        >
+          {option => (
+            <Combobox.Option
+              key={option}
+              value={option.toLowerCase()}
+              label={option}
+            >
+              {option}
+              <Combobox.OptionIndicator />
+            </Combobox.Option>
+          )}
+        </Combobox.Collection>
+      </Combobox.Popup>
+    </Combobox.Root>
+  );
+}

packages/swingset/src/stories/phone-input.mdx

@@ -0,0 +1,72 @@
+import * as PhoneInputStories from './phone-input.stories';
+
+# PhoneInput
+
+The `PhoneInput` combines a searchable country picker and native telephone input into one Mosaic field while exposing a normalized E.164 value.
+
+It composes `InputGroup` for the telephone field and the inline `Combobox` composition for the country search inside its `Popover`.
+
+## Playground
+
+<Preview
+  name='Default'
+  storyModule={PhoneInputStories}
+/>
+
+## Props
+
+<PropTable
+  meta={PhoneInputStories.meta}
+  extra={[
+    { name: 'value', type: 'string', default: '—' },
+    { name: 'defaultValue', type: 'string', default: "''" },
+    { name: 'onValueChange', type: '(value: string) => void', default: '—' },
+    { name: 'country', type: 'CountryIso', default: '—' },
+    { name: 'defaultCountry', type: 'CountryIso', default: "'us'" },
+    { name: 'onCountryChange', type: '(country: CountryIso) => void', default: '—' },
+    { name: 'countrySearchPlaceholder', type: 'string', default: "'Search country or code'" },
+    { name: 'noResultsMessage', type: 'string', default: "'No countries found'" },
+  ]}
+/>
+
+`value` and `defaultValue` use E.164. `onValueChange` reports that normalized value while the visible input formats the national number. Control `country` separately when countries share a calling code.
+
+## Usage
+
+<Usage
+  component='PhoneInput'
+  module='@clerk/ui/mosaic/components/phone-input'
+  props={{ name: 'phoneNumber', placeholder: '202 555 0123' }}
+/>
+
+---
+
+## Examples
+
+### Sizes
+
+<Story
+  name='Sizes'
+  storyModule={PhoneInputStories}
+/>
+
+### Prefilled international number
+
+<Story
+  name='Prefilled'
+  storyModule={PhoneInputStories}
+/>
+
+### Disabled
+
+<Story
+  name='Disabled'
+  storyModule={PhoneInputStories}
+/>
+
+### Invalid
+
+<Story
+  name='Invalid'
+  storyModule={PhoneInputStories}
+/>