@bitforgehq/ui 0.3.0 → 0.3.2

package/ai/components/chart-card.md

@@ -0,0 +1,283 @@
+# bf-chart-card
+
+Card around one chart with a title, period control and loading, empty and error states
+
+`BfChartCardComponent` from `@bitforgehq/ui/charts` · Data display · since 0.3.1
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfSegmentedComponent, type BfSegmentOption } from '@bitforgehq/ui';
+import {
+  BfBarChartComponent,
+  BfChartCardComponent,
+  type BfChartSeries,
+} from '@bitforgehq/ui/charts';
+
+type Period = 'week' | 'month';
+type CardState = 'data' | 'loading' | 'empty' | 'error';
+
+const SERIES: Record<Period, { categories: readonly string[]; series: readonly BfChartSeries[] }> =
+  {
+    week: {
+      categories: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
+      series: [{ name: 'Deploys', values: [4, 7, 3, 6, 2] }],
+    },
+    month: {
+      categories: ['W40', 'W41', 'W42', 'W43'],
+      series: [{ name: 'Deploys', values: [21, 18, 26, 22] }],
+    },
+  };
+
+/**
+ * The bf-chart-card overview.
+ *
+ * Live demo of `bf-chart-card`: deploys per day or per week, with the period switch in the
+ * card's `period` slot. The second control shows the card's loading, empty and error states.
+ */
+@Component({
+  selector: 'app-example-chart-card-overview',
+  imports: [BfChartCardComponent, BfBarChartComponent, BfSegmentedComponent],
+  template: `
+    <div class="flex w-full flex-col gap-4">
+      <bf-segmented size="sm" label="Card state" [options]="states" [(value)]="state" />
+      <bf-chart-card
+        title="Deploys"
+        [loading]="state() === 'loading'"
+        [empty]="state() === 'empty'"
+        [error]="state() === 'error'"
+      >
+        <bf-segmented
+          bfSlot="period"
+          size="sm"
+          label="Period"
+          [options]="periods"
+          [(value)]="period"
+        />
+        <bf-bar-chart [series]="data().series" [categories]="data().categories" [height]="200" />
+      </bf-chart-card>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">
+        Period: {{ period() }} · {{ state() }}
+      </p>
+    </div>
+  `,
+})
+export class ChartCardOverviewExampleComponent {
+  readonly periods: BfSegmentOption<Period>[] = [
+    { value: 'week', label: 'Week' },
+    { value: 'month', label: 'Month' },
+  ];
+  readonly states: BfSegmentOption<CardState>[] = [
+    { value: 'data', label: 'Data' },
+    { value: 'loading', label: 'Loading' },
+    { value: 'empty', label: 'Empty' },
+    { value: 'error', label: 'Error' },
+  ];
+  readonly period = signal<Period | null>('week');
+  readonly state = signal<CardState | null>('data');
+  readonly data = computed(() => SERIES[this.period() ?? 'week']);
+}
+```
+
+## Overview
+
+A card around one chart: a title, a `period` slot for the range control (a `bf-segmented` or a
+`bf-select`), and the chart, or its loading placeholder (a `bf-skeleton`), its empty state or
+its error. The chart inside takes the card's title as its name when it has no `label`, and the
+card's `legend` placement when it sets none.
+
+A chart card frames one chart on a dashboard: a title, a range control at the top end, and the chart, or what stands in for it while the data loads, when there is none and when it failed. `bf-chart-card` draws the `flat` card surface around them; the chart inside takes the card's title as its name and the card's `legend` placement. It lives in `@bitforgehq/ui/charts` (`import { BfChartCardComponent } from '@bitforgehq/ui/charts'`) and works the same in a desktop web app and in the Capacitor shell.
+
+## When to use
+
+Use `bf-chart-card` around a [bf-line-chart](https://bitforge-ui.web.app/components/line-chart), [bf-bar-chart](https://bitforge-ui.web.app/components/bar-chart) or [bf-donut-chart](https://bitforge-ui.web.app/components/donut-chart) on a dashboard or a detail page. Use [bf-card](https://bitforge-ui.web.app/components/card) instead for a card that holds more than one chart or other content, and [bf-stat](https://bitforge-ui.web.app/components/stat) with a [bf-sparkline](https://bitforge-ui.web.app/components/sparkline) for a headline figure with a small trend.
+
+## A dashboard
+
+Stats in a row over chart cards in a grid: the cards stretch to their row's height, so their charts line up. The `period` slot holds a `bf-segmented` (three or four ranges) or a `bf-select` (more); the app reloads the data when it changes.
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfSegmentedComponent, BfStatComponent, type BfSegmentOption } from '@bitforgehq/ui';
+import {
+  BfBarChartComponent,
+  BfChartCardComponent,
+  BfDonutChartComponent,
+  BfLineChartComponent,
+  BfSparklineComponent,
+  type BfChartSeries,
+  type BfDonutSlice,
+} from '@bitforgehq/ui/charts';
+
+type Range = '30d' | '90d';
+
+const REVENUE: Record<Range, { categories: readonly string[]; series: readonly BfChartSeries[] }> =
+  {
+    '30d': {
+      categories: ['Oct 1', 'Oct 8', 'Oct 15', 'Oct 22', 'Oct 29'],
+      series: [
+        { name: 'Subscriptions', values: [9.1, 9.4, 9.8, 10.2, 10.9] },
+        { name: 'Services', values: [2.4, 3.1, 2.2, 2.9, 3.4] },
+      ],
+    },
+    '90d': {
+      categories: ['Aug', 'Sep', 'Oct'],
+      series: [
+        { name: 'Subscriptions', values: [36.2, 38.9, 41.5] },
+        { name: 'Services', values: [9.8, 11.2, 12.0] },
+      ],
+    },
+  };
+
+/**
+ * A dashboard of stats and chart cards.
+ *
+ * Three stats with sparklines over a grid of chart cards: revenue as a line chart with a range
+ * switch, sign-ups by source as a donut, and tickets per weekday as stacked bars. The grid wraps
+ * to one column on a narrow screen.
+ */
+@Component({
+  selector: 'app-example-chart-card-dashboard',
+  imports: [
+    BfStatComponent,
+    BfSparklineComponent,
+    BfSegmentedComponent,
+    BfChartCardComponent,
+    BfLineChartComponent,
+    BfDonutChartComponent,
+    BfBarChartComponent,
+  ],
+  template: `
+    <div class="flex w-full flex-col gap-4">
+      <div class="grid grid-cols-[repeat(auto-fit,minmax(10rem,1fr))] gap-3">
+        <bf-stat label="Monthly revenue" value="CHF 54.4k" variant="card">
+          <span class="flex flex-col gap-1">
+            <bf-sparkline [values]="[46, 47, 49, 48, 51, 54]" />
+            Up 6% on September
+          </span>
+        </bf-stat>
+        <bf-stat label="Active accounts" value="3,812" variant="card">
+          <span class="flex flex-col gap-1">
+            <bf-sparkline [values]="[3510, 3580, 3620, 3700, 3760, 3812]" />
+            Up 2% on September
+          </span>
+        </bf-stat>
+        <bf-stat label="Open tickets" value="41" variant="card">
+          <span class="flex flex-col gap-1">
+            <bf-sparkline [values]="[58, 52, 55, 47, 44, 41]" />
+            Down 7 this week
+          </span>
+        </bf-stat>
+      </div>
+      <div class="grid grid-cols-[repeat(auto-fit,minmax(min(18rem,100%),1fr))] gap-4">
+        <bf-chart-card class="col-span-full" title="Revenue (CHF thousands)" [headingLevel]="3">
+          <bf-segmented
+            bfSlot="period"
+            size="sm"
+            label="Range"
+            [options]="ranges"
+            [(value)]="range"
+          />
+          <bf-line-chart
+            area
+            curve="smooth"
+            [series]="revenue().series"
+            [categories]="revenue().categories"
+          />
+        </bf-chart-card>
+        <bf-chart-card title="Sign-ups by source" [headingLevel]="3">
+          <bf-donut-chart [slices]="sources" [height]="200">
+            <span bfSlot="center" class="text-heading text-text">612</span>
+            <span bfSlot="center" class="text-caption text-text-muted">this month</span>
+          </bf-donut-chart>
+        </bf-chart-card>
+        <bf-chart-card title="Tickets per weekday" [headingLevel]="3">
+          <bf-bar-chart stacked [series]="tickets" [categories]="days" [height]="200" />
+        </bf-chart-card>
+      </div>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">
+        Revenue range: {{ range() }}
+      </p>
+    </div>
+  `,
+})
+export class ChartCardDashboardExampleComponent {
+  readonly ranges: BfSegmentOption<Range>[] = [
+    { value: '30d', label: '30 days' },
+    { value: '90d', label: '90 days' },
+  ];
+  readonly range = signal<Range | null>('30d');
+  readonly revenue = computed(() => REVENUE[this.range() ?? '30d']);
+  readonly sources: readonly BfDonutSlice[] = [
+    { label: 'Search', value: 248 },
+    { label: 'Referral', value: 171 },
+    { label: 'Social', value: 118 },
+    { label: 'Direct', value: 75 },
+  ];
+  readonly days = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'];
+  readonly tickets: readonly BfChartSeries[] = [
+    { name: 'Billing', values: [6, 4, 5, 7, 3] },
+    { name: 'Technical', values: [9, 11, 8, 10, 6] },
+  ];
+}
+```
+
+## Loading, empty and error
+
+`loading` shows a `bf-skeleton` the height of the default chart instead of the chart and marks the body `aria-busy`; with a resource, bind `[loading]="revenue.isLoading()"`. `empty` shows the `empty` slot, else the `chartEmpty` label ("No data to show"); `error` shows the `error` slot, such as a message and a retry button, else the `chartError` label. `loading` wins over `error`, and `error` over `empty`. Each state keeps the chart's height, so the card does not jump when the data arrives.
+
+## Desktop
+
+The card itself is not interactive; its chart and its period control are. The title is a heading (`headingLevel` 2 by default, 3 inside a section), so a dashboard of cards has an outline to move through. Inside `provideBfShell()` it renders and behaves the same; on a phone, stack the cards in one column.
+
+## Theming
+
+- Surface: `surface`, the `card` radius, `--spacing-card` padding (`p-card`) and a 1.5 px `border-strong` edge, as the `flat` `bf-card`.
+- Title: `text-heading` in `text`.
+- Empty and error text: `text-body` in `text-muted`, centred in the chart's height.
+- Loading: `bf-skeleton`'s `surface-sunken` bar with its shimmer.
+
+## Accessibility
+
+The title is an `h2` (or `h3` with `headingLevel`), and the chart inside is a `figure` named by it unless the chart has its own `label`. While `loading`, the body is `aria-busy="true"` and the skeleton is hidden from assistive technology. The empty and error states are `role="status"`, so a screen reader reads them when they replace the chart. Give the period control its own `label` ("Period").
+
+## Inputs
+
+| Name           | Type                                                    | Default    | Description                                                                                                                                    |
+| -------------- | ------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`        | `string`                                                | required   | The card's heading; also the chart's name when the chart has no `label`.                                                                       |
+| `headingLevel` | `BfChartCardHeadingLevel` (`2 \| 3`)                    | `2`        | Heading level of the title so the card fits the page outline.                                                                                  |
+| `legend`       | `BfChartLegendPosition` (`'top' \| 'bottom' \| 'none'`) | `'bottom'` | Where the chart inside draws its legend, unless it sets its own `legend`.                                                                      |
+| `loading`      | `boolean`                                               | `false`    | Shows a placeholder instead of the chart while its data loads, and marks the body `aria-busy`.                                                 |
+| `empty`        | `boolean`                                               | `false`    | Shows the `empty` slot (or the `chartEmpty` label) instead of the chart: there is no data for the period.                                      |
+| `error`        | `boolean`                                               | `false`    | Shows the `error` slot (or the `chartError` label) instead of the chart: the data failed to load. Wins over `empty`; `loading` wins over both. |
+
+## Slots
+
+- `period`: The range control at the top end, such as a bf-segmented or a bf-select.
+- `error`: What shows when `error` is set, such as a message and a retry button; without it, the `chartError` label.
+- `empty`: What shows when `empty` is set; without it, the `chartEmpty` label.
+- `default`: The chart.
+
+## Notes
+
+### Do
+
+- Keep the title short and name the measure ("Revenue"), with the range in the period control.
+- Put a retry button in the `error` slot when the app can load the data again.
+
+### Don't
+
+- Don't put more than one chart in a card; give each its own.
+- Don't wrap the `empty` and `error` slot content in an `@if`; the card decides when to show it.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-chart-card` in `@bitforgehq/ui/charts`: the `flat` card surface around one chart, with a
+`title` (the chart's name when it has no `label`; `headingLevel`, `BfChartCardHeadingLevel` 2 or
+3), a `period` slot for the range control, the `legend` placement for the chart inside, and
+`loading` (a `bf-skeleton`, `aria-busy`), `empty` and `error` states with slots of the same names
+and the `chartEmpty` and `chartError` labels as fallbacks.