@teamofsilicons/silicon-ui 0.0.0-stage → 0.1.0

package/components/password-strength/password-strength.js

@@ -0,0 +1,161 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useEffect, useId, useRef, useState, useSyncExternalStore } from "react";
+import { AnimatePresence, animate, motion, useMotionValue, useReducedMotion } from "motion/react";
+import { motionTokens } from "../../lib/motion-tokens.js";
+import styles from "./password-strength.module.css";
+export const defaultPasswordStrengthMessages = {
+    levels: { tooShort: "Too short", weak: "Weak", fair: "Fair", good: "Good", strong: "Strong" },
+    showPassword: "Show password",
+    meterLabel: "Password strength",
+    noPassword: "No password yet",
+    rulesLabel: "Password requirements",
+    ruleMet: ", met",
+    ruleNotMet: ", not met",
+    remainingPrefix: "",
+    remainingSuffix: "more",
+    summary: ({ label, met, total }) => `Strength: ${label}. ${met} of ${total} requirements met.`,
+};
+/** Counts code points, so an emoji or other astral character counts as one. */
+export const countCodePoints = (password) => Array.from(password).length;
+const defaultRuleLabels = {
+    length: minLength => `At least ${minLength} characters`,
+    case: "Upper and lowercase letters",
+    number: "At least one number",
+    symbol: "At least one symbol",
+};
+/** The built-in rules (length, mixed case, number, symbol) with your own minimum length, labels and character count. */
+export function createPasswordRules({ minLength = 12, labels, countCharacters = countCodePoints } = {}) {
+    const copy = { ...defaultRuleLabels, ...labels };
+    return [
+        { id: "length", label: copy.length(minLength), test: password => countCharacters(password) >= minLength, remaining: password => Math.max(0, minLength - countCharacters(password)) },
+        { id: "case", label: copy.case, test: password => /\p{Ll}/u.test(password) && /\p{Lu}/u.test(password) },
+        { id: "number", label: copy.number, test: password => /\p{N}/u.test(password) },
+        { id: "symbol", label: copy.symbol, test: password => /[^\p{L}\p{N}\s]/u.test(password) },
+    ];
+}
+export const defaultPasswordRules = createPasswordRules();
+/** Scores a password on the device: one step per share of rules met, capped at the first step while it is shorter than the short length (8 by default). */
+export function estimateStrength(password, rules = defaultPasswordRules, { shortLength = 8, levels, countCharacters = countCodePoints } = {}) {
+    if (!password)
+        return { level: 0, label: "", met: [] };
+    const words = { ...defaultPasswordStrengthMessages.levels, ...levels };
+    const met = rules.filter(rule => rule.test(password)).map(rule => rule.id);
+    if (countCharacters(password) < shortLength)
+        return { level: 1, label: words.tooShort, met, short: true };
+    const level = Math.min(4, Math.max(1, Math.round((met.length / Math.max(rules.length, 1)) * 4)));
+    return { level, label: [words.weak, words.fair, words.good, words.strong][level - 1] ?? words.weak, met };
+}
+const enter = [...motionTokens.ease.enter];
+const standard = [...motionTokens.ease.standard];
+const subscribe = () => () => { };
+/** False on the server and during hydration, so reduced motion never changes the first client render. */
+const useHydrated = () => useSyncExternalStore(subscribe, () => true, () => false);
+/** The word rises when strength improves and drops when it falls, so the direction reads without looking at the meter. */
+const rise = {
+    enter: (direction) => ({ opacity: 0, y: `${.3 * direction}em`, filter: `blur(${motionTokens.blur.soft}px)` }),
+    center: { opacity: 1, y: "0em", filter: "blur(0px)", transition: { duration: motionTokens.duration.standard, ease: enter } },
+    exit: (direction) => ({ opacity: 0, y: `${-.3 * direction}em`, filter: `blur(${motionTokens.blur.subtle}px)`, transition: { duration: motionTokens.duration.fast, ease: standard } }),
+};
+const fade = { enter: { opacity: 0 }, center: { opacity: 1, transition: { duration: motionTokens.duration.fast } }, exit: { opacity: 0, transition: { duration: motionTokens.duration.instant } } };
+/** Digits turn like a counter: a shrinking count drops in from above, a growing one rises from below. */
+const roll = {
+    enter: (direction) => ({ opacity: 0, y: `${.45 * direction}em`, filter: `blur(${motionTokens.blur.subtle}px)` }),
+    center: { opacity: 1, y: "0em", filter: "blur(0px)", transition: { y: motionTokens.spring.snappy, opacity: { duration: motionTokens.duration.fast }, filter: { duration: motionTokens.duration.fast } } },
+    exit: (direction) => ({ opacity: 0, y: `${-.45 * direction}em`, filter: `blur(${motionTokens.blur.subtle}px)`, transition: { duration: motionTokens.duration.fast, ease: standard } }),
+};
+function RollingNumber({ value, reduced }) {
+    const [track, setTrack] = useState({ value, direction: 1 });
+    if (track.value !== value)
+        setTrack({ value, direction: value > track.value ? 1 : -1 });
+    const digits = String(value).split("");
+    // Columns are keyed by place value, so 10 → 9 lets the tens column narrow away while the ones column turns.
+    return _jsx("span", { className: styles.number, children: _jsx(AnimatePresence, { initial: false, custom: track.direction, children: digits.map((digit, index) => _jsx(motion.span, { className: styles.place, initial: { width: 0, opacity: 0 }, animate: { width: "auto", opacity: 1 }, exit: { width: 0, opacity: 0 }, transition: reduced ? { duration: 0 } : { width: motionTokens.spring.morph, opacity: { duration: motionTokens.duration.fast } }, children: _jsx(AnimatePresence, { mode: "popLayout", initial: false, custom: track.direction, children: _jsx(motion.span, { className: styles.digit, custom: track.direction, variants: reduced ? fade : roll, initial: "enter", animate: "center", exit: "exit", children: digit }, digit) }) }, digits.length - 1 - index)) }) });
+}
+/** One eye that a slash draws across, cutting the outline beneath it, instead of swapping two icons. */
+function EyeMorph({ slashed, reduced }) {
+    const maskId = `eye-${useId().replace(/[^a-zA-Z0-9_-]/g, "")}`;
+    const slash = { pathLength: slashed ? 1 : 0, opacity: slashed ? 1 : 0 };
+    const transition = reduced ? { duration: 0 } : { pathLength: { duration: motionTokens.duration.standard, ease: standard }, opacity: { duration: motionTokens.duration.instant } };
+    return _jsxs("svg", { width: 18, height: 18, viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 1.75, strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: [_jsxs("mask", { id: maskId, maskUnits: "userSpaceOnUse", x: "0", y: "0", width: "24", height: "24", children: [_jsx("rect", { width: "24", height: "24", fill: "white", stroke: "none" }), _jsx(motion.path, { d: "M3 3l18 18", stroke: "black", strokeWidth: 5, initial: false, animate: slash, transition: transition })] }), _jsxs("g", { mask: `url(#${maskId})`, children: [_jsx("path", { d: "M2.062 12.348a1 1 0 0 1 0-.696 10.75 10.75 0 0 1 19.876 0 1 1 0 0 1 0 .696 10.75 10.75 0 0 1-19.876 0" }), _jsx("circle", { cx: "12", cy: "12", r: "3" })] }), _jsx(motion.path, { d: "M3 3l18 18", initial: false, animate: slash, transition: transition })] });
+}
+/** The tint grows under the tick while the tick draws from its short stroke; unchecking retracts it faster than it drew. */
+function RuleMark({ met, delay, reduced }) {
+    return _jsxs("span", { className: styles.mark, "aria-hidden": "true", children: [_jsx(motion.span, { className: styles.markFill, initial: false, animate: { scale: met ? 1 : .5, opacity: met ? 1 : 0 }, transition: reduced ? { duration: 0 } : { scale: { ...motionTokens.spring.snappy, delay }, opacity: { duration: met ? motionTokens.duration.fast : motionTokens.duration.instant, delay } } }), _jsx("svg", { className: styles.tick, viewBox: "0 0 16 16", fill: "none", stroke: "currentColor", strokeWidth: 1.75, strokeLinecap: "round", strokeLinejoin: "round", children: _jsx(motion.path, { d: "M4.75 8.25 7 10.5l4.25-4.75", initial: false, animate: { pathLength: met ? 1 : 0, opacity: met ? 1 : 0 }, transition: reduced ? { duration: 0 } : met ? { pathLength: { duration: motionTokens.duration.standard, ease: enter, delay: delay + .06 }, opacity: { duration: .05, delay: delay + .06 } } : { pathLength: { duration: motionTokens.duration.fast, ease: standard }, opacity: { duration: motionTokens.duration.fast, delay: .06 } } }) })] });
+}
+/** Error copy opens its row on a spring, then the words settle in. The row follows the measured copy, so a wrap never snaps. */
+function ErrorRow({ id, text, reduced }) {
+    const copy = useRef(null);
+    const [height, setHeight] = useState("auto");
+    useEffect(() => {
+        const node = copy.current;
+        if (!node || typeof ResizeObserver === "undefined")
+            return;
+        const observer = new ResizeObserver(([entry]) => { if (entry)
+            setHeight(entry.borderBoxSize?.[0]?.blockSize ?? node.offsetHeight); });
+        observer.observe(node);
+        return () => observer.disconnect();
+    }, []);
+    return _jsx(motion.span, { className: styles.errorSlot, initial: { height: 0, opacity: 0 }, animate: { height, opacity: 1 }, exit: { height: 0, opacity: 0, transition: reduced ? { duration: 0 } : { height: motionTokens.spring.smooth, opacity: { duration: motionTokens.duration.instant } } }, transition: reduced ? { duration: 0 } : { height: motionTokens.spring.smooth, opacity: { duration: motionTokens.duration.fast } }, children: _jsx("span", { ref: copy, id: id, className: styles.error, children: _jsx(AnimatePresence, { mode: "popLayout", initial: false, custom: 1, children: _jsx(motion.span, { className: styles.errorText, custom: 1, variants: reduced ? fade : rise, initial: "enter", animate: "center", exit: "exit", children: text }, text) }) }) });
+}
+export const PasswordStrength = forwardRef(function PasswordStrength({ label, value: valueProp, defaultValue = "", onValueChange, onChange, rules = defaultPasswordRules, error, revealed: revealedProp, onRevealedChange, messages: messagesProp, shortLength, countCharacters, id, className, ...props }, ref) {
+    const messages = { ...defaultPasswordStrengthMessages, ...messagesProp, levels: { ...defaultPasswordStrengthMessages.levels, ...messagesProp?.levels } };
+    const options = { shortLength, levels: messages.levels, countCharacters };
+    const generated = useId();
+    const controlId = id ?? generated;
+    const rulesId = `${controlId}-rules`, errorId = `${controlId}-error`;
+    const hydrated = useHydrated();
+    const prefersReduced = useReducedMotion();
+    const reduced = hydrated && !!prefersReduced;
+    const [internal, setInternal] = useState(defaultValue);
+    const value = valueProp ?? internal;
+    const [revealedInternal, setRevealedInternal] = useState(false);
+    const revealed = revealedProp ?? revealedInternal;
+    const strength = estimateStrength(value, rules, options);
+    const met = new Set(strength.met);
+    // The previous level and rule states tell which way the word moves and which segments and ticks join a staggered wave.
+    const rank = strength.short ? .5 : strength.level;
+    const metKey = strength.met.join(" ");
+    const [track, setTrack] = useState({ rank, level: strength.level, previousLevel: strength.level, direction: 1, metKey, previousMet: metKey });
+    if (track.rank !== rank || track.metKey !== metKey)
+        setTrack({ rank, level: strength.level, previousLevel: track.rank !== rank ? track.level : track.previousLevel, direction: track.rank === rank ? track.direction : rank > track.rank ? 1 : -1, metKey, previousMet: track.metKey !== metKey ? track.metKey : track.previousMet });
+    const previousMet = new Set(track.previousMet.split(" ").filter(Boolean));
+    const changed = rules.filter(rule => met.has(rule.id) !== previousMet.has(rule.id)).map(rule => rule.id);
+    // Only a change after mount resolves the text, so the field never blurs in on first paint.
+    const [reveal, setReveal] = useState({ revealed, changed: false });
+    if (reveal.revealed !== revealed)
+        setReveal({ revealed, changed: true });
+    const shake = useMotionValue(0);
+    const shaking = useRef(null);
+    const lastError = useRef(error);
+    useEffect(() => {
+        const previous = lastError.current;
+        lastError.current = error;
+        if (!error || error === previous || reduced)
+            return;
+        // A spring released with sideways velocity rings out on its own, the way a refused field shakes on a phone.
+        shaking.current?.stop();
+        shaking.current = animate(shake, 0, { type: "spring", velocity: -240, stiffness: 900, damping: 15, restDelta: .1 });
+    }, [error, reduced, shake]);
+    function toggleReveal() {
+        if (revealedProp === undefined)
+            setRevealedInternal(!revealed);
+        onRevealedChange?.(!revealed);
+    }
+    const summary = strength.level ? messages.summary({ label: strength.label, met: strength.met.length, total: rules.length }) : "";
+    const describedBy = [props["aria-describedby"], error ? errorId : undefined, rulesId].filter(Boolean).join(" ");
+    return _jsxs("div", { className: styles.field, "data-level": strength.level, children: [_jsx("label", { className: styles.label, htmlFor: controlId, children: label }), _jsxs(motion.div, { className: styles.shell, style: { x: shake }, children: [_jsx("input", { autoComplete: "new-password", autoCapitalize: "off", autoCorrect: "off", spellCheck: false, ...props, ref: ref, id: controlId, type: revealed ? "text" : "password", value: value, onChange: event => { const next = event.target.value; if (valueProp === undefined)
+                            setInternal(next); onChange?.(event); onValueChange?.(next, estimateStrength(next, rules, options)); }, "aria-invalid": error ? true : props["aria-invalid"], "aria-describedby": describedBy, "data-reveal": reveal.changed ? (revealed ? "shown" : "hidden") : undefined, className: [styles.input, className].filter(Boolean).join(" ") }), _jsx("button", { type: "button", className: styles.reveal, onClick: toggleReveal, "aria-label": messages.showPassword, "aria-pressed": revealed, "aria-controls": controlId, children: _jsx(EyeMorph, { slashed: revealed, reduced: reduced }) })] }), _jsx(AnimatePresence, { initial: false, children: error ? _jsx(ErrorRow, { id: errorId, text: error, reduced: reduced }, "error") : null }), _jsxs("div", { className: styles.meterRow, children: [_jsx("div", { className: styles.meter, role: "meter", "aria-label": messages.meterLabel, "aria-valuemin": 0, "aria-valuemax": 4, "aria-valuenow": strength.level, "aria-valuetext": strength.level ? strength.label : messages.noPassword, children: [0, 1, 2, 3].map(index => {
+                            const on = index < strength.level;
+                            // A pasted password fills left to right; clearing empties right to left.
+                            const wave = on ? index - track.previousLevel : track.previousLevel - 1 - index;
+                            return _jsx("span", { className: styles.segment, children: _jsx(motion.span, { className: styles.fill, initial: false, animate: { x: on ? "0%" : "-101%" }, transition: reduced ? { duration: 0 } : { ...motionTokens.spring.smooth, delay: Math.max(0, wave) * (on ? .05 : .03) } }) }, index);
+                        }) }), _jsx("span", { className: styles.word, "aria-hidden": "true", children: _jsx(AnimatePresence, { mode: "popLayout", initial: false, custom: track.direction, children: strength.level ? _jsx(motion.span, { className: styles.wordText, custom: track.direction, variants: reduced ? fade : rise, initial: "enter", animate: "center", exit: "exit", children: strength.label }, strength.label) : null }) })] }), _jsx("ul", { id: rulesId, className: styles.rules, "aria-label": messages.rulesLabel, children: rules.map(rule => {
+                    const ok = met.has(rule.id);
+                    const remaining = value && !ok ? rule.remaining?.(value) ?? 0 : 0;
+                    const order = changed.indexOf(rule.id);
+                    return _jsxs("li", { className: styles.rule, "data-met": ok || undefined, children: [_jsx(RuleMark, { met: ok, delay: order > 0 ? order * .05 : 0, reduced: reduced }), _jsxs("span", { className: styles.ruleLabel, children: [rule.label, _jsx("span", { className: styles.srOnly, children: ok ? messages.ruleMet : messages.ruleNotMet })] }), _jsx("span", { className: styles.remaining, "aria-hidden": "true", children: _jsx(AnimatePresence, { mode: "popLayout", initial: false, custom: 1, children: remaining > 0 ? _jsxs(motion.span, { className: styles.remainingText, custom: 1, variants: reduced ? fade : rise, initial: "enter", animate: "center", exit: "exit", children: [messages.remainingPrefix ? `${messages.remainingPrefix} ` : null, _jsx(RollingNumber, { value: remaining, reduced: reduced }), messages.remainingSuffix ? ` ${messages.remainingSuffix}` : null] }, "remaining") : null }) })] }, rule.id);
+                }) }), _jsx("span", { className: styles.srOnly, role: "status", children: summary })] });
+});
+PasswordStrength.displayName = "PasswordStrength";
+export default PasswordStrength;

package/components/password-strength/password-strength.module.css

@@ -0,0 +1,57 @@
+/* No row gap: a closing error row would still pay it. Each row carries its own space instead. */
+.field { --tone: var(--border-strong); display: grid; min-width: 0; }
+.field[data-level="1"] { --tone: var(--danger); }
+.field[data-level="2"] { --tone: var(--warning); }
+.field[data-level="3"], .field[data-level="4"] { --tone: var(--success); }
+.label { margin-bottom: var(--space-related); color: var(--foreground); font-size: var(--text-sm); font-weight: 500; line-height: var(--leading-body); }
+/* The shell only transitions color; its sideways shake is a spring on transform, so the two never fight. */
+.shell { display: flex; min-height: var(--control-height-md); align-items: center; gap: var(--space-tight); padding: 0 5px 0 var(--space-inset); border: 1px solid var(--border-strong); border-radius: var(--radius-control); corner-shape: var(--corner-shape); background: var(--surface); transition: border-color var(--duration-fast) var(--ease-standard); }
+@media (hover: hover) and (pointer: fine) { .shell:hover:not(:focus-within) { border-color: var(--text-muted); } }
+.shell:focus-within { border-color: var(--foreground); }
+.shell:has(.input[aria-invalid="true"]) { border-color: var(--danger); }
+.input { width: 100%; min-width: 0; height: calc(var(--control-height-md) - 2px); padding: 0; border: 0; background: transparent; color: var(--foreground); font: inherit; font-size: var(--text-sm); letter-spacing: var(--tracking-body); outline: 0; }
+.input::placeholder { color: var(--text-muted); }
+/* Touch keyboards zoom into fields under 16px, so coarse pointers get the larger size. */
+@media (pointer: coarse) { .input { font-size: var(--text-base); } }
+/* Dots and characters resolve into each other instead of snapping. Swapping the keyframe name restarts it. */
+.input[data-reveal="shown"] { animation: resolve-shown var(--duration-standard) var(--ease-enter); }
+.input[data-reveal="hidden"] { animation: resolve-hidden var(--duration-standard) var(--ease-enter); }
+@keyframes resolve-shown { from { opacity: .35; filter: blur(2px); } }
+@keyframes resolve-hidden { from { opacity: .35; filter: blur(2px); } }
+.reveal { display: grid; width: 34px; height: 34px; flex: 0 0 auto; place-items: center; padding: 0; border: 0; border-radius: calc(var(--radius-control) - 5px); corner-shape: var(--corner-shape); background: transparent; color: var(--text-muted); cursor: pointer; -webkit-tap-highlight-color: transparent; transition: background-color var(--duration-fast) var(--ease-standard), color var(--duration-fast) var(--ease-standard), transform var(--duration-spring) var(--ease-spring); }
+@media (hover: hover) and (pointer: fine) { .reveal:hover { background: var(--surface-muted); color: var(--foreground); } }
+.reveal:active { transform: scale(.94); transition: background-color var(--duration-fast) var(--ease-standard), color var(--duration-fast) var(--ease-standard), transform 100ms var(--ease-standard); }
+.reveal[aria-pressed="true"] { color: var(--foreground); }
+/* The row's space is padding inside the clipped slot, so its height opens from a true zero. */
+.errorSlot { display: block; overflow: hidden; }
+.error { position: relative; display: block; padding-top: var(--space-related); color: var(--danger); font-size: var(--text-xs); line-height: var(--leading-body); }
+.errorText { display: block; }
+.meterRow { display: flex; align-items: center; gap: var(--space-group); margin-top: var(--space-group); }
+.meter { display: grid; flex: 1 1 auto; min-width: 0; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 5px; }
+/* Each fill slides in from the left inside its clipped track, so the rounded ends keep their shape at every frame. */
+.segment { position: relative; height: 4px; overflow: hidden; isolation: isolate; border-radius: var(--radius-full); corner-shape: round; background: var(--border); }
+.fill { position: absolute; inset: 0; border-radius: inherit; corner-shape: inherit; background: var(--tone); transition: background-color var(--duration-standard) var(--ease-standard); }
+/* A fixed slot: the meter never resizes when the word changes, and the word stays flush with the field's edge. */
+.word { position: relative; display: block; flex: 0 0 4.5rem; height: 1.4em; color: var(--foreground); font-size: var(--text-sm); font-weight: 500; line-height: var(--leading-body); text-align: right; white-space: nowrap; }
+.wordText { display: inline-block; }
+.rules { display: grid; gap: 6px; margin: var(--space-inset) 0 0; padding: 0; list-style: none; }
+.rule { display: flex; min-height: 1.25rem; align-items: center; gap: 10px; color: var(--text-muted); font-size: var(--text-sm); line-height: var(--leading-body); transition: color var(--duration-standard) var(--ease-standard); }
+.rule[data-met] { color: var(--foreground); }
+.ruleLabel { min-width: 0; }
+/* The outline hands over to a faint tint while the tick draws on top; most of the color sits on the tick. */
+.mark { position: relative; display: block; width: 16px; height: 16px; flex: 0 0 16px; border: 1.25px solid var(--border-strong); border-radius: var(--radius-full); corner-shape: round; color: var(--success); transition: border-color var(--duration-fast) var(--ease-standard); }
+.rule[data-met] .mark { border-color: transparent; }
+.markFill { position: absolute; inset: -1.25px; border-radius: inherit; corner-shape: inherit; background: color-mix(in oklab, var(--success) 16%, transparent); }
+.tick { position: absolute; inset: -1.25px; width: 16px; height: 16px; }
+.remaining { position: relative; display: block; margin-left: auto; padding-left: var(--space-related); color: var(--text-muted); font-size: var(--text-xs); white-space: nowrap; }
+.remainingText { display: inline-flex; align-items: baseline; gap: .28em; }
+.number { display: inline-flex; font-variant-numeric: tabular-nums; }
+/* Places clip sideways only, so a narrowing column never shows half a digit and a turning digit is never cut. */
+.place { position: relative; display: inline-block; overflow-x: clip; }
+.digit { display: inline-block; }
+.srOnly { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
+@media (prefers-reduced-motion: reduce) {
+  .shell, .reveal, .fill, .rule, .mark { transition: none; }
+  .reveal:active { transform: none; }
+  .input[data-reveal] { animation: none; }
+}

package/components/phone-input/phone-input.d.ts

@@ -0,0 +1,73 @@
+import type { FocusEvent as ReactFocusEvent } from "react";
+export interface PhoneCountry {
+    /** ISO 3166-1 alpha-2 code, such as "US". */
+    iso: string;
+    name: string;
+    /** Country calling code without the plus, such as "44". */
+    dial: string;
+    /** National formats from shortest to longest. `#` is a digit, anything else is a separator. */
+    patterns: string[];
+    /** A national number people may type before the number itself, such as "0" in "07911 123456". */
+    trunk: string;
+    /** A realistic national number, used for the placeholder and the typing guide. */
+    example: string;
+    /** Area codes that pick this country when several share a calling code, such as Canada inside +1. */
+    areaCodes?: string[];
+}
+export declare const PHONE_COUNTRIES: PhoneCountry[];
+/** Regional indicator letters. Platforms without flag glyphs show the two letters, which still read. */
+export declare const flagOf: (iso: string) => string;
+/** Formats national digits as typed, keeping a typed trunk prefix: "07911123456" in the UK reads "07911 123456". */
+export declare function formatNational(entry: PhoneCountry, digits: string): string;
+export type PhoneStatus = "empty" | "incomplete" | "valid" | "too-long";
+/** Reads "+44 (0)7911 123456", "0044 7911…", or "+14165550123" into a country and national digits. Longest calling code wins. */
+export declare function parsePhoneNumber(input: string, pool?: PhoneCountry[]): {
+    country: PhoneCountry;
+    national: string;
+} | null;
+/** Formats an E.164 number for display, such as "+44 7400 123456". Returns the input when it cannot be read. */
+export declare function formatPhoneNumber(e164: string): string;
+export interface PhoneInputDetails {
+    country: PhoneCountry;
+    /** The number as shown in the field, without the calling code. */
+    formatted: string;
+    status: PhoneStatus;
+    valid: boolean;
+}
+export interface PhoneInputProps {
+    label: string;
+    hideLabel?: boolean;
+    /** The number in E.164, such as "+14155550132". An empty string clears the field. */
+    value?: string;
+    defaultValue?: string;
+    /** Fires on every edit with the E.164 number (empty when there are no digits) and its parsed details. */
+    onValueChange?: (value: string, details: PhoneInputDetails) => void;
+    /** ISO code of the selected country. */
+    country?: string;
+    /** ISO code used until someone picks a country or enters an international number. */
+    defaultCountry?: string;
+    onCountryChange?: (iso: string) => void;
+    /** Limit the picker to these ISO codes. */
+    countries?: string[];
+    /** Pinned at the top of the picker under "Suggested". */
+    preferredCountries?: string[];
+    description?: string;
+    /** Replaces the built-in validation message. */
+    error?: string;
+    /** Show a message after blur when the number is incomplete. On by default. */
+    validate?: boolean;
+    disabled?: boolean;
+    required?: boolean;
+    /** Adds a hidden input carrying the E.164 value for native form submission. */
+    name?: string;
+    id?: string;
+    className?: string;
+    onBlur?: (event: ReactFocusEvent<HTMLInputElement>) => void;
+}
+/**
+ * A phone number field with a country picker. The country button grows into a searchable list, the number formats as it is
+ * typed with a faint guide showing the rest of the expected shape, pasted or autofilled international numbers pick their own
+ * country, and the value comes out in E.164. Typing "+" in the number jumps into the picker with a calling code search.
+ */
+export declare const PhoneInput: import("react").ForwardRefExoticComponent<PhoneInputProps & import("react").RefAttributes<HTMLInputElement>>;
+export default PhoneInput;