@cdx-ui/components 0.2.2 → 0.2.4

package/docs/components/calendar/content.md

@@ -0,0 +1,137 @@
+# Calendar (https://design.candescent.com/docs/components/calendar)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=11954-3139), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/date-time-calendar--default)
+
+`Calendar` renders a day grid for selecting a single date. Values are `DateId` strings in `YYYY-MM-DD` format.
+
+```tsx
+import { Calendar } from '@cdx-ui/components';
+```
+
+## Basic
+
+Control the selected date with `value` and `onValueChange`.
+
+```tsx
+import { useState } from 'react';
+import { Calendar } from '@cdx-ui/components';
+import { dateId, type DateId } from '@cdx-ui/formatters';
+
+export default function CalendarBasicDemo() {
+  const [value, setValue] = useState<DateId | undefined>(dateId('2026-08-03'));
+
+  return (
+    <Calendar
+      value={value}
+      onValueChange={setValue}
+      aria-label="Event date"
+      className="w-full max-w-sm"
+    />
+  );
+}
+```
+
+## Date limits
+
+Set `minValue` and `maxValue` to restrict which days can be selected.
+
+```tsx
+import { useState } from 'react';
+import { Calendar } from '@cdx-ui/components';
+import { dateId, monthId, type DateId } from '@cdx-ui/formatters';
+
+export default function CalendarMinMaxDemo() {
+  const [value, setValue] = useState<DateId | undefined>(dateId('2026-08-15'));
+
+  return (
+    <Calendar
+      value={value}
+      onValueChange={setValue}
+      defaultMonthId={monthId('2026-08-01')}
+      minValue={dateId('2026-08-10')}
+      maxValue={dateId('2026-08-20')}
+      aria-label="Appointment date"
+      className="w-full max-w-sm"
+    />
+  );
+}
+```
+
+## Unavailable dates
+
+Pass `isDateUnavailable` to disable individual days — here, weekends and a holiday list for business-days-only payments.
+
+```tsx
+import { useState } from 'react';
+import { Calendar } from '@cdx-ui/components';
+import { dateId, monthId, type DateId } from '@cdx-ui/formatters';
+import { isNonBusinessDay } from './_business-days';
+
+export default function CalendarBusinessDaysDemo() {
+  const [value, setValue] = useState<DateId | undefined>(dateId('2026-11-16'));
+
+  return (
+    <Calendar
+      value={value}
+      onValueChange={setValue}
+      defaultMonthId={monthId('2026-11-01')}
+      isDateUnavailable={isNonBusinessDay}
+      aria-label="Payment date"
+      className="w-full max-w-sm"
+    />
+  );
+}
+```
+
+## Disabled
+
+Set `disabled` to render a read-only grid that ignores day presses.
+
+```tsx
+import { Calendar } from '@cdx-ui/components';
+import { dateId } from '@cdx-ui/formatters';
+
+export default function CalendarDisabledDemo() {
+  return (
+    <Calendar
+      value={dateId('2026-08-03')}
+      disabled
+      aria-label="Event date"
+      className="w-full max-w-sm"
+    />
+  );
+}
+```
+
+## API
+
+### Calendar
+
+By default, `Calendar` renders a month header with previous/next navigation and a year drill-down, followed by the day grid. `locale` defaults to `en-US` and controls weekday and month formatting.
+
+`isDateUnavailable` combines with `minValue` and `maxValue`: a day is selectable only when it is inside the bounds and the predicate returns `false`. The predicate runs for every day of the visible month; define it outside the component or memoize it so that check is skipped on renders that do not change it.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `value?` | `DateId` | — | Selected date as a `YYYY-MM-DD` string. |
+| `defaultValue?` | `DateId` | — | Uncontrolled initial selection as a `YYYY-MM-DD` string. |
+| `onValueChange?` | `((value: DateId) => void)` | — | Called with the new selection, or `undefined` when the selection is cleared. |
+| `monthId?` | `MonthId` | — | Month shown in the grid as a `YYYY-MM-01` string. Follows the selected `value` unless controlled. |
+| `defaultMonthId?` | `MonthId` | — | Uncontrolled initial month as a `YYYY-MM-01` string. |
+| `onMonthIdChange?` | `((monthId: MonthId) => void)` | — | — |
+| `minValue?` | `DateId` | — | Earliest selectable date. Build with `dateId(...)` from `@cdx-ui/formatters`. |
+| `maxValue?` | `DateId` | — | Latest selectable date. Build with `dateId(...)` from `@cdx-ui/formatters`. |
+| `isDateUnavailable?` | `((date: DateId) => boolean)` | — | Returns `true` for days that cannot be selected, such as weekends or holidays. Unavailable days render disabled and ignore presses, combined with `minValue` / `maxValue`. An inline function is safe; a stable (module-level or memoized) one also skips re-checking every day of the visible month on each render. |
+| `disabled?` | `boolean` | — | — |
+| `locale?` | `string` | — | BCP 47 locale for weekday and month formatting. Defaults to `en-US`. |
+| `labels?` | `Partial<DateComponentLabels>` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+## Accessibility
+
+Pass `accessibilityLabel` to name the calendar for assistive technology; the root carries no landmark role of its own. Days outside the `minValue`–`maxValue` range, days for which `isDateUnavailable` returns `true`, and every day while `disabled`, are not selectable.
+
+Unavailable days render in the same disabled state as out-of-range days and announce no reason of their own, so pair the calendar with helper text that explains which days are unavailable and why — for example, "Payments process on business days only."

package/docs/components/card/content.md

@@ -0,0 +1,283 @@
+# Card (https://design.candescent.com/docs/components/card)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--React-Native-Components?node-id=456-14), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/surfaces-card--with-stripe)
+
+A compound component for grouping related information and actions in a bordered surface. Compose only the regions the card needs.
+
+```tsx
+import { Card } from '@cdx-ui/components';
+```
+
+## Basic
+
+Use `Card.Header`, `Card.Content`, and `Card.Footer` to organize a card into distinct regions.
+
+```tsx
+import { Card, Heading, Text } from '@cdx-ui/components';
+
+export default function CardBasicDemo() {
+  return (
+    <Card className="w-full max-w-md">
+      <Card.Stripe />
+      <Card.Header>
+        <Heading size="sm">Account summary</Heading>
+      </Card.Header>
+      <Card.Content>
+        <Text>Your checking account has an available balance of $4,250.18.</Text>
+      </Card.Content>
+      <Card.Footer>
+        <Text color="secondary">Updated moments ago</Text>
+      </Card.Footer>
+    </Card>
+  );
+}
+```
+
+## Stripe options
+
+Place `Card.Stripe` first to add a brand accent. It can be used with or without `Card.Header`, or omitted for a neutral surface.
+
+```tsx
+import { Card, Heading, Text, VStack } from '@cdx-ui/components';
+
+export default function CardStripeOptionsDemo() {
+  return (
+    <VStack space="lg" className="w-full max-w-md">
+      <Card>
+        <Card.Stripe />
+        <Card.Header>
+          <Heading size="sm">With stripe</Heading>
+        </Card.Header>
+        <Card.Content>
+          <Text>Place Card.Stripe first to add a brand accent.</Text>
+        </Card.Content>
+      </Card>
+
+      <Card>
+        <Card.Header>
+          <Heading size="sm">Without stripe</Heading>
+        </Card.Header>
+        <Card.Content>
+          <Text>Omit Card.Stripe for a neutral card.</Text>
+        </Card.Content>
+      </Card>
+
+      <Card>
+        <Card.Stripe />
+        <Card.Content>
+          <Text>Card.Stripe can also be used without a header.</Text>
+        </Card.Content>
+      </Card>
+    </VStack>
+  );
+}
+```
+
+## With actions
+
+Place related actions in `Card.Footer`. Override its layout classes when actions should appear side by side.
+
+```tsx
+import { Button, Card, Heading, Text } from '@cdx-ui/components';
+
+export default function CardWithActionsDemo() {
+  return (
+    <Card className="w-full max-w-md">
+      <Card.Stripe />
+      <Card.Header>
+        <Heading size="sm">Ready to buy a home?</Heading>
+      </Card.Header>
+      <Card.Content>
+        <Text>
+          Explore mortgage options and down payment assistance programs tailored to your goals.
+        </Text>
+      </Card.Content>
+      <Card.Footer className="flex-row gap-3">
+        <Button variant="outline" className="flex-1">
+          <Button.Label>Learn more</Button.Label>
+        </Button>
+        <Button color="action" className="flex-1">
+          <Button.Label>Apply</Button.Label>
+        </Button>
+      </Card.Footer>
+    </Card>
+  );
+}
+```
+
+## Full bleed
+
+Set `fullBleed` on `Card` to remove padding from `Card.Content` and apply standalone padding to `Card.Footer`. This is useful for edge-to-edge lists and media.
+
+```tsx
+import { Button, Card, Chip, HStack, ListItem, Text } from '@cdx-ui/components';
+
+const accounts = [
+  {
+    name: 'Visa Platinum Plus',
+    last4: '0275',
+    balance: '$9,834.67',
+    balanceLabel: 'Outstanding balance',
+  },
+  {
+    name: 'Auto loan',
+    last4: '0865',
+    balance: '$15,620.11',
+    balanceLabel: 'Outstanding balance',
+    status: { label: 'Payment overdue', tone: 'danger' },
+  },
+] as const;
+
+export default function CardFullBleedDemo() {
+  return (
+    <Card fullBleed className="w-full max-w-md">
+      <Card.Content>
+        <ListItem.SectionHeader variant="gradient" showDivider={false}>
+          Credit &amp; loans
+        </ListItem.SectionHeader>
+        {accounts.map((account, index) => (
+          <ListItem
+            key={account.last4}
+            crossAlign="start"
+            showSeparator={index < accounts.length - 1}
+            onPress={() => {}}
+          >
+            <ListItem.Content>
+              <HStack space="sm" className="items-baseline">
+                <ListItem.Title>{account.name}</ListItem.Title>
+                <Text size="sm" color="secondary">
+                  •••{account.last4}
+                </Text>
+              </HStack>
+              <Text size="xl" weight="semibold">
+                {account.balance}
+              </Text>
+              <ListItem.Description>{account.balanceLabel}</ListItem.Description>
+              {'status' in account ? (
+                <Chip
+                  variant="subtle"
+                  size="small"
+                  color={account.status.tone}
+                  className="mt-1 self-start"
+                >
+                  <Chip.Label>{account.status.label}</Chip.Label>
+                </Chip>
+              ) : null}
+            </ListItem.Content>
+          </ListItem>
+        ))}
+      </Card.Content>
+      <Card.Footer>
+        <Button variant="outline" color="action" fullWidth onPress={() => {}}>
+          <Button.Label>Pay due bills</Button.Label>
+        </Button>
+      </Card.Footer>
+    </Card>
+  );
+}
+```
+
+## Header content
+
+`Card.Header` accepts more than text. Compose headings with status, metadata, or controls as needed.
+
+```tsx
+import { Card, Chip, Heading, Text } from '@cdx-ui/components';
+
+export default function CardHeaderContentDemo() {
+  return (
+    <Card className="w-full max-w-md">
+      <Card.Header>
+        <Heading size="sm">Primary checking</Heading>
+        <Chip color="success" size="small">
+          <Chip.Label>Active</Chip.Label>
+        </Chip>
+      </Card.Header>
+      <Card.Content>
+        <Text>Available balance: $4,250.18</Text>
+      </Card.Content>
+    </Card>
+  );
+}
+```
+
+## API
+
+### Card
+
+Root surface that provides `fullBleed` styling context to its content and footer.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `fullBleed?` | `boolean \| null` | — | When `true`, `Card.Content` drops its padding and `Card.Footer` uses standalone padding. Both inherit this unless they set their own `fullBleed`. |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+## Sub-components
+
+### Card.Stripe
+
+Full-width brand accent bar. Render it as the first child when present.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Card.Header
+
+Top region for a heading and optional supporting controls. Includes a bottom divider.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Card.Content
+
+Main content region. Reads `fullBleed` from `Card`, or accepts a local override.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `fullBleed?` | `boolean \| null` | — | Removes this region's padding. Inherits the parent `Card`'s `fullBleed` when omitted. |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Card.Footer
+
+Bottom region for actions or supporting information. Reads `fullBleed` from `Card`, or accepts a local override.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `fullBleed?` | `boolean \| null` | — | Uses standalone padding instead of flush-top padding. Inherits the parent `Card`'s `fullBleed` when omitted. |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+## Anatomy
+
+| `data-slot`    | Element             |
+| -------------- | ------------------- |
+| `card`         | Root surface        |
+| `card-stripe`  | Brand accent        |
+| `card-header`  | Header region       |
+| `card-content` | Main content region |
+| `card-footer`  | Footer region       |
+
+## Accessibility
+
+`Card` is a visual grouping and does not add a role or heading level. Use semantic heading components inside `Card.Header`, and add an accessibility role or label to the root only when the card's meaning requires it.