@bitforgehq/ui 0.3.0 → 0.3.2

package/ai/components/skeleton.md

@@ -0,0 +1,215 @@
+# bf-skeleton
+
+Loading placeholder shaped as text lines, a rectangle or a circle, with a shimmer
+
+`BfSkeletonComponent` from `@bitforgehq/ui` · Feedback · since 0.3.1
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { BfSkeletonComponent } from '@bitforgehq/ui';
+
+/**
+ * The bf-skeleton overview.
+ *
+ * Live demo of `bf-skeleton`: the three shapes (a circle for an avatar, text lines with a shorter
+ * last line, a rect for an image) inside a region marked `aria-busy="true"` while it loads.
+ */
+@Component({
+  selector: 'app-example-skeleton-overview',
+  imports: [BfSkeletonComponent],
+  template: `
+    <div aria-busy="true" class="flex max-w-md flex-col gap-4">
+      <div class="flex items-center gap-3">
+        <bf-skeleton shape="circle" />
+        <div class="flex min-w-0 flex-1 flex-col gap-2">
+          <bf-skeleton width="40%" height="0.875rem" />
+          <bf-skeleton width="25%" />
+        </div>
+      </div>
+      <bf-skeleton [lines]="3" height="0.875rem" />
+      <bf-skeleton shape="rect" height="8rem" />
+    </div>
+  `,
+})
+export class SkeletonOverviewExampleComponent {}
+```
+
+## Overview
+
+Loading placeholder in the shape of the content to come: text lines, a rectangle or a circle,
+on the sunken surface with a shimmer. It is hidden from assistive technology; mark the region it
+stands in for with `aria-busy="true"` while it loads.
+
+A skeleton is a placeholder in the shape of the content that is still loading: a few text lines, a rectangle for an image or a chart, a circle for an avatar. It sits on the `surface-sunken` fill with a soft shimmer, so the page keeps its layout while the data arrives and nothing jumps when it does. `bf-skeleton` is hidden from assistive technology; the region it stands in for says that it is busy. It works the same in both shells: in a desktop web app and in the Capacitor shell.
+
+## When to use
+
+Use `bf-skeleton` while a screen or a section loads content whose shape you know: a card, a list, the rows of a table. Use [bf-spinner](https://bitforge-ui.web.app/components/spinner) instead for a short wait with no known shape, or inside a button, and [bf-progress](https://bitforge-ui.web.app/components/progress) when you can say how far the work is. Once loading has failed, replace the skeletons with a [bf-alert](https://bitforge-ui.web.app/components/alert); when it returned nothing, with a [bf-empty-state](https://bitforge-ui.web.app/components/empty-state).
+
+## Shapes and sizes
+
+`shape` picks the placeholder. `text` (the default) draws one line, fully rounded; `lines` draws several, the last one shorter, as a paragraph's last line is. `rect` is one bar with the field radius, for an image, a chart or a field. `circle` is a disc for an avatar.
+
+`width` and `height` take CSS lengths (`12rem`, `60%`, `48px`). Without a `width` a text or rect skeleton fills its container and a circle is 40 px; a circle's height always follows its width. `height` is the height of each text line (default `0.75rem`) or of the rect (default `6rem`); a circle ignores it. Match the size of the content to come, such as `0.875rem` lines for `text-body`, so the page does not move when it arrives.
+
+## A card while it loads
+
+Build the placeholder from the same layout as the loaded card: the same `bf-card`, the same gaps, a skeleton where each piece of content goes. Mark the region the skeletons stand in for with `aria-busy="true"` while it loads, and drop the attribute (or set it to `false`) when the content is in.
+
+```ts
+import { Component } from '@angular/core';
+import { BfAvatarComponent, BfCardComponent, BfSkeletonComponent } from '@bitforgehq/ui';
+
+/**
+ * A card while it loads, beside the loaded card.
+ *
+ * The loading card has the loaded one's layout, with a skeleton where each piece of content goes:
+ * a 40 px circle for the avatar, two short lines for the name and the role, three lines of text.
+ * Only the loading card carries `aria-busy="true"`.
+ */
+@Component({
+  selector: 'app-example-skeleton-card',
+  imports: [BfCardComponent, BfAvatarComponent, BfSkeletonComponent],
+  template: `
+    <div class="grid grid-cols-[repeat(auto-fit,minmax(15rem,1fr))] gap-4">
+      <bf-card aria-busy="true">
+        <div class="flex flex-col gap-4">
+          <div class="flex items-center gap-3">
+            <bf-skeleton shape="circle" />
+            <div class="flex min-w-0 flex-1 flex-col gap-2">
+              <bf-skeleton width="55%" height="1rem" />
+              <bf-skeleton width="35%" height="0.75rem" />
+            </div>
+          </div>
+          <bf-skeleton [lines]="3" height="0.875rem" />
+        </div>
+      </bf-card>
+      <bf-card>
+        <div class="flex flex-col gap-4">
+          <div class="flex items-center gap-3">
+            <bf-avatar initials="MK" />
+            <div class="flex min-w-0 flex-col">
+              <p class="text-label text-text">Mara Keller</p>
+              <p class="text-caption text-text-muted">Design lead</p>
+            </div>
+          </div>
+          <p class="text-body text-text-muted">
+            Runs the Atlas rebrand and the design reviews on Thursdays. Ask her about the type
+            scale.
+          </p>
+        </div>
+      </bf-card>
+    </div>
+  `,
+})
+export class SkeletonCardExampleComponent {}
+```
+
+## Table rows
+
+A loading `bf-table` keeps its real header and shows skeleton rows: pass a few placeholder rows and render a `bf-skeleton` in each column through `bfTableCell` templates, with widths that differ from row to row. The header tells the user what is coming; the table's wrapper carries `aria-busy="true"`. In a list, render a few `bf-list-item`s with a circle and two lines the same way.
+
+```ts
+import { Component } from '@angular/core';
+import {
+  BfSkeletonComponent,
+  BfTableCellDirective,
+  BfTableComponent,
+  type BfTableColumn,
+} from '@bitforgehq/ui';
+
+interface PlaceholderRow {
+  id: string;
+  /** The width of each column's skeleton in this row, so the rows do not look stamped. */
+  widths: Readonly<Record<'title' | 'client' | 'amount', string>>;
+}
+
+/**
+ * Skeleton rows in a bf-table.
+ *
+ * The table keeps its real header while the rows load: four placeholder rows render a
+ * `bf-skeleton` in every column through `bfTableCell` templates, at widths that differ from row to
+ * row, and the wrapper carries `aria-busy="true"`.
+ */
+@Component({
+  selector: 'app-example-skeleton-table',
+  imports: [BfTableComponent, BfTableCellDirective, BfSkeletonComponent],
+  template: `
+    <div aria-busy="true">
+      <bf-table label="Invoices" [rows]="rows" [columns]="columns">
+        <ng-template bfTableCell="title" [bfTableCellOf]="rows" let-row>
+          <bf-skeleton [width]="row.widths.title" height="0.875rem" />
+        </ng-template>
+        <ng-template bfTableCell="client" [bfTableCellOf]="rows" let-row>
+          <bf-skeleton [width]="row.widths.client" height="0.875rem" />
+        </ng-template>
+        <ng-template bfTableCell="amount" [bfTableCellOf]="rows" let-row>
+          <bf-skeleton class="ms-auto" [width]="row.widths.amount" height="0.875rem" />
+        </ng-template>
+      </bf-table>
+    </div>
+  `,
+})
+export class SkeletonTableExampleComponent {
+  readonly columns: readonly BfTableColumn[] = [
+    { key: 'title', label: 'Invoice' },
+    { key: 'client', label: 'Client' },
+    { key: 'amount', label: 'Amount', align: 'end' },
+  ];
+  readonly rows: readonly PlaceholderRow[] = [
+    { id: 'a', widths: { title: '70%', client: '55%', amount: '4rem' } },
+    { id: 'b', widths: { title: '55%', client: '70%', amount: '3rem' } },
+    { id: 'c', widths: { title: '80%', client: '45%', amount: '4.5rem' } },
+    { id: 'd', widths: { title: '60%', client: '60%', amount: '3.5rem' } },
+  ];
+}
+```
+
+## Desktop
+
+A skeleton is not interactive: no hover, no pointer cursor, no focus stop, and its size does not follow `provideBfDefaults()`. On desktop and in the Capacitor shell it looks and behaves the same. Show skeletons only for a wait that lasts: when a load usually finishes in a few hundred milliseconds, start showing them after a short delay (a timer in the state service), so a fast connection never sees a flash of placeholders.
+
+## Theming
+
+- Fill: `surface-sunken`. Shimmer: a `surface` highlight at 70 % opacity that sweeps across from the inline start, with `--animate-skeleton-shimmer` (1.6 s, ease-in-out, endless) and `--animate-skeleton-shimmer-rtl` under `dir="rtl"`.
+- Radius: text lines and the circle `rounded-full`; the rect `rounded-field`.
+- Under `prefers-reduced-motion: reduce` the shimmer is hidden and the placeholder stays still. Under forced colours a `GrayText` border draws the shape, as backgrounds are dropped there.
+
+## Accessibility
+
+Every `bf-skeleton` carries `aria-hidden="true"`: a placeholder has nothing to say, and a screen reader that read out a row of shapes would only make noise. Say that the content is loading on the region it stands in for instead: `aria-busy="true"` on that element tells assistive technology the region is being updated, and dropping it lets the finished content be read. For a load the user started and waits for (a search), also put a short polite status in the page, such as "Loading results", from a `role="status"` element or a `bf-spinner`, which announces its `label` (default "Loading"). The skeleton takes no focus, so keyboard focus stays where the user left it.
+
+## Inputs
+
+| Name     | Type                                               | Default  | Description                                                                                                                |
+| -------- | -------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `shape`  | `BfSkeletonShape` (`'text' \| 'rect' \| 'circle'`) | `'text'` | What it stands in for: `text` lines (default), a `rect` (an image, a chart) or a `circle` (an avatar).                     |
+| `lines`  | `number`                                           | `1`      | How many lines a `text` skeleton draws, the last one shorter when there are several; ignored by the other shapes.          |
+| `width`  | `string`                                           | `''`     | Width as a CSS length (`12rem`, `60%`); empty fills the container, a circle is 40 px. A circle's height follows its width. |
+| `height` | `string`                                           | `''`     | Height as a CSS length: of each line of `text` (default `0.75rem`) or of the `rect` (default `6rem`); a circle ignores it. |
+
+## Notes
+
+### Do
+
+- Shape the skeleton like the content to come, at its size, so nothing jumps when it loads.
+- Put `aria-busy="true"` on the loading region, and remove it once the content is there.
+- Show a few rows or cards, not a whole page of them.
+
+### Don't
+
+- Don't show a skeleton for a wait that has no known shape; use a `bf-spinner`.
+- Don't leave skeletons up after a load fails or returns nothing; show the error or the empty state.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-skeleton` in `@bitforgehq/ui`, a loading placeholder for both shells: `shape` (the new
+`BfSkeletonShape`: `text` lines, a `rect` or a `circle`), `lines` for several text lines with a
+shorter last one, and `width` / `height` as CSS lengths. It draws the `surface-sunken` fill with a
+`surface` shimmer that sweeps from the inline start (hidden under reduced motion) and carries
+`aria-hidden="true"`; the docs mark the loading region with `aria-busy="true"` and show a card and
+a table of skeleton rows.

package/ai/components/sparkline.md

@@ -0,0 +1,188 @@
+# bf-sparkline
+
+Tiny trend line with no axes or legend, for stats and table cells
+
+`BfSparklineComponent` from `@bitforgehq/ui/charts` · Data display · since 0.3.1
+
+## Example
+
+```ts
+import { Component } from '@angular/core';
+import { BfStatComponent } from '@bitforgehq/ui';
+import { BfSparklineComponent } from '@bitforgehq/ui/charts';
+
+/**
+ * The bf-sparkline overview.
+ *
+ * Live demo of `bf-sparkline`: three stats with a 30-day trend in their supporting line, the
+ * trend also stated in words; the middle one fills its area.
+ */
+@Component({
+  selector: 'app-example-sparkline-overview',
+  imports: [BfStatComponent, BfSparklineComponent],
+  template: `
+    <div class="grid w-full grid-cols-[repeat(auto-fit,minmax(10rem,1fr))] gap-3">
+      <bf-stat label="Revenue" value="CHF 48.2k" variant="card">
+        <span class="flex flex-col gap-1">
+          <bf-sparkline [values]="revenue" />
+          Up 12% in 30 days
+        </span>
+      </bf-stat>
+      <bf-stat label="Sign-ups" value="1,204" variant="card">
+        <span class="flex flex-col gap-1">
+          <bf-sparkline area curve="smooth" [values]="signups" />
+          Up 4% in 30 days
+        </span>
+      </bf-stat>
+      <bf-stat label="Churn" value="2.1%" variant="card">
+        <span class="flex flex-col gap-1">
+          <bf-sparkline [values]="churn" />
+          Down 0.4 points in 30 days
+        </span>
+      </bf-stat>
+    </div>
+  `,
+})
+export class SparklineOverviewExampleComponent {
+  readonly revenue = [31, 34, 33, 36, 35, 39, 42, 41, 45, 48];
+  readonly signups = [980, 1010, 1060, 1040, 1100, 1120, 1150, 1170, 1190, 1204];
+  readonly churn = [2.6, 2.5, 2.6, 2.4, 2.4, 2.3, 2.3, 2.2, 2.2, 2.1];
+}
+```
+
+## Overview
+
+A tiny line of one series with no axes, legend or tooltip, for a trend beside a figure (in a
+`bf-stat`'s supporting line, a table cell). Its scale spans the values' own range, so it shows
+the shape of the trend, not its size; a dot marks the latest value. With a `label` it is an
+image with that name (say what the trend means, such as "Revenue up 12% over 30 days"); without
+one it is decorative and hidden from assistive technology. It draws in on the first render and
+on every data change, still under reduced motion; under `dir="rtl"` it runs from the right.
+
+A sparkline is a word-sized line of one series with no axes, legend or tooltip: the shape of a trend beside a figure. `bf-sparkline` draws it in SVG from `values`, oldest first, scaled to their own range, with a dot on the latest value. It lives in `@bitforgehq/ui/charts` (`import { BfSparklineComponent } from '@bitforgehq/ui/charts'`) and works the same in a desktop web app and in the Capacitor shell.
+
+## When to use
+
+Use `bf-sparkline` in a [bf-stat](https://bitforge-ui.web.app/components/stat)'s supporting line, a table cell or a list row, where the figure carries the number and the line only its direction. Use [bf-line-chart](https://bitforge-ui.web.app/components/line-chart) instead when readers need the values, the axis or more than one series.
+
+## Area and size
+
+`area` fills under the line; `curve="smooth"` draws a monotone curve. `height` sets the height in px (32 by default); the width follows the container, so give the element a width (`class="w-24"`) where it sits in a row. A flat series draws a level line in the middle, and a `null` value leaves a gap. The line draws in on the first render and whenever `values` change.
+
+```ts
+import { Component } from '@angular/core';
+import { BfSparklineComponent } from '@bitforgehq/ui/charts';
+
+interface Region {
+  readonly name: string;
+  readonly total: string;
+  readonly trend: readonly (number | null)[];
+  readonly summary: string;
+}
+
+/**
+ * Sparklines in a table.
+ *
+ * A fixed-width sparkline per row, each named for screen readers by what its trend means; a
+ * `null` leaves a gap where a week was not reported.
+ */
+@Component({
+  selector: 'app-example-sparkline-table',
+  imports: [BfSparklineComponent],
+  template: `
+    <table class="text-label-sm w-full text-start">
+      <caption class="sr-only">
+        Orders by region
+      </caption>
+      <thead>
+        <tr class="border-border border-b">
+          <th scope="col" class="text-label-xs text-text-muted h-8 px-3 text-start">Region</th>
+          <th scope="col" class="text-label-xs text-text-muted h-8 px-3 text-end">Orders</th>
+          <th scope="col" class="text-label-xs text-text-muted h-8 px-3 text-start">8 weeks</th>
+        </tr>
+      </thead>
+      <tbody>
+        @for (region of regions; track region.name) {
+          <tr class="border-divider border-b">
+            <th scope="row" class="text-text h-10 px-3 text-start font-bold">{{ region.name }}</th>
+            <td class="text-text h-10 px-3 text-end tabular-nums">{{ region.total }}</td>
+            <td class="h-10 px-3">
+              <bf-sparkline
+                class="w-24"
+                [height]="24"
+                [values]="region.trend"
+                [label]="region.summary"
+              />
+            </td>
+          </tr>
+        }
+      </tbody>
+    </table>
+  `,
+})
+export class SparklineTableExampleComponent {
+  readonly regions: readonly Region[] = [
+    {
+      name: 'North',
+      total: '1,284',
+      trend: [120, 132, 128, 141, 150, 149, 162, 171],
+      summary: 'Rising',
+    },
+    {
+      name: 'Central',
+      total: '962',
+      trend: [131, 127, 119, null, 112, 118, 109, 104],
+      summary: 'Falling',
+    },
+    {
+      name: 'South',
+      total: '1,047',
+      trend: [128, 131, 126, 133, 129, 132, 130, 131],
+      summary: 'Steady',
+    },
+  ];
+}
+```
+
+## Desktop
+
+A sparkline is not interactive: no hover, no tooltip, no focus stop. Its size does not follow `provideBfDefaults()`. Inside `provideBfShell()` it renders the same.
+
+## Theming
+
+- Line: `--color-chart-1` (`stroke-chart-1`), 2 px; area the same at 16 % (`fill-chart-1/16`); the end dot `fill-chart-1`.
+- Motion: `--animate-chart-draw` and `--animate-chart-fade`; none under `prefers-reduced-motion`.
+
+## Accessibility
+
+With a `label` the SVG is a `role="img"` named by it: say what the trend means ("Revenue up 12% over 30 days"), not that it is a chart. Without one it is decorative and hidden from assistive technology, which is right beside a figure whose supporting text already states the trend. It has no focus stop and no data table; put the values in a table or a `bf-line-chart` when readers need them.
+
+## Inputs
+
+| Name     | Type                                    | Default    | Description                                                                                                    |
+| -------- | --------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------- |
+| `values` | `readonly (number \| null)[]`           | required   | The values in order, oldest first; `null` leaves a gap.                                                        |
+| `label`  | `string`                                | `''`       | What the trend means, its accessible name ("Revenue up 12% this month"); empty makes the sparkline decorative. |
+| `height` | `number`                                | `32`       | Height in px; the width follows the container.                                                                 |
+| `area`   | `boolean`                               | `false`    | Fills the area under the line.                                                                                 |
+| `curve`  | `BfChartCurve` (`'linear' \| 'smooth'`) | `'linear'` | The line between points: `linear` (default) or `smooth`, a monotone curve.                                     |
+
+## Notes
+
+### Do
+
+- State the trend in words next to it (the stat's supporting line, a `+12%`), so it is never colour or shape alone.
+- Use the same time window for every sparkline in a row.
+
+### Don't
+
+- Don't compare sparklines' heights: each one is scaled to its own range.
+- Don't put a tooltip or a link on a sparkline; link the stat or the row instead.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-sparkline` in `@bitforgehq/ui/charts`: a tiny line of one series with no axes, legend or
+tooltip, for a `bf-stat`'s supporting line or a table cell; `area`, `curve` and `height`, a dot on
+the latest value. With a `label` it is a named image, without one it is decorative.