@cdx-ui/components 0.3.5 → 0.3.7

package/docs/components/content.md

@@ -50,6 +50,7 @@
 - [Progress Bar](https://design.candescent.com/docs/components/progress-bar/content.md) — A continuous progress bar that visualizes determinate or indeterminate progress with a compound track and indicator.
 - [Progress Circle](https://design.candescent.com/docs/components/progress-circle/content.md) — A circular progress indicator that visualizes determinate or indeterminate progress with a compound ring and indicator.
 - [Progress Segmented](https://design.candescent.com/docs/components/progress-segmented/content.md) — A segmented progress bar that visualizes step-by-step completion as a row of discrete segments.
+- [Stepper](https://design.candescent.com/docs/components/stepper/content.md) — A vertical or horizontal list of labeled steps that shows which step is current, which are complete, and how far each one has progressed.
 - [Skeleton](https://design.candescent.com/docs/components/skeleton/content.md) — A pulsing loading placeholder shaped via className — no intrinsic size, layout preserved while content loads.
 
 ## Content display
@@ -60,6 +61,7 @@
 - [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.
 - [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.
@@ -70,6 +72,7 @@
 ## Feedback
 
 - [Alert](https://design.candescent.com/docs/components/alert/content.md) — An inline severity banner that renders contextual feedback — danger, warning, success, or info — with an optional title, body, and trailing actions.
+- [System Alert](https://design.candescent.com/docs/components/system-alert/content.md) — A full-width, strong-surface banner at the top of the screen for app-wide messages such as closures, outages, and required actions.
 - [Alert Dialog](https://design.candescent.com/docs/components/alert-dialog/content.md) — A modal confirmation for destructive or important actions that requires an explicit response.
 - [Dialog](https://design.candescent.com/docs/components/dialog/content.md) — A modal overlay that interrupts the user with critical information or decisions requiring immediate attention.
 - [Full Screen Dialog](https://design.candescent.com/docs/components/full-screen-dialog/content.md) — A modal page that covers the viewport with a back, title, and close header for single-step or multi-step tasks.
@@ -97,4 +100,10 @@
 
 - [Data Grid](https://design.candescent.com/docs/components/data-grid/content.md) — A web data grid with rows, columns, sort, filters, selection, and pagination.
 - [Table](https://design.candescent.com/docs/components/table/content.md) — A presentational compound table for displaying tabular data with consistent Forge styling.
-- [Table Pagination](https://design.candescent.com/docs/components/table-pagination/content.md) — A compound pager for moving between pages of a list or table.
+- [Table Pagination](https://design.candescent.com/docs/components/table-pagination/content.md) — A compound pager for moving between pages of a list or table.
+
+## Charts
+
+- [Bar Chart](https://design.candescent.com/docs/components/bar-chart/content.md) — A vertical or horizontal bar chart for comparing categories, with grouped, stacked, overlay, and waterfall series.
+- [Line Chart](https://design.candescent.com/docs/components/line-chart/content.md) — A line or area chart for values over time, with per-series styling, dashed forecasts, and event markers.
+- [Pie Chart](https://design.candescent.com/docs/components/pie-chart/content.md) — A pie or donut chart for share-of-whole data, with a category legend, tooltip, and optional selection.

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 country's flag from an officially assigned ISO 3166-1 alpha-2 `code`.
+
+```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` | `'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. |
+
+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`.
+
+## 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/data-grid/content.md

@@ -2,7 +2,7 @@
 
 Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/data-visualization-datagrid--default)
 
-`DataGrid` is a **web-only** data-driven grid. Install `@cdx-ui/data-grid` in addition to `@cdx-ui/components`. For fully custom markup use `Table`. For a standalone pager use `TablePagination`.
+`DataGrid` is a **web-only** data-driven grid. Install `@cdx-ui/data-grid` in addition to `@cdx-ui/components`, and add `@import '@cdx-ui/data-grid/styles.css';` after `@cdx-ui/components/styles.css` in your Tailwind CSS entry; without it the grid renders without its border, header background, or row dividers. For fully custom markup use `Table`. For a standalone pager use `TablePagination`.
 
 ```tsx
 import {
@@ -26,6 +26,8 @@ Search is **not** always on. Set `showToolbar` to show the search field (same op
 
 The grid is a fixed viewport like MUI Data Grid Community: **300px** tall by default. Column headers stay visible while rows scroll; pagination stays at the bottom. Override height with a `className` such as `h-full` or a spacing-scale height (`h-130`).
 
+Set `autoHeight` to size the grid to its rows instead, so a short table leaves no empty space below the last row. The grid then grows with every row on the page, so pair it with pagination for long data. The empty state keeps a minimum height.
+
 When `rows` is empty, a centered "No rows" message is shown and pagination is omitted. Pass `noRowsOverlay` to replace the default message.
 
 ```tsx

package/docs/components/icon/content.md

@@ -180,7 +180,7 @@ Inherits all `ForgeIconProps` except the SVG `color`: [`SvgProps`](https://githu
 - A raw `color` value, such as a hex string, is deprecated. It is passed to the SVG unchanged and logs a one-time warning in development. Use a semantic color instead.
 - `className` defaults to `size-5 shrink-0`, so an icon keeps its size in a row of text on web.
 - Consumer classes are merged after the defaults, so `size-*` and `shrink` utilities override them.
-- Don't pass the inherited numeric `size` prop; it bypasses the spacing scale. Use `size-4` or `size-6` when the default doesn't fit.
+- Don't pass the inherited numeric `size` prop; it bypasses the spacing scale. Use another `size-*` class on the spacing scale when the default doesn't fit.
 - `filled` defaults to `false`.
 
 ## Accessibility

package/docs/components/input/content.md

@@ -346,6 +346,7 @@ Renders a Forge icon sized to the input. Inherits size from the parent Input con
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `className?` | `string` | — | Utility classes for size (`size-*`) and placement, merged after the defaults. |
+| `children?` | `ReactNode` | — | The element rendered when `asChild` is set. |
 | `filled?` | `boolean` | — | When `true`, renders the filled variant of the icon (if available). Defaults to `false` (outlined). |
 | `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. |