@cdx-ui/components 0.3.6 → 0.3.8

package/docs/components/content.md

@@ -61,6 +61,8 @@
 - [Divider](https://design.candescent.com/docs/components/divider/content.md) — A horizontal or vertical separator for grouping related content, with an optional inline label.
 - [Insurance Disclosure](https://design.candescent.com/docs/components/insurance-disclosure/content.md) — Domain-specific regulatory disclosure — official FDIC lockup with optional copy for account footers, deposit screens, and onboarding.
 - [Icon](https://design.candescent.com/docs/components/icon/content.md) — A cross-platform SVG icon wrapper with semantic color, sizing, filled variants, and accessibility support.
+- [Country Flag](https://design.candescent.com/docs/components/country-flag/content.md) — A flag for a country-flag-icons code, including unofficial codes used by libphonenumber-js.
+- [Currency Flag](https://design.candescent.com/docs/components/currency-flag/content.md) — The flag of the country or union that issues an ISO 4217 currency.
 - [Image](https://design.candescent.com/docs/components/image/content.md) — Displays local or remote images across native and web platforms.
 - [List Item](https://design.candescent.com/docs/components/list-item/content.md) — A composable row for display and navigation — accounts, transactions, alerts, settings, and nav rows.
 - [Reorderable List](https://design.candescent.com/docs/components/reorderable-list/content.md) — A short, mount-all list that lets members drag rows into a new order via an explicit handle.

package/docs/components/country-flag/content.md

@@ -0,0 +1,232 @@
+# Country Flag (https://design.candescent.com/docs/components/country-flag)
+
+Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/content-countryflag--default)
+
+`CountryFlag` renders a flag from a `FlagCode`. The codes match the `country-flag-icons` 3x2 set this package was built with: officially assigned ISO 3166-1 alpha-2 codes, the unofficial codes that package ships for `libphonenumber-js`, and its subdivision codes.
+
+```tsx
+import { CountryFlag, Select } from '@cdx-ui/components';
+import { FlagUS } from '@cdx-ui/icons/flags';
+```
+
+Flags keep their source colors. Each path has an explicit fill, so text color classes and theme tokens do not recolor the artwork.
+
+An app that shows one fixed flag can import that component from `@cdx-ui/icons/flags` (`FlagUS`) instead of `CountryFlag`. `CountryFlag` pulls in the `flags` record and therefore every flag.
+
+## Basic
+
+Pass `code`. The default box is `size-5`.
+
+```tsx
+import { Box, CountryFlag, Text, type FlagCode } from '@cdx-ui/components';
+
+const examples: { code: FlagCode; name: string }[] = [
+  { code: 'US', name: 'United States' },
+  { code: 'CA', name: 'Canada' },
+  { code: 'GB', name: 'United Kingdom' },
+  { code: 'JP', name: 'Japan' },
+];
+
+export default function CountryFlagBasicDemo() {
+  return (
+    <Box className="flex-row items-end gap-5">
+      {examples.map((country) => (
+        <Box key={country.code} className="items-center gap-2">
+          <CountryFlag code={country.code} accessibilityLabel={country.name} />
+          <Text size="sm" color="secondary">
+            {country.code}
+          </Text>
+        </Box>
+      ))}
+    </Box>
+  );
+}
+```
+
+## Sizes
+
+A `size-*` class overrides the default box. The flag scales with the box. The default `size-5` box is 20 pixels.
+
+```tsx
+import { Box, CountryFlag, Text } from '@cdx-ui/components';
+
+const sizes = [
+  { className: 'size-4', label: '16' },
+  { className: 'size-5', label: '20' },
+  { className: 'size-6', label: '24' },
+  { className: 'size-8', label: '32' },
+  { className: 'size-10', label: '40' },
+] as const;
+
+export default function CountryFlagSizesDemo() {
+  return (
+    <Box className="flex-row items-end gap-5">
+      {sizes.map((size) => (
+        <Box key={size.className} className="items-center gap-2">
+          <CountryFlag code="US" className={size.className} />
+          <Text size="sm" color="secondary">
+            {size.label}
+          </Text>
+        </Box>
+      ))}
+    </Box>
+  );
+}
+```
+
+## With icons
+
+Place the flag in the leading slot of a [`Select`](https://design.candescent.com/docs/components/select/content.md). `position="leading"` emits `data-icon="inline-start"`, and the slot's size class wins over `size-5`. A small select uses `size-4`. The same flag works in an [`Input`](https://design.candescent.com/docs/components/input/content.md) through `Input.Icon` with `asChild`, which sizes the flag for both the default and small input. On that composed node, `data-slot` is `country-flag` and `data-icon` is kept.
+
+```tsx
+import { useState } from 'react';
+import {
+  Box,
+  CountryFlag,
+  Input,
+  Select,
+  Text,
+  type FlagCode,
+  type InputProps,
+  type SelectProps,
+} from '@cdx-ui/components';
+
+const countries: { value: FlagCode; label: string }[] = [
+  { value: 'US', label: 'United States (+1)' },
+  { value: 'CA', label: 'Canada (+1)' },
+  { value: 'GB', label: 'United Kingdom (+44)' },
+  { value: 'JP', label: 'Japan (+81)' },
+];
+
+function isListedCode(value: string): value is FlagCode {
+  return countries.some((country) => country.value === value);
+}
+
+function CountryCodeSelect({
+  size,
+  defaultCode,
+}: {
+  size: NonNullable<SelectProps['size']>;
+  defaultCode: FlagCode;
+}) {
+  const [code, setCode] = useState(defaultCode);
+
+  return (
+    <Select
+      items={countries}
+      size={size}
+      value={code}
+      onValueChange={(value) => {
+        if (isListedCode(value)) setCode(value);
+      }}
+      className="w-full"
+      accessibilityLabel="Country code"
+    >
+      <Select.Trigger>
+        <Select.Icon asChild position="leading">
+          <CountryFlag code={code} />
+        </Select.Icon>
+        <Select.Value />
+      </Select.Trigger>
+      <Select.Content>
+        {countries.map((country) => (
+          <Select.Item key={country.value} value={country.value}>
+            <CountryFlag code={country.value} />
+            <Select.ItemLabel>{country.label}</Select.ItemLabel>
+          </Select.Item>
+        ))}
+      </Select.Content>
+    </Select>
+  );
+}
+
+function CountryInput({ size, code }: { size: NonNullable<InputProps['size']>; code: FlagCode }) {
+  return (
+    <Input size={size}>
+      <Input.Icon asChild>
+        <CountryFlag code={code} />
+      </Input.Icon>
+      <Input.Field accessibilityLabel={`${size} phone number`} placeholder="Phone number" />
+    </Input>
+  );
+}
+
+export default function CountryFlagWithIconsDemo() {
+  return (
+    <Box className="w-full gap-4">
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          default
+        </Text>
+        <CountryCodeSelect size="default" defaultCode="US" />
+        <CountryInput size="default" code="US" />
+      </Box>
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          small
+        </Text>
+        <CountryCodeSelect size="small" defaultCode="CA" />
+        <CountryInput size="small" code="CA" />
+      </Box>
+    </Box>
+  );
+}
+```
+
+## Accessibility
+
+The flag is decorative unless `accessibilityLabel` is set. Omit the label when the country name or dialing code is already next to the flag.
+
+```tsx
+import { Box, CountryFlag, Text } from '@cdx-ui/components';
+
+export default function CountryFlagAccessibilityDemo() {
+  return (
+    <Box className="gap-5">
+      <Box className="flex-row items-center gap-3">
+        <CountryFlag code="US" accessibilityLabel="United States" />
+        <Text>Informative flag with a screen reader label</Text>
+      </Box>
+      <Box className="flex-row items-center gap-3">
+        <CountryFlag code="CA" />
+        <Text>Canada</Text>
+      </Box>
+    </Box>
+  );
+}
+```
+
+## API
+
+### CountryFlag
+
+Renders the flag for `code`. An unknown `code` renders nothing and logs a warning in development only. It does not throw.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Utility classes for size (`size-*`) and placement, merged after the defaults. |
+| `children?` | `React.ReactNode` | — | — |
+| `size?` | `string \| number` | — | Width and height of the icon, in pixels or any SVG length. The bare icon renders at 24 when omitted. |
+| `data-testid?` | `string` | — | Test identifier forwarded to the rendered SVG. |
+| `code` | `'AC' \| 'AD' \| 'AE' \| 'AF' \| 'AG' \| 'AI' \| 'AL' \| 'AM' \| 'AO' \| 'AQ' \| 'AR' \| 'AS' \| 'AT' \| 'AU' \| 'AW' \| 'AX' \| 'AZ' \| 'BA' \| 'BB' \| 'BD' \| 'BE' \| 'BF' \| 'BG' \| 'BH' \| 'BI' \| 'BJ' \| 'BL' \| 'BM' \| 'BN' \| 'BO' \| 'BQ' \| 'BQ-BO' \| 'BQ-SA' \| 'BQ-SE' \| 'BR' \| 'BS' \| 'BT' \| 'BV' \| 'BW' \| 'BY' \| 'BZ' \| 'CA' \| 'CC' \| 'CD' \| 'CF' \| 'CG' \| 'CH' \| 'CI' \| 'CK' \| 'CL' \| 'CM' \| 'CN' \| 'CO' \| 'CR' \| 'CU' \| 'CV' \| 'CW' \| 'CX' \| 'CY' \| 'CZ' \| 'DE' \| 'DJ' \| 'DK' \| 'DM' \| 'DO' \| 'DZ' \| 'EC' \| 'EE' \| 'EG' \| 'EH' \| 'ER' \| 'ES' \| 'ES-CT' \| 'ET' \| 'EU' \| 'FI' \| 'FJ' \| 'FK' \| 'FM' \| 'FO' \| 'FR' \| 'GA' \| 'GB' \| 'GB-ENG' \| 'GB-NIR' \| 'GB-SCT' \| 'GB-WLS' \| 'GD' \| 'GE' \| 'GF' \| 'GG' \| 'GH' \| 'GI' \| 'GL' \| 'GM' \| 'GN' \| 'GP' \| 'GQ' \| 'GR' \| 'GS' \| 'GT' \| 'GU' \| 'GW' \| 'GY' \| 'HK' \| 'HM' \| 'HN' \| 'HR' \| 'HT' \| 'HU' \| 'IC' \| 'ID' \| 'IE' \| 'IL' \| 'IM' \| 'IN' \| 'IO' \| 'IQ' \| 'IR' \| 'IS' \| 'IT' \| 'JE' \| 'JM' \| 'JO' \| 'JP' \| 'KE' \| 'KG' \| 'KH' \| 'KI' \| 'KM' \| 'KN' \| 'KP' \| 'KR' \| 'KW' \| 'KY' \| 'KZ' \| 'LA' \| 'LB' \| 'LC' \| 'LI' \| 'LK' \| 'LR' \| 'LS' \| 'LT' \| 'LU' \| 'LV' \| 'LY' \| 'MA' \| 'MC' \| 'MD' \| 'ME' \| 'MF' \| 'MG' \| 'MH' \| 'MK' \| 'ML' \| 'MM' \| 'MN' \| 'MO' \| 'MP' \| 'MQ' \| 'MR' \| 'MS' \| 'MT' \| 'MU' \| 'MV' \| 'MW' \| 'MX' \| 'MY' \| 'MZ' \| 'NA' \| 'NC' \| 'NE' \| 'NF' \| 'NG' \| 'NI' \| 'NL' \| 'NO' \| 'NP' \| 'NR' \| 'NU' \| 'NZ' \| 'OM' \| 'PA' \| 'PE' \| 'PF' \| 'PG' \| 'PH' \| 'PK' \| 'PL' \| 'PM' \| 'PN' \| 'PR' \| 'PS' \| 'PT' \| 'PW' \| 'PY' \| 'QA' \| 'RE' \| 'RO' \| 'RS' \| 'RU' \| 'RW' \| 'SA' \| 'SB' \| 'SC' \| 'SD' \| 'SE' \| 'SG' \| 'SH' \| 'SI' \| 'SJ' \| 'SK' \| 'SL' \| 'SM' \| 'SN' \| 'SO' \| 'SR' \| 'SS' \| 'ST' \| 'SV' \| 'SX' \| 'SY' \| 'SZ' \| 'TA' \| 'TC' \| 'TD' \| 'TF' \| 'TG' \| 'TH' \| 'TJ' \| 'TK' \| 'TL' \| 'TM' \| 'TN' \| 'TO' \| 'TR' \| 'TT' \| 'TV' \| 'TW' \| 'TZ' \| 'UA' \| 'UG' \| 'UM' \| 'US' \| 'UY' \| 'UZ' \| 'VA' \| 'VC' \| 'VE' \| 'VG' \| 'VI' \| 'VN' \| 'VU' \| 'WF' \| 'WS' \| 'XA' \| 'XC' \| 'XK' \| 'XO' \| 'YE' \| 'YT' \| 'ZA' \| 'ZM' \| 'ZW'` | — | Code from the country-flag-icons 3x2 set. Includes officially assigned ISO 3166-1 alpha-2 codes, the unofficial codes that package ships for libphonenumber-js, and its subdivision codes. Subdivision codes keep their hyphen (`GB-ENG`). |
+
+Inherits [`SvgProps`](https://github.com/software-mansion/react-native-svg#common-props) except `color`, including `style` and `accessibilityLabel`. `as`, `filled`, and `color` are not accepted. `code` is `FlagCode`, exported from `@cdx-ui/components` and `@cdx-ui/icons/flags`. Subdivision codes keep the hyphen (`GB-ENG`). The icon component replaces it with an underscore (`FlagGB_ENG`).
+
+## Defaults and styling
+
+- `className` defaults to a `size-5` box. Consumer classes are merged after that default, so a `size-*` utility overrides it.
+- Flag artwork keeps its source colors. Text color classes and theme tokens do not recolor it, because each path has an explicit fill.
+- Prefer a `size-*` class over the inherited numeric `size` prop. The numeric prop bypasses the spacing scale.
+
+## Anatomy
+
+| `data-slot`    | Element       |
+| -------------- | ------------- |
+| `country-flag` | Rendered flag |
+
+When `CountryFlag` is the child of `Select.Icon` with `asChild`, the rendered node keeps `data-slot="country-flag"`. `position="leading"` still sets `data-icon="inline-start"`, and `position="trailing"` sets `data-icon="inline-end"`. The select's icon size class replaces the default `size-5`. A small select uses `size-4`.
+
+## Accessibility
+
+- Without `accessibilityLabel`, the flag is decorative and hidden from assistive technology.
+- With `accessibilityLabel`, the flag is exposed as an image and announced with that label.

package/docs/components/currency-flag/content.md

@@ -0,0 +1,202 @@
+# Currency Flag (https://design.candescent.com/docs/components/currency-flag)
+
+Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/content-currencyflag--default)
+
+`CurrencyFlag` renders the flag of the country or union that issues an ISO 4217 currency `code`. `EUR` renders the European Union flag.
+
+```tsx
+import { CurrencyFlag, CountryFlag, Select } from '@cdx-ui/components';
+```
+
+Flags keep their source colors. Each path has an explicit fill, so text color classes and theme tokens do not recolor the artwork.
+
+## Basic
+
+Pass a currency `code`. The default box is `size-5`, and a `size-*` class overrides it.
+
+```tsx
+import { Box, CurrencyFlag, Text } from '@cdx-ui/components';
+
+const examples = [
+  { code: 'USD', name: 'US Dollar' },
+  { code: 'EUR', name: 'Euro' },
+  { code: 'GBP', name: 'British Pound' },
+  { code: 'JPY', name: 'Japanese Yen' },
+];
+
+export default function CurrencyFlagBasicDemo() {
+  return (
+    <Box className="flex-row items-end gap-5">
+      {examples.map((currency) => (
+        <Box key={currency.code} className="items-center gap-2">
+          <CurrencyFlag code={currency.code} accessibilityLabel={currency.name} />
+          <Text size="sm" color="secondary">
+            {currency.code}
+          </Text>
+        </Box>
+      ))}
+    </Box>
+  );
+}
+```
+
+## Shared currencies
+
+The flag shows the currency's issuer, not where the user is. `DKK` renders Denmark's flag for accounts in Greenland and the Faroe Islands, and `USD` renders the United States flag in Ecuador. When the flag should show the user's country, pass the account's country code to [`CountryFlag`](https://design.candescent.com/docs/components/country-flag/content.md) instead.
+
+```tsx
+import { Box, CountryFlag, CurrencyFlag, Text } from '@cdx-ui/components';
+
+export default function CurrencyFlagSharedCurrenciesDemo() {
+  return (
+    <Box className="gap-5">
+      <Box className="flex-row items-center gap-3">
+        <CurrencyFlag code="DKK" />
+        <Text>DKK in Greenland shows the issuer, Denmark</Text>
+      </Box>
+      <Box className="flex-row items-center gap-3">
+        <CountryFlag code="GL" />
+        <Text>Greenland, from the account country code</Text>
+      </Box>
+    </Box>
+  );
+}
+```
+
+## With icons
+
+Place the flag in the leading slot of a [`Select`](https://design.candescent.com/docs/components/select/content.md). `position="leading"` emits `data-icon="inline-start"`, and the slot's size class wins over `size-5`. A small select uses `size-4`.
+
+```tsx
+import { useState } from 'react';
+import { Box, CurrencyFlag, Select, Text, type SelectProps } from '@cdx-ui/components';
+
+const currencies = [
+  { value: 'USD', label: 'US Dollar (USD)' },
+  { value: 'EUR', label: 'Euro (EUR)' },
+  { value: 'GBP', label: 'British Pound (GBP)' },
+  { value: 'CAD', label: 'Canadian Dollar (CAD)' },
+];
+
+function CurrencySelect({
+  size,
+  defaultCode,
+}: {
+  size: NonNullable<SelectProps['size']>;
+  defaultCode: string;
+}) {
+  const [code, setCode] = useState(defaultCode);
+
+  return (
+    <Select
+      items={currencies}
+      size={size}
+      value={code}
+      onValueChange={setCode}
+      className="w-full"
+      accessibilityLabel="Currency"
+    >
+      <Select.Trigger>
+        <Select.Icon asChild position="leading">
+          <CurrencyFlag code={code} />
+        </Select.Icon>
+        <Select.Value />
+      </Select.Trigger>
+      <Select.Content>
+        {currencies.map((currency) => (
+          <Select.Item key={currency.value} value={currency.value}>
+            <CurrencyFlag code={currency.value} />
+            <Select.ItemLabel>{currency.label}</Select.ItemLabel>
+          </Select.Item>
+        ))}
+      </Select.Content>
+    </Select>
+  );
+}
+
+export default function CurrencyFlagWithIconsDemo() {
+  return (
+    <Box className="w-full gap-4">
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          default
+        </Text>
+        <CurrencySelect size="default" defaultCode="USD" />
+      </Box>
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          small
+        </Text>
+        <CurrencySelect size="small" defaultCode="EUR" />
+      </Box>
+    </Box>
+  );
+}
+```
+
+## Accessibility
+
+The flag is decorative unless `accessibilityLabel` is set. Omit the label when the currency name or code is already next to the flag.
+
+```tsx
+import { Box, CurrencyFlag, Text } from '@cdx-ui/components';
+
+export default function CurrencyFlagAccessibilityDemo() {
+  return (
+    <Box className="gap-5">
+      <Box className="flex-row items-center gap-3">
+        <CurrencyFlag code="EUR" accessibilityLabel="Euro" />
+        <Text>Informative flag with a screen reader label</Text>
+      </Box>
+      <Box className="flex-row items-center gap-3">
+        <CurrencyFlag code="USD" />
+        <Text>US Dollar</Text>
+      </Box>
+    </Box>
+  );
+}
+```
+
+## API
+
+### CurrencyFlag
+
+Renders the issuer flag for `code`. A code with no single issuer or no flag renders nothing and logs a warning in development only. It does not throw.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Utility classes for size (`size-*`) and placement, merged after the defaults. |
+| `children?` | `React.ReactNode` | — | — |
+| `size?` | `string \| number` | — | Width and height of the icon, in pixels or any SVG length. The bare icon renders at 24 when omitted. |
+| `data-testid?` | `string` | — | Test identifier forwarded to the rendered SVG. |
+| `code` | `string` | — | ISO 4217 alphabetic currency code, such as `USD` or `EUR`. |
+
+Inherits [`SvgProps`](https://github.com/software-mansion/react-native-svg#common-props) except `color`, including `style` and `accessibilityLabel`. `as`, `filled`, and `color` are not accepted.
+
+### currencyFlagCode
+
+`currencyFlagCode(code)` returns the `FlagCode` that `CurrencyFlag` renders for `code`, or `undefined` when it renders nothing. Use it to decide whether to reserve space for a flag.
+
+- A national code resolves to its first two letters, which ISO 4217 takes from the issuer's ISO 3166-1 alpha-2 code: `USD` resolves to `US`.
+- `EUR` resolves to `EU`.
+- Codes that start with `X` resolve to `undefined`. They name currencies shared by a region (`XOF`, `XAF`, `XCD`, `XPF`), precious metals (`XAU`), and fund or testing codes, none of which has a single issuing country.
+- A code that is not three uppercase letters resolves to `undefined`.
+
+## Defaults and styling
+
+- `className` defaults to a `size-5` box. Consumer classes are merged after that default, so a `size-*` utility overrides it.
+- Flag artwork keeps its source colors. Text color classes and theme tokens do not recolor it, because each path has an explicit fill.
+- Prefer a `size-*` class over the inherited numeric `size` prop. The numeric prop bypasses the spacing scale.
+
+## Anatomy
+
+| `data-slot`     | Element       |
+| --------------- | ------------- |
+| `currency-flag` | Rendered flag |
+
+When `CurrencyFlag` is the child of `Select.Icon` with `asChild`, the rendered node keeps `data-slot="currency-flag"`. `position="leading"` still sets `data-icon="inline-start"`, and `position="trailing"` sets `data-icon="inline-end"`.
+
+## Accessibility
+
+- Without `accessibilityLabel`, the flag is decorative and hidden from assistive technology.
+- With `accessibilityLabel`, the flag is exposed as an image and announced with that label. Use the currency name, such as `Euro`, not the issuer's country name.