@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/PhoneInput/PhoneInput.tsx

@@ -0,0 +1,271 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  useId,
+  type HTMLAttributes,
+} from 'react';
+import clsx from 'clsx';
+import { Select, type SelectOption } from '../Select';
+import { Input } from '../Input';
+import { useTranslation } from '../../i18n';
+import {
+  getCountryOptions,
+  parseE164,
+  formatNational,
+  toE164,
+  isoToFlag,
+  countryDisplayLabel,
+  type CountryCode,
+  type CountryOption,
+  type CountryDisplay,
+} from './phone';
+import styles from './PhoneInput.module.scss';
+
+/** PhoneInput size — passed through to the inner Select + Input. */
+export type PhoneInputSize = 'sm' | 'md' | 'lg';
+
+export interface PhoneInputProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'onChange' | 'defaultValue'
+> {
+  /** Controlled E.164 value (e.g. `"+442071838750"`); `null` = empty. */
+  value: string | null;
+  /** Fires with canonical E.164 on every edit; `null` when empty. */
+  onChange: (e164: string | null) => void;
+  /** ISO 3166-1 alpha-2 country used to seed the picker when `value` is empty. Default `"US"`. */
+  defaultCountry?: string;
+  /** Restrict the picker to this ISO-code subset. Defaults to all libphonenumber-js countries. An empty array is treated as all countries. */
+  countries?: string[];
+  /**
+   * How the SELECTED country renders in the picker trigger. Default `"code"`.
+   * - `"code"` — calling code only (`+1`).
+   * - `"iso"` — ISO code + code (`US +1`).
+   * - `"name"` — full country name + code (`United States +1`).
+   * - `"flag"` — emoji flag + code (`🇺🇸 +1`). Note: emoji flags don't render on
+   *   Windows Chrome/Edge (they show the letters), so prefer `"iso"` there.
+   *
+   * The dropdown rows always show the full country name + code (plus a flag in
+   * `"flag"` mode) so they stay searchable + identifiable regardless of this.
+   */
+  countryDisplay?: CountryDisplay;
+  /**
+   * Overrides the country picker's full accessible name. By default the picker
+   * is named after the group — "<group label> Country" (e.g. "Phone Country") —
+   * so it never collides with a form's own Country field; with no group label
+   * it is just "Country". Set this when that composed name reads badly.
+   */
+  countryLabel?: string;
+  /** Control size, forwarded to the Select + Input. Default `"md"`. */
+  size?: PhoneInputSize;
+  /** Error chrome on both controls (host/Field-driven). */
+  invalid?: boolean;
+  /** Disable both controls. */
+  disabled?: boolean;
+  /** Mark required (forwarded for Field semantics). */
+  required?: boolean;
+  /** BCP-47 locale for country-name localization. Defaults to the i18n locale, else `"en"`. */
+  locale?: string;
+  /** Stable id; placed on the number field so an external `<label htmlFor>` focuses it. */
+  id?: string;
+  /**
+   * Accessible name when used STANDALONE (outside `<Field>`). A standalone
+   * PhoneInput MUST be named via `aria-label` or `aria-labelledby`, else the
+   * country/number group is unnamed. Inside `<Field>` the label is wired
+   * automatically via `aria-labelledby`.
+   */
+  'aria-label'?: string;
+  /** Ids of elements labelling the group (injected by `<Field>`; takes precedence over `aria-label`). */
+  'aria-labelledby'?: string;
+  /** Ids of description/error elements; forwarded to the number field so it is announced on focus (injected by `<Field>`). */
+  'aria-describedby'?: string;
+}
+
+const FALLBACK_COUNTRY = 'US' as CountryCode;
+
+function seedCountry(value: string | null, defaultCountry: string): CountryCode {
+  if (value) {
+    const parsed = parseE164(value);
+    if (parsed?.country) return parsed.country;
+  }
+  return (defaultCountry || FALLBACK_COUNTRY) as CountryCode;
+}
+
+function seedNational(value: string | null): string {
+  if (!value) return '';
+  const parsed = parseE164(value);
+  return parsed ? parsed.national : value;
+}
+
+/**
+ * International phone field: a searchable country picker plus a national-number input that emits E.164.
+ * @see docs/components/PhoneInput.md
+ */
+export const PhoneInput = forwardRef<HTMLDivElement, PhoneInputProps>(function PhoneInput(
+  {
+    value,
+    onChange,
+    defaultCountry = 'US',
+    countries,
+    countryDisplay = 'code',
+    countryLabel,
+    size = 'md',
+    invalid,
+    disabled,
+    required,
+    locale,
+    id,
+    'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledby,
+    'aria-describedby': ariaDescribedby,
+    className,
+    ...rest
+  },
+  ref,
+) {
+  const t = useTranslation();
+  const resolvedLocale = locale ?? 'en';
+  const countryWordId = `${useId()}-country`;
+  // Picker name, derived from the group's so two "Country" comboboxes in one
+  // form stay distinguishable (#638). labelledby wins, mirroring the group.
+  const countryWord = t('phoneInput.countryLabel');
+  const countryNaming = countryLabel
+    ? { 'aria-label': countryLabel }
+    : ariaLabelledby
+      ? { 'aria-labelledby': `${ariaLabelledby} ${countryWordId}` }
+      : { 'aria-label': ariaLabel ? `${ariaLabel} ${countryWord}` : countryWord };
+
+  const options = useMemo<CountryOption[]>(
+    () => getCountryOptions(resolvedLocale, countries),
+    [resolvedLocale, countries],
+  );
+  const selectOptions = useMemo<SelectOption<CountryOption>[]>(
+    () =>
+      options.map((o) => ({
+        value: o.iso,
+        // The combobox trigger shows the option's `label` (renderValue is ignored
+        // for a searchable Select), so the label IS the compact trigger format…
+        label: countryDisplayLabel(o, countryDisplay),
+        // …while `description` carries the full search terms (name + iso + code)
+        // so filtering still matches by name even in `"code"`/`"iso"` modes.
+        description: `${o.name} ${o.iso} +${o.callingCode}`,
+        data: o,
+      })),
+    [options, countryDisplay],
+  );
+
+  const [country, setCountry] = useState<CountryCode>(() => seedCountry(value, defaultCountry));
+  const [national, setNational] = useState<string>(() => seedNational(value));
+  // Track what we last emitted so our own onChange echoes don't resync (and clobber typing).
+  const lastEmitted = useRef<string | null>(value);
+
+  useEffect(() => {
+    if (value === lastEmitted.current) return;
+    lastEmitted.current = value;
+    if (!value) {
+      setNational('');
+      return;
+    }
+    const parsed = parseE164(value);
+    if (parsed) {
+      if (parsed.country) setCountry(parsed.country);
+      setNational(parsed.national);
+    } else {
+      setNational(value);
+    }
+  }, [value]);
+
+  const emit = useCallback(
+    (rawNational: string, ctry: CountryCode) => {
+      const e164 = toE164(rawNational, ctry);
+      lastEmitted.current = e164;
+      onChange(e164);
+    },
+    [onChange],
+  );
+
+  const onNumberChange = useCallback(
+    (e: React.ChangeEvent<HTMLInputElement>) => {
+      const formatted = formatNational(e.target.value, country);
+      setNational(formatted);
+      emit(formatted, country);
+    },
+    [country, emit],
+  );
+
+  const onCountryChange = useCallback(
+    (next: string) => {
+      const c = next as CountryCode;
+      setCountry(c);
+      const reformatted = formatNational(national, c);
+      setNational(reformatted);
+      emit(reformatted, c);
+    },
+    [national, emit],
+  );
+
+  return (
+    <div
+      // {...rest} first so the component's structural ARIA contract
+      // (role=group + the resolved labelledby/label) can't be clobbered.
+      {...rest}
+      ref={ref}
+      className={clsx(styles.root, className)}
+      role="group"
+      aria-label={ariaLabelledby ? undefined : ariaLabel}
+      aria-labelledby={ariaLabelledby}
+    >
+      {/* `hidden` keeps it out of reading order; aria-labelledby still reads it. */}
+      <span id={countryWordId} hidden>
+        {countryWord}
+      </span>
+      <Select
+        className={styles.country}
+        options={selectOptions}
+        value={country}
+        onChange={(v) => onCountryChange(Array.isArray(v) ? v[0] : v)}
+        searchable
+        // A phone always has a country — never offer to clear the selection.
+        clearable={false}
+        // Highlight the trigger text on open so the user can type to search.
+        selectOnOpen
+        size={size}
+        invalid={invalid}
+        disabled={disabled}
+        {...countryNaming}
+        placeholder={t('phoneInput.countrySearch')}
+        // Rows always show the full name (+ flag in `flag` mode), single-line.
+        renderOption={(opt) =>
+          opt.data ? (
+            <span className={styles.option}>
+              {countryDisplay === 'flag'
+                ? `${isoToFlag(opt.data.iso)} ${opt.data.name} +${opt.data.callingCode}`
+                : `${opt.data.name} +${opt.data.callingCode}`}
+            </span>
+          ) : (
+            opt.label
+          )
+        }
+      />
+      <Input
+        className={styles.number}
+        id={id}
+        type="tel"
+        inputMode="tel"
+        autoComplete="tel-national"
+        value={national}
+        onChange={onNumberChange}
+        size={size}
+        invalid={invalid}
+        disabled={disabled}
+        required={required}
+        aria-label={t('phoneInput.numberLabel')}
+        aria-describedby={ariaDescribedby}
+        placeholder={t('phoneInput.numberPlaceholder')}
+      />
+    </div>
+  );
+});

package/src/components/PhoneInput/index.ts

@@ -0,0 +1,4 @@
+export { PhoneInput } from './PhoneInput';
+export type { PhoneInputProps, PhoneInputSize } from './PhoneInput';
+export { isValidPhone } from './phone';
+export type { CountryOption, CountryCode, CountryDisplay } from './phone';

package/src/components/PhoneInput/phone.ts

@@ -0,0 +1,128 @@
+// phone.ts — pure wrappers around libphonenumber-js (compact `min` metadata) +
+// Intl.DisplayNames for localized country names. The ONLY place the library
+// imports libphonenumber-js, so the dependency stays isolated + testable.
+import {
+  AsYouType,
+  getCountries,
+  getCountryCallingCode,
+  parsePhoneNumberFromString,
+  isValidPhoneNumber,
+  type CountryCode,
+} from 'libphonenumber-js';
+
+export type { CountryCode };
+
+/** One selectable country: ISO code, localized name, and calling code (no `+`). */
+export interface CountryOption {
+  iso: CountryCode;
+  name: string;
+  callingCode: string;
+}
+
+/**
+ * How the SELECTED country renders in the picker trigger:
+ * - `'flag'` — emoji flag + calling code (`🇺🇸 +1`)
+ * - `'iso'` — ISO code + calling code (`US +1`)
+ * - `'name'` — full country name + calling code (`United States +1`)
+ * - `'code'` — calling code only (`+1`)
+ */
+export type CountryDisplay = 'flag' | 'iso' | 'name' | 'code';
+
+/**
+ * Emoji flag for an ISO 3166-1 alpha-2 code, built from Unicode regional-
+ * indicator symbols. Note: emoji flags do NOT render on Windows Chrome/Edge —
+ * those show the letters (e.g. "US") instead.
+ */
+export function isoToFlag(iso: string): string {
+  return iso
+    .toUpperCase()
+    .replace(/[^A-Z]/g, '')
+    .replace(/./g, (c) => String.fromCodePoint(0x1f1e6 + c.charCodeAt(0) - 65));
+}
+
+/** The compact trigger label for `country` under the chosen `display` mode. */
+export function countryDisplayLabel(country: CountryOption, display: CountryDisplay): string {
+  const code = `+${country.callingCode}`;
+  switch (display) {
+    case 'flag':
+      return `${isoToFlag(country.iso)} ${code}`;
+    case 'iso':
+      return `${country.iso} ${code}`;
+    case 'code':
+      return code;
+    case 'name':
+    default:
+      return `${country.name} ${code}`;
+  }
+}
+
+function displayNames(locale: string): Intl.DisplayNames {
+  try {
+    return new Intl.DisplayNames([locale], { type: 'region' });
+  } catch {
+    return new Intl.DisplayNames(['en'], { type: 'region' });
+  }
+}
+
+/**
+ * Every supported country (or the `only` subset) as `{ iso, name, callingCode }`,
+ * names localized to `locale` via `Intl.DisplayNames`, sorted by name.
+ */
+export function getCountryOptions(locale: string, only?: string[]): CountryOption[] {
+  const display = displayNames(locale);
+  const all = getCountries();
+  const isos: CountryCode[] =
+    only && only.length
+      ? (only.filter((c) => all.includes(c as CountryCode)) as CountryCode[])
+      : all;
+  return isos
+    .map((iso) => ({
+      iso,
+      name: display.of(iso) ?? iso,
+      callingCode: getCountryCallingCode(iso),
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name, locale));
+}
+
+/** Parse an E.164 string into its country + national display, or null if unparseable. */
+export function parseE164(
+  value: string,
+): { country: CountryCode | undefined; national: string } | null {
+  const parsed = parsePhoneNumberFromString(value);
+  if (!parsed) return null;
+  const country = parsed.country ?? parsed.getPossibleCountries()[0];
+  return { country, national: parsed.formatNational() };
+}
+
+/** Format a raw national input for `country` as the user types (idempotent on a formatted string). */
+export function formatNational(input: string, country: CountryCode): string {
+  return new AsYouType(country).input(input);
+}
+
+/**
+ * Canonical E.164 once the input is a *possible* complete number for `country`;
+ * `null` while still partial or empty.
+ */
+export function toE164(input: string, country: CountryCode): string | null {
+  const ayt = new AsYouType(country);
+  ayt.input(input);
+  const num = ayt.getNumber();
+  return num && num.isPossible() ? num.number : null;
+}
+
+/**
+ * True iff `e164` is a valid phone number. Exported so a host can drive Field `invalid` chrome.
+ *
+ * @example
+ * <Field error={isValidPhone(value) ? undefined : 'Enter a valid number'}>
+ *   <PhoneInput value={value} onChange={setValue} />
+ * </Field>
+ */
+export function isValidPhone(e164: string | null | undefined): boolean {
+  if (!e164) return false;
+  try {
+    return isValidPhoneNumber(e164);
+  } catch {
+    return false;
+  }
+}

package/src/components/PillMenu/PillMenu.module.scss

@@ -0,0 +1,117 @@
+@use '../../styles/mixins' as *;
+@use './PillMenu.tokens';
+
+// Shared by .trigger (interactive) and .chip (read-only) — both render the
+// same colored pill; only the interaction affordances differ below.
+.trigger,
+.chip {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--pill-menu-gap);
+  border-radius: var(--pill-menu-radius);
+  padding: var(--pill-menu-padding-y) var(--pill-menu-padding-x);
+  font-family: inherit;
+  font-size: var(--pill-menu-font-size);
+  font-weight: var(--pill-menu-font-weight);
+  background: var(--pill-menu-bg, transparent);
+  color: var(--pill-menu-fg, currentColor);
+  white-space: nowrap;
+
+  // Content-width even as a stretching flex/grid item (a vertical Field, a
+  // Stack), where the pill was blockified and stretched with the chevron
+  // stranded mid-pill. Sizes the element's own box, not its placement.
+  width: fit-content;
+}
+
+.trigger {
+  border: none;
+  cursor: pointer;
+
+  &:hover:not(:disabled) {
+    filter: brightness(0.96);
+  }
+
+  &:focus-visible {
+    @include focus-ring(var(--pill-menu-ring-focus));
+  }
+
+  &:disabled {
+    opacity: var(--pill-menu-disabled-opacity);
+    cursor: not-allowed;
+  }
+}
+
+.chevron {
+  flex-shrink: 0;
+}
+
+// Form-column mode (#578): the pill fills the field like a Select trigger —
+// icon + name at the start, chevron at the end edge.
+.fullWidth {
+  display: flex;
+  width: 100%;
+
+  > .chevron {
+    // stylelint-disable-next-line property-disallowed-list -- internal child of the pill's OWN flex row: pushes the chevron to the end edge without wrapping icon + name (a wrapper would change what getByText(name) returns in consumer tests)
+    margin-inline-start: auto;
+  }
+}
+
+// Coloured rows read as one block when flush (DropdownMenu's gap is 0);
+// separate them so each option is its own chip.
+.menu {
+  --dropdown-menu-gap: var(--pill-menu-option-gap);
+}
+
+// DropdownMenu's own hover/focus-visible rule is
+// `.item:hover:not([aria-disabled='true'])` — (0,3,0): the attribute
+// selector inside `:not()` counts toward specificity. A plain
+// `.option.option:hover` only reaches (0,3,0) too — a tie, whose winner
+// depends on CSS-module emission order, which isn't guaranteed. Adding our
+// own `:not([aria-disabled='true'])` pushes us to (0,4,0), a provable win
+// regardless of source order. CSS also cascades per PROPERTY, not per
+// rule — winning the selector fight doesn't help unless we redeclare
+// background/color here too, since DropdownMenu's rule would otherwise be
+// the only one setting `background` at all.
+.option.option {
+  // Item's icon slot defaults to a muted grey; on a coloured row the glyph
+  // takes the row's colour, like the pill's.
+  --dropdown-menu-icon-fg: var(--pill-menu-fg, currentColor);
+
+  background: var(--pill-menu-bg, transparent);
+  color: var(--pill-menu-fg, currentColor);
+}
+
+.option.option:hover:not([aria-disabled='true']) {
+  background: var(--pill-menu-bg, transparent);
+  color: var(--pill-menu-fg, currentColor);
+  filter: brightness(0.94);
+}
+
+.option.option:focus-visible:not([aria-disabled='true']) {
+  background: var(--pill-menu-bg, transparent);
+  color: var(--pill-menu-fg, currentColor);
+  filter: brightness(0.94);
+}
+
+.srOnly {
+  @include visually-hidden;
+}
+
+// Optional per-value glyph before the name (#572). Decorative; sized by the
+// consumer's icon. Centred on the pill's text line.
+.icon {
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+}
+
+// Optional visible caption before the value (#605) and its middle-dot
+// separator. Muted by WEIGHT at the full fg colour, not by opacity/colour:
+// the tightest palette pair (light mint) has no headroom above AA for a
+// dimmer foreground. contrast.test.ts measures it and pins both the palette
+// pairs and this rule's lack of a colour change.
+.caption {
+  flex-shrink: 0;
+  font-weight: var(--pill-menu-caption-font-weight);
+}

package/src/components/PillMenu/PillMenu.tokens.scss

@@ -0,0 +1,22 @@
+// PillMenu.tokens.scss
+// Component-scoped tokens for <PillMenu>. Each token defaults to the
+// primitive/token it replaces — overriding any of these at :root re-themes
+// PillMenu without touching globals. Convention: --pill-menu-<part>.
+// See docs/superpowers/specs/2026-05-27-component-tokens-design.md
+@use '../DropdownMenu/DropdownMenu.tokens';
+
+:root {
+  --pill-menu-radius: var(--radius-md);
+  --pill-menu-padding-y: var(--space-1);
+  --pill-menu-padding-x: var(--space-3);
+  --pill-menu-font-size: var(--font-size-sm);
+  --pill-menu-font-weight: var(--font-weight-medium);
+  --pill-menu-gap: var(--space-2);
+
+  // Option rows are spaced by the panel's inline padding, so gaps match the sides.
+  --pill-menu-option-gap: var(--dropdown-menu-padding);
+
+  --pill-menu-caption-font-weight: var(--font-weight-regular);
+  --pill-menu-disabled-opacity: var(--opacity-disabled);
+  --pill-menu-ring-focus: var(--ring-accent);
+}