@tailor-platform/app-shell 1.15.0 → 1.17.0

package/skills/app-shell-patterns/references/components/tabs.md

@@ -0,0 +1,158 @@
+---
+title: Tabs
+description: Tab navigation with a compound component API
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/tabs.docs.outline.md — do not edit by hand. -->
+
+# Tabs
+
+The `Tabs` component provides tab-based navigation for toggling between related panels on the same page. It is backed by Base UI's Tabs primitive.
+
+## Import
+
+```tsx
+import { Tabs } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+function BasicUsage() {
+  return (
+    <Tabs.Root defaultValue="overview">
+      <Tabs.List>
+        <Tabs.Tab value="overview">Overview</Tabs.Tab>
+        <Tabs.Tab value="projects">Projects</Tabs.Tab>
+        <Tabs.Tab value="account">Account</Tabs.Tab>
+      </Tabs.List>
+      <Tabs.Panel value="overview">Overview content</Tabs.Panel>
+      <Tabs.Panel value="projects">Projects content</Tabs.Panel>
+      <Tabs.Panel value="account">Account content</Tabs.Panel>
+    </Tabs.Root>
+  );
+}
+```
+
+## Sub-components
+
+| Sub-component | Description                                                    |
+| ------------- | -------------------------------------------------------------- |
+| `Tabs.Root`   | Manages tab selection state                                    |
+| `Tabs.List`   | Groups the individual tab buttons                              |
+| `Tabs.Tab`    | An interactive tab button that toggles the corresponding panel |
+| `Tabs.Panel`  | A panel displayed when the corresponding tab is active         |
+
+## Props
+
+### Tabs.Root Props
+
+| Prop            | Type                                | Default     | Description                                                   |
+| --------------- | ----------------------------------- | ----------- | ------------------------------------------------------------- |
+| `defaultValue`  | `Tabs.Tab.Value`                    | `0`         | Initial active tab value (uncontrolled)                       |
+| `value`         | `Tabs.Tab.Value`                    | -           | Controlled active tab value                                   |
+| `onValueChange` | `(value: any) => void`              | -           | Callback when the active tab changes                          |
+| `variant`       | `'default' \| 'line' \| 'capsule'`  | `'default'` | Visual style of the tabs                                      |
+| `size`          | `'xs' \| 'sm' \| 'default' \| 'lg'` | `'default'` | Minimum size (`capsule` only) — mirrors Button's height tiers |
+| `className`     | `string`                            | -           | Additional CSS classes for root                               |
+| `children`      | `React.ReactNode`                   | -           | Tabs sub-components                                           |
+
+### Tabs.List Props
+
+Accepts `className` and all standard HTML `<div>` props.
+
+### Tabs.Tab Props
+
+| Prop       | Type             | Default | Description                        |
+| ---------- | ---------------- | ------- | ---------------------------------- |
+| `value`    | `Tabs.Tab.Value` | -       | **Required.** The value of the tab |
+| `disabled` | `boolean`        | -       | Whether the tab is disabled        |
+
+Also accepts `className` and all standard HTML `<button>` props.
+
+### Tabs.Panel Props
+
+| Prop          | Type             | Default | Description                                            |
+| ------------- | ---------------- | ------- | ------------------------------------------------------ |
+| `value`       | `Tabs.Tab.Value` | -       | **Required.** The value matching the corresponding tab |
+| `keepMounted` | `boolean`        | `false` | Whether to keep the panel in the DOM when hidden       |
+
+Also accepts `className` and all standard HTML `<div>` props.
+
+## Controlled Usage
+
+```tsx
+const [activeTab, setActiveTab] = useState("overview");
+
+<Tabs.Root value={activeTab} onValueChange={setActiveTab}>
+  <Tabs.List>
+    <Tabs.Tab value="overview">Overview</Tabs.Tab>
+    <Tabs.Tab value="details">Details</Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panel value="overview">Overview content</Tabs.Panel>
+  <Tabs.Panel value="details">Details content</Tabs.Panel>
+</Tabs.Root>;
+```
+
+## Examples
+
+### With Disabled Tab
+
+```tsx
+<Tabs.Root defaultValue="active">
+  <Tabs.List>
+    <Tabs.Tab value="active">Active</Tabs.Tab>
+    <Tabs.Tab value="pending">Pending</Tabs.Tab>
+    <Tabs.Tab value="archived" disabled>
+      Archived
+    </Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panel value="active">Active items</Tabs.Panel>
+  <Tabs.Panel value="pending">Pending items</Tabs.Panel>
+  <Tabs.Panel value="archived">Archived items</Tabs.Panel>
+</Tabs.Root>
+```
+
+### Use Icons in Tab
+
+In the `capsule` variant, a tab whose only child is an icon renders **square** —
+its `min-width` matches its `min-height` — making it a natural fit for icon-only
+view toggles (e.g. table/kanban). Use `size` to align the track with a sibling
+`Button`: `size="default"` (36px) matches `Button`'s default height. Unsized
+icons default to `16px`, so the square is consistent regardless of the icon.
+
+> **Accessibility:** an icon-only tab has no visible text, so give each one an
+> `aria-label`. Without it, screen readers announce an unnamed tab.
+
+```tsx
+<Tabs.Root defaultValue="overview" variant="capsule" size="default">
+  <Tabs.List>
+    <Tabs.Tab value="overview" aria-label="Overview">
+      <LayoutDashboardIcon />
+    </Tabs.Tab>
+    <Tabs.Tab value="projects" aria-label="Projects">
+      <FolderKanbanIcon />
+    </Tabs.Tab>
+    <Tabs.Tab value="settings" aria-label="Settings">
+      <SettingsIcon />
+    </Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panel value="overview">Overview content</Tabs.Panel>
+  <Tabs.Panel value="projects">Projects content</Tabs.Panel>
+  <Tabs.Panel value="settings">Settings content</Tabs.Panel>
+</Tabs.Root>
+```
+
+### Sizing the capsule variant
+
+`size` mirrors `Button`'s height tiers, so a capsule can sit flush next to a
+button. The value sets a **minimum** height — taller content still grows.
+
+| `size`    | Track height | Matches Button |
+| --------- | ------------ | -------------- |
+| `xs`      | 28px         | `size="xs"`    |
+| `sm`      | 32px         | `size="sm"`    |
+| `default` | 36px         | default        |
+| `lg`      | 40px         | `size="lg"`    |

package/skills/app-shell-patterns/references/components/textarea.md

@@ -0,0 +1,122 @@
+---
+title: Textarea
+description: Styled multi-line text input sized by rows, with automatic Field / React Hook Form integration
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/textarea.docs.outline.md — do not edit by hand. -->
+
+# Textarea
+
+The `Textarea` component is a styled multi-line text input. It wraps Base UI's field control rendered as a `<textarea>`, so it works with [`Field`](./form.md) and React Hook Form the same way `Input`, `Checkbox`, and `Select` do — dropped inside a `Field.Root` it inherits label association, `aria-describedby`, `disabled`, and the invalid (error) state automatically.
+
+Unlike `Input`, it has no fixed height: `rows` sets the visible line count (floored at `min-h-16`) and the user can drag the box taller, so long text stays readable instead of scrolling inside a single-line window.
+
+## Import
+
+```tsx
+import { Textarea } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+<example-preview name="basic-usage"></example-preview>
+
+```tsx
+function BasicUsage() {
+  return <Textarea placeholder="Add a note…" />;
+}
+```
+
+## Props
+
+Accepts Base UI's field-control props plus the standard HTML `<textarea>` props, minus `cols` and `wrap` — the control is always `w-full`, so `cols` could never affect its width, and every `wrap` value depends on `cols` being set. The most common:
+
+| Prop            | Type                                    | Default | Description                                             |
+| --------------- | --------------------------------------- | ------- | ------------------------------------------------------- |
+| `value`         | `string`                                | -       | Controlled value.                                       |
+| `defaultValue`  | `string`                                | -       | Initial value when uncontrolled.                        |
+| `onChange`      | `(event) => void`                       | -       | Native change handler.                                  |
+| `onValueChange` | `(value: string, eventDetails) => void` | -       | Called with the next string value.                      |
+| `rows`          | `number`                                | -       | Visible line count — the height knob.                   |
+| `placeholder`   | `string`                                | -       | Placeholder text.                                       |
+| `disabled`      | `boolean`                               | `false` | Disables the control.                                   |
+| `required`      | `boolean`                               | `false` | Marks the control required for native/Field validation. |
+| `readOnly`      | `boolean`                               | `false` | Renders the value without allowing edits.               |
+| `name`          | `string`                                | -       | Field name for native form submission.                  |
+| `className`     | `string`                                | -       | Additional CSS classes.                                 |
+
+## Examples
+
+### Controlled
+
+```tsx
+const [note, setNote] = useState("");
+
+<Textarea value={note} onChange={(e) => setNote(e.target.value)} placeholder="Add a note…" />;
+```
+
+### Height
+
+`rows` sets the visible line count, and the user can drag the box taller for a long value.
+
+`min-h-16` (64px) is a hard floor, so `rows={1}` and `rows={2}` both render at 64px — `rows` only starts moving the height from 3 up. There is no supported way to go below the floor.
+
+```tsx
+<Textarea rows={8} placeholder="Paste the incident log…" />
+```
+
+> The box does not auto-grow as you type. `field-sizing: content` would do that, but the browser then ignores `rows` — leaving height settable only through a `min-h-*` utility. Use `rows` instead.
+
+### Disabled
+
+```tsx
+<Textarea value="Read-only value" disabled />
+```
+
+## Use With Field
+
+Placed inside a `Field.Root`, `Textarea` picks up the field's label, description, and invalid/disabled state automatically — no `error` prop of its own.
+
+```tsx
+<Field.Root name="description">
+  <Field.Label>Description</Field.Label>
+  <Textarea placeholder="What changed?" />
+  <Field.Description>Optional — visible to the whole team.</Field.Description>
+</Field.Root>
+```
+
+## React Hook Form
+
+Drive it with a `Controller`. Spreading `field` wires `value`/`onChange`/`onBlur`, and spreading `fieldState` onto `Field.Root` wires the error/invalid state.
+
+```tsx
+import { useForm, Controller } from "react-hook-form";
+import { Field, Textarea } from "@tailor-platform/app-shell";
+
+const { control } = useForm({ defaultValues: { description: "" } });
+
+<Controller
+  name="description"
+  control={control}
+  rules={{ required: "Description is required." }}
+  render={({ field, fieldState }) => (
+    <Field.Root name={field.name} {...fieldState}>
+      <Field.Label>Description</Field.Label>
+      <Textarea {...field} />
+      <Field.Error match={fieldState.invalid}>{fieldState.error?.message}</Field.Error>
+    </Field.Root>
+  )}
+/>;
+```
+
+## TypeScript
+
+```typescript
+import { type TextareaProps } from "@tailor-platform/app-shell";
+```
+
+## Related Components
+
+- [Input](./input.md) - Single-line text input with the same styling and `Field` integration
+- [Form](./form.md) - Form root and `Field` composition
+- [Button](./button.md) - Pair with a textarea in a composer action row

package/skills/app-shell-patterns/references/components/timeline.md

@@ -0,0 +1,317 @@
+---
+title: Timeline
+description: Composable primitives for building time-based layouts with axis guides, row backgrounds, intervals, and dependency links
+---
+
+<!-- GENERATED by docs-kit from docs-src/components/timeline.docs.outline.md — do not edit by hand. -->
+
+# Timeline
+
+`Timeline` provides composable primitives for building time-based layouts such as Gantt charts, schedules, and project timelines. It is a compound component with five sub-components: `Root`, `Viewport`, `Row`, `Interval`, and `Link`.
+
+## Import
+
+```tsx
+import { Timeline } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+```tsx
+import { Timeline } from "@tailor-platform/app-shell";
+
+<Timeline.Root start={0} end={100}>
+  <Timeline.Viewport
+    axis={{
+      guides: [{ at: 0 }, { at: 50 }, { at: 100 }],
+      levels: [
+        {
+          kind: "spans",
+          items: [
+            { start: 0, end: 50, label: "Phase 1" },
+            { start: 50, end: 100, label: "Phase 2" },
+          ],
+        },
+      ],
+    }}
+  >
+    <Timeline.Row height={40}>
+      <Timeline.Interval start={10} end={35}>
+        <div className="h-full rounded-md bg-primary" />
+      </Timeline.Interval>
+    </Timeline.Row>
+  </Timeline.Viewport>
+</Timeline.Root>;
+```
+
+## Sub-components
+
+| Sub-component       | Description                                                                    |
+| ------------------- | ------------------------------------------------------------------------------ |
+| `Timeline.Root`     | Provides the shared time range for all nested timeline primitives              |
+| `Timeline.Viewport` | Renders the axis, decorations, scrolling area, and link overlay layer          |
+| `Timeline.Row`      | Defines one horizontal lane with a fixed height and optional background        |
+| `Timeline.Interval` | Positions content across a time range inside a row                             |
+| `Timeline.Link`     | Draws an orthogonal dependency connector between two named `Interval` elements |
+
+## TimeValue
+
+All time position props (`start`, `end`, `at`) accept either a `Date` object or a millisecond-precision number timestamp.
+
+```tsx
+// Using Date objects
+<Timeline.Root start={new Date("2024-01-01")} end={new Date("2024-12-31")}>
+
+// Using numeric timestamps
+<Timeline.Root start={0} end={100}>
+```
+
+## Props
+
+### Timeline.Root Props
+
+| Prop        | Type              | Default | Description                                        |
+| ----------- | ----------------- | ------- | -------------------------------------------------- |
+| `start`     | `Date \| number`  | —       | Inclusive start of the overall timeline range      |
+| `end`       | `Date \| number`  | —       | Inclusive end of the overall timeline range        |
+| `children`  | `React.ReactNode` | —       | Timeline subtree, usually a `Timeline.Viewport`    |
+| `className` | `string`          | —       | Additional CSS classes applied to the root element |
+| `style`     | `CSSProperties`   | —       | Inline style applied to the root element           |
+
+### Timeline.Viewport Props
+
+| Prop           | Type                   | Default | Description                                                           |
+| -------------- | ---------------------- | ------- | --------------------------------------------------------------------- |
+| `children`     | `React.ReactNode`      | —       | Rows and links, in any order                                          |
+| `axis`         | `TimelineAxis`         | —       | Axis configuration: guides and stacked header levels                  |
+| `decorations`  | `TimelineDecorations`  | —       | Decorative layers: bands and markers                                  |
+| `linkDefaults` | `TimelineLinkDefaults` | —       | Shared defaults applied to all `Timeline.Link` nodes in this viewport |
+| `canvasWidth`  | `number`               | —       | Fixed canvas width in pixels for horizontally scrollable timelines    |
+| `stickyAxis`   | `boolean`              | `false` | Pins the axis to the top of the viewport during vertical scrolling    |
+| `className`    | `string`               | —       | Additional CSS classes applied to the scroll viewport                 |
+| `style`        | `CSSProperties`        | —       | Inline style applied to the scroll viewport                           |
+
+### Timeline.Row Props
+
+| Prop         | Type                            | Default | Description                                                                                 |
+| ------------ | ------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
+| `children`   | `React.ReactNode`               | —       | Row contents, typically `Timeline.Interval` elements                                        |
+| `height`     | `number`                        | `32`    | Row height in pixels                                                                        |
+| `background` | `TimelineRowBackground \| null` | —       | Optional background rendered in a dedicated layer, in front of bands but behind guide lines |
+| `className`  | `string`                        | —       | Additional CSS classes applied to the row content container                                 |
+| `style`      | `CSSProperties`                 | —       | Inline style applied to the row content container                                           |
+
+### Timeline.Interval Props
+
+| Prop        | Type              | Default | Description                                                         |
+| ----------- | ----------------- | ------- | ------------------------------------------------------------------- |
+| `start`     | `Date \| number`  | —       | Start of the interval                                               |
+| `end`       | `Date \| number`  | —       | End of the interval                                                 |
+| `children`  | `React.ReactNode` | —       | Rendered content for the interval                                   |
+| `id`        | `string`          | —       | Stable id used by `Timeline.Link` to reference this interval        |
+| `insetY`    | `number`          | `0`     | Top and bottom inset in pixels within the row                       |
+| `className` | `string`          | —       | Additional CSS classes applied to the positioned interval container |
+| `style`     | `CSSProperties`   | —       | Inline style applied to the positioned interval container           |
+
+### Timeline.Link Props
+
+| Prop          | Type                           | Default   | Description                                       |
+| ------------- | ------------------------------ | --------- | ------------------------------------------------- |
+| `from`        | `string`                       | —         | Source `Timeline.Interval` id                     |
+| `to`          | `string`                       | —         | Target `Timeline.Interval` id                     |
+| `fromAnchor`  | `"start" \| "center" \| "end"` | `"end"`   | Source anchor used for routing                    |
+| `toAnchor`    | `"start" \| "center" \| "end"` | `"start"` | Target anchor used for routing                    |
+| `arrow`       | `boolean`                      | —         | Overrides the viewport-level `linkDefaults.arrow` |
+| `gap`         | `number`                       | —         | Overrides the viewport-level `linkDefaults.gap`   |
+| `strokeWidth` | `number`                       | —         | Optional stroke width for the link path           |
+| `className`   | `string`                       | —         | Additional CSS classes applied to the link SVG    |
+| `style`       | `CSSProperties`                | —         | Inline style applied to the link SVG              |
+
+## Type Reference
+
+### TimelineAxis
+
+Axis configuration for `Timeline.Viewport`.
+
+| Field       | Type                  | Description                                           |
+| ----------- | --------------------- | ----------------------------------------------------- |
+| `guides`    | `TimelineGuide[]`     | Vertical boundary lines rendered in the axis and body |
+| `levels`    | `TimelineAxisLevel[]` | Stacked header levels rendered above the body         |
+| `className` | `string`              | Optional class applied to the axis container          |
+
+### TimelineAxisLevel
+
+A stacked axis level. Has a discriminated union `kind` field:
+
+- `kind: "spans"` — renders labeled time ranges (`TimelineAxisSpan[]`)
+- `kind: "ticks"` — renders labeled point-in-time markers (`TimelineAxisTick[]`)
+
+| Field       | Type                                       | Default | Description                                   |
+| ----------- | ------------------------------------------ | ------- | --------------------------------------------- |
+| `kind`      | `"spans" \| "ticks"`                       | —       | Level rendering mode                          |
+| `items`     | `TimelineAxisSpan[] \| TimelineAxisTick[]` | —       | Items to render in this level                 |
+| `height`    | `number`                                   | `28`    | Height of this axis level in pixels           |
+| `className` | `string`                                   | —       | Optional class applied to the level container |
+
+### TimelineGuide
+
+A vertical guide line rendered in both the axis and the body.
+
+| Field           | Type             | Description                                      |
+| --------------- | ---------------- | ------------------------------------------------ |
+| `at`            | `Date \| number` | Time position for the guide line                 |
+| `key`           | `React.Key`      | Optional stable React key                        |
+| `axisClassName` | `string`         | Optional class for the axis portion of the guide |
+| `axisStyle`     | `CSSProperties`  | Optional style for the axis portion of the guide |
+| `bodyClassName` | `string`         | Optional class for the body portion of the guide |
+| `bodyStyle`     | `CSSProperties`  | Optional style for the body portion of the guide |
+
+### TimelineDecorations
+
+Decorative layers rendered by `Timeline.Viewport`.
+
+| Field     | Type               | Description                                       |
+| --------- | ------------------ | ------------------------------------------------- |
+| `bands`   | `TimelineBand[]`   | Background range highlights rendered behind rows  |
+| `markers` | `TimelineMarker[]` | Vertical markers rendered in the axis and/or body |
+
+### TimelineBand
+
+A decorative horizontal band rendered behind rows.
+
+| Field       | Type             | Description                                |
+| ----------- | ---------------- | ------------------------------------------ |
+| `start`     | `Date \| number` | Start of the band                          |
+| `end`       | `Date \| number` | End of the band                            |
+| `key`       | `React.Key`      | Optional stable React key                  |
+| `color`     | `string`         | Optional background color convenience prop |
+| `className` | `string`         | Optional class applied to the band element |
+| `style`     | `CSSProperties`  | Optional inline style applied to the band  |
+
+### TimelineMarker
+
+A decorative vertical marker line.
+
+| Field            | Type                         | Default  | Description                                        |
+| ---------------- | ---------------------------- | -------- | -------------------------------------------------- |
+| `at`             | `Date \| number`             | —        | Time position for the marker                       |
+| `key`            | `React.Key`                  | —        | Optional stable React key                          |
+| `color`          | `string`                     | —        | Optional line color convenience prop               |
+| `label`          | `React.ReactNode`            | —        | Optional marker label                              |
+| `placement`      | `"axis" \| "body" \| "both"` | `"body"` | Controls where the marker is rendered              |
+| `className`      | `string`                     | —        | Optional class applied to the outer marker wrapper |
+| `lineClassName`  | `string`                     | —        | Optional class applied to the marker line          |
+| `labelClassName` | `string`                     | —        | Optional class applied to the marker label         |
+
+### TimelineLinkDefaults
+
+Shared defaults for all `Timeline.Link` nodes inside one viewport.
+
+| Field         | Type            | Default        | Description                                              |
+| ------------- | --------------- | -------------- | -------------------------------------------------------- |
+| `routing`     | `"orthogonal"`  | `"orthogonal"` | Link routing strategy                                    |
+| `arrow`       | `boolean`       | `true`         | Whether links end with an arrow marker                   |
+| `gap`         | `number`        | `16`           | Horizontal gap in px used when routing out of/into items |
+| `strokeWidth` | `number`        | —              | Optional default stroke width for link paths             |
+| `className`   | `string`        | —              | Optional class applied to each link SVG                  |
+| `style`       | `CSSProperties` | —              | Optional style applied to each link SVG                  |
+
+### TimelineRowBackground
+
+Background content for a row rendered in a dedicated layer (in front of bands, behind guides).
+
+| Field       | Type            | Description                                            |
+| ----------- | --------------- | ------------------------------------------------------ |
+| `className` | `string`        | Optional class applied to the background layer element |
+| `style`     | `CSSProperties` | Optional style applied to the background layer element |
+
+## Examples
+
+### Horizontal Scrolling
+
+Use `canvasWidth` on `Timeline.Viewport` to enable horizontal scrolling:
+
+```tsx
+<Timeline.Root start={projectStart} end={projectEnd}>
+  <Timeline.Viewport canvasWidth={2400} axis={axis}>
+    {rows}
+  </Timeline.Viewport>
+</Timeline.Root>
+```
+
+### Sticky Axis
+
+Pin the axis to the top during vertical scrolling with `stickyAxis`:
+
+```tsx
+<Timeline.Root start={0} end={100}>
+  <Timeline.Viewport stickyAxis axis={axis}>
+    {rows}
+  </Timeline.Viewport>
+</Timeline.Root>
+```
+
+### Dependency Links
+
+Use `id` on `Timeline.Interval` and `Timeline.Link` to draw dependency connectors:
+
+```tsx
+<Timeline.Root start={0} end={100}>
+  <Timeline.Viewport
+    linkDefaults={{ style: { color: "var(--muted-foreground)" }, strokeWidth: 1.5 }}
+  >
+    <Timeline.Row height={40}>
+      <Timeline.Interval id="task-a" start={10} end={40}>
+        <div className="h-full rounded-md bg-primary" />
+      </Timeline.Interval>
+    </Timeline.Row>
+    <Timeline.Row height={40}>
+      <Timeline.Interval id="task-b" start={50} end={80}>
+        <div className="h-full rounded-md bg-secondary" />
+      </Timeline.Interval>
+    </Timeline.Row>
+    <Timeline.Link from="task-a" to="task-b" />
+  </Timeline.Viewport>
+</Timeline.Root>
+```
+
+### Background Bands and Markers
+
+Use `decorations` to add background highlights and vertical marker lines:
+
+```tsx
+<Timeline.Viewport
+  axis={axis}
+  decorations={{
+    bands: [
+      {
+        start: freezeStart,
+        end: freezeEnd,
+        color: "var(--destructive/10)",
+        className: "border-x border-destructive/30",
+      },
+    ],
+    markers: [
+      {
+        at: today,
+        color: "var(--primary)",
+        label: <span className="text-xs text-primary">Today</span>,
+      },
+    ],
+  }}
+>
+  {rows}
+</Timeline.Viewport>
+```
+
+### Row Background
+
+Use `background` on `Timeline.Row` to apply a background that respects guide lines:
+
+```tsx
+<Timeline.Row height={40} background={{ style: { background: "var(--muted)" } }}>
+  <Timeline.Interval start={10} end={35}>
+    <div className="h-full rounded-md bg-primary" />
+  </Timeline.Interval>
+</Timeline.Row>
+```