# Citation

## Usage

`Citation` marks a source inside a sentence. The `label` variant is a chip with the source title. The `number` variant is a compact superscript. Pass `number` as the 1-based index; it is spoken in the accessible name and shown by the number variant.

When `source.url` is set, the citation is a link that opens in a new tab and uses `role="doc-noteref"`. Without a URL it is a `<span>` and does not claim to be a link. The accessible name is localized, for example “Citation 2: Release notes”. The visible title falls back to the number when `source.title` is empty.

`source.icon` wins over `source.src`. A value that looks like a URL or a path is drawn as an image. Any other string is passed to `Icon` as a CSS class. The icon is only drawn for the label variant.

```vue
<script setup lang="ts">
import { Citation } from '@astryx-vue/core/Citation'
</script>

<template>
  <p>
    See
    <Citation :number="1" :source="{ title: 'Release notes', url: 'https://example.com/notes' }" />
    <Citation :number="1" variant="number" :source="{ title: 'Release notes', url: 'https://example.com/notes' }" />
  </p>
</template>
```

### Anatomy

- **Container**: The root wrapper. Accepted source URLs render an anchor; missing or rejected URLs render an inert span.
- **Icon**: An optional source icon shown before the label text. Accepts a favicon/logo image URL (via source.src) or slot content such as an Astryx <Icon>. Only available in the label variant.
- **Label text**: The source title, truncated with ellipsis when it exceeds the max width. Shown in the label variant.
- **Number**: The citation index displayed as a superscript badge. Shown in the number variant.

## Best practices

| Guidance | Practices |
| --- | --- |
| Do | Keep `number` stable for a source inside one answer, so the chip and the superscript refer to the same note. |
| Do | Give `title` the name a person would recognize. The number is only a fallback. |
| Do | Use the number variant in dense paragraphs, and the label variant where the source name should be readable without a footnote. |
| Don't | Put a long sentence in `title`. The chip clips, and the accessible name would be the whole sentence. |
| Don't | Use a citation as a general link. It is a note reference, not a navigation control. |

## Examples

### Citation — Inline Text

Citations embedded within a paragraph of text, showing how they flow inline with surrounding content.

```vue
<script setup lang="ts">
import { Citation } from '@astryx-vue/core/Citation'
import { Stack } from '@astryx-vue/core/Stack'
import { Text } from '@astryx-vue/core/Text'
</script>

<template>
  <Stack direction="vertical" :gap="4" style="max-width: 560px">
    <Text type="body">
      React uses a virtual DOM to minimize expensive DOM operations<Citation
        :number="1"
        variant="number"
        :source="{ title: 'React Documentation', url: 'https://react.dev' }"
      />. This approach was inspired by earlier functional UI frameworks<Citation
        :number="2"
        variant="number"
        :source="{ title: 'Elm Architecture', url: 'https://guide.elm-lang.org/architecture/' }"
      />.
    </Text>
    <Text type="body">
      TypeScript adds static types to JavaScript for safer refactoring<Citation
        :number="3"
        variant="label"
        :source="{ title: 'TypeScript Documentation', url: 'https://www.typescriptlang.org', icon: 'https://www.typescriptlang.org/favicon-32x32.png' }"
      />.
    </Text>
  </Stack>
</template>
```

### Citation — Source List

A list of citation sources with icons, as you might show at the end of an AI-generated response or article footer.

```vue
<script setup lang="ts">
import { Citation } from '@astryx-vue/core/Citation'
import { Stack } from '@astryx-vue/core/Stack'
import { Text } from '@astryx-vue/core/Text'

const sources = [
  { title: 'React Documentation', url: 'https://react.dev', icon: 'https://react.dev/favicon-32x32.png' },
  { title: 'TypeScript Handbook', url: 'https://www.typescriptlang.org/docs/handbook/', icon: 'https://www.typescriptlang.org/favicon-32x32.png' },
  { title: 'MDN Web Docs', url: 'https://developer.mozilla.org', icon: 'https://developer.mozilla.org/favicon-48x48.cbbd161b.png' },
  { title: 'W3C WAI-ARIA Specification', url: 'https://www.w3.org/TR/wai-aria/' },
]
</script>

<template>
  <Stack direction="vertical" :gap="3">
    <Text type="supporting" color="secondary">
      Sources
    </Text>
    <Stack direction="horizontal" :gap="2" style="flex-wrap: wrap">
      <Citation
        v-for="(source, index) in sources"
        :key="source.title"
        :source="source"
        :number="index + 1"
        variant="label"
      />
    </Stack>
  </Stack>
</template>
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `source` | `CitationSource` | - | `title` is the visible label and falls back to the number. `url` renders a link. `src` is a favicon. `icon` is an image URL or a CSS icon class and wins over `src`. |
| `number` | `number` | - | 1-based index. Spoken in the accessible name and shown by the number variant. |
| `variant` | `'label' \| 'number'` | `'label'` | `label` is a chip with the title. `number` is a compact superscript. |

A template ref exposes <code>element</code>, the link or the span.

## Theming

`packages/themes/neutral/citation.css` maps component variables onto semantic tokens. Another theme overrides those variables.

- `--astryx-citation-foreground` / `--astryx-citation-foreground-hover`: resting and hover text.
- `--astryx-citation-border` / `--astryx-citation-hover`: chip border and hover fill.
- `--astryx-citation-number-background`: superscript fill.
- `--astryx-citation-icon-background`: the circle behind a label icon.
- `--astryx-citation-focus`: keyboard outline.
- `--astryx-duration-fast-max` / `--astryx-ease-standard`: hover transition.

## Native attributes

Attributes fall through to the root, which is an `<a>` when `source.url` is set and a `<span>` otherwise. `target`, `rel`, `role`, `aria-label`, and `title` are set by the component.