# Marker

Displays an inline status, system note, bordered row, or labeled separator in a conversation.

Source: https://webjs.dev/ui/docs/components/marker

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { markerClass, markerContentClass, markerIconClass } from '#components/ui/marker.ts';
import { spinner } from '#components/ui/spinner.ts';
import { GitBranchIcon, SearchIcon } from '#lib/ui/lucide.ts';

export default function MarkerDemo() {
  return html`
    <div class="flex w-full max-w-sm flex-col gap-8 py-12">
      <div data-slot="marker" data-variant="default" class=${markerClass()}>
        <span data-slot="marker-icon" aria-hidden="true" class=${markerIconClass()}>
          ${GitBranchIcon()}
        </span>
        <span data-slot="marker-content" class=${markerContentClass()}>Switched to a new branch</span>
      </div>
      <div data-slot="marker" data-variant="default" role="status" class=${markerClass()}>
        <span data-slot="marker-icon" aria-hidden="true" class=${markerIconClass()}>
          ${spinner({ decorative: true })}
        </span>
        <span data-slot="marker-content" class=${cn(markerContentClass(), 'shimmer')}>Thinking...</span>
      </div>
      <div data-slot="marker" data-variant="separator" class=${markerClass({ variant: 'separator' })}>
        <span data-slot="marker-content" class=${markerContentClass()}>Conversation compacted</span>
      </div>
      <div data-slot="marker" data-variant="default" class=${markerClass()}>
        <span data-slot="marker-icon" aria-hidden="true" class=${markerIconClass()}>
          ${SearchIcon()}
        </span>
        <span data-slot="marker-content" class=${markerContentClass()}>Explored 4 files</span>
      </div>
    </div>
  `;
}
```

## Installation

```bash
npx @webjsdev/ui add marker
```

### Copy and paste the following code into your project.

````ts title="components/ui/marker.ts"
/**
 * Marker: a small inline note in a stream of content, such as "Today" between
 * chat messages or "Edited" under a post, with an optional icon. Tier-1
 * class helper; compose with a plain element.
 *
 * shadcn parity:
 *   Marker (variant: default | separator | border)
 *                    → markerClass({ variant }), alias markerVariants
 *   MarkerIcon       → markerIconClass()
 *   MarkerContent    → markerContentClass()
 *
 * The `separator` variant draws a rule on both sides of the content, and
 * `border` underlines the whole marker. Set `data-variant` to the variant you
 * pass, which is what the content's centring keys on.
 *
 * A11y (required for accessible output): a marker is text, so it needs no
 * role. When it announces a change in a live log (a date divider inside a
 * chat), it is read in order with the messages around it, which is usually
 * right. Hide a purely decorative icon with `aria-hidden="true"`.
 *
 * Design tokens used: --muted-foreground, --foreground, --border.
 *
 * @example
 * ```html
 * <div class=${markerClass({ variant: 'separator' })} data-variant="separator">
 *   <span class=${markerContentClass()}>Today</span>
 * </div>
 * ```
 */
import { cn } from '../lib/utils.ts';

const BASE = "min-h-4 gap-2 text-start text-sm text-muted-foreground [&_svg:not([class*='size-'])]:size-4 [a]:underline [a]:underline-offset-3 [a]:hover:text-foreground group/marker relative flex w-full items-center";

const VARIANTS = {
  default: '',
  separator: 'before:me-1 before:h-px before:min-w-0 before:flex-1 before:bg-border after:ms-1 after:h-px after:min-w-0 after:flex-1 after:bg-border',
  border: 'border-b border-border pb-2',
} as const;

export type MarkerVariant = keyof typeof VARIANTS;

/** The marker row. Pair with `data-variant` set to the same variant. */
export function markerClass(opts: { variant?: MarkerVariant } & { className?: string } = {}): string {
  return cn(BASE, VARIANTS[opts.variant ?? 'default'], opts.className);
}

/**
 * shadcn's name for {@link markerClass}, so shadcn code ports verbatim. Like
 * cva, it merges a `className` into the result.
 */
export function markerVariants(opts: { variant?: MarkerVariant } & { className?: string } = {}): string {
  return markerClass(opts);
}

/** The leading icon. */
export function markerIconClass(): string {
  return "size-4 [&_svg:not([class*='size-'])]:size-4 shrink-0";
}

/** The marker's text. */
export function markerContentClass(): string {
  return 'group-data-[variant=separator]/marker:flex-none group-data-[variant=separator]/marker:text-center *:[a]:underline *:[a]:underline-offset-3 *:[a]:hover:text-foreground min-w-0 wrap-break-word';
}
````

### Update the import paths to match your project setup.

## Usage

```ts
import { markerClass, markerContentClass, markerIconClass } from '#components/ui/marker.ts';
```

```ts
<div data-slot="marker" data-variant="default" class=${markerClass()}>
  <span data-slot="marker-icon" aria-hidden="true" class=${markerIconClass()}>
    ${CheckIcon()}
  </span>
  <span data-slot="marker-content" class=${markerContentClass()}>Explored 4 files</span>
</div>
```

## Composition

Use the following composition to build a marker:

```text
markerClass()
├── markerIconClass()
└── markerContentClass()
```

## Features

- Inline marker, bordered row, and labeled separator variants
- Decorative icon slot that is hidden from assistive tech
- Class helpers, so the root can be a `<div>`, a link, or a button
- Pairs with the [`shimmer`](https://webjs.dev/ui/docs/utils/shimmer) utility for streaming status text
- Customizable styling by merging classes into each helper's result with `cn`

## Variants

Use the `variant` option to switch between an inline marker, bordered row, and labeled separator. Set `data-variant` on the root to the same variant: the content's centring keys on it.

```ts
import { html } from '@webjsdev/core';
import { markerClass, markerContentClass } from '#components/ui/marker.ts';

export default function MarkerVariantsDemo() {
  return html`
    <div class="flex w-full max-w-sm flex-col gap-8 py-12">
      <div data-slot="marker" data-variant="default" class=${markerClass()}>
        <span data-slot="marker-content" class=${markerContentClass()}>A default marker for inline notes.</span>
      </div>
      <div data-slot="marker" data-variant="separator" class=${markerClass({ variant: 'separator' })}>
        <span data-slot="marker-content" class=${markerContentClass()}>A separator marker</span>
      </div>
      <div data-slot="marker" data-variant="border" class=${markerClass({ variant: 'border' })}>
        <span data-slot="marker-content" class=${markerContentClass()}>A border marker for row boundaries.</span>
      </div>
    </div>
  `;
}
```

| Variant | Description |
| --- | --- |
| `default` | An inline marker for status, notes, and actions. |
| `border` | A default marker with a bottom border under the row. |
| `separator` | A centered label with divider lines on each side. |

## Status

Set `role="status"` and include a [Spinner](https://webjs.dev/ui/docs/components/spinner) for streaming or in-progress markers so updates are announced.

```ts
import { html } from '@webjsdev/core';
import { markerClass, markerContentClass, markerIconClass } from '#components/ui/marker.ts';
import { spinner } from '#components/ui/spinner.ts';

export default function MarkerStatusDemo() {
  return html`
    <div class="flex w-full max-w-sm flex-col gap-8 py-12">
      <div data-slot="marker" data-variant="default" role="status" class=${markerClass()}>
        <span data-slot="marker-icon" aria-hidden="true" class=${markerIconClass()}>
          ${spinner({ decorative: true })}
        </span>
        <span data-slot="marker-content" class=${markerContentClass()}>Compacting conversation</span>
      </div>
      <div data-slot="marker" data-variant="separator" role="status" class=${markerClass({ variant: 'separator' })}>
        <span data-slot="marker-icon" aria-hidden="true" class=${markerIconClass()}>
          ${spinner({ decorative: true })}
        </span>
        <span data-slot="marker-content" class=${markerContentClass()}>Running tests</span>
      </div>
    </div>
  `;
}
```

## Shimmer

Add the [`shimmer`](https://webjs.dev/ui/docs/utils/shimmer) utility class to the marker content for an animated streaming-text effect. The utility comes from the kit's Tailwind stylesheet and is not part of its generated component CSS, so add it to your stylesheet first. See the shimmer docs for installation.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { markerClass, markerContentClass } from '#components/ui/marker.ts';

export default function MarkerShimmerDemo() {
  return html`
    <div class="flex w-full max-w-sm flex-col gap-8 py-12">
      <div data-slot="marker" data-variant="default" role="status" class=${markerClass()}>
        <span data-slot="marker-content" class=${cn(markerContentClass(), 'shimmer')}>Thinking...</span>
      </div>
      <div data-slot="marker" data-variant="separator" role="status" class=${markerClass({ variant: 'separator' })}>
        <span data-slot="marker-content" class=${cn(markerContentClass(), 'shimmer')}>Reading 4 files</span>
      </div>
    </div>
  `;
}
```

## Separator

Use the `separator` variant for labeled dividers, such as dates or section breaks, in a conversation. A [Checkpoint](https://webjs.dev/ui/docs/ai-elements/checkpoint) is a separator with a button that restores the thread to that point.

```ts
import { html } from '@webjsdev/core';
import { markerClass, markerContentClass } from '#components/ui/marker.ts';

export default function MarkerSeparatorDemo() {
  return html`
    <div class="flex w-full max-w-sm flex-col gap-8 py-12">
      <div data-slot="marker" data-variant="separator" class=${markerClass({ variant: 'separator' })}>
        <span data-slot="marker-content" class=${markerContentClass()}>Today</span>
      </div>
      <div data-slot="marker" data-variant="separator" class=${markerClass({ variant: 'separator' })}>
        <span data-slot="marker-content" class=${markerContentClass()}>Worked for 42s</span>
      </div>
      <div data-slot="marker" data-variant="separator" class=${markerClass({ variant: 'separator' })}>
        <span data-slot="marker-content" class=${markerContentClass()}>Conversation compacted</span>
      </div>
    </div>
  `;
}
```

## Border

Use the `border` variant for status rows that should keep the default marker alignment while separating the next row.

```ts
import { html } from '@webjsdev/core';
import { markerClass, markerContentClass, markerIconClass } from '#components/ui/marker.ts';
import { FileTextIcon, GitBranchIcon, SearchIcon } from '#lib/ui/lucide.ts';

export default function MarkerBorderDemo() {
  return html`
    <div class="flex w-full max-w-sm flex-col gap-3 py-12">
      <div data-slot="marker" data-variant="border" class=${markerClass({ variant: 'border' })}>
        <span data-slot="marker-icon" aria-hidden="true" class=${markerIconClass()}>
          ${GitBranchIcon()}
        </span>
        <span data-slot="marker-content" class=${markerContentClass()}>Switched to release-candidate</span>
      </div>
      <div data-slot="marker" data-variant="border" class=${markerClass({ variant: 'border' })}>
        <span data-slot="marker-icon" aria-hidden="true" class=${markerIconClass()}>
          ${SearchIcon()}
        </span>
        <span data-slot="marker-content" class=${markerContentClass()}>Reviewed 8 related files</span>
      </div>
      <div data-slot="marker" data-variant="border" class=${markerClass({ variant: 'border' })}>
        <span data-slot="marker-icon" aria-hidden="true" class=${markerIconClass()}>
          ${FileTextIcon()}
        </span>
        <span data-slot="marker-content" class=${markerContentClass()}>Opened implementation notes</span>
      </div>
    </div>
  `;
}
```

## With Icon

Use `markerIconClass()` to render an icon alongside the content. Add `flex-col` to the root to stack the icon above the content.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { markerClass, markerContentClass, markerIconClass } from '#components/ui/marker.ts';
import { BookOpenCheck, GitBranchIcon, SearchIcon } from '#lib/ui/lucide.ts';

export default function MarkerIconDemo() {
  return html`
    <div class="flex w-full max-w-sm flex-col gap-12 py-12">
      <div data-slot="marker" data-variant="default" class=${markerClass()}>
        <span data-slot="marker-icon" aria-hidden="true" class=${markerIconClass()}>
          ${GitBranchIcon()}
        </span>
        <span data-slot="marker-content" class=${markerContentClass()}>Switched to a new branch</span>
      </div>
      <div data-slot="marker" data-variant="separator" class=${markerClass({ variant: 'separator' })}>
        <span data-slot="marker-icon" aria-hidden="true" class=${markerIconClass()}>
          ${SearchIcon()}
        </span>
        <span data-slot="marker-content" class=${markerContentClass()}>Explored 4 files</span>
      </div>
      <div data-slot="marker" data-variant="default" class=${cn(markerClass(), 'flex-col')}>
        <span data-slot="marker-icon" aria-hidden="true" class=${markerIconClass()}>
          ${BookOpenCheck()}
        </span>
        <span data-slot="marker-content" class=${markerContentClass()}>Syncing completed</span>
      </div>
    </div>
  `;
}
```

## Links and Buttons

A class helper styles any element, so a marker that links or acts is an `<a>` or a `<button>` with the marker's classes.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { markerClass, markerContentClass, markerIconClass } from '#components/ui/marker.ts';
import { GitBranchIcon, RotateCcwIcon } from '#lib/ui/lucide.ts';

export default function MarkerLinkButtonDemo() {
  return html`
    <div class="flex w-full max-w-sm flex-col gap-8 py-12">
      <a href="#links-and-buttons" data-slot="marker" data-variant="default" class=${markerClass()}>
        <span data-slot="marker-icon" aria-hidden="true" class=${markerIconClass()}>
          ${GitBranchIcon()}
        </span>
        <span data-slot="marker-content" class=${markerContentClass()}>View the pull request</span>
      </a>
      <button type="button" data-slot="marker" data-variant="default" class=${cn(markerClass(), 'transition-colors hover:text-foreground')}>
        <span data-slot="marker-icon" aria-hidden="true" class=${markerIconClass()}>
          ${RotateCcwIcon()}
        </span>
        <span data-slot="marker-content" class=${markerContentClass()}>Revert this change</span>
      </button>
    </div>
  `;
}
```

```ts
import { html } from '@webjsdev/core';
import { markerClass, markerContentClass } from '#components/ui/marker.ts';

export function MarkerLinkDemo() {
  return html`
    <a href="#" data-slot="marker" data-variant="default" class=${markerClass()}>
      <span data-slot="marker-content" class=${markerContentClass()}>View the pull request</span>
    </a>
  `;
}
```

## Accessibility

A marker is presentational by default. The correct semantics depend on how you use it, so choose the role based on intent rather than relying on a single default.

### Status and Progress

For streaming or progress markers such as "Thinking..." or a running tool, set `role="status"` on the root so assistive tech announces the update as it appears.

```ts
<div data-slot="marker" data-variant="default" role="status" class=${markerClass()}>
  <span data-slot="marker-icon" aria-hidden="true" class=${markerIconClass()}>
    ${spinner({ decorative: true })}
  </span>
  <span data-slot="marker-content" class=${markerContentClass()}>Compacting conversation</span>
</div>
```

### Labeled Separators

A separator that carries text, such as a date or a section label, needs no role. The divider lines are decorative CSS pseudo-elements, and the text is announced as ordinary content.

```ts
<div data-slot="marker" data-variant="separator" class=${markerClass({ variant: 'separator' })}>
  <span data-slot="marker-content" class=${markerContentClass()}>Today</span>
</div>
```

**Note:** Do not add `role="separator"` to a labeled divider. A separator takes its accessible name from `aria-label`, not from its text, and its contents are treated as presentational, so the visible label would not be announced. Reserve `role="separator"` for a divider with no meaningful text.

### Bordered Markers

A bordered marker keeps the same semantics as the default marker. The bottom border is decorative, so choose `role="status"`, a link or button element, or no role based on the marker's purpose.

```ts
<div data-slot="marker" data-variant="border" class=${markerClass({ variant: 'border' })}>
  <span data-slot="marker-icon" aria-hidden="true" class=${markerIconClass()}>
    ${FileTextIcon()}
  </span>
  <span data-slot="marker-content" class=${markerContentClass()}>Opened implementation notes</span>
</div>
```

### Decorative Icons

The icon slot is decorative: put `aria-hidden="true"` on it, as the examples do, so the adjacent content carries the meaning. For an icon-only marker, provide an `aria-label` or visible text so it is not announced as empty.

```ts
<div data-slot="marker" data-variant="default" aria-label="Synced" class=${markerClass()}>
  <span data-slot="marker-icon" aria-hidden="true" class=${markerIconClass()}>
    ${CheckIcon()}
  </span>
</div>
```

### Interactive Markers

When a marker links or triggers an action, render it as a real `<button>` or `<a>` carrying the marker's classes so it is focusable and exposes the correct role. The accessible name comes from the marker text.

```ts
<a href="/files" data-slot="marker" data-variant="default" class=${markerClass()}>
  <span data-slot="marker-icon" aria-hidden="true" class=${markerIconClass()}>
    ${FileTextIcon()}
  </span>
  <span data-slot="marker-content" class=${markerContentClass()}>Explored 4 files</span>
</a>
```

## API Reference

### markerClass

`markerClass()` returns the classes for the root marker element. Set `data-variant` to the variant you pass. `markerVariants()` is an alias of `markerClass()` that also merges a `className`.

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `"default" \| "border" \| "separator"` | `"default"` | The marker layout. |

### markerIconClass

The classes for the decorative icon slot. Hide it from assistive tech with `aria-hidden="true"`. Takes no options.

### markerContentClass

The classes for the marker text content. Takes no options.
