# Marker

A status line, system note, bordered row or labelled divider inside a conversation.

```tsx
import { Marker, MarkerContent, MarkerIcon } from "@/components/ui/marker"
import { Spinner } from "@/components/ui/spinner"
import { VStack } from "@/components/ui/stack"
import { shimmerStyles } from "@/lib/shimmer"
import { widths } from "@/theme/widths"
import { GitBranchIcon } from "@phosphor-icons/react/dist/csr/GitBranch"
import { MagnifyingGlassIcon } from "@phosphor-icons/react/dist/csr/MagnifyingGlass"

export default function MarkerDemo() {
  return (
    <VStack gap={8} xstyle={widths.sm}>
      <Marker>
        <MarkerIcon>
          <GitBranchIcon />
        </MarkerIcon>
        <MarkerContent>Created branch fix/leap-years</MarkerContent>
      </Marker>
      <Marker role="status">
        <MarkerIcon>
          <Spinner />
        </MarkerIcon>
        <MarkerContent xstyle={shimmerStyles.base}>Thinking…</MarkerContent>
      </Marker>
      <Marker variant="separator">
        <MarkerContent>Earlier messages summarised</MarkerContent>
      </Marker>
      <Marker>
        <MarkerIcon>
          <MagnifyingGlassIcon />
        </MarkerIcon>
        <MarkerContent>Searched 3 files</MarkerContent>
      </Marker>
    </VStack>
  )
}
```

## Installation

**Command**

```bash
npx shadcn@latest add @arene/marker
```

Needs the [arene setup](https://www.arene.style/docs/installation) first. Also adds [Separator](https://www.arene.style/docs/components/separator).

**Manual**

1. Install the packages it imports:

   ```bash
   npm install @base-ui/react @stylexjs/stylex clsx
   ```

2. Set up the token layer and the StyleX compiler, if you have not already. See
   [Installation](https://www.arene.style/docs/installation). The marker also needs `interop.css`, which
   sizes the icons inside it and styles links inside its content.

3. Install [Separator](https://www.arene.style/docs/components/separator), whose styles draw the lines of
   the `separator` variant.

4. Paste this source into the file named in its title.

   ```tsx title="components/ui/marker.tsx"
   "use client"

   import { useRender } from "@base-ui/react/use-render"
   import * as stylex from "@stylexjs/stylex"
   import type { StyleXStyles } from "@stylexjs/stylex"
   import { clsx } from "clsx"

   import { separatorStyles } from "@/components/ui/separator"
   import { states } from "@/theme/states"
   import { color, duration, ease, leading, radius, space, text } from "@/theme/tokens.stylex"

   const styles = stylex.create({
     root: {
       position: "relative",
       display: "flex",
       alignItems: "center",
       gap: space.s2,
       width: "100%",
       minHeight: space.s4,
       borderRadius: radius.md,
       color: { default: color.mutedForeground, ":is(a, button):hover": color.foreground },
       fontSize: text.sm,
       lineHeight: leading.sm,
       textAlign: "start",
       textDecorationLine: { default: null, ":is(a)": "underline" },
       textUnderlineOffset: 3,
       cursor: { default: null, ":is(a, button)": "pointer" },
       transitionProperty: "color",
       transitionDuration: duration.color,
       transitionTimingFunction: ease.standard,
       "--arene-icon-size": space.s4,
     },
     icon: {
       display: "flex",
       flexShrink: 0,
       alignItems: "center",
       justifyContent: "center",
       width: `var(--arene-icon-size, ${space.s4})`,
       height: `var(--arene-icon-size, ${space.s4})`,
     },
     content: { minWidth: 0, overflowWrap: "break-word" },
     rule: { flexGrow: 1, flexBasis: 0, minWidth: 0 },
     ruleStart: { marginInlineEnd: space.s1 },
     ruleEnd: { marginInlineStart: space.s1 },
   })

   const variants = stylex.create({
     default: {},
     separator: { textAlign: "center" },
     border: {
       paddingBlockEnd: space.s2,
       borderBlockEndWidth: 1,
       borderBlockEndStyle: "solid",
       borderBlockEndColor: color.border,
     },
   })

   const markerStyles = {
     base: [styles.root, states.rowFocusRing],
     variants,
     icon: styles.icon,
     content: styles.content,
   }

   const rule = [separatorStyles.base, separatorStyles.orientations.horizontal, styles.rule]

   type MarkerVariant = keyof typeof variants

   type Overrides = { xstyle?: StyleXStyles; className?: string }

   type MarkerProps = useRender.ComponentProps<"div"> & Overrides & { variant?: MarkerVariant }

   function Marker({
     render,
     ref,
     style,
     variant = "default",
     xstyle,
     className,
     children,
     ...props
   }: MarkerProps) {
     const sx = stylex.props(markerStyles.base, variants[variant] ?? variants.default, xstyle)
     return useRender({
       defaultTagName: "div",
       render,
       ref,
       props: {
         "data-slot": "marker",
         "data-variant": variant,
         ...sx,
         ...props,
         className: clsx("arene-icons", sx.className, className),
         style: { ...sx.style, ...style },
         children:
           variant === "separator" ? (
             <>
               <span aria-hidden="true" {...stylex.props(rule, styles.ruleStart)} />
               {children}
               <span aria-hidden="true" {...stylex.props(rule, styles.ruleEnd)} />
             </>
           ) : (
             children
           ),
       },
     })
   }

   function MarkerIcon({
     render,
     ref,
     style,
     xstyle,
     className,
     ...props
   }: useRender.ComponentProps<"span"> & Overrides) {
     const sx = stylex.props(styles.icon, xstyle)
     return useRender({
       defaultTagName: "span",
       render,
       ref,
       props: {
         "data-slot": "marker-icon",
         "aria-hidden": "true",
         ...sx,
         ...props,
         className: clsx(sx.className, className),
         style: { ...sx.style, ...style },
       },
     })
   }

   function MarkerContent({
     render,
     ref,
     style,
     xstyle,
     className,
     ...props
   }: useRender.ComponentProps<"span"> & Overrides) {
     const sx = stylex.props(styles.content, xstyle)
     return useRender({
       defaultTagName: "span",
       render,
       ref,
       props: {
         "data-slot": "marker-content",
         ...sx,
         ...props,
         className: clsx(sx.className, className),
         style: { ...sx.style, ...style },
       },
     })
   }

   export { Marker, MarkerContent, MarkerIcon, markerStyles, type MarkerVariant }
   ```

5. Change the `@/` imports if your project uses different aliases.

## Usage

```tsx
import { Marker, MarkerContent, MarkerIcon } from "@/components/ui/marker"
```

```tsx
<Marker>
  <MarkerIcon>
    <CheckIcon />
  </MarkerIcon>
  <MarkerContent>Searched 3 files</MarkerContent>
</Marker>
```

## Composition

```text
Marker
├── MarkerIcon
└── MarkerContent
```

## Variants

`variant` picks one of three shapes: inline, a bordered row or a labelled
separator.

```tsx
import { Marker, MarkerContent } from "@/components/ui/marker"
import { VStack } from "@/components/ui/stack"
import { widths } from "@/theme/widths"

export default function MarkerVariants() {
  return (
    <VStack gap={8} xstyle={widths.sm}>
      <Marker>
        <MarkerContent>The default marker sits inline with the text.</MarkerContent>
      </Marker>
      <Marker variant="separator">
        <MarkerContent>The separator variant</MarkerContent>
      </Marker>
      <Marker variant="border">
        <MarkerContent>The border variant marks off a row.</MarkerContent>
      </Marker>
    </VStack>
  )
}
```

| Variant     | Description                                        |
| ----------- | -------------------------------------------------- |
| `default`   | An inline marker for status, notes and actions     |
| `border`    | A default marker with a hairline under the row     |
| `separator` | A centred label with a divider line on either side |

## Status

Set `role="status"` and put a [Spinner](https://www.arene.style/docs/components/spinner) in
`MarkerIcon` for a streaming or in-progress marker, so the update is
announced.

```tsx
import { Marker, MarkerContent, MarkerIcon } from "@/components/ui/marker"
import { Spinner } from "@/components/ui/spinner"
import { VStack } from "@/components/ui/stack"
import { widths } from "@/theme/widths"

export default function MarkerStatus() {
  return (
    <VStack gap={8} xstyle={widths.sm}>
      <Marker role="status">
        <MarkerIcon>
          <Spinner />
        </MarkerIcon>
        <MarkerContent>Summarising earlier messages</MarkerContent>
      </Marker>
      <Marker variant="separator" role="status">
        <MarkerIcon>
          <Spinner />
        </MarkerIcon>
        <MarkerContent>Running 48 tests</MarkerContent>
      </Marker>
    </VStack>
  )
}
```

## Shimmer

Merge [`shimmerStyles.base`](https://www.arene.style/docs/utilities/shimmer) into `MarkerContent`
through `xstyle` to animate streaming status text.

```tsx
import { Marker, MarkerContent } from "@/components/ui/marker"
import { VStack } from "@/components/ui/stack"
import { shimmerStyles } from "@/lib/shimmer"
import { widths } from "@/theme/widths"

export default function MarkerShimmer() {
  return (
    <VStack gap={8} xstyle={widths.sm}>
      <Marker role="status">
        <MarkerContent xstyle={shimmerStyles.base}>Thinking…</MarkerContent>
      </Marker>
      <Marker variant="separator" role="status">
        <MarkerContent xstyle={shimmerStyles.base}>Searching the docs</MarkerContent>
      </Marker>
    </VStack>
  )
}
```

## Separator

Use the `separator` variant for a labelled divider, such as a date or a
section break, in a conversation.

```tsx
import { Marker, MarkerContent } from "@/components/ui/marker"
import { VStack } from "@/components/ui/stack"
import { widths } from "@/theme/widths"

export default function MarkerSeparator() {
  return (
    <VStack gap={8} xstyle={widths.sm}>
      <Marker variant="separator">
        <MarkerContent>Today</MarkerContent>
      </Marker>
      <Marker variant="separator">
        <MarkerContent>Took 1m 12s</MarkerContent>
      </Marker>
      <Marker variant="separator">
        <MarkerContent>Earlier messages summarised</MarkerContent>
      </Marker>
    </VStack>
  )
}
```

## Border

The `border` variant keeps the default layout and draws a hairline under the
row, which sets it apart from the row that follows.

```tsx
import { Marker, MarkerContent, MarkerIcon } from "@/components/ui/marker"
import { VStack } from "@/components/ui/stack"
import { widths } from "@/theme/widths"
import { FileTextIcon } from "@phosphor-icons/react/dist/csr/FileText"
import { GitBranchIcon } from "@phosphor-icons/react/dist/csr/GitBranch"
import { MagnifyingGlassIcon } from "@phosphor-icons/react/dist/csr/MagnifyingGlass"

export default function MarkerBorder() {
  return (
    <VStack gap={3} xstyle={widths.sm}>
      <Marker variant="border">
        <MarkerIcon>
          <GitBranchIcon />
        </MarkerIcon>
        <MarkerContent>Checked out fix/leap-years</MarkerContent>
      </Marker>
      <Marker variant="border">
        <MarkerIcon>
          <MagnifyingGlassIcon />
        </MarkerIcon>
        <MarkerContent>Searched 12 calendar modules</MarkerContent>
      </Marker>
      <Marker variant="border">
        <MarkerIcon>
          <FileTextIcon />
        </MarkerIcon>
        <MarkerContent>Opened the design notes</MarkerContent>
      </Marker>
    </VStack>
  )
}
```

## With icon

Use `MarkerIcon` to render an icon beside the content. To stack the icon above
the content, pass `flexDirection: "column"` through `xstyle`.

```tsx
import * as stylex from "@stylexjs/stylex"
import { Marker, MarkerContent, MarkerIcon } from "@/components/ui/marker"
import { VStack } from "@/components/ui/stack"
import { widths } from "@/theme/widths"
import { BookOpenTextIcon } from "@phosphor-icons/react/dist/csr/BookOpenText"
import { GitBranchIcon } from "@phosphor-icons/react/dist/csr/GitBranch"
import { MagnifyingGlassIcon } from "@phosphor-icons/react/dist/csr/MagnifyingGlass"

const styles = stylex.create({
  stacked: { flexDirection: "column" },
})

export default function MarkerIconDemo() {
  return (
    <VStack gap={12} xstyle={widths.sm}>
      <Marker>
        <MarkerIcon>
          <GitBranchIcon />
        </MarkerIcon>
        <MarkerContent>Created branch fix/leap-years</MarkerContent>
      </Marker>
      <Marker variant="separator">
        <MarkerIcon>
          <MagnifyingGlassIcon />
        </MarkerIcon>
        <MarkerContent>Searched 3 files</MarkerContent>
      </Marker>
      <Marker xstyle={styles.stacked}>
        <MarkerIcon>
          <BookOpenTextIcon />
        </MarkerIcon>
        <MarkerContent>Notes synced</MarkerContent>
      </Marker>
    </VStack>
  )
}
```

## Links and buttons

Turn a marker into a link or a button with `render`. A marker rendered as an
`a` is underlined, and an `a` or `button` marker shows a pointer, turns to the
foreground colour on hover and shows a ring on keyboard focus. A link inside
`MarkerContent` is underlined and lights up on hover too.

```tsx
"use client"

import { useState } from "react"
import { Marker, MarkerContent, MarkerIcon } from "@/components/ui/marker"
import { VStack } from "@/components/ui/stack"
import { widths } from "@/theme/widths"
import { ArrowCounterClockwiseIcon } from "@phosphor-icons/react/dist/csr/ArrowCounterClockwise"
import { GitPullRequestIcon } from "@phosphor-icons/react/dist/csr/GitPullRequest"

export default function MarkerLinkButton() {
  const [reverted, setReverted] = useState(false)

  return (
    <VStack gap={8} xstyle={widths.sm}>
      <Marker render={<a href="#links-and-buttons" />}>
        <MarkerIcon>
          <GitPullRequestIcon />
        </MarkerIcon>
        <MarkerContent>Open pull request #128</MarkerContent>
      </Marker>
      <Marker render={<button type="button" onClick={() => setReverted((value) => !value)} />}>
        <MarkerIcon>
          <ArrowCounterClockwiseIcon />
        </MarkerIcon>
        <MarkerContent>{reverted ? "Edit undone. Redo" : "Undo this edit"}</MarkerContent>
      </Marker>
    </VStack>
  )
}
```

```tsx
<Marker render={<a href="/pulls/128" />}>
  <MarkerContent>Open pull request #128</MarkerContent>
</Marker>
```

## Accessibility

`Marker` renders a plain `div` with no role, because the right semantics depend
on what the marker is for.

- **Status and progress.** For a marker that updates while work runs, such as
  "Thinking…" or a running tool, pass `role="status"` so assistive
  technology announces the change.
- **Labelled separators.** A separator with text needs no role. Its lines are
  hidden with `aria-hidden`, and the label is read as ordinary content.
- **Decorative icons.** `MarkerIcon` sets `aria-hidden`, so `MarkerContent`
  carries the meaning. A marker with only an icon still needs text: put it in a
  `MarkerContent` with `xstyle={states.srOnly}`, which hides it visually. An
  `aria-label` on the marker is not read, because a `div` with no role cannot
  be named.
- **Interactive markers.** A marker that navigates or acts should render a real
  `a` or `button` through `render`, so it is focusable and exposes the right
  role. Its accessible name comes from the marker text.

> **Warning**
>
> Don't put `role="separator"` on a labelled divider. That role is named only by
> `aria-label` and treats its children as presentational, so a screen reader
> would skip the visible label.

## API reference

Pass `render` to replace a part's element or compose it with another component.
Every part also takes `xstyle`, `className` and `style`, which is real inline
CSS merged over the compiled styles.

### Marker

Renders a `div`. With `variant="separator"` it renders a hidden line, styled
with `separatorStyles` from [Separator](https://www.arene.style/docs/components/separator), before and
after its children.

| Prop      | Type                                   | Default     |
| --------- | -------------------------------------- | ----------- |
| `variant` | `"default" \| "border" \| "separator"` | `"default"` |

### MarkerIcon

Renders a `span` with `aria-hidden`, sized by `--arene-icon-size`.

### MarkerContent

Renders a `span` that wraps long words rather than overflowing.

### markerStyles

The style map behind the component, exported so you can apply the same styles
to any element.

| Key        | Description                                                    |
| ---------- | -------------------------------------------------------------- |
| `base`     | The row, muted text, link and hover styles, and the focus ring |
| `variants` | One entry per `variant`, keyed by its name                     |
| `icon`     | The icon box                                                   |
| `content`  | The content's wrapping                                         |

### Data attributes

| Attribute                    | On          | Effect                      |
| ---------------------------- | ----------- | --------------------------- |
| `data-slot="marker"`         | the root    | Targets the marker          |
| `data-variant`               | the root    | Reflects the `variant` prop |
| `data-slot="marker-icon"`    | the icon    | Targets the icon box        |
| `data-slot="marker-content"` | the content | Targets the text            |

### CSS variables

| Variable            | On       | Effect                                                 |
| ------------------- | -------- | ------------------------------------------------------ |
| `--arene-icon-size` | the root | The icon size, `1rem`. Set it with `style` on `Marker` |

Cast the object to `CSSProperties`, as [Sidebar](https://www.arene.style/docs/components/sidebar#width)
does. `xstyle` rejects a StyleX entry that sets only custom properties.
