@cdx-ui/components 0.3.7 → 0.3.9

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/components/data-grid/content.md

@@ -215,6 +215,53 @@ export default function DataGridRichCellsDemo() {
 }
 ```
 
+## Numeric columns
+
+Set `align: 'end'` on numeric columns so values line up by their last digit. The header label follows the column alignment, and the sort control moves to the label's leading side so the label ends at the same edge as the values. A header label that is wider than its column truncates with an ellipsis, and the full label is available as a tooltip. Give the column enough `width` for its label plus the sort control to keep the label readable.
+
+```tsx
+import { DataGrid, type GridColDef } from '@cdx-ui/data-grid';
+import { accounts, type Account } from './_data';
+
+const currencyFormatter = new Intl.NumberFormat('en-US', {
+  style: 'currency',
+  currency: 'USD',
+  maximumFractionDigits: 0,
+});
+
+const columns: GridColDef<Account>[] = [
+  { field: 'name', headerName: 'Account', flex: 1, minWidth: 160 },
+  {
+    field: 'balance',
+    headerName: 'Available balance',
+    width: 200,
+    align: 'end',
+    valueFormatter: (_, row) => currencyFormatter.format(row.balance),
+  },
+  {
+    field: 'automation',
+    headerName: 'Automated payments share of all outgoing payments',
+    width: 160,
+    align: 'end',
+    valueFormatter: (_, row) => `${row.automation.toString()}%`,
+  },
+];
+
+export default function DataGridNumericColumnsDemo() {
+  return (
+    <DataGrid
+      rows={accounts}
+      columns={columns}
+      aria-label="Account balances"
+      defaultSortModel={[{ field: 'balance', sort: 'desc' }]}
+      defaultPaginationModel={{ page: 0, pageSize: 5 }}
+      pageSizeOptions={[5, 10]}
+      autoHeight
+    />
+  );
+}
+```
+
 ## Toolbar actions
 
 `toolbarActions` is an extension slot for your own toolbar controls beside search — export, density, view toggles, and so on. DataGrid does not ship toolbar buttons; you compose them and wire `onPress` to state that drives grid props.

package/docs/components/date-range-picker/content.md

@@ -128,6 +128,60 @@ export default function DateRangePickerBottomSheetDemo() {
 }
 ```
 
+## Snap points
+
+The sheet snaps to 70% and 90% of the screen by default. Pass `snapPoints` for a different height, and set `stackBehavior="push"` when the picker opens over another sheet so that sheet stays presented underneath. With a short snap point, set `fill` and wrap the content in `BottomSheet.ScrollView` so the calendar scrolls under a fixed header instead of being cut off.
+
+```tsx
+import { useState } from 'react';
+import {
+  BottomSheet,
+  DateField,
+  DateRangePicker,
+  Field,
+  type DateRangeValue,
+} from '@cdx-ui/components';
+import { PickerBottomSheetFrame } from './_frame';
+
+export default function DateRangePickerBottomSheetSnapPointsDemo() {
+  const [value, setValue] = useState<DateRangeValue | undefined>();
+  const [open, setOpen] = useState(false);
+
+  return (
+    <PickerBottomSheetFrame>
+      <Field className="w-full max-w-sm">
+        <DateRangePicker
+          value={value}
+          onValueChange={setValue}
+          isOpen={open}
+          onOpenChange={setOpen}
+        >
+          <Field.Label>Due dates</Field.Label>
+          <DateRangePicker.Trigger className="w-full">
+            <DateField.Group fullWidth>
+              <DateField.Input slot="start" />
+              <DateRangePicker.RangeSeparator />
+              <DateField.Input slot="end" />
+              <DateField.Suffix>
+                <DateRangePicker.TriggerIndicator />
+              </DateField.Suffix>
+            </DateField.Group>
+          </DateRangePicker.Trigger>
+          <DateRangePicker.BottomSheet snapPoints={['55%']} stackBehavior="push" fill>
+            <BottomSheet.Header title="Select dates" onClose={() => setOpen(false)} />
+            <BottomSheet.ScrollView>
+              <BottomSheet.Content>
+                <DateRangePicker.Calendar accessibilityLabel="Due dates" />
+              </BottomSheet.Content>
+            </BottomSheet.ScrollView>
+          </DateRangePicker.BottomSheet>
+        </DateRangePicker>
+      </Field>
+    </PickerBottomSheetFrame>
+  );
+}
+```
+
 ## Standalone
 
 Render a `DateRangePicker.Calendar` inline instead of a presentation surface when the fields and calendar share the screen.
@@ -294,7 +348,14 @@ Presents the range calendar in a modal dialog. Wires the surface's open state an
 
 ### DateRangePicker.BottomSheet
 
-Presents the range calendar in a bottom sheet, the preferred surface on native. It wires open state only — compose `BottomSheet.Header` and `BottomSheet.Content` (or any sheet layout) as its children.
+Presents the range calendar in a bottom sheet, the preferred surface on native. It wires open state only — compose `BottomSheet.Header` and `BottomSheet.Content` (or any sheet layout) as its children. `snapPoints`, `enableDynamicSizing`, and `stackBehavior` are forwarded to [`BottomSheet.Modal`](https://design.candescent.com/docs/components/bottom-sheet/content.md).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `snapPoints?` | `(string \| number)[] \| SharedValue<(string \| number)[]>` | `['70%', '90%']` | Heights the sheet snaps to, as percentages of the screen or pixel values. |
+| `enableDynamicSizing?` | `boolean` | `false` | Sizes the sheet to its content and adds that height as a snap point. |
+| `stackBehavior?` | `'replace' \| 'push' \| 'switch'` | `'switch'` | How the sheet opens over a sheet that is already presented: `push` keeps that sheet underneath, `switch` minimizes it until this sheet closes, and `replace` dismisses it. |
+| `fill?` | `boolean` | `false` | Lays the children out in a container that fills the sheet, so a fixed header can sit above a `BottomSheet.ScrollView`. By default the children size a `BottomSheet.View`. |
 
 ## Accessibility