{ "name": "CodeSnippet", "source": "src/components/CodeSnippet.tsx", "propsType": "CodeSnippetProps", "description": "CodeSnippet — code shown as code: a command to run, a config to paste, a\nname in a sentence.\n\nTHE BLOCK IS A REGION YOU CAN SCROLL FROM THE KEYBOARD. Code does not wrap\n— a wrapped command reads as two — so `single` and `multi` scroll sideways,\nand a scroll area that cannot be focused cannot be scrolled without a\nmouse. Each is a named, focusable region; the arrow keys scroll it.\nChromium has made a scroll area focusable by itself since 130, so a test\nthere passes without `tabIndex`; Safari does not, and axe's\n`scrollable-region-focusable` is what catches it.\n\nTHE WHOLE TEXT IS ALWAYS THERE. A long `multi` block is cut to `maxLines`\nby height, not by dropping lines, so find-in-page still finds them, and the\ncopy button copies all of it whether it is expanded or not.\n\nCOPYING IS CopyButton's. It confirms on the button and announces; the code\nitself is on screen, so a copy that fails leaves it there to select.", "import": "import { CodeSnippet } from 'ionbase-ui';", "status": "stable", "summary": "Code shown as code: a name in a sentence, a command to run, a block to paste. Commands and blocks scroll rather than wrap, are named regions a keyboard can scroll, and carry a CopyButton that copies all of it.", "useWhen": [ "the user will run, paste or type what is shown — a CLI command, an API request, a config file", "a sentence names something the user types exactly — a flag, a file name, a command — and it should read as code" ], "useInstead": [ { "when": "the value is an ID or key shown among other facts, not code", "use": "CopyButton", "why": "an ID beside its label in a DescriptionList reads as a fact; a snippet's block around it reads as something to run" }, { "when": "a keyboard shortcut", "use": "Kbd", "why": "keys are pressed, not typed; Kbd draws each key and never prints a plus between them" }, { "when": "an agent's tool input or output", "use": "ToolCall", "why": "it shows the payload with the call it belongs to, its status and duration, collapsed until asked for" } ], "composition": { "order": [ "CodeSnippet" ], "note": "`children` is the code as a string, shown and copied exactly as given. `type` picks inline, single or multi; `label` names a single or multi block, and `copyLabel` its copy button when there is more than one on a page.", "example": "iops runs start --agent invoice-reconciler" }, "variants": { "type": { "single": { "use": "the default — one command, scrolling sideways if it is long" }, "multi": { "use": "a block — a request, a config; cut to `maxLines` with Show more" }, "inline": { "use": "in a sentence; no copy button" } } }, "a11y": { "requires": [ "`label` on each single or multi snippet when a page has more than one — \"Start command\"; the default is \"Code\"", "`copyLabel` naming what is copied when a page has more than one — \"Copy start command\"; the default is \"Copy code\"", "`label`, `copyLabel`, `copiedLabel`, `showMoreLabel` and `showLessLabel` translated" ], "guarantees": [ "single and multi are focusable regions named by `label`, so the arrow keys scroll what is off screen", "code never wraps: single stays one line, 32px tall, and scrolls sideways; multi scrolls sideways line by line", "a multi block longer than `maxLines` is cut by height, not by dropping lines: every line is in the page and found by find-in-page", "Show more is a Button with `aria-expanded` and `aria-controls` pointing at the region; it becomes Show less", "the copy button is a CopyButton: it copies the whole text, cut or not, confirms on the button and announces", "a trailing newline is not counted as a line", "inline is a in the sentence, with no region and no button" ], "notes": [ "never put a secret in a snippet unless the user must copy it now; redact it everywhere else, as ToolCall's payloads are", "`language` only sets `language-` on the ; IonBase does not highlight, and a highlighter added on top must keep the text readable against `surface/muted`" ] }, "antiPatterns": [ { "dont": "
{command}
", "do": "{command}", "why": "a wrapped command reads as two, and a hand-built 
 that scrolls is not focusable, so a keyboard cannot reach what is off screen"
    },
    {
      "dont": "a multi block cut to its first lines with the rest dropped",
      "do": "`maxLines`, which cuts by height",
      "why": "dropped lines are missed by find-in-page, by a screen reader and by a copy that copies what is shown"
    },
    {
      "dont": " for a command the user will copy",
      "do": "type=\"single\"",
      "why": "inline has no copy button, and a command selected by hand from a sentence picks up the full stop"
    }
  ],
  "stylesheet": "src/styles/code-snippet.css",
  "tokens": [
    "--border-default",
    "--border-focus",
    "--border-width-default",
    "--border-width-thick",
    "--font-family-mono",
    "--ion-code-snippet-lines",
    "--radius-md",
    "--radius-xs",
    "--spacing-12",
    "--spacing-4",
    "--spacing-6",
    "--surface-muted",
    "--text-default",
    "--type-body-sm",
    "--type-body-sm-line-height"
  ],
  "props": {
    "children": {
      "type": "string",
      "required": true,
      "origin": "own",
      "description": "The code, as text. It is shown and copied exactly as given."
    },
    "type": {
      "type": "CodeSnippetType | undefined",
      "required": false,
      "origin": "own",
      "description": "`inline` sits in a sentence and has no copy button. `single` is one line\nthat scrolls sideways — a command. `multi` is a block — a config file, a\nrequest.",
      "values": [
        "inline",
        "single",
        "multi"
      ]
    },
    "label": {
      "type": "string | undefined",
      "required": false,
      "origin": "own",
      "description": "Names the block for a screen reader — \"Install command\". `single` and\n`multi` are focusable regions, and a region needs a name. Default \"Code\";\nwith more than one snippet on a page, name each."
    },
    "copyLabel": {
      "type": "string | undefined",
      "required": false,
      "origin": "own",
      "description": "The copy button's name. Default \"Copy code\"; with more than one snippet\non a page, say which — \"Copy install command\"."
    },
    "copiedLabel": {
      "type": "string | undefined",
      "required": false,
      "origin": "own",
      "description": "Default \"Copied\"."
    },
    "failedLabel": {
      "type": "string | undefined",
      "required": false,
      "origin": "own",
      "description": "Read and shown when the clipboard refused the copy — CopyButton's `failedLabel`."
    },
    "hideCopyButton": {
      "type": "boolean | undefined",
      "required": false,
      "origin": "own",
      "description": "Leaves out the copy button — for code that is read, not run."
    },
    "maxLines": {
      "type": "number | undefined",
      "required": false,
      "origin": "own",
      "description": "`multi` only: lines shown before \"Show more\". Default 12."
    },
    "showMoreLabel": {
      "type": "string | undefined",
      "required": false,
      "origin": "own",
      "description": "Default \"Show more\"."
    },
    "showLessLabel": {
      "type": "string | undefined",
      "required": false,
      "origin": "own",
      "description": "Default \"Show less\"."
    },
    "language": {
      "type": "string | undefined",
      "required": false,
      "origin": "own",
      "description": "Set as `language-` on the ``, the class highlighters look\nfor. IonBase does not highlight."
    },
    "onCopy": {
      "type": "((text: string) => void) | undefined",
      "required": false,
      "origin": "own"
    },
    "onCopyError": {
      "type": "((error: unknown, text: string) => void) | undefined",
      "required": false,
      "origin": "own"
    },
    "className": {
      "type": "string | undefined",
      "required": false,
      "origin": "own"
    }
  },
  "propCounts": {
    "own": 14,
    "aria": 0,
    "dom": 0,
    "other": 0
  }
}