@cdx-ui/components 0.3.7 → 0.3.8

package/docs/components/content.md

@@ -61,7 +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 country flag rendered from an officially assigned ISO 3166-1 alpha-2 code.
+- [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

@@ -2,7 +2,7 @@
 
 Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/content-countryflag--default)
 
-`CountryFlag` renders a country's flag from an officially assigned ISO 3166-1 alpha-2 `code`.
+`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';
@@ -208,9 +208,9 @@ Renders the flag for `code`. An unknown `code` renders nothing and logs a warnin
 | `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` | `'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' \| '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' \| 'ET' \| 'FI' \| 'FJ' \| 'FK' \| 'FM' \| 'FO' \| 'FR' \| 'GA' \| 'GB' \| 'GD' \| 'GE' \| 'GF' \| 'GG' \| 'GH' \| 'GI' \| 'GL' \| 'GM' \| 'GN' \| 'GP' \| 'GQ' \| 'GR' \| 'GS' \| 'GT' \| 'GU' \| 'GW' \| 'GY' \| 'HK' \| 'HM' \| 'HN' \| 'HR' \| 'HT' \| 'HU' \| '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' \| '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' \| 'YE' \| 'YT' \| 'ZA' \| 'ZM' \| 'ZW'` | — | ISO 3166-1 alpha-2 country code. |
+| `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 the officially assigned ISO 3166-1 alpha-2 set, exported as `FlagCode` from `@cdx-ui/components` and `@cdx-ui/icons/flags`.
+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
 

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.

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

@@ -129,32 +129,72 @@ export default function CurrencyInputCustomSymbolDemo() {
 
 ## States
 
-The root controls disabled, read-only, required, and invalid state for the field.
+The root controls disabled, read-only, required, and invalid state for the field. Disabled, read-only, and invalid apply to both `ghost` and `outline`.
 
 ```tsx
-import { Box, CurrencyInput, Text } from '@cdx-ui/components';
+import { Box, CurrencyInput, Text, type CurrencyInputProps } from '@cdx-ui/components';
+
+const variants = ['ghost', 'outline'] as const satisfies readonly NonNullable<
+  CurrencyInputProps['variant']
+>[];
+
+const states = [
+  { label: 'Disabled', value: 1200, isDisabled: true },
+  { label: 'Read-only', value: 4890, isReadOnly: true },
+  { label: 'Invalid', value: 0, isInvalid: true },
+] as const satisfies readonly {
+  label: string;
+  value: number;
+  isDisabled?: boolean;
+  isReadOnly?: boolean;
+  isInvalid?: boolean;
+}[];
+
+function StateRow({
+  variant,
+  label,
+  value,
+  isDisabled,
+  isReadOnly,
+  isInvalid,
+}: {
+  variant: NonNullable<CurrencyInputProps['variant']>;
+  label: string;
+  value: number;
+  isDisabled?: boolean;
+  isReadOnly?: boolean;
+  isInvalid?: boolean;
+}) {
+  return (
+    <Box className="gap-2">
+      <Text size="sm" color="secondary">
+        {label}
+      </Text>
+      <CurrencyInput
+        accessibilityLabel={`${label} ${variant} transfer amount`}
+        isDisabled={isDisabled}
+        isInvalid={isInvalid}
+        isReadOnly={isReadOnly}
+        variant={variant}
+        value={value}
+      />
+    </Box>
+  );
+}
 
 export default function CurrencyInputStatesDemo() {
   return (
-    <Box className="w-full gap-4">
-      <Box className="gap-2">
-        <Text size="sm" color="secondary">
-          Disabled
-        </Text>
-        <CurrencyInput accessibilityLabel="Disabled transfer amount" isDisabled value={1200} />
-      </Box>
-      <Box className="gap-2">
-        <Text size="sm" color="secondary">
-          Read-only
-        </Text>
-        <CurrencyInput accessibilityLabel="Read-only transfer amount" isReadOnly value={4890} />
-      </Box>
-      <Box className="gap-2">
-        <Text size="sm" color="secondary">
-          Invalid
-        </Text>
-        <CurrencyInput accessibilityLabel="Invalid transfer amount" isInvalid value={0} />
-      </Box>
+    <Box className="w-full gap-6">
+      {variants.map((variant) => (
+        <Box key={variant} className="gap-4">
+          <Text size="sm" color="secondary">
+            {variant}
+          </Text>
+          {states.map((state) => (
+            <StateRow key={state.label} variant={variant} {...state} />
+          ))}
+        </Box>
+      ))}
     </Box>
   );
 }
@@ -200,60 +240,138 @@ export default function CurrencyInputWithFieldDemo() {
 }
 ```
 
-## With field and validation
+## In card
 
-Set invalid state on both `Field` and `CurrencyInput` so the error message and amount styling stay in sync.
+Stack the label above the amount. Align `Field.Label` to the start, and set `align="end"` on `CurrencyInput`.
 
 ```tsx
-import { useState } from 'react';
-import { CurrencyInput, Field } from '@cdx-ui/components';
-
-const DAILY_LIMIT = 1200;
-
-export default function CurrencyInputOutlineWithFieldInvalidDemo() {
-  const [amount, setAmount] = useState(1500);
-  const isInvalid = amount > DAILY_LIMIT;
+import { Card, CurrencyInput, Field } from '@cdx-ui/components';
 
+export default function CurrencyInputInCardDemo() {
   return (
-    <Field className="w-full" isRequired isInvalid={isInvalid}>
-      <Field.Label>Amount</Field.Label>
-      <CurrencyInput
-        isInvalid={isInvalid}
-        isRequired
-        variant="outline"
-        value={amount}
-        onChangeValue={setAmount}
-      />
-      <Field.Error>Amount exceeds your daily limit.</Field.Error>
-    </Field>
+    <Card className="w-full max-w-md">
+      <Card.Content>
+        <Field className="w-full">
+          <Field.Label className="self-start">Available balance</Field.Label>
+          <CurrencyInput align="end" isReadOnly size="small" value={4250.18} />
+        </Field>
+      </Card.Content>
+    </Card>
   );
 }
 ```
 
-The same validation in the `ghost` pattern, with a centered label and error.
+## With field and validation
+
+Set disabled, read-only, and invalid on both `Field` and `CurrencyInput` so the label, message, and amount styling stay in sync. Keep the `outline` label and error aligned to the start. For `ghost`, center the label and error and use `size="small"`.
 
 ```tsx
 import { useState } from 'react';
-import { CurrencyInput, Field } from '@cdx-ui/components';
+import { Box, CurrencyInput, Field, Text } from '@cdx-ui/components';
 
 const DAILY_LIMIT = 1200;
 
-export default function CurrencyInputWithFieldInvalidDemo() {
+function OutlineFields() {
   const [amount, setAmount] = useState(1500);
   const isInvalid = amount > DAILY_LIMIT;
 
   return (
-    <Field className="w-full" isRequired isInvalid={isInvalid}>
-      <Field.Label className="text-center">Amount</Field.Label>
-      <CurrencyInput
-        isInvalid={isInvalid}
-        isRequired
-        size="small"
-        value={amount}
-        onChangeValue={setAmount}
-      />
-      <Field.Error className="justify-center">Amount exceeds your daily limit.</Field.Error>
-    </Field>
+    <Box className="w-full gap-4">
+      <Text size="sm" color="secondary">
+        outline
+      </Text>
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Disabled
+        </Text>
+        <Field className="w-full" isDisabled>
+          <Field.Label>Amount</Field.Label>
+          <CurrencyInput isDisabled variant="outline" value={1200} />
+        </Field>
+      </Box>
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Read-only
+        </Text>
+        <Field className="w-full" isReadOnly>
+          <Field.Label>Amount</Field.Label>
+          <CurrencyInput isReadOnly variant="outline" value={4890} />
+        </Field>
+      </Box>
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Invalid
+        </Text>
+        <Field className="w-full" isRequired isInvalid={isInvalid}>
+          <Field.Label>Amount</Field.Label>
+          <CurrencyInput
+            isInvalid={isInvalid}
+            isRequired
+            variant="outline"
+            value={amount}
+            onChangeValue={setAmount}
+          />
+          <Field.Error>Amount exceeds your daily limit.</Field.Error>
+        </Field>
+      </Box>
+    </Box>
+  );
+}
+
+function GhostFields() {
+  const [amount, setAmount] = useState(1500);
+  const isInvalid = amount > DAILY_LIMIT;
+
+  return (
+    <Box className="w-full gap-4">
+      <Text size="sm" color="secondary">
+        ghost
+      </Text>
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Disabled
+        </Text>
+        <Field className="w-full" isDisabled>
+          <Field.Label className="text-center">Amount</Field.Label>
+          <CurrencyInput isDisabled size="small" variant="ghost" value={1200} />
+        </Field>
+      </Box>
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Read-only
+        </Text>
+        <Field className="w-full" isReadOnly>
+          <Field.Label className="text-center">Amount</Field.Label>
+          <CurrencyInput isReadOnly size="small" variant="ghost" value={4890} />
+        </Field>
+      </Box>
+      <Box className="gap-2">
+        <Text size="sm" color="secondary">
+          Invalid
+        </Text>
+        <Field className="w-full" isRequired isInvalid={isInvalid}>
+          <Field.Label className="text-center">Amount</Field.Label>
+          <CurrencyInput
+            isInvalid={isInvalid}
+            isRequired
+            size="small"
+            variant="ghost"
+            value={amount}
+            onChangeValue={setAmount}
+          />
+          <Field.Error className="justify-center">Amount exceeds your daily limit.</Field.Error>
+        </Field>
+      </Box>
+    </Box>
+  );
+}
+
+export default function CurrencyInputOutlineWithFieldInvalidDemo() {
+  return (
+    <Box className="w-full gap-6">
+      <OutlineFields />
+      <GhostFields />
+    </Box>
   );
 }
 ```
@@ -278,6 +396,7 @@ Controlled calculator-style monetary entry. The numeric `value` is expressed in
 | `isFullWidth?` | `boolean` | — | If true, the input element will span the full width of its parent. |
 | `variant?` | `'ghost' \| 'outline'` | `'ghost'` | Visual style. `ghost` is the large, centered, borderless amount entry; `outline` renders the bordered `Input` shell with a leading currency-symbol prefix, for amounts that sit alongside other form fields. |
 | `size?` | `'default' \| 'small'` | `'default'` | Height, padding, and text size. |
+| `align?` | `'center' \| 'end'` | — | Horizontal alignment of the amount. Defaults to `center` on `ghost`. On `outline`, the amount stays at the start of the field until `align` is set. |
 
 Supports `accessibilityLabel`, `accessibilityHint`, `testID`, `onFocus`, `onBlur`, and `returnKeyType` from [`TextInputProps`](https://reactnative.dev/docs/textinput#props). `style` applies to the root container, and the forwarded ref targets the underlying `TextInput`.
 

package/docs/foundations/expressions/icons/content.md

@@ -2,7 +2,7 @@
 
 Cross-platform icon library for Forge UI, built on [Material Symbols](https://fonts.google.com/icons) (outlined style, weight 400, optical size 24). Renders via `react-native-svg` and targets iOS, Android, and Web.
 
-3,986 icons are available, each with outlined and filled variants, plus support for custom
+3,991 icons are available, each with outlined and filled variants, plus support for custom
 SVGs. Country flags are a separate set and do not appear in the browser below. Render one with
 [`CountryFlag`](https://design.candescent.com/docs/components/country-flag/content.md).
 

package/docs/getting-started/developers/styling/content.md

@@ -52,7 +52,7 @@ Every component's API table lists the props that choose its look. Reach for them
 - **Typography:** `Text` takes `size`, `weight` and `italic`. `Heading` takes `size` only.
 - **Nesting:** a `Text` inside another text element (a `Text`, a `Heading`, or a slot such as `Button.Label`) inherits its color, size and weight. Set only what differs.
 - **Alignment:** `text-center`, `text-start` and `text-end` are allowed as classes. Never use `text-left` or `text-right`, which break right-to-left layouts.
-- **Casing:** `uppercase` is allowed as a class.
+- **Other text styling:** `color`, `size`, `weight` and `italic` are the only typography props, and Forge UI will not add more. Everything else is a plain class, on `Text`, `Heading` and a component's text slot (`Button.Label`, `Chip.Label`): decoration (`underline`, `line-through`), casing (`uppercase`, `capitalize`), truncation and wrapping (`truncate`, `line-clamp-*`, `text-ellipsis`, `whitespace-nowrap`) and numerals (`tabular-nums`). Line height and letter spacing come with `size`, so `leading-*` and `tracking-*` stay off.
 - **Icon size:** use a `size-*` class on the spacing scale. The default is `size-5`, so don't restate it, and don't pass a numeric `size`.
 
 ```tsx
@@ -86,7 +86,7 @@ On a Forge UI component, `className` positions the component in its parent and n
 | Width constraints           | `w-full`, `max-w-md`, `min-w-0`                           |
 | Margin on the spacing scale | `mt-4`, `mx-2`                                            |
 
-Padding, backgrounds, borders, radii, colors, typography and heights are not allowed, on the component or on any of its parts. Between siblings, prefer a stack's `space` prop to margins.
+Padding, backgrounds, borders, radii, colors, font size, weight and family, and heights are not allowed, on the component or on any of its parts. The text classes under [Text, Heading and Icon](#text-heading-and-icon) are. Between siblings, prefer a stack's `space` prop to margins.
 
 ```tsx
 // Wrong: restyling Card parts to match a mockup

package/docs/llms.txt

@@ -85,7 +85,8 @@ Links point at each page's `content.md`, which carries the page's prose, demo so
   - [Divider](components/divider/content.md): A horizontal or vertical separator for grouping related content, with an optional inline label. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=6771-8895), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/layout-divider--default)
   - [Insurance Disclosure](components/insurance-disclosure/content.md): Domain-specific regulatory disclosure — official FDIC lockup with optional copy for account footers, deposit screens, and onboarding. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=8550-3291), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/domain-insurancedisclosure--default)
   - [Icon](components/icon/content.md): A cross-platform SVG icon wrapper with semantic color, sizing, filled variants, and accessibility support. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--React-Native-Components?node-id=397-33), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/content-icon--default)
-  - [Country Flag](components/country-flag/content.md): A country flag rendered from an officially assigned ISO 3166-1 alpha-2 code. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/content-countryflag--default)
+  - [Country Flag](components/country-flag/content.md): A flag for a country-flag-icons code, including unofficial codes used by libphonenumber-js. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/content-countryflag--default)
+  - [Currency Flag](components/currency-flag/content.md): The flag of the country or union that issues an ISO 4217 currency. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/content-currencyflag--default)
   - [Image](components/image/content.md): Displays local or remote images across native and web platforms. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=9091-16186), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/content-image--default)
   - [List Item](components/list-item/content.md): A composable row for display and navigation — accounts, transactions, alerts, settings, and nav rows. Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--React-Native-Components?node-id=3710-4649), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/surfaces-listitem--default)
   - [Reorderable List](components/reorderable-list/content.md): A short, mount-all list that lets members drag rows into a new order via an explicit handle. Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/layout-reorderablelist--default)
@@ -150,6 +151,7 @@ Links point at each page's `content.md`, which carries the page's prose, demo so
 
 ## Release notes
 
+- [0.3.7](resources/release-notes/0.3.7/content.md): Adds CountryFlag for ISO country flags, ProgressBar size and color props, DataGrid autoHeight, and fixes for web charts and published DataGrid styles.
 - [0.3.6](resources/release-notes/0.3.6/content.md): Adds SystemAlert, bar, line, and pie charts on a shared MUI X-shaped API, Stepper, and a fix for tabs scroll controls.
 - [0.3.5](resources/release-notes/0.3.5/content.md): Selected subtle Chip labels stay visible on Android when the variant changes from outline to subtle.
 - [0.3.4](resources/release-notes/0.3.4/content.md): Select adds multiple selection, in-list search, and a native bottom sheet; Input gains a subtle variant for fields inside popups and sheets.

package/docs/resources/release-notes/0.3.7/content.md

@@ -0,0 +1,27 @@
+# 0.3.7 (https://design.candescent.com/docs/resources/release-notes/0.3.7)
+
+Adds CountryFlag for ISO country flags, ProgressBar size and color props, DataGrid autoHeight, and fixes for web charts and published DataGrid styles.
+
+This release adds **[CountryFlag](https://design.candescent.com/docs/components/country-flag/content.md)** and new **[Progress Bar](https://design.candescent.com/docs/components/progress-bar/content.md)** styling options, lets **DataGrid** size to its rows, and fixes web chart accessibility warnings plus DataGrid styling when installed from npm.
+
+## What's new
+
+**[CountryFlag](https://design.candescent.com/docs/components/country-flag/content.md)** — Renders officially assigned ISO country flags from `@cdx-ui/icons/flags` so country pickers and forms can show a flag without a third-party flag library. Pass a country code and optional `size` to match surrounding icons; use it inside **[Input](https://design.candescent.com/docs/components/input/content.md)** or **[Select](https://design.candescent.com/docs/components/select/content.md)** adornments the same way you use other Forge icons ([#912](https://github.com/dfh-candescent/forge-design-system/pull/912)).
+
+**[Progress Bar](https://design.candescent.com/docs/components/progress-bar/content.md)** — `size` and `color` props tune track height and semantic fill without custom classes. Use them for dense lists, dashboards, and budget-style insights where several bars share one screen ([#873](https://github.com/dfh-candescent/forge-design-system/pull/873)).
+
+**DataGrid** — `autoHeight` (MUI X naming) removes the default fixed viewport height so the grid grows with its rows; horizontal overflow still scrolls. Empty and custom loading overlays keep a minimum height because they are absolutely positioned ([#899](https://github.com/dfh-candescent/forge-design-system/pull/899)).
+
+## Bug fixes
+
+**[Progress Bar](https://design.candescent.com/docs/components/progress-bar/content.md)** — Indeterminate mode (`value={null}`) animates a segment across the track instead of collapsing the indicator to zero width ([#873](https://github.com/dfh-candescent/forge-design-system/pull/873)).
+
+**[Input](https://design.candescent.com/docs/components/input/content.md)** — `Input.Icon` with `asChild` accepts a child element, so icons such as CountryFlag typecheck and render in adornment slots ([#912](https://github.com/dfh-candescent/forge-design-system/pull/912)).
+
+**DataGrid** — Published `@cdx-ui/data-grid` installs include a stylesheet so Uniwind generates grid utility classes in consumer apps; import it alongside your other Forge UI styles as documented on the DataGrid page ([#906](https://github.com/dfh-candescent/forge-design-system/pull/906)).
+
+**[LineChart](https://design.candescent.com/docs/components/line-chart/content.md)** and **[BarChart](https://design.candescent.com/docs/components/bar-chart/content.md)** — Decorative chart SVGs on web no longer pass React Native accessibility props through to the DOM, which removes React warnings in the browser ([#899](https://github.com/dfh-candescent/forge-design-system/pull/899)).
+
+## Dependencies
+
+Upgrade every installed `@cdx-ui/*` package to `0.3.7` together when you adopt this release ([#910](https://github.com/dfh-candescent/forge-design-system/pull/910)).

package/docs/resources/release-notes/content.md

@@ -8,6 +8,7 @@ Notes are generated from the release commit itself, so the versions and commit r
 each entry are exact. Releases that contained nothing but backlog or dependency bookkeeping
 are omitted.
 
+- [0.3.7](https://design.candescent.com/docs/resources/release-notes/0.3.7/content.md) — 2026-10-27 — Adds CountryFlag for ISO country flags, ProgressBar size and color props, DataGrid autoHeight, and fixes for web charts and published DataGrid styles.
 - [0.3.6](https://design.candescent.com/docs/resources/release-notes/0.3.6/content.md) — 2026-10-23 — Adds SystemAlert, bar, line, and pie charts on a shared MUI X-shaped API, Stepper, and a fix for tabs scroll controls.
 - [0.3.5](https://design.candescent.com/docs/resources/release-notes/0.3.5/content.md) — 2026-10-21 — Selected subtle Chip labels stay visible on Android when the variant changes from outline to subtle.
 - [0.3.4](https://design.candescent.com/docs/resources/release-notes/0.3.4/content.md) — 2026-10-20 — Select adds multiple selection, in-list search, and a native bottom sheet; Input gains a subtle variant for fields inside popups and sheets.

package/lib/commonjs/components/CountryFlag/index.js

@@ -10,7 +10,7 @@ var _utils = require("@cdx-ui/utils");
 var _Icon = require("../Icon");
 var _jsxRuntime = require("react/jsx-runtime");
 /**
- * Renders the country flag for an ISO 3166-1 alpha-2 code.
+ * Renders the flag for a country-flag-icons code, including unofficial libphonenumber-js codes.
  *
  * The flag is drawn through `Icon`, so `className` sizing and `asChild` icon slots
  * apply. Flag artwork keeps its own colors. The flag is decorative unless
@@ -26,7 +26,7 @@ var _jsxRuntime = require("react/jsx-runtime");
  * <CountryFlag code="US" className="size-6" accessibilityLabel="United States" />
  * ```
  *
- * @param {FlagCode} code - ISO 3166-1 alpha-2 country code.
+ * @param {FlagCode} code - Code from the country-flag-icons 3x2 set. Subdivision codes keep their hyphen (`GB-ENG`).
  * @param {string} className - Utility classes for size and placement, merged after the default `size-5` box.
  * @param {string} accessibilityLabel - When set, the flag is announced as an image with this name.
  * @param {object} style - Style overrides passed through to the icon.