@bspk/ui 1.1.32 → 1.1.33

package/src/index.ts

@@ -6,7 +6,51 @@
  * @bspk/ui/Txt".
  */
 
-import { ComponentProps, JSXElementConstructor, ReactNode } from 'react';
+import { JSXElementConstructor, ReactNode, ComponentPropsWithoutRef } from 'react';
+
+export const BRANDS: {
+    /** The title of the brand. */
+    title: string;
+    /** The slug of the brand, used in URLs and identifiers. */
+    slug: Brand;
+}[] = [
+    {
+        title: 'Anywhere',
+        slug: 'anywhere',
+    },
+    {
+        title: 'Better Homes & Gardens',
+        slug: 'better-homes-gardens',
+    },
+    {
+        title: 'Cartus',
+        slug: 'cartus',
+    },
+    {
+        title: 'Century 21',
+        slug: 'century-21',
+    },
+    {
+        title: 'Coldwell Banker',
+        slug: 'coldwell-banker',
+    },
+    {
+        title: 'Corcoran',
+        slug: 'corcoran',
+    },
+    {
+        title: 'Denali Boss',
+        slug: 'denali-boss',
+    },
+    {
+        title: 'ERA',
+        slug: 'era',
+    },
+    {
+        title: "Sotheby's",
+        slug: 'sothebys',
+    },
+] as const;
 
 export type AlertVariant = 'error' | 'informational' | 'success' | 'warning';
 
@@ -16,7 +60,12 @@ export type ElementProps<
     P extends Record<string, unknown>,
     E extends JSXElementConstructor<unknown> | keyof JSX.IntrinsicElements,
     O extends string = '',
-> = Omit<ComponentProps<E>, O | keyof P> & P;
+> = Omit<ComponentPropsWithoutRef<E>, O | keyof P> & P;
+
+export type ElementConstructorProps<
+    E extends JSXElementConstructor<unknown> | keyof JSX.IntrinsicElements,
+    O extends string = '',
+> = Omit<ComponentPropsWithoutRef<E>, O>;
 
 export type ButtonSize = 'large' | 'medium' | 'small' | 'x-small';
 
@@ -37,8 +86,6 @@ export type CallToActionButton = {
     size?: ButtonSize;
 };
 
-export type CommonProps<K extends keyof CommonPropsLibrary> = Pick<CommonPropsLibrary, K>;
-
 /**
  * The props that are common to input elements.
  *
@@ -61,6 +108,8 @@ export type InvalidPropsLibrary = {
     errorMessage?: string;
 };
 
+export type InvalidProps<K extends keyof InvalidPropsLibrary> = Pick<InvalidPropsLibrary, K>;
+
 export type CommonPropsLibrary = {
     /** The id of the element. If not provided one will be generated. */
     id?: string;
@@ -118,8 +167,16 @@ export type CommonPropsLibrary = {
      * @required
      */
     'aria-label': string;
+    /**
+     * This is a utility attribute used to identify the owning component of another component.
+     *
+     * This is used to identify the component in the UI library and is not intended for public use.
+     */
+    'data-bspk-owner'?: string;
 };
 
+export type CommonProps<K extends keyof CommonPropsLibrary> = Pick<CommonPropsLibrary, K>;
+
 export type Brand =
     | 'anywhere'
     | 'better-homes-gardens'
@@ -131,16 +188,4 @@ export type Brand =
     | 'era'
     | 'sothebys';
 
-export const BRANDS: { title: string; slug: Brand }[] = [
-    { title: 'Anywhere', slug: 'anywhere' },
-    { title: 'Better Homes & Gardens', slug: 'better-homes-gardens' },
-    { title: 'Cartus', slug: 'cartus' },
-    { title: 'Century 21', slug: 'century-21' },
-    { title: 'Coldwell Banker', slug: 'coldwell-banker' },
-    { title: 'Corcoran', slug: 'corcoran' },
-    { title: 'Denali Boss', slug: 'denali-boss' },
-    { title: 'ERA', slug: 'era' },
-    { title: "Sotheby's", slug: 'sothebys' },
-] as const;
-
 /** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/utils/countryCodes.ts

@@ -0,0 +1,276 @@
+/* eslint-disable @cspell/spellchecker */
+import { IconName } from '@bspk/icons/meta';
+import { CountryCode } from 'libphonenumber-js';
+
+export type SupportedCountryCode = keyof CountryCodeData;
+
+type CountryCodeData = Omit<
+    Record<CountryCode, { name: string; flagIconName: IconName }>,
+    | 'AC'
+    | 'CI'
+    | 'CV'
+    | 'FM'
+    | 'GP'
+    | 'KN'
+    | 'LC'
+    | 'MF'
+    | 'NC'
+    | 'RE'
+    | 'SH'
+    | 'SJ'
+    | 'TA'
+    | 'VA'
+    | 'VC'
+    | 'WF'
+    | 'XK'
+    | 'YT'
+>;
+
+export const countryCodeData: CountryCodeData = {
+    AD: { name: 'Andorra', flagIconName: 'FlagAndorra' },
+    AE: { name: 'United Arab Emirates', flagIconName: 'FlagUnitedArabEmirates' },
+    AF: { name: 'Afghanistan', flagIconName: 'FlagAfghanistan' },
+    AG: { name: 'Antigua and Barbuda', flagIconName: 'FlagAntiguaAndBarbuda' },
+    AI: { name: 'Anguilla', flagIconName: 'FlagAnguilla' },
+    AL: { name: 'Albania', flagIconName: 'FlagAlbania' },
+    AM: { name: 'Armenia', flagIconName: 'FlagArmenia' },
+    AO: { name: 'Angola', flagIconName: 'FlagAngola' },
+    AR: { name: 'Argentina', flagIconName: 'FlagArgentina' },
+    AS: { name: 'American Samoa', flagIconName: 'FlagAmericanSamoa' },
+    AT: { name: 'Austria', flagIconName: 'FlagAustria' },
+    AU: { name: 'Australia', flagIconName: 'FlagAustralia' },
+    AW: { name: 'Aruba', flagIconName: 'FlagAruba' },
+    AX: { name: 'Åland Islands', flagIconName: 'FlagAlandIsland' },
+    AZ: { name: 'Azerbaijan', flagIconName: 'FlagAzerbaijan' },
+    BA: { name: 'Bosnia and Herzegovina', flagIconName: 'FlagBosniaAndHerzegovina' },
+    BB: { name: 'Barbados', flagIconName: 'FlagBarbados' },
+    BD: { name: 'Bangladesh', flagIconName: 'FlagBangladesh' },
+    BE: { name: 'Belgium', flagIconName: 'FlagBelgium' },
+    BF: { name: 'Burkina Faso', flagIconName: 'FlagBurkinaFaso' },
+    BG: { name: 'Bulgaria', flagIconName: 'FlagBulgaria' },
+    BH: { name: 'Bahrain', flagIconName: 'FlagBahrain' },
+    BI: { name: 'Burundi', flagIconName: 'FlagBurundi' },
+    BJ: { name: 'Benin', flagIconName: 'FlagBenin' },
+    BL: { name: 'Saint Barthélemy', flagIconName: 'FlagSaintBarthelemy' },
+    BM: { name: 'Bermuda', flagIconName: 'FlagBermuda' },
+    BN: { name: 'Brunei', flagIconName: 'FlagBrunei' },
+    BO: { name: 'Bolivia', flagIconName: 'FlagBolivia' },
+    BQ: { name: 'Bonaire, Sint Eustatius and Saba', flagIconName: 'FlagBonaire' },
+    BR: { name: 'Brazil', flagIconName: 'FlagBrazil' },
+    BS: { name: 'Bahamas', flagIconName: 'FlagBahamas' },
+    BT: { name: 'Bhutan', flagIconName: 'FlagBhutan' },
+    BW: { name: 'Botswana', flagIconName: 'FlagBotswana' },
+    BY: { name: 'Belarus', flagIconName: 'FlagBelarus' },
+    BZ: { name: 'Belize', flagIconName: 'FlagBelize' },
+    CA: { name: 'Canada', flagIconName: 'FlagCanada' },
+    CC: { name: 'Cocos (Keeling) Islands', flagIconName: 'FlagCocosIslands' },
+    CD: { name: 'Democratic Republic of the Congo', flagIconName: 'FlagDemocraticRepublicOfTheCongo' },
+    CF: { name: 'Central African Republic', flagIconName: 'FlagCentralAfricanRepublic' },
+    CG: { name: 'Republic of the Congo', flagIconName: 'FlagRepublicOfTheCongo' },
+    CH: { name: 'Switzerland', flagIconName: 'FlagSwitzerland' },
+    // CI: { //     name: "Ivory Coast", //     flagIconName: "FlagIvoryCoast"// },
+    CK: { name: 'Cook Islands', flagIconName: 'FlagCookIsland' },
+    CL: { name: 'Chile', flagIconName: 'FlagChile' },
+    CM: { name: 'Cameroon', flagIconName: 'FlagCameroon' },
+    CN: { name: 'China', flagIconName: 'FlagChina' },
+    CO: { name: 'Colombia', flagIconName: 'FlagColombia' },
+    CR: { name: 'Costa Rica', flagIconName: 'FlagCostaRica' },
+    CU: { name: 'Cuba', flagIconName: 'FlagCuba' },
+    // CV: { //     name: "Cape Verde", //     flagIconName: "FlagCapeVerde"// },
+    CW: { name: 'Curaçao', flagIconName: 'FlagCuracao' },
+    CX: { name: 'Christmas Island', flagIconName: 'FlagChristmasIsland' },
+    CY: { name: 'Cyprus', flagIconName: 'FlagCyprus' },
+    CZ: { name: 'Czech Republic', flagIconName: 'FlagCzechRepublic' },
+    DE: { name: 'Germany', flagIconName: 'FlagGermany' },
+    DJ: { name: 'Djibouti', flagIconName: 'FlagDjibouti' },
+    DK: { name: 'Denmark', flagIconName: 'FlagDenmark' },
+    DM: { name: 'Dominica', flagIconName: 'FlagDominica' },
+    DO: { name: 'Dominican Republic', flagIconName: 'FlagDominicanRepublic' },
+    DZ: { name: 'Algeria', flagIconName: 'FlagAlgeria' },
+    EC: { name: 'Ecuador', flagIconName: 'FlagEcuador' },
+    EE: { name: 'Estonia', flagIconName: 'FlagEstonia' },
+    EG: { name: 'Egypt', flagIconName: 'FlagEgypt' },
+    EH: { name: 'Western Sahara', flagIconName: 'FlagWestSahara' },
+    ER: { name: 'Eritrea', flagIconName: 'FlagEritrea' },
+    ES: { name: 'Spain', flagIconName: 'FlagSpain' },
+    ET: { name: 'Ethiopia', flagIconName: 'FlagEthiopia' },
+    FI: { name: 'Finland', flagIconName: 'FlagFinland' },
+    FJ: { name: 'Fiji', flagIconName: 'FlagFiji' },
+    FK: { name: 'Falkland Islands', flagIconName: 'FlagFalklandIslands' },
+    // FM: { //     name: "Micronesia", //     flagIconName: "FlagMicronesia"// },
+    FO: { name: 'Faroe Islands', flagIconName: 'FlagFaroeIslands' },
+    FR: { name: 'France', flagIconName: 'FlagFrance' },
+    GA: { name: 'Gabon', flagIconName: 'FlagGabon' },
+    GB: { name: 'United Kingdom', flagIconName: 'FlagUnitedKingdom' },
+    GD: { name: 'Grenada', flagIconName: 'FlagGrenada' },
+    GE: { name: 'Georgia', flagIconName: 'FlagGeorgia' },
+    GF: { name: 'French Guiana', flagIconName: 'FlagFrenchGuiana' },
+    GG: { name: 'Guernsey', flagIconName: 'FlagGuernsey' },
+    GH: { name: 'Ghana', flagIconName: 'FlagGhana' },
+    GI: { name: 'Gibraltar', flagIconName: 'FlagGibraltar' },
+    GL: { name: 'Greenland', flagIconName: 'FlagGreeland' },
+    GM: { name: 'Gambia', flagIconName: 'FlagGambia' },
+    GN: { name: 'Guinea', flagIconName: 'FlagGuinea' },
+    // GP: { //     name: "Guadeloupe", //     flagIconName: "FlagGuadeloupe"// },
+    GQ: { name: 'Equatorial Guinea', flagIconName: 'FlagEquatorialGuinea' },
+    GR: { name: 'Greece', flagIconName: 'FlagGreece' },
+    GT: { name: 'Guatemala', flagIconName: 'FlagGuatemala' },
+    GU: { name: 'Guam', flagIconName: 'FlagGuam' },
+    GW: { name: 'Guinea-Bissau', flagIconName: 'FlagGuinea' },
+    GY: { name: 'Guyana', flagIconName: 'FlagGuyana' },
+    HK: { name: 'Hong Kong', flagIconName: 'FlagHongKong' },
+    HN: { name: 'Honduras', flagIconName: 'FlagHonduras' },
+    HR: { name: 'Croatia', flagIconName: 'FlagCroatia' },
+    HT: { name: 'Haiti', flagIconName: 'FlagHaiti' },
+    HU: { name: 'Hungary', flagIconName: 'FlagHungary' },
+    ID: { name: 'Indonesia', flagIconName: 'FlagIndonesia' },
+    IE: { name: 'Ireland', flagIconName: 'FlagIreland' },
+    IL: { name: 'Israel', flagIconName: 'FlagIsrael' },
+    IM: { name: 'Isle of Man', flagIconName: 'FlagIsleOfMan' },
+    IN: { name: 'India', flagIconName: 'FlagIndia' },
+    IO: { name: 'British Indian Ocean Territory', flagIconName: 'FlagIndianOceanTerritory' },
+    IQ: { name: 'Iraq', flagIconName: 'FlagIraq' },
+    IR: { name: 'Iran', flagIconName: 'FlagIran' },
+    IS: { name: 'Iceland', flagIconName: 'FlagIceland' },
+    IT: { name: 'Italy', flagIconName: 'FlagItaly' },
+    JE: { name: 'Jersey', flagIconName: 'FlagJersey' },
+    JM: { name: 'Jamaica', flagIconName: 'FlagJamaica' },
+    JO: { name: 'Jordan', flagIconName: 'FlagJordan' },
+    JP: { name: 'Japan', flagIconName: 'FlagJapan' },
+    KE: { name: 'Kenya', flagIconName: 'FlagKenya' },
+    KG: { name: 'Kyrgyzstan', flagIconName: 'FlagKyrgyzstan' },
+    KH: { name: 'Cambodia', flagIconName: 'FlagCambodia' },
+    KI: { name: 'Kiribati', flagIconName: 'FlagKiribati' },
+    KM: { name: 'Comoros', flagIconName: 'FlagComoros' },
+    // KN: { //     name: "Saint Kitts and Nevis", //     flagIconName: "FlagSaintKittsandNevis"// },
+    KP: { name: 'North Korea', flagIconName: 'FlagNorthKorea' },
+    KR: { name: 'South Korea', flagIconName: 'FlagSouthKorea' },
+    KW: { name: 'Kuwait', flagIconName: 'FlagKuwait' },
+    KY: { name: 'Cayman Islands', flagIconName: 'FlagCaymanIslands' },
+    KZ: { name: 'Kazakhstan', flagIconName: 'FlagKazakhstan' },
+    LA: { name: 'Laos', flagIconName: 'FlagLaos' },
+    LB: { name: 'Lebanon', flagIconName: 'FlagLebanon' },
+    // LC: { //     name: "Saint Lucia", //     flagIconName: "FlagSaintLucia"// },
+    LI: { name: 'Liechtenstein', flagIconName: 'FlagLiechtenstein' },
+    LK: { name: 'Sri Lanka', flagIconName: 'FlagSriLanka' },
+    LR: { name: 'Liberia', flagIconName: 'FlagLiberia' },
+    LS: { name: 'Lesotho', flagIconName: 'FlagLesotho' },
+    LT: { name: 'Lithuania', flagIconName: 'FlagLithuania' },
+    LU: { name: 'Luxembourg', flagIconName: 'FlagLuxembourg' },
+    LV: { name: 'Latvia', flagIconName: 'FlagLatvia' },
+    LY: { name: 'Libya', flagIconName: 'FlagLibya' },
+    MA: { name: 'Morocco', flagIconName: 'FlagMorroco' },
+    MC: { name: 'Monaco', flagIconName: 'FlagMonaco' },
+    MD: { name: 'Moldova', flagIconName: 'FlagMoldova' },
+    ME: { name: 'Montenegro', flagIconName: 'FlagMontenegro' },
+    // MF: { //     name: "Saint Martin", //     flagIconName: "FlagSaintMartin"// },
+    MG: { name: 'Madagascar', flagIconName: 'FlagMadagascar' },
+    MH: { name: 'Marshall Islands', flagIconName: 'FlagMarshallIslands' },
+    MK: { name: 'North Macedonia', flagIconName: 'FlagNorthMacedonia' },
+    ML: { name: 'Mali', flagIconName: 'FlagMali' },
+    MM: { name: 'Myanmar', flagIconName: 'FlagMyanmar' },
+    MN: { name: 'Mongolia', flagIconName: 'FlagMongolia' },
+    MO: { name: 'Macau', flagIconName: 'FlagMacau' },
+    MP: { name: 'Northern Mariana Islands', flagIconName: 'FlagNorthernMarianaIslands' },
+    MQ: { name: 'Martinique', flagIconName: 'FlagMartinique' },
+    MR: { name: 'Mauritania', flagIconName: 'FlagMauritania' },
+    MS: { name: 'Montserrat', flagIconName: 'FlagMontserrat' },
+    MT: { name: 'Malta', flagIconName: 'FlagMalta' },
+    MU: { name: 'Mauritius', flagIconName: 'FlagMauritius' },
+    MV: { name: 'Maldives', flagIconName: 'FlagMaldives' },
+    MW: { name: 'Malawi', flagIconName: 'FlagMalawi' },
+    MX: { name: 'Mexico', flagIconName: 'FlagMexico' },
+    MY: { name: 'Malaysia', flagIconName: 'FlagMalasia' },
+    MZ: { name: 'Mozambique', flagIconName: 'FlagMozambique' },
+    NA: { name: 'Namibia', flagIconName: 'FlagNamibia' },
+    // NC: { //     name: "New Caledonia", //     flagIconName: "FlagNewCaledonia"// },
+    NE: { name: 'Niger', flagIconName: 'FlagNiger' },
+    NF: { name: 'Norfolk Island', flagIconName: 'FlagNorfolkIsland' },
+    NG: { name: 'Nigeria', flagIconName: 'FlagNigeria' },
+    NI: { name: 'Nicaragua', flagIconName: 'FlagNicaragua' },
+    NL: { name: 'Netherlands', flagIconName: 'FlagNetherlands' },
+    NO: { name: 'Norway', flagIconName: 'FlagNorway' },
+    NP: { name: 'Nepal', flagIconName: 'FlagNepal' },
+    NR: { name: 'Nauru', flagIconName: 'FlagNauru' },
+    NU: { name: 'Niue', flagIconName: 'FlagNiue' },
+    NZ: { name: 'New Zealand', flagIconName: 'FlagNewZealand' },
+    OM: { name: 'Oman', flagIconName: 'FlagOman' },
+    PS: { name: 'Palestine', flagIconName: 'FlagPalestine' },
+    PA: { name: 'Panama', flagIconName: 'FlagPanama' },
+    PE: { name: 'Peru', flagIconName: 'FlagPeru' },
+    PF: { name: 'French Polynesia', flagIconName: 'FlagFrenchPolynesia' },
+    PG: { name: 'Papua New Guinea', flagIconName: 'FlagPapuaNewGuinea' },
+    PH: { name: 'Philippines', flagIconName: 'FlagPhilippines' },
+    PK: { name: 'Pakistan', flagIconName: 'FlagPakistan' },
+    PL: { name: 'Poland', flagIconName: 'FlagPoland' },
+    PM: { name: 'Saint Pierre and Miquelon', flagIconName: 'FlagSaintBarthelemy' },
+    PR: { name: 'Puerto Rico', flagIconName: 'FlagPuertoRico' },
+    PT: { name: 'Portugal', flagIconName: 'FlagPortugal' },
+    PW: { name: 'Palau', flagIconName: 'FlagPalau' },
+    PY: { name: 'Paraguay', flagIconName: 'FlagParaguay' },
+    QA: { name: 'Qatar', flagIconName: 'FlagQatar' },
+    // RE: { //     name: "Réunion", //     flagIconName: "FlagRéunion"// },
+    RO: { name: 'Romania', flagIconName: 'FlagRomania' },
+    RS: { name: 'Serbia', flagIconName: 'FlagSerbia' },
+    RU: { name: 'Russia', flagIconName: 'FlagRussia' },
+    RW: { name: 'Rwanda', flagIconName: 'FlagRwanda' },
+    SA: { name: 'Saudi Arabia', flagIconName: 'FlagSaudiArabia' },
+    SB: { name: 'Solomon Islands', flagIconName: 'FlagSolomonIslands' },
+    SC: { name: 'Seychelles', flagIconName: 'FlagSeychelles' },
+    SD: { name: 'Sudan', flagIconName: 'FlagSudan' },
+    SE: { name: 'Sweden', flagIconName: 'FlagSweden' },
+    SG: { name: 'Singapore', flagIconName: 'FlagSingapore' },
+    // SH: { //     name: "Saint Helena", //     flagIconName: "FlagSaintHelena"// },
+    SI: { name: 'Slovenia', flagIconName: 'FlagSlovenia' },
+    // SJ: { //     name: "Svalbard and Jan Mayen", //     flagIconName: "FlagSvalbardandJanMayen"// },
+    SK: { name: 'Slovakia', flagIconName: 'FlagSlovakia' },
+    SL: { name: 'Sierra Leone', flagIconName: 'FlagSierraLeone' },
+    SM: { name: 'San Marino', flagIconName: 'FlagSanMarino' },
+    SN: { name: 'Senegal', flagIconName: 'FlagSenegal' },
+    SO: { name: 'Somalia', flagIconName: 'FlagSomalia' },
+    SR: { name: 'Suriname', flagIconName: 'FlagSuriname' },
+    SS: { name: 'South Sudan', flagIconName: 'FlagSouthSudan' },
+    ST: { name: 'São Tomé and Príncipe', flagIconName: 'FlagSaoTomeAndPrincipe' },
+    SV: { name: 'El Salvador', flagIconName: 'FlagElSalvador' },
+    SX: { name: 'Sint Maarten', flagIconName: 'FlagSintMaarten' },
+    SY: { name: 'Syria', flagIconName: 'FlagSyria' },
+    SZ: { name: 'Eswatini', flagIconName: 'FlagEswatini' },
+    // TA: { //     name: "Tristan da Cunha", //     flagIconName: "FlagTristanDaCunha"// },
+    TC: { name: 'Turks and Caicos Islands', flagIconName: 'FlagTurksAndCaicos' },
+    TD: { name: 'Chad', flagIconName: 'FlagChad' },
+    TG: { name: 'Togo', flagIconName: 'FlagTogo' },
+    TH: { name: 'Thailand', flagIconName: 'FlagThailand' },
+    TJ: { name: 'Tajikistan', flagIconName: 'FlagTajikistan' },
+    TK: { name: 'Tokelau', flagIconName: 'FlagTokelau' },
+    TL: { name: 'Timor-Leste', flagIconName: 'FlagTimorLeste' },
+    TM: { name: 'Turkmenistan', flagIconName: 'FlagTurkmenistan' },
+    TN: { name: 'Tunisia', flagIconName: 'FlagTunisia' },
+    TO: { name: 'Tonga', flagIconName: 'FlagTonga' },
+    TR: { name: 'Turkey', flagIconName: 'FlagTurkey' },
+    TT: { name: 'Trinidad and Tobago', flagIconName: 'FlagTrinidadAndTobago' },
+    TV: { name: 'Tuvalu', flagIconName: 'FlagTuvalu' },
+    TW: { name: 'Taiwan', flagIconName: 'FlagTaiwan' },
+    TZ: { name: 'Tanzania', flagIconName: 'FlagTanzania' },
+    UA: { name: 'Ukraine', flagIconName: 'FlagUkraine' },
+    UG: { name: 'Uganda', flagIconName: 'FlagUganda' },
+    US: { name: 'United States of America', flagIconName: 'FlagUnitedStates' },
+    UY: { name: 'Uruguay', flagIconName: 'FlagUruguay' },
+    UZ: { name: 'Uzbekistan', flagIconName: 'FlagUzbekistan' },
+    // VA: { //     name: "Vatican City", //     flagIconName: "FlagVaticanCity"// },
+    // VC: { //     name: "Saint Vincent and the Grenadines", //     flagIconName: "FlagSaintVincentandtheGrenadines"// },
+    VE: { name: 'Venezuela', flagIconName: 'FlagVenezuela' },
+    VG: { name: 'British Virgin Islands', flagIconName: 'FlagVirginIslandsBritish' },
+    VI: { name: 'United States Virgin Islands', flagIconName: 'FlagVirginIslands' },
+    VN: { name: 'Vietnam', flagIconName: 'FlagVietnam' },
+    VU: { name: 'Vanuatu', flagIconName: 'FlagVanuatu' },
+    // WF: { //     name: "Wallis and Futuna", //     flagIconName: "FlagWallisandFutuna"// },
+    WS: { name: 'Samoa', flagIconName: 'FlagSamoa' },
+    // XK: { //     name: "Kosovo", //     flagIconName: "FlagKosovo"// },
+    YE: { name: 'Yemen', flagIconName: 'FlagYemen' },
+    // YT: { //     name: "Mayotte", //     flagIconName: "FlagMayotte"// },
+    ZA: { name: 'South Africa', flagIconName: 'FlagSouthAfrica' },
+    ZM: { name: 'Zambia', flagIconName: 'FlagZambia' },
+    ZW: { name: 'Zimbabwe', flagIconName: 'FlagZimbabwe' },
+} as const;
+
+export const countryCodes = Object.keys(countryCodeData) as SupportedCountryCode[];

package/src/utils/cwv.ts

@@ -0,0 +1,13 @@
+import { CSSProperties } from 'react';
+
+export type CSSWithVariables = CSSProperties & Record<`--${string}`, unknown>;
+
+/**
+ * Ensures that the styles with custom properties (variables) are properly typed.
+ *
+ * @param input {CSSWithVariables}
+ * @returns CSSProperties
+ */
+export function cssWithVars(input: CSSWithVariables) {
+    return input as CSSProperties;
+}

package/src/utils/demo.ts

@@ -0,0 +1,121 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import { AlertVariant } from '-';
+
+export type TypeProperty = {
+    name: string;
+    description?: string;
+    type?: string[] | string;
+    default?: unknown;
+    required?: boolean;
+    options?: number[] | string[];
+    variants?: string[];
+    references?: string[];
+    minimum?: number;
+    maximum?: number;
+    example?: string;
+    exampleType?: string;
+};
+
+export type DemoAction = (message: string, variant?: AlertVariant) => void;
+
+export type DemoSetState<Props = Record<string, unknown>> = (
+    next: Partial<Props> | ((prev: Props) => Partial<Props>),
+) => void;
+
+export type ComponentPhase =
+    | 'AccessibilityReview'
+    | 'Backlog'
+    | 'DesignReview'
+    | 'ProductionReady'
+    | 'Utility'
+    | 'WorkInProgress';
+
+export type TypePropertyDemo = Omit<TypeProperty, 'example'> & {
+    libraryDefault?: TypeProperty['default'];
+    label?: string;
+    example?: any;
+    disabled?: boolean;
+};
+
+export type TypePropertyDemoWithControls = Pick<TypeProperty, 'type'> &
+    TypePropertyDemo & {
+        haveControl: boolean;
+        typeOptions: number[] | string[] | undefined;
+        multiline?: boolean;
+    };
+
+export type ComponentExampleRenderProps<Props = Record<string, unknown>> = {
+    props: Props;
+    preset?: DemoPreset;
+    setState: DemoSetState<Props>;
+    Component: React.ComponentType<Props>;
+    context?: {
+        [key: string]: unknown;
+        preset?: DemoPreset;
+    };
+    id: string;
+};
+
+export type ComponentExampleRender<Props = Record<string, unknown>> = (
+    params: ComponentExampleRenderProps<Props>,
+) => React.ReactNode;
+
+export type ComponentExample<Props = Record<string, unknown>, PropName = keyof Props> = {
+    /**
+     * The style of the wrapping component.
+     *
+     * //
+     */
+    containerStyle?: React.CSSProperties | ((propState: Props) => React.CSSProperties);
+    /**
+     * True to hide all or a list of variants to hide.
+     *
+     * Helpful for hiding variants that can have unexpected collisions with the other examples.
+     */
+    hideVariants?: PropName[] | true;
+    /**
+     * This is used to set the initial propState of the component.
+     *
+     * Specifically to highlight certain features of the component.
+     */
+    presets?: Preset<Props>[];
+    /**
+     * This is used to set the initial propState of the component before any preset propState is applied.
+     *
+     * Specifically to highlight certain features of the component.
+     */
+    defaultState?: Partial<Props>;
+    /**
+     * The component to render in the example.
+     *
+     * By default, this will be the component that is being documented.
+     *
+     * If you only need to update the props of the component, you can use renderProps.
+     */
+    render?: ComponentExampleRender<Props>;
+    /** We may not want certain props editable in the props table. */
+    disableProps?: PropName[];
+};
+
+export type ComponentExampleFn<Props = Record<string, unknown>> = (params: {
+    setState: DemoSetState<Props>;
+    action: DemoAction;
+}) => ComponentExample<Props>;
+
+export type Preset<Props> = {
+    /** The name of the preset. This is used to display the preset in the UI. */
+    label: string;
+    /** The props of the component. This is used to set props of the component. These values can't be changed in the UI. */
+    propState?: Partial<Props>;
+    /** Determines if the preset is the default preset. This is used to set the initial propState of the component. */
+    isDefault?: boolean;
+};
+
+export type DemoPreset<P = Record<string, unknown>> = Preset<P> & {
+    value: string;
+};
+
+export function createUid(prefix: string = 'uid'): string {
+    return `${prefix}-${Math.random().toString(36).substring(2, 9)}`;
+}

package/src/utils/errors.ts

@@ -0,0 +1,105 @@
+/**
+ * ERROR LOGGING
+ *
+ * When an error is logged it is stored in a buffer.
+ *
+ * After a debounce period all errors are merged and of they no longer exist are cleared.
+ *
+ * These errors are grouped by contextId and dispatched as a custom event.
+ *
+ * At this point the buffer is cleared.
+ */
+
+import { createContext, useContext, useEffect, useState } from 'react';
+
+export type ErrorDetail = {
+    message: string;
+    data?: unknown;
+    contextId?: string;
+    location: Location;
+    exists: boolean;
+};
+
+export const bspkErrorType = (contextId: string) => `bspk-error-${contextId}`;
+
+export type LogError = (exists: boolean, message: string, data?: unknown) => boolean;
+
+let logBuffer: Record<string, ErrorDetail[]> = {};
+let logDebounce: ReturnType<typeof setTimeout> | null = null;
+
+export function logError(detail: Pick<ErrorDetail, 'contextId' | 'data' | 'exists' | 'message'>): boolean {
+    if (!detail.contextId) return detail.exists;
+
+    const bufferKey = `${detail.contextId}-${detail.message}`;
+
+    logBuffer[bufferKey] = logBuffer[bufferKey] || [];
+    logBuffer[bufferKey].push({ ...detail, location: document.location });
+
+    if (logDebounce) clearTimeout(logDebounce);
+
+    logDebounce = setTimeout(() => {
+        const contextErrors: Record<string, ErrorDetail[]> = {};
+
+        Object.values(logBuffer).flatMap((siblingErrors) => {
+            const lastSiblingError = siblingErrors[siblingErrors.length - 1];
+
+            const nextErrors = lastSiblingError.exists ? [lastSiblingError] : [];
+
+            if (lastSiblingError.contextId) {
+                // we send all errors to the contextId even if they are empty so we can clear the errors
+                contextErrors[lastSiblingError.contextId] = contextErrors[lastSiblingError.contextId] || [];
+                contextErrors[lastSiblingError.contextId].push(...nextErrors);
+            } else if (nextErrors.length) {
+                // eslint-disable-next-line no-console
+                nextErrors.forEach((e) => console.error(e));
+            }
+        });
+
+        logBuffer = {};
+
+        Object.entries(contextErrors).forEach(([contextId, errors]) => {
+            globalThis.dispatchEvent(new CustomEvent(bspkErrorType(contextId), { detail: errors }));
+        });
+    }, 500);
+
+    return detail.exists;
+}
+
+export const errorContext = createContext(undefined as string | undefined);
+
+export function useErrorLogger(): {
+    logError: LogError;
+} {
+    const contextId = useContext(errorContext);
+
+    return {
+        logError: (exists: boolean, message: string, data?: unknown) => logError({ exists, contextId, message, data }),
+    };
+}
+
+export function useErrorLog() {
+    const [errors, setErrors] = useState<ErrorDetail[]>([]);
+    const contextId = useContext(errorContext);
+
+    useEffect(() => {
+        if (!contextId) return;
+
+        const listener = (e: Event) => {
+            const event = e as CustomEvent<ErrorDetail[]>;
+            // eslint-disable-next-line no-console
+            event.detail.forEach(console.error);
+            setErrors(event.detail);
+        };
+
+        const errorType = bspkErrorType(contextId);
+
+        globalThis.addEventListener(errorType, listener);
+        return () => {
+            globalThis.removeEventListener(errorType, listener);
+        };
+    }, [contextId]);
+
+    return { errors, contextId };
+}
+
+/** Copyright 2025 Anywhere Real Estate - CC BY 4.0 */

package/src/utils/guessUserCountryCode.ts

@@ -0,0 +1,17 @@
+import { countryCodeData, SupportedCountryCode } from './countryCodes';
+
+/**
+ * Guesses the user's country code based on their locale. If the locale does not match any supported country codes,
+ * defaults to 'US'.
+ *
+ * @returns {SupportedCountryCode} The guessed or default country code.
+ */
+export const guessUserCountryCode = (): SupportedCountryCode => {
+    const guessedCountry = Intl.DateTimeFormat().resolvedOptions().locale.split('-')[1];
+
+    if (guessedCountry && countryCodeData[guessedCountry as SupportedCountryCode]) {
+        return guessedCountry as SupportedCountryCode;
+    }
+
+    return 'US';
+};

package/src/utils/uiContext.ts

@@ -0,0 +1,15 @@
+import { createContext } from 'react';
+
+export const COLOR_THEMES = ['light', 'dark'] as const;
+
+export type ColorTheme = (typeof COLOR_THEMES)[number];
+
+export type UIContextProps = {
+    theme: ColorTheme;
+    setTheme: (theme: ColorTheme) => void;
+    isMobile: boolean;
+    isTablet: boolean;
+    isDesktop: boolean;
+};
+
+export const UIContext = createContext<UIContextProps | undefined>(undefined);