@seekalfred/primitives 0.6.0 → 0.7.3

package/README.md

@@ -132,6 +132,34 @@ makes `description` **required** — React Aria associates the description
 for that role, so a confirmation built from a plain `Dialog` loses the
 sentence explaining what is about to happen.
 
+### Rich content: `body`
+
+`body` puts rich content between the description and the actions: a plan
+comparison, a before/after diff, a quoted reply, a field to fill in or a choice
+to make (a `RadioGroup`). It shares the description's edge and is in the
+dialog's tab order before the actions. `false`, `true` and `""` (as from
+`cond && <X />`) render no body.
+
+```tsx
+<AlertDialog
+  isOpen={open}
+  onOpenChange={setOpen}
+  title="Cancel subscription?"
+  description="You keep Pro until the end of the period, then move to Free."
+  body={<PlanSummary plan={plan} />}
+>
+  <AlertDialogCancel>Keep plan</AlertDialogCancel>
+  <AlertDialogAction onPress={cancel}>Cancel subscription</AlertDialogAction>
+</AlertDialog>
+```
+
+The body is not part of the accessible description: a screen reader announces
+only the `description` sentence with the title, and reads the body in place or
+as focus reaches its controls, each with its own label. So a field or a choice
+belongs in `body`, but the `description` must say everything needed to answer,
+including that something below is required ("Pick what happens to your
+recordings, then confirm.").
+
 ### Migrating from the legacy shadcn AlertDialog
 
 | legacy                     | Alfred                          |                                                     |
@@ -224,8 +252,8 @@ A new string label swaps as a whole and the pill's width springs to the new size
 ```tsx
 <Breadcrumbs>
   <BreadcrumbItem href="/">Home</BreadcrumbItem>
-  <BreadcrumbItem href="/design-thinking">Design Thinking</BreadcrumbItem>
-  <BreadcrumbItem>User Personas</BreadcrumbItem>
+  <BreadcrumbItem href="/design-thinking">Design thinking</BreadcrumbItem>
+  <BreadcrumbItem>User personas</BreadcrumbItem>
 </Breadcrumbs>
 ```
 
@@ -528,6 +556,28 @@ Padding is **block-only on the shell and inline-only on the sections**, which
 is what lets a divider or a full-bleed image run edge to edge. A single `p-6`
 on the shell would make that impossible.
 
+### Featured and flush cards
+
+```tsx
+<Card highlighted>…</Card>   {/* the one featured card in a view */}
+<Card flush>…</Card>         {/* a table, list or chart that meets the top and bottom */}
+```
+
+`highlighted` replaces the hairline with a brand gradient edge (secondary to
+tertiary, so it follows the theme) without changing the card's box. To repaint
+the edge, set the `--card-highlight` custom property on the card element itself
+(`className` or `style` on `Card`): the utility declares it on the card, so a
+value set on an ancestor does not reach it. Use it for one card per view and
+say in the content why it is featured: the edge is decoration. `flush` drops
+the shell's block padding and the gap between parts and clips the content to
+the rounded border, keeping the outline, radius, surface and shadow; a
+`className` padding still wins. The header and footer keep a 24px block
+inset, so their text clears the corner curve; the content stays block-flush.
+Every section keeps its inline padding, so text never sits in the corner, and
+a section's fill (`<CardContent className="bg-muted">`) still reaches the side
+edges because background paints the padding. Both default to `false`, and the two
+compose: a flush featured card keeps its gradient edge.
+
 ### Migrating from the legacy shadcn Card
 
 | legacy                   | Alfred                           |                                                                         |
@@ -682,6 +732,16 @@ What a list shows when it has nothing to show: one muted line, centred in a
 bordered box the width of the list. `action` is an optional next step under the
 text and is omitted from the DOM when absent.
 
+`image` is an optional illustration above the icon and the title (an `<img>`,
+an inline SVG or any element). It is centred, shrinks to fit a narrow box and
+keeps its aspect ratio; its size is the artwork's. The slot reserves no space,
+so set the artwork's intrinsic `width` and `height`, or the layout jumps when
+it loads. The slot does not hide it from assistive technology, so name it:
+give an `<img>` an `alt` (`alt=""` when the title already says it all), and an
+inline `<svg>` `role="img"` with an `aria-label`, or `aria-hidden="true"` when
+it is decorative. Omitted from the DOM when absent; `false` (from
+`cond && <img />`) counts as absent.
+
 ### Motion (EmptyState)
 
 New optional `icon` settles in once when the state first appears (small and transparent to rest over 480ms); a different icon component later swaps in place. A string message swaps as a whole when it changes and the message column follows its height on the smooth spring. The message now sits in an `empty-state-copy` frame.
@@ -1044,6 +1104,20 @@ default). Native input props apply to the input, and `className` goes to the
 input; `disabled` also disables the toggle, and `aria-invalid` gives the box its
 invalid border. The box shares the field look of `Input` and `Textarea`.
 
+`error` is `Input`'s prop: error text under the field, announced as an alert,
+that sets `aria-invalid` and is named in `aria-describedby`. `isRequired` makes
+the input `required` and shows a required marker (an asterisk, hidden from
+assistive technology, which hears the input's own `required`) after the label.
+
+```tsx
+<PasswordField
+  label="API secret"
+  isRequired
+  error={errors.secret?.message}
+  {...register("secret")}
+/>
+```
+
 **The toggle's name changes with its state and it is also `aria-pressed`**, so a
 screen reader may announce both ("Hide password, pressed"); this is not tested
 with a screen reader. Reduced motion drops every transition and the press.
@@ -1135,9 +1209,18 @@ and no number. `formatOptions` reaches it too, so a currency or "3 of 7" needs n
 second prop. `trackClassName` and `fillClassName` are escape hatches for a colour
 no tone covers.
 
+`isIndeterminate` draws a segment 40% of the track wide that sweeps across it
+from the start edge on a loop (right to left in RTL), and announces no value.
+With `labelHidden` and no `showValue` nothing is printed above the track, so the
+6px header gap collapses and the bar sits at the top of its box.
+
+`showCompletion={false}` keeps a bar from saying "done" at 100%: the fill keeps
+its tone and no check lands. Use it for a timer-driven estimate that can reach
+100% before the work finishes.
+
 ### Motion (Progress)
 
-The fill follows the value on the smooth spring (it was a 200ms ease) and the printed percentage counts to the new number on the same spring, so the number always matches the bar. When a default-toned bar completes it eases to the success colour (after 200ms) and a check lands beside the count; an explicit `tone` is never overridden, and a bar that is full at mount shows its check with no motion. A value that is not a percentage (a price) is shown as it is. A changed string label swaps as a whole.
+The fill follows the value on the smooth spring (it was a 200ms ease) and the printed percentage counts to the new number on the same spring, so the number always matches the bar. When a default-toned bar completes it eases to the success colour (after 200ms) and a check lands beside the count; an explicit `tone` is never overridden, `showCompletion={false}` turns both off, and a bar that is full at mount shows its check with no motion. An indeterminate segment sweeps the track every 1.6s; under reduced motion it does not travel, and the fill spans the track and pulses slowly instead. A value that is not a percentage (a price) is shown as it is. A changed string label swaps as a whole.
 
 ## RadioGroup
 
@@ -1148,6 +1231,32 @@ The fill follows the value on the smooth spring (it was a 200ms ease) and the pr
 </RadioGroup>
 ```
 
+### Card variant
+
+`variant="card"` draws each choice as a selectable card: the whole card is the
+target, the title is `children`, and each `Radio` can take a `description` and
+a decorative `icon`. The group becomes a grid, so the caller sets the columns.
+
+```tsx
+<RadioGroup variant="card" value={mode} onChange={setMode} aria-label="How to run" className="sm:grid-cols-2">
+  <Radio value="draft" icon={<DraftIcon />} description="Save as a draft and review it first.">
+    Draft only
+  </Radio>
+  <Radio value="everywhere" description="Apply to every category now.">
+    Run everywhere
+  </Radio>
+</RadioGroup>
+```
+
+- The title alone is the option's name; the description is wired as its
+  description (`aria-describedby`), so a screen reader does not run the two
+  together. The icon is `aria-hidden`.
+- Selected shows twice: a `primary-strong` edge (StatCard's selected pair) and
+  the same dot as the default radio, so it never rests on colour alone.
+- Keyboard is unchanged: one tab stop, arrow keys move and select. The focus
+  ring is drawn on the card, not the dot.
+- `description` and `icon` are ignored by the default variant.
+
 ### Migrating from the legacy RadioGroup
 
 | legacy                              | Alfred                    |                                        |
@@ -1192,6 +1301,8 @@ New opt-in `fade` (px, default `0` = off, so an area is unchanged) fades the con
 
 ```tsx
 <SearchField label="Search contacts" value={query} onValueChange={setQuery} />
+<SearchField label="Search tickets" labelHidden size="sm" placeholder="Search tickets"
+             value={query} onValueChange={setQuery} />
 ```
 
 A search input with a clear button. It is controlled: `value` and
@@ -1205,7 +1316,13 @@ animation, and while the button leaves it cannot be pressed or focused. The
 magnifier is muted at rest and takes full contrast while the field has focus or
 a value.
 
-`label` is required and visible; `clearLabel` renames the button (default "Clear
+`label` is required and visible unless `labelHidden` is set, which keeps it as
+the input's accessible name (`aria-label`) without printing it — for a toolbar
+search whose purpose the surrounding UI already shows. That holds inside a
+React Aria `TextField` too, including one with no `Label` child. `size` (`sm` · `md` ·
+`lg`, default `md`) takes the same `--density-control-*` height and padding as
+Input, Select and Button, and `sm` takes Input's 14px text (16px on a touch
+screen). `clearLabel` renames the button (default "Clear
 search"). Native input props apply to the input, `className` goes to the input,
 and `disabled` also disables the clear button. The browser's own clear button
 and search decoration are hidden. The box shares the field look of `Input`.
@@ -1270,17 +1387,26 @@ only — WCAG 1.4.1. The message is wired into `aria-describedby` for you.
 ```tsx
 <Separator />
 <Separator orientation="vertical" />
+<Separator orientation="vertical" decorative />
 ```
 
 React Aria renders an `<hr>` horizontally and a `<div role="separator">`
-vertically.
+vertically. The line is painted with `--color-separator`, the hairline between
+rows and groups inside a surface, not `--color-border`, which is the surface's
+own outline.
+
+`decorative` draws the same line as a plain `aria-hidden` div, for a rule that
+only spaces inline items (a metadata row) where announcing "separator" between
+each pair is noise. Leave it off for a line between two groups of content.
+Other props (`id`, `data-*`, handlers) reach the div in this mode too; a name
+(`aria-label`, `aria-labelledby`) is dropped.
 
 ### Migrating from the legacy Separator
 
 | legacy        | Alfred          |                                                              |
 | ------------- | --------------- | ------------------------------------------------------------ |
 | `orientation` | `orientation`   | unchanged                                                     |
-| `decorative`  | *no equivalent* | zero call sites; see below                                    |
+| `decorative`  | `decorative`    | default flipped to `false`; see below                         |
 
 **This changes the semantics of all six existing uses.** The legacy defaulted
 to `decorative: true`, rendering `role="none"` — so every divider in the app
@@ -1351,17 +1477,21 @@ The pulse dims a block to about half and back over 1.8s, 11 times (about 20 seco
 ## Slider
 
 ```tsx
-<Slider label="Input volume" defaultValue={40} />
+<Slider label="Volume" defaultValue={60} formatOptions={{ style: "unit", unit: "percent" }} />
+<Slider label="Budget" defaultValue={[2200, 8000]} minValue={0} maxValue={10000} step={100} description="Per month" />
+<Slider label="Volume" step={25} marks={[0, 25, 50, 75, 100].map((v) => ({ value: v, label: `${v}%` }))} start={<Button size="icon" aria-label="Mute">...</Button>} />
 ```
 
 **`label` is required** — all four legacy call sites are unnamed sliders.
 
+The look follows the design spec: a thin, rounded, light-grey track with a solid ink (`foreground`) fill, and a solid white thumb with a soft shadow. The label sits left and the value right. `value`/`defaultValue` may be a `[low, high]` pair, which gives two thumbs and a range readout ("$2,200 – $8,000"); `description` adds grey helper text; `marks` draws tick dots (a mark with a `label` prints it under the track); `start`/`end` hold content beside the track, such as an icon button.
+
 The thumb is 24×24 (WCAG 2.5.8); the legacy's was 16. `aria-valuetext` comes
 free, so a scrubber can announce a time instead of a raw second count.
 
 ### Motion (Slider)
 
-A value that arrives from outside a drag (a key, a prop, a click on the track) moves the thumb and the fill on the snappy spring; while dragging they stay under the pointer. The thumb swells to 1.16 while held. A bubble with the value rises in over the thumb (from small and blurred) while it is dragged or keyboard focused, and drops away in 120ms; the readout and the bubble roll their value up or down as it changes. The bubble is `aria-hidden`: the output beside the label carries the value. Reduced motion keeps opacity changes only. Not ported: marks, range, the springing catch-up on a click of the track (React Aria starts a drag at once), rubber-banding past the limits and release momentum.
+A value that arrives from outside a drag (a key, a prop, a click on the track) moves the thumb and the fill on the snappy spring; while dragging they stay under the pointer. The thumb swells to 1.16 while held. A bubble with the value rises in over the thumb (from small and blurred) while it is dragged or keyboard focused, and drops away in 120ms; the readout and the bubble roll their value up or down as it changes. The bubble is `aria-hidden`: the output beside the label carries the value. Reduced motion keeps opacity changes only. Not ported: clicking a mark label to move there, the springing catch-up on a click of the track (React Aria starts a drag at once), rubber-banding past the limits and release momentum.
 
 ## SplitButton
 
@@ -1422,8 +1552,9 @@ The thumb travels on a no-overshoot spring (559ms), stretches 5px toward its tra
 
 **The track colours are not the legacy's, and could not be.** A white thumb
 on `--color-primary` is 2.44:1 and on `--color-muted` is 1.13:1 — both fail
-WCAG 1.4.11. The track is `border` unchecked and `primary-strong` checked,
-which clears 3:1 in both themes.
+WCAG 1.4.11. The track is `control-edge` unchecked and `primary-strong`
+checked, which clears 3:1 in both themes. (`control-edge`, not the light
+page `border`, which is a decorative hairline.)
 
 ## Table
 
@@ -1526,9 +1657,10 @@ already agree on every value that matters:
 | cell padding | 16px / 12px | same |
 | typeface | Satoshi | same |
 
-The text colours were never a gap: the product's `--muted-foreground` is
-`#6B6B78` and its body ink is `#02021e`, which are this system's
-`--color-muted-foreground` and `--color-foreground` exactly. An earlier draft of
+The text colours were never a gap at the time: the product's
+`--muted-foreground` (`#6B6B78`) and body ink (`#02021e`) matched this
+system's `--color-muted-foreground` and `--color-foreground`. Since the 2026
+colour refresh these roles follow the design tokens (ink 600 and ink 900). An earlier draft of
 this section claimed otherwise and prescribed `#0f172b` / `#6b6b6b`; those come
 from `--table-text-*`, which the AI-visibility tables do not use. Do not apply
 them.
@@ -1591,8 +1723,8 @@ uncommitted form state, a running video or a scroll position will lose it
 on tab change — pass `shouldForceMount` on that `TabPanel`. With 31 legacy
 panels, some will need it.
 
-The selected tab carries a **border**, not just a fill: `bg-background` on
-a `bg-muted` list is 1.13:1, and WCAG 1.4.11 wants 3:1 for the thing
+The selected tab carries a **border**, not just a fill: a surface on a
+`bg-muted` list is barely distinguishable, and WCAG 1.4.11 wants 3:1 for the thing
 telling you which tab is active.
 
 ## ThemeSwitch
@@ -1629,6 +1761,28 @@ builds a `Time` at runtime, so the peer dependency is a real import here.
 (1, 5, 10, 15 or 30; a time between steps is added to the list so it is never lost),
 and `hourCycle` chooses 12 or 24 hour times.
 
+**In a form**: `id` goes on the trigger (so an outside `<label htmlFor>` or a form
+library reaches it), `name` submits the time as `"HH:MM"` in 24-hour time, as
+`<input type="time">` does, and `onBlur` fires when focus leaves the trigger.
+`isInvalid` paints the invalid border and `errorMessage` shows under the control
+while it is invalid, named in `aria-describedby`, as on `Select`. With
+react-hook-form, wire them from a `Controller`. Pass `field.value ?? null`, not
+`field.value`: `undefined` makes the picker uncontrolled, so a form reset to
+`undefined` would leave the last time on screen, while `null` clears it. With no
+time chosen, `name` submits an empty string.
+
+```tsx
+<Controller
+  name="syncTime"
+  control={control}
+  render={({ field, fieldState }) => (
+    <TimePicker label="Sync time" id={field.name} name={field.name}
+                value={field.value ?? null} onChange={field.onChange} onBlur={field.onBlur}
+                isInvalid={!!fieldState.error} errorMessage={fieldState.error?.message} />
+  )}
+/>
+```
+
 **Motion** (plain CSS and a little plain React, no animation library): the shown
 time rolls like a clock face (a later time rises in from below, an earlier one
 drops in from above, and the old one lifts away); the chevron turns half a turn on
@@ -1681,6 +1835,8 @@ A toast rises 16px from below and grows from .96 on the morph spring while it fa
 </TooltipTrigger>
 ```
 
+The bubble is solid ink with `background` text (so it inverts in dark mode), a large corner and comfortable padding; long text wraps at 15rem. It opens above its trigger with **no arrow**; `placement` and `showArrow` are opt-in.
+
 **`delay` defaults to 0**, matching the legacy provider. React Aria ships
 1500ms — taking that default would have put a 1.5-second warm-up on every
 tooltip in the app. Focus opens it immediately regardless.
@@ -1699,3 +1855,46 @@ inherits from the document. Set both if you support RTL.
 
 A tooltip rises 3px from its trigger and settles from .97 over 160ms (offset follows the side it opens on), and leaves in 120ms. While any tooltip is open, and for 300ms after the last one closes, the next one only fades in (no travel). The open delay stays 0. Reduced motion fades only. **DOM:** an empty hidden `span` inside the tooltip marks the warm case. Not ported: the crossfade and size spring when a string tooltip's text changes while open.
 
+
+## UsageMeter
+
+```tsx
+<UsageMeter label="Workspace storage" segments={segments} limit={10} unit="GB" />
+```
+
+The meter works its state out from the numbers: almost full from `warnAt` (a
+share of the limit, 0.9 by default), over once the total passes the limit.
+
+### A status from the backend
+
+When the product decides the state, pass `status` and the meter shows that
+instead of its own reading (badge, `data-status`, the bar's name and the
+announcement). The bar and legend agree with it:
+
+- `full` and `exhausted` under the limit mean the allowance is used up, so
+  there is no free share: the bar spans what is used and the free item reads 0.
+  The headline still states the plan size ("7.7 GB of 10 GB used").
+- Past the limit, `ok` and `warn` give way to the meter's own over state, since
+  the hatch already shows the overage. `full` and `exhausted` keep their words.
+
+| `status`    | meaning                     | badge           | `data-status` |
+| ----------- | --------------------------- | --------------- | ------------- |
+| `ok`        | under the limit             | "N free"        | `ok`          |
+| `warn`      | almost full                 | "Almost full"   | `near`        |
+| `full`      | allowance used up           | "Limit reached" | `full`        |
+| `exhausted` | nothing left to draw on     | "None left"     | `exhausted`   |
+
+`statusLabel` is the product's own words for the status ("Credits paused"). It
+replaces the badge's words in every mode (including "Unlimited"), the status in
+the bar's name and the announcement; the tone and icon still follow the status.
+
+### Unlimited
+
+`unlimited` is a plan with no limit. The badge reads "Unlimited" (unless
+`statusLabel` is set), the bar shows
+each category's share of what is used, and there is no free share, limit marker
+or overflow hatch. `limit`, `warnAt` and `status` are ignored.
+
+```tsx
+<UsageMeter label="Keyword slots" segments={segments} limit={0} unlimited />
+```

package/dist/activity-heatmap/activity-heatmap.d.ts

@@ -0,0 +1,92 @@
+import { ReactNode } from "react";
+//#region src/activity-heatmap/activity-heatmap.d.ts
+/**
+ * ActivityHeatmap: one square per day, weeks as columns, four tints of the
+ * primary chart colour for how busy a day was. Use it when rhythm, streaks and
+ * quiet weeks matter more than exact comparisons; use a bar chart when the
+ * exact comparison is the point.
+ *
+ * The squares wave in once, diagonally, when the grid is seen. A tooltip
+ * glides between squares on hover or keyboard focus and its words rise in. A
+ * new range recolours the grid in a sweep instead of redrawing it, and the
+ * total rolls to its new number. The legend's squares preview a level on the
+ * grid (the others step back) and pin it on press.
+ *
+ * It sits in a card (`framed`, on by default). A year switch (`periods`) sits
+ * beside the total, and a detail line under the legend says what the hovered,
+ * focused or selected day holds (`describeDay`).
+ *
+ * The grid is a `grid` of `gridcell`s with one tab stop: arrow keys move by
+ * day (up and down) and by week (left and right), Home and End jump to the
+ * ends, Enter selects. A visually hidden table carries every day.
+ */
+export interface ActivityDay {
+  /** Calendar day as YYYY-MM-DD. */
+  date: string;
+  count: number;
+}
+/** What `describeDay` is given for one day. */
+export interface ActivityDayDetail {
+  /** The day as YYYY-MM-DD. */
+  date: string;
+  count: number;
+  /** The day spelled out, such as "Tuesday, March 18". The year is added when the range spans more than one. */
+  label: string;
+  /** The nouns for the count, as passed in `unit`. */
+  unit: {
+    one: string;
+    other: string;
+  };
+}
+export interface ActivityHeatmapProps {
+  /** One entry per day, oldest first. Days missing inside the range count as zero. */
+  days: ActivityDay[];
+  /** Accessible name for the grid, such as "Contributions in 2025". */
+  label: string;
+  /** Finishes the summary line: "1,284 contributions in {period}". */
+  period: string;
+  /** Nouns for the count. @default { one: "contribution", other: "contributions" } */
+  unit?: {
+    one: string;
+    other: string;
+  };
+  /** Upper bounds for levels one to three; anything above the last is level four. Defaults to quarters of the busiest day. */
+  thresholds?: [number, number, number];
+  /** @default 0 (Sunday) */
+  weekStartsOn?: 0 | 1;
+  /** Controlled selected day, as YYYY-MM-DD. */
+  selectedDate?: string | null;
+  defaultSelectedDate?: string | null;
+  /** Called with the day's YYYY-MM-DD when a day is pressed or chosen with Enter. */
+  onSelectDate?: (date: string) => void;
+  /** Controls beside the summary. */
+  actions?: ReactNode;
+  /**
+   * The ranges to switch between, such as ["2025", "2024", "2023"], shown as a segmented switch beside the summary with the one
+   * equal to `period` selected. You own the data: when `onPeriodChange` fires, pass the new `days`, `period` and `label`.
+   */
+  periods?: string[];
+  /** Called with the chosen entry of `periods`. */
+  onPeriodChange?: (period: string) => void;
+  /** Accessible name for the switch. @default "Period" */
+  periodsLabel?: string;
+  /**
+   * The sentence under the legend about the hovered, focused or selected day. Return the whole sentence, so it can carry data
+   * the heatmap does not hold. Pass `null` to remove the line. The default is date and count only:
+   * "Tuesday, March 18: 4 contributions."
+   */
+  describeDay?: ((day: ActivityDayDetail) => string) | null;
+  /** The detail line when no day is hovered, focused or selected. @default "Hover or select a day for details." */
+  detailHint?: string;
+  /** Draws the card around it: border, panel radius, surface and padding. Turn it off to place the heatmap inside a card of your own. @default true */
+  framed?: boolean;
+  /** Shown instead of the grid when there are no days. @default "No activity yet" */
+  emptyLabel?: string;
+  /** Formatting locale. Fixed by default so server and client render the same labels. @default "en-US" */
+  locale?: string;
+  /** Extra classes for the root. Merged last. */
+  className?: string;
+}
+export declare const ActivityHeatmap: import("react").ForwardRefExoticComponent<ActivityHeatmapProps & import("react").RefAttributes<HTMLDivElement>>;
+//#endregion
+//# sourceMappingURL=activity-heatmap.d.ts.map