@cdx-ui/components 0.3.5 → 0.3.7

package/docs/patterns/insights/content.md

@@ -0,0 +1,659 @@
+# Insights (https://design.candescent.com/docs/patterns/insights)
+
+## Insights Overview
+
+A summary card over topic tabs of chart preview cards for budget, spending, daily spend, cash flow, and credit score.
+
+**Platforms:** iOS, Android
+
+```tsx
+import {
+  BarChart,
+  Box,
+  Card,
+  Chip,
+  Divider,
+  Heading,
+  HStack,
+  Insight,
+  LineChart,
+  PieChart,
+  Tabs,
+  Text,
+  VStack,
+} from '@cdx-ui/components';
+import { FILL_WIDTH, formatUsd, formatUsdThousands } from '../_utils';
+
+const SAFE_TO_SPEND = [
+  { id: 'left', label: 'Left to spend', value: 462, color: 'simple-primary' },
+  // TODO(forge-ui): charts have no light neutral color for a progress track. `categorical-6` is
+  // the closest existing token but is much darker than the design's grey.
+  { id: 'spent', label: 'Spent on bills', value: 738, color: 'categorical-6' },
+] as const;
+
+const SPENDING = [
+  { id: 'housing', label: 'Housing', value: 2130 },
+  { id: 'food', label: 'Food and dining', value: 1065 },
+  { id: 'shopping', label: 'Shopping', value: 800 },
+  { id: 'transport', label: 'Transport', value: 745 },
+  { id: 'other', label: 'Other', value: 585, color: 'categorical-6' },
+] as const;
+
+// Today is its own series so it can take a darker color than the earlier days; both share one
+// stack, so each day still draws a single bar.
+// TODO(forge-ui): BarChart can't format band-axis labels, so the single-letter days are the data
+// itself and tooltips and screen readers read "S" for both Saturday and Sunday.
+const DAILY_SPENDING = [
+  { day: 'S', earlier: 46, today: null },
+  { day: 'S', earlier: 62, today: null },
+  { day: 'M', earlier: 38, today: null },
+  { day: 'T', earlier: 62, today: null },
+  { day: 'W', earlier: 50, today: null },
+  { day: 'T', earlier: 36, today: null },
+  { day: 'F', earlier: null, today: 37 },
+];
+
+const CASH_FLOW = [
+  { day: 'Mon', moneyIn: 6200, moneyOut: 2400 },
+  { day: 'Tue', moneyIn: 1800, moneyOut: 3100 },
+  { day: 'Wed', moneyIn: 2500, moneyOut: 1900 },
+  { day: 'Thu', moneyIn: 7400, moneyOut: 4200 },
+  { day: 'Fri', moneyIn: 3100, moneyOut: 2800 },
+  { day: 'Sat', moneyIn: 900, moneyOut: 1600 },
+  { day: 'Sun', moneyIn: 600, moneyOut: 1200 },
+];
+
+const CASH_FLOW_SUMMARY = [
+  { label: 'Money in', value: '$22,500' },
+  { label: 'Money out', value: '$17,200' },
+  { label: 'Net', value: '+$5,300', color: 'success' as const },
+];
+
+const CREDIT_SCORE = [
+  { month: 'May', score: 575 },
+  { month: 'Jun', score: 572 },
+  { month: 'Jul', score: 568 },
+  { month: 'Aug', score: 571 },
+  { month: 'Sep', score: 560 },
+  { month: 'Oct', score: 547 },
+];
+
+function OnTrackChip() {
+  return (
+    <Chip color="action" size="small">
+      <Chip.Label>On track</Chip.Label>
+    </Chip>
+  );
+}
+
+function SafeToSpendCard() {
+  return (
+    <Card>
+      <Card.Stripe />
+      <Card.Header>
+        <Heading size="sm">Safe to spend</Heading>
+        <OnTrackChip />
+      </Card.Header>
+      <Card.Content>
+        <VStack space="md">
+          <HStack space="lg" className="items-center">
+            <Box className="size-24">
+              <PieChart
+                series={[
+                  {
+                    id: 'safe-to-spend',
+                    data: SAFE_TO_SPEND,
+                    innerRadius: '80%',
+                    valueFormatter: formatUsd,
+                  },
+                ]}
+                width={96}
+                height={96}
+                hideLegend
+                accessibilityLabel="$462 of your $1,200 monthly budget is left after bills."
+              />
+            </Box>
+            <VStack space="xs" className="flex-1">
+              <Heading size="xl">$462</Heading>
+              <Text size="sm" color="secondary">
+                left after bills
+              </Text>
+            </VStack>
+          </HStack>
+          <Text color="secondary">
+            You have <Text weight="semibold">$57/day</Text> for the next 8 days until your Jan 30
+            paycheck.
+          </Text>
+        </VStack>
+      </Card.Content>
+    </Card>
+  );
+}
+
+function SpendingCard() {
+  return (
+    <Card>
+      <Card.Header>
+        <Heading size="sm">Spending this month</Heading>
+      </Card.Header>
+      <Card.Content>
+        <VStack space="lg">
+          <PieChart
+            series={[
+              {
+                id: 'spending',
+                data: SPENDING,
+                innerRadius: '72%',
+                paddingAngle: 2,
+                cornerRadius: 4,
+                valueFormatter: formatUsd,
+              },
+            ]}
+            width={192}
+            height={192}
+            legendLayout="list"
+            centerLabel={
+              <Box className="items-center">
+                <Heading size="md">$5,325</Heading>
+                <Text size="xs" color="secondary" className="uppercase">
+                  Total
+                </Text>
+              </Box>
+            }
+          />
+          <Insight aiGenerated>
+            <Insight.Description>
+              Food and dining is 18% higher than last month, mostly from weekend restaurant visits.
+            </Insight.Description>
+          </Insight>
+        </VStack>
+      </Card.Content>
+    </Card>
+  );
+}
+
+function DailySpendingCard() {
+  return (
+    <Card>
+      <Card.Header>
+        <Heading size="sm">Daily spending</Heading>
+        <OnTrackChip />
+      </Card.Header>
+      <Card.Content>
+        <HStack space="lg" className="flex-wrap items-end">
+          <VStack space="sm">
+            <VStack space="xs">
+              <Heading size="xl">$37</Heading>
+              <Text weight="medium">spent so far today</Text>
+            </VStack>
+            <Text size="sm" color="secondary">
+              Daily average: $49
+            </Text>
+          </VStack>
+          <BarChart
+            className="min-w-32 flex-1"
+            dataset={DAILY_SPENDING}
+            xAxis={[{ id: 'day', dataKey: 'day', scaleType: 'band' }]}
+            yAxis={[{ id: 'spend', position: 'none', min: 0, max: 62 }]}
+            series={[
+              {
+                id: 'earlier',
+                dataKey: 'earlier',
+                label: 'Spent',
+                stack: 'day',
+                color: 'simple-primary',
+                valueFormatter: formatUsd,
+              },
+              {
+                id: 'today',
+                dataKey: 'today',
+                label: 'Spent so far today',
+                stack: 'day',
+                color: 'simple-secondary',
+                valueFormatter: formatUsd,
+              },
+            ]}
+            grid={{ horizontal: false }}
+            tooltip={{ trigger: 'item' }}
+            categoryGapRatio={0.7}
+            borderRadius={999}
+            width={FILL_WIDTH}
+            height={112}
+            hideLegend
+            scrollable={false}
+            accessibilityLabel="Spending for the last seven days. $37 so far today, Friday, against a $49 daily average."
+          />
+        </HStack>
+      </Card.Content>
+    </Card>
+  );
+}
+
+function CashFlowCard() {
+  return (
+    <Card>
+      <Card.Header>
+        <Heading size="sm">Cash flow this week</Heading>
+      </Card.Header>
+      <Card.Content>
+        <VStack space="lg">
+          <BarChart
+            dataset={CASH_FLOW}
+            xAxis={[{ id: 'day', dataKey: 'day', scaleType: 'band' }]}
+            yAxis={[
+              {
+                id: 'amount',
+                min: 0,
+                max: 15000,
+                tickNumber: 4,
+                valueFormatter: formatUsdThousands,
+              },
+            ]}
+            series={[
+              {
+                id: 'moneyIn',
+                dataKey: 'moneyIn',
+                label: 'In',
+                stack: 'flow',
+                valueFormatter: formatUsd,
+              },
+              {
+                id: 'moneyOut',
+                dataKey: 'moneyOut',
+                label: 'Out',
+                stack: 'flow',
+                valueFormatter: formatUsd,
+              },
+            ]}
+            borderRadius={2}
+            width={FILL_WIDTH}
+            height={176}
+            scrollable={false}
+            accessibilityLabel="Money in and out each day this week."
+          />
+          <VStack>
+            {CASH_FLOW_SUMMARY.map((row, index) => (
+              <VStack key={row.label}>
+                {index > 0 ? <Divider /> : null}
+                <HStack className="items-center justify-between py-2">
+                  <Text size="sm" color="secondary">
+                    {row.label}
+                  </Text>
+                  <Text size="sm" weight="medium" color={row.color}>
+                    {row.value}
+                  </Text>
+                </HStack>
+              </VStack>
+            ))}
+          </VStack>
+          <Insight aiGenerated>
+            <Insight.Description>
+              More came in than went out this week. Moving $1,000 to savings would still leave a
+              cushion.
+            </Insight.Description>
+          </Insight>
+        </VStack>
+      </Card.Content>
+    </Card>
+  );
+}
+
+function CreditScoreCard() {
+  return (
+    <Card>
+      <Card.Header>
+        <Heading size="sm">Credit score</Heading>
+      </Card.Header>
+      <Card.Content>
+        <VStack space="lg">
+          <HStack space="lg" className="items-center">
+            <LineChart
+              className="min-w-0 flex-1"
+              dataset={CREDIT_SCORE}
+              xAxis={[
+                {
+                  id: 'month',
+                  dataKey: 'month',
+                  tickLabelInterval: (_, index) => (CREDIT_SCORE.length - 1 - index) % 2 === 0,
+                },
+              ]}
+              yAxis={[{ id: 'score', min: 540, max: 580, tickNumber: 3 }]}
+              series={[{ id: 'score', dataKey: 'score', label: 'Credit score', color: 'danger' }]}
+              width={FILL_WIDTH}
+              height={128}
+              hideLegend
+              scrollable={false}
+              accessibilityLabel="Credit score from May to October, falling from 575 to 547."
+            />
+            <VStack space="xs" className="items-end">
+              <Heading size="xl">547</Heading>
+              <Text size="sm" color="secondary">
+                Poor
+              </Text>
+              <Text size="sm" color="danger">
+                −13 since Sep
+              </Text>
+            </VStack>
+          </HStack>
+          <Insight aiGenerated color="danger">
+            {/* TODO(forge-ui): a summary Insight has no body-size title, and Insight.Title renders
+                as a heading. The emphasized first line is a semibold nested Text instead. */}
+            <Insight.Description>
+              <Text weight="semibold">
+                2 missed payments in the last 90 days are impacting your score
+              </Text>
+              {'\n'}
+              <Text color="secondary">
+                Set up autopay on all your cards and bills to prevent this.
+              </Text>
+            </Insight.Description>
+          </Insight>
+        </VStack>
+      </Card.Content>
+    </Card>
+  );
+}
+
+export default function InsightsOverviewBlock() {
+  return (
+    <VStack space="lg" className="w-full">
+      <Heading size="md">Your money this month</Heading>
+      <SafeToSpendCard />
+      <Tabs defaultValue="spending">
+        <Tabs.List accessibilityLabel="Insight topics" scrollable={false} className="self-center">
+          <Tabs.Tab value="spending">
+            <Tabs.TabLabel>Spending</Tabs.TabLabel>
+          </Tabs.Tab>
+          <Tabs.Tab value="cash-flow">
+            <Tabs.TabLabel>Cash flow</Tabs.TabLabel>
+          </Tabs.Tab>
+          <Tabs.Tab value="credit">
+            <Tabs.TabLabel>Credit</Tabs.TabLabel>
+          </Tabs.Tab>
+        </Tabs.List>
+        <Tabs.Panel value="spending" className="mt-3">
+          <VStack space="lg">
+            <SpendingCard />
+            <DailySpendingCard />
+          </VStack>
+        </Tabs.Panel>
+        <Tabs.Panel value="cash-flow" className="mt-3">
+          <CashFlowCard />
+        </Tabs.Panel>
+        <Tabs.Panel value="credit" className="mt-3">
+          <CreditScoreCard />
+        </Tabs.Panel>
+      </Tabs>
+    </VStack>
+  );
+}
+```
+
+## Insight with Chart
+
+Dismissible insight cards that back their headline with a chart: a horizontal bar comparison with month-over-month change, a cash-flow waterfall, and budget progress bars.
+
+**Platforms:** iOS, Android
+
+```tsx
+import {
+  BarChart,
+  Button,
+  HStack,
+  Icon,
+  Insight,
+  ProgressBar,
+  Text,
+  VStack,
+  type ChartValueFormatter,
+} from '@cdx-ui/components';
+import { CheckCircle, Error } from '@cdx-ui/icons';
+import { FILL_WIDTH, formatUsd } from '../_utils';
+
+const SPENDING = [
+  { category: 'Housing', amount: 1800, change: 0 },
+  { category: 'Dining', amount: 720, change: 195 },
+  { category: 'Transport', amount: 510, change: -110 },
+];
+
+// TODO(forge-ui): bar labels are plain SVG text, so the change can't take the design's trend
+// icon or tertiary color. It is written into the label as an arrow instead.
+const formatSpending: ChartValueFormatter = (value, { dataIndex }) => {
+  const change = dataIndex === undefined ? 0 : SPENDING[dataIndex].change;
+  if (change === 0) return formatUsd(value);
+  return `${formatUsd(value)}  ${change > 0 ? '↗' : '↘'} ${formatUsd(Math.abs(change))}`;
+};
+
+const CASH_FLOW = [
+  { step: 'Starting', amount: 2300, isTotal: true },
+  { step: 'Income', amount: 1850 },
+  { step: 'Expenses', amount: -1430 },
+  { step: 'Ending', isTotal: true },
+];
+
+function SpendingInsight() {
+  return (
+    <Insight layout="detail" onClose={() => {}}>
+      <Insight.Tag>Spending</Insight.Tag>
+      <Insight.Header>
+        <Insight.Title>
+          Housing made up 36% of your spending this month vs. last month
+        </Insight.Title>
+      </Insight.Header>
+      <Insight.Content>
+        <BarChart
+          dataset={SPENDING}
+          layout="horizontal"
+          yAxis={[{ id: 'category', dataKey: 'category', scaleType: 'band' }]}
+          xAxis={[{ id: 'amount', position: 'none', min: 0, max: 1800 }]}
+          series={[
+            {
+              id: 'amount',
+              dataKey: 'amount',
+              label: 'This month',
+              valueFormatter: formatSpending,
+            },
+          ]}
+          barLabel
+          grid={{ vertical: false }}
+          borderRadius={4}
+          width={FILL_WIDTH}
+          height={112}
+          hideLegend
+          scrollable={false}
+          accessibilityLabel="Spending this month by category. Housing $1,800, unchanged. Dining $720, up $195. Transport $510, down $110."
+        />
+      </Insight.Content>
+      <Insight.Footer>
+        <Button variant="outline" color="action" size="small" className="flex-1">
+          <Button.Label>Compare spending</Button.Label>
+        </Button>
+      </Insight.Footer>
+    </Insight>
+  );
+}
+
+function CashFlowInsight() {
+  return (
+    <Insight layout="detail" onClose={() => {}}>
+      <Insight.Tag>Cashflow</Insight.Tag>
+      <Insight.Header>
+        <Insight.Title>You brought in $420 more than you spent this week</Insight.Title>
+        <Insight.Description>
+          You received <Text weight="bold">$1,850</Text> and spent{' '}
+          <Text weight="bold">$1,430 this week</Text>, so your checking balance grew from{' '}
+          <Text weight="bold">$2,300 to $2,720</Text>.
+        </Insight.Description>
+      </Insight.Header>
+      <Insight.Content>
+        <BarChart
+          dataset={CASH_FLOW}
+          xAxis={[{ id: 'step', dataKey: 'step', scaleType: 'band' }]}
+          yAxis={[{ id: 'amount', position: 'none', min: 0, max: 4150 }]}
+          series={[
+            {
+              id: 'balance',
+              dataKey: 'amount',
+              waterfall: { totalKey: 'isTotal' },
+              valueFormatter: formatUsd,
+            },
+          ]}
+          barLabel
+          grid={{ horizontal: false }}
+          borderRadius={4}
+          width={FILL_WIDTH}
+          height={240}
+          hideLegend
+          scrollable={false}
+          accessibilityLabel="Checking balance this week: starting $2,300, income $1,850, expenses $1,430, ending $2,720."
+        />
+      </Insight.Content>
+      <Insight.Footer>
+        <Button variant="outline" color="action" size="small" className="flex-1">
+          <Button.Label>Compare spending</Button.Label>
+        </Button>
+        <Button variant="outline" color="action" size="small" className="flex-1">
+          <Button.Label>View categories</Button.Label>
+        </Button>
+      </Insight.Footer>
+    </Insight>
+  );
+}
+
+function BudgetInsight() {
+  return (
+    <Insight layout="detail" onClose={() => {}}>
+      <Insight.Tag>Budget</Insight.Tag>
+      <Insight.Header>
+        <Insight.Title>You’ve gone over your Entertainment budget this month</Insight.Title>
+        <Insight.Description>
+          Dining Out is close to its limit · <Text weight="bold">8 days left</Text>
+        </Insight.Description>
+      </Insight.Header>
+      <Insight.Content className="gap-4">
+        <VStack space="xs">
+          <HStack className="items-center justify-between">
+            <Text weight="semibold">Entertainment</Text>
+            <HStack space="xs" className="items-center">
+              <Icon as={Error} className="size-4 text-chart-categorical-2" />
+              <Text size="sm" weight="semibold">
+                $65 over
+              </Text>
+            </HStack>
+          </HStack>
+          <ProgressBar
+            value={100}
+            max={100}
+            size="large"
+            color="categorical-2"
+            accessibilityLabel="Entertainment budget, $65 over"
+          >
+            <ProgressBar.Indicator />
+          </ProgressBar>
+        </VStack>
+        <VStack space="xs">
+          <HStack className="items-center justify-between">
+            <Text weight="semibold">Dining Out</Text>
+            <Text size="sm" weight="medium" color="secondary">
+              $120 left
+            </Text>
+          </HStack>
+          <ProgressBar
+            value={73}
+            max={100}
+            size="large"
+            color="categorical-1"
+            accessibilityLabel="Dining Out budget, $120 left"
+          >
+            <ProgressBar.Indicator />
+          </ProgressBar>
+        </VStack>
+      </Insight.Content>
+      <Insight.Footer className="justify-between">
+        <HStack space="xs" className="shrink items-center">
+          <Icon as={CheckCircle} color="success" className="size-4" />
+          <Text size="sm" color="secondary">
+            3 other budgets on track
+          </Text>
+        </HStack>
+        <Button variant="outline" color="action" size="small">
+          <Button.Label>View budgets</Button.Label>
+        </Button>
+      </Insight.Footer>
+    </Insight>
+  );
+}
+
+export default function InsightChartBlock() {
+  return (
+    <VStack space="lg" className="w-full">
+      <SpendingInsight />
+      <CashFlowInsight />
+      <BudgetInsight />
+    </VStack>
+  );
+}
+```
+
+## Insight with Table
+
+A dismissible insight card that lists upcoming bills in a compact table.
+
+**Platforms:** iOS, Android
+
+```tsx
+import { Avatar, Button, HStack, Insight, Table, Text } from '@cdx-ui/components';
+import { Call, DirectionsCar, HumidityLow, Wifi } from '@cdx-ui/icons';
+
+const BILLS = [
+  { name: 'Car insurance', icon: DirectionsCar, due: 'Oct 13', amount: '$460' },
+  { name: 'Phone', icon: Call, due: 'Oct 14', amount: '$68' },
+  { name: 'Internet', icon: Wifi, due: 'Oct 15', amount: '$96' },
+  { name: 'Water', icon: HumidityLow, due: 'Oct 16', amount: '$111' },
+];
+
+export default function InsightTableBlock() {
+  return (
+    <Insight layout="detail" onClose={() => {}} className="w-full">
+      <Insight.Tag>Bills</Insight.Tag>
+      <Insight.Header>
+        <Insight.Title>We found 7 recurring bills</Insight.Title>
+        <Insight.Description>
+          4 due next week · about <Text weight="bold">$735</Text>
+        </Insight.Description>
+      </Insight.Header>
+      <Insight.Content>
+        <Table fullBleed accessibilityLabel="Bills due next week">
+          <Table.Body>
+            {BILLS.map((bill) => (
+              <Table.Row key={bill.name}>
+                <Table.Cell colSpan={2}>
+                  <HStack space="sm" className="items-center">
+                    <Avatar color="brand" variant="subtle" shape="circle" size="sm">
+                      <Avatar.Icon as={bill.icon} />
+                    </Avatar>
+                    <Text numberOfLines={1}>{bill.name}</Text>
+                  </HStack>
+                </Table.Cell>
+                <Table.Cell align="end">
+                  <Text size="sm" color="secondary">
+                    {bill.due}
+                  </Text>
+                </Table.Cell>
+                <Table.Cell align="end">
+                  <Text weight="medium">{bill.amount}</Text>
+                </Table.Cell>
+              </Table.Row>
+            ))}
+          </Table.Body>
+        </Table>
+      </Insight.Content>
+      <Insight.Footer>
+        <Button variant="outline" color="action" size="small" className="flex-1">
+          <Button.Label>View bills</Button.Label>
+        </Button>
+      </Insight.Footer>
+    </Insight>
+  );
+}
+```

package/docs/resources/content.md

@@ -3,6 +3,7 @@
 ## Tools
 
 - [Figma libraries](https://design.candescent.com/docs/resources/figma-libraries/content.md) — Access our official design system Figma libraries
+- [Agent skills](https://design.candescent.com/docs/resources/skills/content.md) — Teach AI coding agents to build with Forge UI components as they ship, without restyling them.
 
 ## Changelogs
 

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

@@ -0,0 +1,7 @@
+# 0.3.5 (https://design.candescent.com/docs/resources/release-notes/0.3.5)
+
+Selected subtle Chip labels stay visible on Android when the variant changes from outline to subtle.
+
+## Bug fixes
+
+**[Chip](https://design.candescent.com/docs/components/chip/content.md)** — A selected chip that switches from `outline` to `subtle` keeps its label painted on Android ([#872](https://github.com/dfh-candescent/forge-design-system/pull/872)).