@cdx-ui/components 0.3.5 → 0.3.7

package/docs/patterns/content.md

@@ -6,5 +6,6 @@
 - [Onboarding](https://design.candescent.com/docs/patterns/onboarding/content.md) — Welcome screens, setup wizards, and guided first-run experiences.
 - [Settings](https://design.candescent.com/docs/patterns/settings/content.md) — User preferences, notification controls, and account settings.
 - [Dashboard](https://design.candescent.com/docs/patterns/dashboard/content.md) — Home screens, greetings, summaries, and at-a-glance views.
+- [Insights](https://design.candescent.com/docs/patterns/insights/content.md) — Personalized insight cards that pair a headline with a chart, table, or actions.
 - [Forms](https://design.candescent.com/docs/patterns/forms/content.md) — Data entry patterns for personal info, addresses, and profile editing.
 - [Empty States](https://design.candescent.com/docs/patterns/empty-states/content.md) — Placeholder screens shown when content is not yet available.

package/docs/patterns/dashboard/content.md

@@ -1,34 +1,438 @@
 # Dashboard (https://design.candescent.com/docs/patterns/dashboard)
 
+## 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>
+  );
+}
+```
+
 ## Dashboard Greeting
 
-A personalized greeting header with search, notifications, and avatar.
+A branded app header with search and a notification-badged avatar, above a personalized welcome.
 
 **Platforms:** iOS, Android
 
 ```tsx
-import { Avatar, Badge, Heading, HStack, IconButton, Text, VStack } from '@cdx-ui/components';
-import { Notifications, Search } from '@cdx-ui/icons';
+import { Avatar, Badge, Heading, HStack, IconButton, Image, VStack } from '@cdx-ui/components';
+import { Search } from '@cdx-ui/icons';
+
+const LOGO_STYLE = { height: 20, aspectRatio: 686 / 100 };
 
 export default function DashboardGreetingBlock() {
   return (
-    <HStack className="w-full max-w-md items-center justify-between py-4 px-4">
-      <VStack space="xs">
-        <Text size="sm" color="secondary">
-          Good morning,
-        </Text>
-        <Heading>Bernadette</Heading>
-      </VStack>
-      <HStack space="sm" className="items-center">
-        <IconButton as={Search} accessibilityLabel="Search" />
-        <Badge label={3} color="danger" overlap="circular" accessibilityLabel="3 notifications">
-          <IconButton as={Notifications} accessibilityLabel="Notifications" />
-        </Badge>
-        <Avatar size="lg">
-          <Avatar.Text>Bernadette Miller</Avatar.Text>
-        </Avatar>
+    <VStack className="w-full max-w-md">
+      <HStack className="items-center justify-between px-4 pt-3 pb-2">
+        <Image
+          source="/candescent/logo-dark.png"
+          accessibilityLabel="Candescent"
+          className="dark:hidden"
+          style={LOGO_STYLE}
+        />
+        <Image
+          source="/candescent/logo-light.png"
+          accessibilityLabel="Candescent"
+          className="hidden dark:flex"
+          style={LOGO_STYLE}
+        />
+        <HStack space="md" className="items-center">
+          <IconButton as={Search} accessibilityLabel="Search" />
+          <Badge
+            label="99+"
+            color="info"
+            overlap="circular"
+            accessibilityLabel="99 or more notifications"
+          >
+            <Avatar size="lg">
+              <Avatar.Text>Bernadette Miller</Avatar.Text>
+            </Avatar>
+          </Badge>
+        </HStack>
       </HStack>
-    </HStack>
+      <Heading className="px-5 pt-4">Welcome, Bernadette</Heading>
+    </VStack>
   );
 }
 ```