{
  "name": "Citation",
  "source": "src/components/Citation.tsx",
  "propsType": "CitationProps",
  "description": "Citation — the inline marker.\n\nTHE MARKER IS NOT THE NAME. Rendered naively, a superscript \"1\" announces as\n\"link, 1\", which tells a screen-reader user nothing about whether to follow\nit. The visible marker stays a number; the accessible name is\n\"Source 1: <source>\". The number is for the sighted reader's eye and the\nsentence is for everyone.\n\nNOT A TOOLTIP. A tooltip cannot be reached on touch and closes on the way to\nit; attribution has to survive both. It is a real link, or a real\nnon-interactive marker when there is nowhere to go.\n\nWITHOUT `href` IT IS NOT A LINK. A citation to a phone call or an internal\ndocument has no address, and rendering a dead anchor for it puts an\nunfollowable link in the page's link list. It becomes a plain marked-up\nreference instead.",
  "import": "import { Citation } from 'ionbase-ui';",
  "status": "stable",
  "summary": "The inline source marker. The visible number is for the eye; the accessible name is the sentence.",
  "useWhen": [
    "a claim in generated text is drawn from a specific source the reader can check",
    "attribution has to survive being read aloud, on touch, and in a links list"
  ],
  "useInstead": [
    {
      "when": "the source needs a full row with a passage",
      "use": "CitationListItem"
    },
    {
      "when": "it is an ordinary link in prose",
      "use": "Link"
    },
    {
      "when": "you were about to put the source in a hover-only hint",
      "use": "Popover",
      "why": "a tooltip cannot be reached on touch and closes on the way to it"
    }
  ],
  "a11y": {
    "role": "link when `href` is set, note otherwise",
    "guarantees": [
      "the accessible name is \"Source <index>: <source>\", never the bare number — a superscript 1 announces as \"link, 1\", which tells a screen-reader user nothing about whether to follow it",
      "without `href` it renders a marker rather than a dead anchor, so an unfollowable link never enters the page's link list"
    ],
    "requires": [
      "`source` naming what is being cited",
      "an `index` matching the footer row, if there is one"
    ]
  },
  "antiPatterns": [
    {
      "dont": "a bare superscript number with no accessible name",
      "why": "\"link, 1\" is not attribution"
    },
    {
      "dont": "an empty `href` for a source with no address",
      "do": "omit `href`",
      "why": "a dead anchor is announced as a link and goes nowhere"
    },
    {
      "dont": "putting the source only in a tooltip",
      "why": "undiscoverable on touch, and gone before it can be read"
    }
  ],
  "stylesheet": "src/styles/citation.css",
  "tokens": [
    "--border-focus",
    "--border-width-thick",
    "--font-family-sans",
    "--font-weight-medium",
    "--font-weight-semibold",
    "--ion-duration-base",
    "--ion-ease-out",
    "--radius-xs",
    "--spacing-16",
    "--spacing-2",
    "--spacing-4",
    "--spacing-8",
    "--surface-primary-subtle",
    "--surface-primary-subtle-hover",
    "--text-link",
    "--text-tertiary",
    "--type-body-sm",
    "--type-body-sm-line-height",
    "--type-caption",
    "--type-caption-line-height"
  ],
  "props": {
    "index": {
      "type": "string | number",
      "required": true,
      "origin": "own",
      "description": "The marker shown inline — usually a number matching the footer list."
    },
    "source": {
      "type": "string",
      "required": true,
      "origin": "own",
      "description": "What is being cited. Required: it is the link's accessible name, and a\ncitation a reader cannot identify without following it is not attribution."
    },
    "href": {
      "type": "string | undefined",
      "required": false,
      "origin": "own",
      "description": "Where it goes. Omit for a source with no address — a document, a call."
    },
    "label": {
      "type": "string | undefined",
      "required": false,
      "origin": "own",
      "description": "The accessible name — \"Source 1: <source>\" in English."
    }
  },
  "propCounts": {
    "own": 4,
    "aria": 0,
    "dom": 284,
    "other": 0
  }
}