phonefield 0.1.0

package/README.md

@@ -0,0 +1,84 @@
+## PhoneField
+
+Composable phone field primitive built with Base UI and libphonenumber-js.
+
+- Country picker with localized names, dial codes, and flags.
+- As-you-type formatting via `formatOnType`.
+- Controlled and uncontrolled usage.
+- FormData integration via `name` on `PhoneField.Root`.
+- Shared utils for parsing, validation, and country metadata.
+
+### Install
+
+```bash
+pnpm add phonefield
+# or
+npm install phonefield
+yarn add phonefield
+bun add phonefield
+```
+
+### Usage
+
+```tsx
+import { PhoneField } from "phonefield";
+
+export function SignupPhone() {
+  return (
+    <PhoneField.Root defaultCountry="US" lang="en">
+      <PhoneField.Country />
+      <PhoneField.Input />
+    </PhoneField.Root>
+  );
+}
+```
+
+```tsx
+import * as React from "react";
+import { PhoneField } from "phonefield";
+
+export function ControlledExample() {
+  const [phone, setPhone] = React.useState<PhoneField.Value>({
+    countryIso2: "US",
+    countryDialCode: "1",
+    nationalNumber: "",
+    e164: null,
+    isValid: false,
+  });
+
+  return (
+    <PhoneField.Root value={phone} onValueChange={setPhone}>
+      <PhoneField.Country />
+      <PhoneField.Input />
+    </PhoneField.Root>
+  );
+}
+```
+
+### FormData
+
+```tsx
+import { PhoneField } from "phonefield";
+import { PhoneFieldUtils } from "phonefield/utils";
+
+function ExampleForm() {
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault();
+        const formData = new FormData(event.currentTarget);
+        const phone = PhoneFieldUtils.fromFormData(formData, "phone");
+        // phone -> PhoneField.Value | null
+      }}
+    >
+      <PhoneField.Root name="phone" defaultCountry="US">
+        <PhoneField.Country />
+        <PhoneField.Input />
+      </PhoneField.Root>
+    </form>
+  );
+}
+```
+
+More documentation and API reference: https://phonefield.vercel.app
+

package/dist/chunk-ERF62DTM.js

@@ -0,0 +1 @@
+import{getCountries as n,AsYouType as t,parsePhoneNumberFromString as e,getCountryCallingCode as r}from"libphonenumber-js/min";function o(n){if("undefined"==typeof Intl||void 0===Intl.DisplayNames)return null;try{return new Intl.DisplayNames([n],{type:"region"})}catch{return null}}var i=o("en"),u=n();function a(n,t){return t?.of(n)??i?.of(n)??n}function l(n){return n.toUpperCase().replace(/./g,n=>String.fromCodePoint(n.charCodeAt(0)+127397))}function c(n){if(!n)return"en";try{return Intl.getCanonicalLocales(n)[0]??"en"}catch{return Array.isArray(n)?n[0]??"en":n}}var s=new Map;function f(n){const t=c(n),e=s.get(t);if(e)return e;const i=function(n){const t=o(n),e=function(n){if("undefined"==typeof Intl||void 0===Intl.Collator)return null;try{return new Intl.Collator(n)}catch{return null}}(n),i=u.map(n=>({iso2:n,name:a(n,t),dialCode:`+${r(n)}`,flag:l(n)})).sort((t,r)=>e?e.compare(t.name,r.name):t.name.localeCompare(r.name,n));return new Map(i.map(n=>[n.iso2,n]))}(t);return s.set(t,i),i}var d="US";function p(){return f("en")}function y(n){return n.replace(/\D+/g,"")}function m(n,t){if(!t?.length){const t=Array.from(n.values());if(0===t.length)throw new Error("PhoneField.Root requires at least one valid country code.");return t}const e=t,r=new Set,o=[];for(const t of e){if(r.has(t))continue;r.add(t);const e=n.get(t);e&&o.push(e)}if(0===o.length)throw new Error("PhoneField.Root requires at least one valid country code.");return o}function g(n,t){if(0===n.length)throw new Error("PhoneField.Root requires at least one available country.");let e=n[0];for(const r of n)if("US"===r.iso2&&(e=r),t&&r.iso2===t)return r;return e}function h(n,r,o){const i=y(r),u=o?i?new t(n.iso2).input(i):"":r,a=function(n){return y(n.dialCode)}(n),l=i?`+${a}${i}`:null,c=l?e(l):void 0;return{countryIso2:n.iso2,countryDialCode:a,nationalNumber:u,e164:l,isValid:c?.isValid()??!1}}function C(n){return`${n.name} ${n.iso2} ${n.dialCode}`}function v(n,t){if("string"==typeof n)return e(n,t?.defaultCountry);const r=n.e164?e(n.e164):void 0;if(r)return r;const o=`+${n.countryDialCode}${y(n.nationalNumber)}`;return e(o,n.countryIso2)}function w(n,t){return v(n,t)?.isValid()??!1}function I(n){return!(!n||"object"!=typeof n||"string"!=typeof n.countryIso2||"string"!=typeof n.countryDialCode||"string"!=typeof n.nationalNumber||"string"!=typeof n.e164&&null!==n.e164||"boolean"!=typeof n.isValid)}function b(n,t){const e=n.get(t);if("string"!=typeof e)return null;try{const n=JSON.parse(e);return I(n)?n:null}catch{return null}}var $={parse:v,isValid:w,fromFormData:b,getCountries:f,get countries(){return p()}};export{d as DEFAULT_COUNTRY,$ as PhoneFieldUtils,h as buildValue,C as defaultCountrySearchText,b as fromFormData,f as getCountriesMap,p as getDefaultCountriesMap,I as isPhoneFieldValue,w as isValidPhoneField,c as normalizeLang,y as onlyDigits,v as parsePhoneField,g as resolveCountry,m as toAvailableCountries};

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Combobox } from '@base-ui/react/combobox';
+import { Input } from '@base-ui/react/input';
+import React from 'react';
+import { P as PhoneFieldCountry, a as PhoneFieldCountryMap, b as PhoneFieldCountryCodeValue, c as PhoneFieldCountryName, d as PhoneFieldLang, e as PhoneFieldValue } from './types-BPc8XSky.js';
+import 'libphonenumber-js/min';
+
+/**
+ * Root container for the phone field. Provides context to Country and Input.
+ * Supports controlled and uncontrolled usage, optional FormData serialization via `name`, and country subset.
+ */
+declare function Root({ value, defaultValue, onValueChange, defaultCountry, countries, lang, name, formatOnType, children, className, ...props }: PhoneField.RootProps): react_jsx_runtime.JSX.Element;
+/**
+ * Country combobox: trigger + searchable list. Use `slots` to style trigger, popup, list, item, etc.
+ */
+declare function Country({ placeholder, noResultsText, inputPlaceholder, icon, slots, renderCountryItem, renderCountryValue, }: PhoneField.CountryProps): react_jsx_runtime.JSX.Element;
+declare const PhoneField: {
+    Root: typeof Root;
+    Country: typeof Country;
+    Input: ({ className, onValueChange, type, onKeyDown, ref, ...props }: PhoneField.InputProps) => react_jsx_runtime.JSX.Element;
+};
+declare namespace PhoneField {
+    /** Country descriptor: iso2, name, dialCode, flag. */
+    type Country = PhoneFieldCountry;
+    /** Read-only map of ISO2 to country. */
+    type CountryMap = PhoneFieldCountryMap;
+    /** ISO2 country code (e.g. "US", "GB"). */
+    type CountryCodeValue = PhoneFieldCountryCodeValue;
+    /** Alias for ISO2 country code. */
+    type CountryName = PhoneFieldCountryName;
+    /** BCP 47 locale for country names and sorting. */
+    type Lang = PhoneFieldLang;
+    /** Emitted/controlled value: countryIso2, countryDialCode, nationalNumber, e164, isValid. */
+    type Value = PhoneFieldValue;
+    /** Renders a single country in the dropdown list. */
+    type RenderCountryItem = (country: Country) => React.ReactNode;
+    /** Renders the selected country in the trigger. */
+    type RenderCountryValue = (country: Country) => React.ReactNode;
+    /** Class names for Country sub-parts (trigger, popup, searchInput, list, item, etc.). */
+    type CountrySlots<Value extends PhoneField.Country = PhoneField.Country> = {
+        root?: Combobox.Root.Props<Value>;
+        placeholder?: React.HTMLAttributes<HTMLSpanElement>;
+        trigger?: Combobox.Trigger.Props;
+        value?: Combobox.Value.Props;
+        icon?: Combobox.Icon.Props;
+        popup?: Combobox.Popup.Props;
+        positioner?: Combobox.Positioner.Props;
+        searchInput?: Combobox.Input.Props;
+        list?: Combobox.List.Props;
+        item?: Combobox.Item.Props;
+        empty?: Combobox.Empty.Props;
+    };
+    /**
+     * Props for `PhoneField.Root`. Extends div. Use `value`/`onValueChange` for controlled mode,
+     * or `defaultValue`/`defaultCountry` for uncontrolled. Set `name` to serialize value into FormData.
+     */
+    type RootProps = Omit<React.ComponentPropsWithoutRef<"div">, "defaultValue"> & {
+        value?: Value;
+        defaultValue?: Value;
+        onValueChange?: (value: Value) => void;
+        defaultCountry?: CountryCodeValue;
+        countries?: readonly CountryCodeValue[];
+        lang?: Lang;
+        name?: string;
+        formatOnType?: boolean;
+    };
+    /** Props for `PhoneField.Country`: label, placeholders, icon, and `slots` for styling. */
+    type CountryProps = {
+        placeholder?: React.ReactNode;
+        noResultsText?: React.ReactNode;
+        inputPlaceholder?: string;
+        icon?: React.ReactNode;
+        slots?: CountrySlots;
+        renderCountryItem?: RenderCountryItem;
+        renderCountryValue?: RenderCountryValue;
+    };
+    /** Props for `PhoneField.Input`. Extends Base UI Input (className, onValueChange, etc.). */
+    type InputProps = Input.Props;
+}
+
+export { PhoneField, PhoneFieldCountry, PhoneFieldCountryCodeValue, PhoneFieldCountryMap, PhoneFieldCountryName, PhoneFieldLang, PhoneFieldValue };

package/dist/index.js

@@ -0,0 +1 @@
+import{getCountriesMap as e,toAvailableCountries as t,resolveCountry as n,buildValue as o,defaultCountrySearchText as r}from"./chunk-ERF62DTM.js";import{Combobox as i}from"@base-ui/react/combobox";import{Input as l}from"@base-ui/react/input";import a from"react";import{jsx as u,jsxs as s}from"react/jsx-runtime";function c(...e){return e.filter(Boolean).join(" ")}var d=a.createContext(null);function f(){const e=a.useContext(d);if(!e)throw new Error("PhoneField compound components must be used inside <PhoneField.Root>.");return e}function m(e){return s("svg",{width:"8",height:"12",viewBox:"0 0 8 12",fill:"none",stroke:"currentColor",strokeWidth:"1.5",...e,children:[u("title",{children:"Arrow"}),u("path",{d:"M0.5 4.5L4 1.5L7.5 4.5"}),u("path",{d:"M0.5 7.5L4 10.5L7.5 7.5"})]})}function p(...e){return t=>{for(const n of e)n&&("function"==typeof n?n(t):n.current=t)}}var h={Root:function({value:r,defaultValue:i,onValueChange:l,defaultCountry:c,countries:f,lang:m,name:p,formatOnType:h=!0,children:y,className:v,...g}){const C=a.useMemo(()=>e(m),[m]),b=a.useMemo(()=>t(C,f),[C,f]),N=n(b,c),[x,I]=a.useState(i??o(N,"",h)),w=r??x,V=n(b,w.countryIso2),P=o(V,w.nationalNumber,h),R=(e,t)=>{const n=o(e,t,h);void 0===r&&I(n),l?.(n)};return u(d.Provider,{value:{value:P,selectedCountry:V,availableCountries:b,setCountry:e=>R(e,P.nationalNumber),setNumber:e=>R(V,e)},children:s("div",{className:v,...g,children:[y,p?u("input",{type:"hidden",name:p,value:JSON.stringify(P)}):null]})})},Country:function({placeholder:e="Select country",noResultsText:t="No countries found",inputPlaceholder:n="Search country",icon:o,slots:l,renderCountryItem:a,renderCountryValue:c}){const{selectedCountry:d,availableCountries:p,setCountry:h}=f(),y=p.find(e=>e.iso2===d.iso2)??p[0];return s(i.Root,{...l?.root,items:p,value:y,itemToStringLabel:r,onValueChange:e=>{e&&h(e)},isItemEqualToValue:(e,t)=>e.iso2===t.iso2,children:[s(i.Trigger,{...l?.trigger,children:[u(i.Value,{...l?.value,placeholder:e,children:t=>t?c?.(t)??`${t.flag?`${t.flag} `:""}${t.name} (${t.dialCode})`:e}),u(i.Icon,{...l?.icon,children:o??u(m,{})})]}),u(i.Portal,{children:u(i.Positioner,{align:"start",sideOffset:4,...l?.positioner,children:s(i.Popup,{...l?.popup,children:[u(i.Input,{...l?.searchInput,placeholder:n,"aria-label":n}),u(i.Empty,{...l?.empty,children:t}),u(i.List,{...l?.list,children:e=>u(i.Item,{value:e,...l?.item,children:a?.(e)??s("div",{className:"flex items-center justify-between gap-4",children:[s("span",{className:"truncate",children:[e.flag?`${e.flag} `:"",e.name]}),s("span",{className:"text-xs opacity-70",children:[e.iso2," · ",e.dialCode]})]})},e.iso2)})]})})})]})},Input:({className:e,onValueChange:t,type:n="text",onKeyDown:o,ref:r,...i})=>{const{value:s,setNumber:d}=f(),m=a.useRef(null),h="h-10 rounded-md border border-zinc-300 px-3 flex-1 outline-none focus:border-zinc-500",y="function"==typeof e?t=>c(h,e(t)):c(h,e);return u(l,{...i,ref:p(r,m),type:n,inputMode:"tel",autoComplete:"tel",pattern:"[0-9]*",className:y,value:s.nationalNumber,onKeyDown:e=>{if("Backspace"===e.key){const t=m.current;if(!t)return;const n=t.selectionStart??0;if(n===(t.selectionEnd??0)&&n>0){const o=t.value[n-1];if(o&&/\D/.test(o)){e.preventDefault();const o=function(e,t){let n=t;for(;n>0&&/\D/.test(e[n-1]??"");)n--;return n-1}(t.value,n);if(o>=0){const e=function(e,t){return e.slice(0,t)+e.slice(t+1)}(t.value,o);d(e),requestAnimationFrame(()=>{t.setSelectionRange(o,o)})}}}}o?.(e)},onValueChange:(e,n)=>{d(e),t?.(e,n)}})}};export{h as PhoneField};

package/dist/types-BPc8XSky.d.ts

@@ -0,0 +1,32 @@
+import { CountryCode } from 'libphonenumber-js/min';
+
+/**
+ * Country descriptor used by the country picker: ISO2 code, display name, dial code, and optional flag emoji.
+ */
+type PhoneFieldCountry = {
+    iso2: CountryCode;
+    name: string;
+    dialCode: string;
+    flag?: string;
+};
+/** Read-only map of ISO2 country code to `PhoneFieldCountry`. */
+type PhoneFieldCountryMap = ReadonlyMap<CountryCode, PhoneFieldCountry>;
+/** ISO2 country code (e.g. `"US"`, `"GB"`). */
+type PhoneFieldCountryCodeValue = CountryCode;
+/** Alias for ISO2 country code. */
+type PhoneFieldCountryName = CountryCode;
+/** BCP 47 locale string or list of locale strings for country display names and sorting. */
+type PhoneFieldLang = string | readonly string[];
+/**
+ * Emitted and controlled value shape: country, national number, E.164, and validity.
+ * Used as the value/onValueChange payload and when reading from FormData.
+ */
+type PhoneFieldValue = {
+    countryIso2: CountryCode;
+    countryDialCode: string;
+    nationalNumber: string;
+    e164: string | null;
+    isValid: boolean;
+};
+
+export type { PhoneFieldCountry as P, PhoneFieldCountryMap as a, PhoneFieldCountryCodeValue as b, PhoneFieldCountryName as c, PhoneFieldLang as d, PhoneFieldValue as e };

package/dist/utils.d.ts

@@ -0,0 +1,68 @@
+import * as libphonenumber_js_min from 'libphonenumber-js/min';
+import { CountryCode } from 'libphonenumber-js/min';
+import { e as PhoneFieldValue, d as PhoneFieldLang, a as PhoneFieldCountryMap, P as PhoneFieldCountry, b as PhoneFieldCountryCodeValue } from './types-BPc8XSky.js';
+
+/**
+ * Normalizes a BCP 47 locale (string or array) to a single canonical locale string. Returns `"en"` when missing or invalid.
+ */
+declare function normalizeLang(lang?: PhoneFieldLang): any;
+/**
+ * Returns a cached map of ISO2 → PhoneFieldCountry for the given locale. Used for country names and sorting.
+ */
+declare function getCountriesMap(lang?: PhoneFieldLang): PhoneFieldCountryMap;
+/** Default country code used when none is specified (e.g. "US"). */
+declare const DEFAULT_COUNTRY: CountryCode;
+/** Returns the default countries map for locale "en". */
+declare function getDefaultCountriesMap(): PhoneFieldCountryMap;
+/** Strips all non-digit characters from a string. */
+declare function onlyDigits(value: string): string;
+/**
+ * Filters a countries map to the given ISO2 codes, or returns all countries if none provided.
+ * @throws If the resulting list is empty.
+ */
+declare function toAvailableCountries(countriesMap: PhoneFieldCountryMap, countries?: readonly PhoneFieldCountryCodeValue[]): PhoneFieldCountry[];
+/**
+ * Resolves an ISO2 code to a country from the available list. Falls back to US if present, else first country.
+ * @throws If availableCountries is empty.
+ */
+declare function resolveCountry(availableCountries: readonly PhoneFieldCountry[], iso2?: CountryCode): PhoneFieldCountry;
+/**
+ * Builds a PhoneFieldValue from country, raw national number string, and formatOnType flag.
+ * When formatOnType is true, national number is formatted as-you-type.
+ */
+declare function buildValue(country: PhoneFieldCountry, rawNumber: string, formatOnType: boolean): PhoneFieldValue;
+/** Default search text for a country (name, iso2, dialCode) used by the combobox. */
+declare function defaultCountrySearchText(country: PhoneFieldCountry): string;
+/**
+ * Parses a PhoneFieldValue or E.164 string into a libphonenumber PhoneNumber.
+ * Use for formatNational(), formatInternational(), getURI(). Options.defaultCountry for national-number strings.
+ */
+declare function parsePhoneField(value: string | PhoneFieldValue, options?: {
+    defaultCountry?: CountryCode;
+}): libphonenumber_js_min.PhoneNumber | undefined;
+/**
+ * Returns whether the value is a valid phone number. Accepts PhoneFieldValue or E.164 string.
+ * Options.defaultCountry for national-number strings.
+ */
+declare function isValidPhoneField(value: string | PhoneFieldValue, options?: {
+    defaultCountry?: CountryCode;
+}): boolean;
+/** Type guard: true if the value has the PhoneFieldValue shape. */
+declare function isPhoneFieldValue(value: unknown): value is PhoneFieldValue;
+/**
+ * Reads a serialized PhoneField.Value from FormData (JSON string). Returns null if missing or invalid.
+ */
+declare function fromFormData(formData: FormData, name: string): PhoneFieldValue | null;
+/**
+ * Helper facade for parse, isValid, fromFormData, getCountries, and default countries map.
+ * Use from "phonefield/utils" on client or server.
+ */
+declare const PhoneFieldUtils: {
+    parse: typeof parsePhoneField;
+    isValid: typeof isValidPhoneField;
+    fromFormData: typeof fromFormData;
+    getCountries: typeof getCountriesMap;
+    readonly countries: PhoneFieldCountryMap;
+};
+
+export { DEFAULT_COUNTRY, PhoneFieldUtils, buildValue, defaultCountrySearchText, fromFormData, getCountriesMap, getDefaultCountriesMap, isPhoneFieldValue, isValidPhoneField, normalizeLang, onlyDigits, parsePhoneField, resolveCountry, toAvailableCountries };

package/dist/utils.js

@@ -0,0 +1 @@
+export{DEFAULT_COUNTRY,PhoneFieldUtils,buildValue,defaultCountrySearchText,fromFormData,getCountriesMap,getDefaultCountriesMap,isPhoneFieldValue,isValidPhoneField,normalizeLang,onlyDigits,parsePhoneField,resolveCountry,toAvailableCountries}from"./chunk-ERF62DTM.js";

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "phonefield",
+  "version": "0.1.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Composable phone field primitive built with Base UI and libphonenumber-js.",
+  "author": "damianricobelli",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/damianricobelli/phonefield.git",
+    "directory": "package"
+  },
+  "homepage": "https://phonefield.vercel.app",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./utils": {
+      "types": "./dist/utils.d.ts",
+      "import": "./dist/utils.js"
+    }
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.2.0",
+    "libphonenumber-js": "^1.12.38"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "terser": "^5.46.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}