@cdx-ui/components 0.3.1 → 0.3.3

package/README.md

@@ -48,7 +48,7 @@ The [component reference](https://design.candescent.com/docs/components) is the
 
 The package also ships that reference as markdown in `docs/`, matched to the installed version; coding agents should start at `AGENTS.md` in the package root.
 
-> `Box` is exported but deprecated — use React Native's `View` directly.
+> Use [`Box`](https://design.candescent.com/docs/components/box) for layout containers. The `View` re-export below is deprecated.
 
 ### Providers
 
@@ -91,7 +91,7 @@ For convenience, the package re-exports several core RN components and hooks wit
 
 | Export                 | Source                           |
 | ---------------------- | -------------------------------- |
-| `View`                 | `react-native`                   |
+| `View` (deprecated)    | `react-native`                   |
 | `ScrollView`           | `react-native`                   |
 | `KeyboardAvoidingView` | `react-native`                   |
 | `SafeAreaView`         | `react-native-safe-area-context` |

package/coverage.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="108" height="20" role="img" aria-label="coverage: 92.7%"><title>coverage: 92.7%</title><filter id="blur"><feGaussianBlur stdDeviation="16"/></filter><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="108" height="20" rx="3"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="47" height="20" fill="#4b0"/><rect width="108" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="315" y="150" fill-opacity=".8" filter="url(#blur)" textLength="510">coverage</text><text x="315" y="150" fill-opacity=".3" textLength="510">coverage</text></g><text x="315" y="140" textLength="510">coverage</text></g><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="835" y="150" fill-opacity=".8" filter="url(#blur)" textLength="370">92.7%</text><text x="835" y="150" fill-opacity=".3" textLength="370">92.7%</text></g><text x="835" y="140" textLength="370">92.7%</text></g></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="108" height="20" role="img" aria-label="coverage: 92.9%"><title>coverage: 92.9%</title><filter id="blur"><feGaussianBlur stdDeviation="16"/></filter><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="108" height="20" rx="3"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="47" height="20" fill="#4b0"/><rect width="108" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="315" y="150" fill-opacity=".8" filter="url(#blur)" textLength="510">coverage</text><text x="315" y="150" fill-opacity=".3" textLength="510">coverage</text></g><text x="315" y="140" textLength="510">coverage</text></g><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="835" y="150" fill-opacity=".8" filter="url(#blur)" textLength="370">92.9%</text><text x="835" y="150" fill-opacity=".3" textLength="370">92.9%</text></g><text x="835" y="140" textLength="370">92.9%</text></g></g></svg>

package/docs/components/bottom-sheet/content.md

@@ -310,11 +310,11 @@ Required once at the app root. Wraps the tree to enable modal presentation.
 
 ### BottomSheet.ScrollView
 
-Scrollable content wrapper for sheets with long content. Enables footer margin adjustment by default.
+Scrollable content wrapper for sheets with long content. Enables footer margin adjustment by default when the sheet has a footer.
 
 ### BottomSheet.View
 
-Non-scrollable content wrapper for fit-to-content sheets. Enables footer margin adjustment by default.
+Non-scrollable content wrapper for fit-to-content sheets. Enables footer margin adjustment by default when the sheet has a footer.
 
 ## Hook
 

package/docs/components/content.md

@@ -82,6 +82,8 @@
 - [Box](https://design.candescent.com/docs/components/box/content.md) — The layout container for building screens, with semantic web elements through role and an asChild escape hatch.
 - [Card](https://design.candescent.com/docs/components/card/content.md) — A composable surface for grouping related content, with optional brand stripe, header, content, and footer regions.
 - [Drawer](https://design.candescent.com/docs/components/drawer/content.md) — A panel attached to an edge of the viewport or container, with modal and permanent presentations.
+- [Insight](https://design.candescent.com/docs/components/insight/content.md) — A bordered card for a personalised, often AI-generated, insight, shown as a pressable summary or a detail card.
+- [Insight Stack](https://design.candescent.com/docs/components/insight-stack/content.md) — Draws decorative cards behind a summary Insight to show that more insights are waiting.
 - [Scoped Theme](https://design.candescent.com/docs/components/scoped-theme/content.md) — Forces a specific theme on a component subtree, regardless of the application's global theme.
 - [Scroll Shadow](https://design.candescent.com/docs/components/scroll-shadow/content.md) — Fades the edges of a scroll view so overflowing content reads as scrollable on iOS, Android, and web.
 - [Stack](https://design.candescent.com/docs/components/stack/content.md) — Horizontal and vertical layout primitives with token-based spacing and optional reversed order.

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

@@ -23,9 +23,50 @@ export default function CurrencyInputBasicDemo() {
 }
 ```
 
+## Variants
+
+Use the default `ghost` variant for a large, centered amount that is the focus of the screen. Use `outline` when the amount sits in a form next to other fields: it renders the same bordered shell as `Input`, with the currency symbol as a separate prefix.
+
+```tsx
+import { useState } from 'react';
+import { Box, CurrencyInput, Text, type CurrencyInputProps } from '@cdx-ui/components';
+
+const variants = ['ghost', 'outline'] as const satisfies readonly NonNullable<
+  CurrencyInputProps['variant']
+>[];
+
+function VariantRow({ variant }: { variant: NonNullable<CurrencyInputProps['variant']> }) {
+  const [amount, setAmount] = useState(4890);
+
+  return (
+    <Box className="gap-2">
+      <Text size="sm" color="secondary">
+        {variant}
+      </Text>
+      <CurrencyInput
+        accessibilityLabel={`${variant} transfer amount`}
+        variant={variant}
+        value={amount}
+        onChangeValue={setAmount}
+      />
+    </Box>
+  );
+}
+
+export default function CurrencyInputVariantsDemo() {
+  return (
+    <Box className="w-full gap-4">
+      {variants.map((variant) => (
+        <VariantRow key={variant} variant={variant} />
+      ))}
+    </Box>
+  );
+}
+```
+
 ## Sizes
 
-Use `size="small"` when the amount appears alongside other form fields.
+Use `size="small"` for a more compact amount. When the amount appears alongside other form fields, use `variant="outline"` instead so it matches them.
 
 ```tsx
 import { useState } from 'react';
@@ -121,7 +162,26 @@ export default function CurrencyInputStatesDemo() {
 
 ## With field
 
-Compose with `Field` to provide a visible label, helper text, and required state.
+Compose with `Field` to provide a visible label, helper text, and required state. In a form, use `variant="outline"` with the label and helper aligned to the start, as with `Input`.
+
+```tsx
+import { useState } from 'react';
+import { CurrencyInput, Field } from '@cdx-ui/components';
+
+export default function CurrencyInputOutlineWithFieldDemo() {
+  const [amount, setAmount] = useState(0);
+
+  return (
+    <Field className="w-full" isRequired>
+      <Field.Label>Amount</Field.Label>
+      <CurrencyInput isRequired variant="outline" value={amount} onChangeValue={setAmount} />
+      <Field.Helper>Daily limit remaining: $1,200</Field.Helper>
+    </Field>
+  );
+}
+```
+
+For the `ghost` pattern, center the label and helper over the amount.
 
 ```tsx
 import { useState } from 'react';
@@ -150,6 +210,34 @@ 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;
+
+  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>
+  );
+}
+```
+
+The same validation in the `ghost` pattern, with a centered label and error.
+
+```tsx
+import { useState } from 'react';
+import { CurrencyInput, Field } from '@cdx-ui/components';
+
+const DAILY_LIMIT = 1200;
+
 export default function CurrencyInputWithFieldInvalidDemo() {
   const [amount, setAmount] = useState(1500);
   const isInvalid = amount > DAILY_LIMIT;
@@ -181,14 +269,15 @@ Controlled calculator-style monetary entry. The numeric `value` is expressed in
 | `className?` | `string` | — | — |
 | `value?` | `number` | — | Current amount in major currency units, not cents. Renders a formatted zero when omitted or null. |
 | `style?` | `StyleProp<ViewStyle>` | — | — |
-| `size?` | `'default' \| 'small' \| null` | — | — |
 | `onChangeValue?` | `((value: number) => void)` | — | Called with the parsed amount in major currency units, not cents, when the user edits the field. |
-| `currencySymbol?` | `string` | — | Currency symbol rendered as an inline prefix. Defaults to `"$"`. |
+| `currencySymbol?` | `string` | — | Currency symbol shown before the amount. Defaults to `"$"`. Part of the field text in `ghost`; a separate, non-editable prefix in `outline`. |
 | `isInvalid?` | `boolean` | — | If true, the input will indicate an error. |
 | `isDisabled?` | `boolean` | — | If true, the input will be disabled. |
 | `isRequired?` | `boolean` | — | Sets `aria-required="true"` on web when passed in form control. |
 | `isReadOnly?` | `boolean` | — | If true, prevents the value of the input from being edited. |
 | `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. |
 
 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`.
 
@@ -201,5 +290,5 @@ Only digits contribute to the amount. Each new digit appends to the cents value,
 | Item            | Behavior                                                                             |
 | --------------- | ------------------------------------------------------------------------------------ |
 | Accessible name | Compose with `Field.Label` or pass `accessibilityLabel` directly.                    |
-| Value           | `accessibilityValue.text` contains the fully formatted amount.                       |
+| Value           | `accessibilityValue.text` contains the fully formatted amount, including the symbol. |
 | Validation      | Pair `isInvalid` with `Field.Error` so the error is not communicated by color alone. |

package/docs/components/data-grid/content.md

@@ -5,7 +5,16 @@ Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?
 `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`.
 
 ```tsx
-import { Avatar, Chip, IconButton, Menu, ProgressBar, Text, VStack } from '@cdx-ui/components';
+import {
+  Avatar,
+  Checkbox,
+  Chip,
+  IconButton,
+  Menu,
+  ProgressBar,
+  Text,
+  VStack,
+} from '@cdx-ui/components';
 import { DataGrid } from '@cdx-ui/data-grid';
 ```
 
@@ -332,6 +341,121 @@ export default function DataGridSelectionDemo() {
 }
 ```
 
+## Checkbox cells
+
+To edit boolean fields in place, render a `Checkbox` from `renderCell`. This is separate from `checkboxSelection`: the checkbox reflects a row field, not row selection. Keep `rows` in state and update the matching row in `onChange` so the grid re-renders with the new value.
+
+Give each checkbox an accessible label that names both the column and the row, such as "View — Accounts", so every control keeps a distinct name when reached outside the table context. Set `isDisabled` where an action does not apply, and turn off `sortable` and `filterable` on checkbox columns. Build columns that close over the change handler with `useMemo` so they stay stable between renders.
+
+```tsx
+import { useCallback, useMemo, useState } from 'react';
+import { Checkbox, Text, VStack } from '@cdx-ui/components';
+import { DataGrid, type GridColDef } from '@cdx-ui/data-grid';
+import { permissions, type PermissionAction, type PermissionRow } from './_data';
+
+type ToggleField = PermissionAction | 'additional';
+
+const actionColumns: { field: PermissionAction; headerName: string }[] = [
+  { field: 'view', headerName: 'View' },
+  { field: 'create', headerName: 'Create' },
+  { field: 'modify', headerName: 'Modify' },
+  { field: 'delete', headerName: 'Delete' },
+];
+
+function createColumns(
+  onToggle: (id: string, field: ToggleField, checked: boolean) => void,
+): GridColDef<PermissionRow>[] {
+  return [
+    {
+      field: 'name',
+      headerName: 'Permission',
+      minWidth: 240,
+      flex: 1,
+      renderCell: ({ row }) => (
+        <VStack>
+          <Text numberOfLines={1} weight="medium">
+            {row.name}
+          </Text>
+          <Text numberOfLines={1} color="secondary" size="sm">
+            {row.description}
+          </Text>
+        </VStack>
+      ),
+    },
+    ...actionColumns.map(
+      ({ field, headerName }): GridColDef<PermissionRow> => ({
+        field,
+        headerName,
+        width: 96,
+        align: 'center',
+        headerAlign: 'center',
+        sortable: false,
+        filterable: false,
+        renderCell: ({ row }) => (
+          <Checkbox
+            value={`${row.id}-${field}`}
+            isChecked={row[field] === true}
+            isDisabled={row[field] === null}
+            onChange={(checked) => onToggle(row.id, field, checked)}
+            accessibilityLabel={`${headerName} — ${row.name}`}
+            aria-label={`${headerName} — ${row.name}`}
+          />
+        ),
+      }),
+    ),
+    {
+      field: 'additional',
+      headerName: 'Additional',
+      width: 140,
+      sortable: false,
+      filterable: false,
+      renderCell: ({ row }) =>
+        row.additional ? (
+          <Checkbox
+            value={`${row.id}-additional`}
+            isChecked={row.additional.checked}
+            onChange={(checked) => onToggle(row.id, 'additional', checked)}
+            accessibilityLabel={`${row.additional.label} — ${row.name}`}
+            aria-label={`${row.additional.label} — ${row.name}`}
+          >
+            <Checkbox.Label>{row.additional.label}</Checkbox.Label>
+          </Checkbox>
+        ) : null,
+    },
+  ];
+}
+
+export default function DataGridCheckboxCellsDemo() {
+  const [rows, setRows] = useState(permissions);
+
+  const handleToggle = useCallback((id: string, field: ToggleField, checked: boolean) => {
+    setRows((current) =>
+      current.map((row) => {
+        if (row.id !== id) {
+          return row;
+        }
+        if (field === 'additional') {
+          return row.additional ? { ...row, additional: { ...row.additional, checked } } : row;
+        }
+        return { ...row, [field]: checked };
+      }),
+    );
+  }, []);
+
+  const columns = useMemo(() => createColumns(handleToggle), [handleToggle]);
+
+  return (
+    <DataGrid
+      rows={rows}
+      columns={columns}
+      hideFooter
+      aria-label="Set permissions"
+      className="h-85"
+    />
+  );
+}
+```
+
 ## Server data
 
 Set `paginationMode="server"` and `sortingMode="server"` to let your data source own those operations. `filterMode` follows `paginationMode` unless you set it, so server pagination also means server filtering. Keep the models controlled, pass the current page in `rows`, and provide the full `rowCount` of matching rows.