ionbase-ui 0.22.0 → 0.25.0

package/dist/meta/CitationListItem.json

@@ -0,0 +1,88 @@
+{
+  "name": "CitationListItem",
+  "source": "src/components/Citation.tsx",
+  "propsType": "CitationListItemProps",
+  "import": "import { CitationListItem } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "One source row: its number, what it is, and the passage it supports.",
+  "useWhen": [
+    "a child of CitationList"
+  ],
+  "useInstead": [
+    {
+      "when": "it is the inline marker in the prose",
+      "use": "Citation"
+    }
+  ],
+  "slots": {
+    "children": {
+      "accepts": "text",
+      "note": "the quoted or summarised passage this source supports"
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "the visible number is `aria-hidden`; the row is named by its source text, which is what a reader needs to hear",
+      "without `href` the source renders as text rather than a dead link"
+    ],
+    "requires": [
+      "`source` naming what is being cited"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "a bare URL as the `source`",
+      "why": "a screen reader spells it out character by character, and it names nothing"
+    }
+  ],
+  "stylesheet": "src/styles/citation.css",
+  "tokens": [
+    "--border-focus",
+    "--border-width-thick",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--font-weight-semibold",
+    "--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"
+    },
+    "source": {
+      "type": "string",
+      "required": true,
+      "origin": "own"
+    },
+    "href": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "children": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "The quoted or summarised passage this citation supports."
+    }
+  },
+  "propCounts": {
+    "own": 4,
+    "aria": 0,
+    "dom": 278,
+    "other": 0
+  }
+}

package/dist/meta/ConfidenceIndicator.json

@@ -0,0 +1,115 @@
+{
+  "name": "ConfidenceIndicator",
+  "source": "src/components/ConfidenceIndicator.tsx",
+  "propsType": "ConfidenceIndicatorProps",
+  "description": "ConfidenceIndicator — how much to trust the thing next to it.\n\nTHERE IS NO PERCENTAGE PROP, AND THERE WILL NOT BE ONE\n\n\"87% confident\" reads as a measurement. Almost nowhere is it one: it is\nusually a softmax score, a heuristic, or a number a model produced about\nitself — none of which are calibrated probabilities, and all of which invite\na reader to treat two digits of precision as real. Three levels cannot\noverclaim in that way.\n\n`basis` IS REQUIRED FOR THE SAME REASON. A level with nothing behind it is\ndecoration that changes behaviour: people act on \"high confidence\" whether or\nnot anything justifies it. Making the justification a required prop is the\nonly enforcement available here, and it is a type error rather than a policy\n— which is the strongest kind this system can offer.\n\nIt renders as text plus a three-bar meter, never the meter alone. The bars\ndiffer in filled COUNT, not only in colour, so the reading survives greyscale\nand forced-colours mode.",
+  "import": "import { ConfidenceIndicator } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "How much to trust the thing next to it — three levels with a required basis, never a percentage.",
+  "useWhen": [
+    "a generated answer varies in reliability and the reader should weigh it",
+    "you can say what the confidence rests on"
+  ],
+  "useInstead": [
+    {
+      "when": "the answer is wrong or missing rather than uncertain",
+      "use": "Alert"
+    },
+    {
+      "when": "you want to show where the claim came from",
+      "use": "Citation",
+      "why": "a source is stronger than a confidence level, and often what the reader actually wanted"
+    },
+    {
+      "when": "it is a status rather than a reliability",
+      "use": "Badge"
+    }
+  ],
+  "variants": {
+    "level": {
+      "low": {
+        "use": "thin or conflicting evidence. One bar, warning colour"
+      },
+      "medium": {
+        "use": "reasonable support with real gaps. Two bars"
+      },
+      "high": {
+        "use": "corroborated, and you can say by what. Three bars"
+      }
+    }
+  },
+  "a11y": {
+    "guarantees": [
+      "the level is spelled out in text, so it never depends on the meter",
+      "the meter differs in filled COUNT rather than only in colour, and in forced-colours mode filled bars are solid while empty ones are outlined"
+    ],
+    "requires": [
+      "`basis` — a type error if omitted, and the reason this component exists rather than a coloured dot"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "asking for a percentage prop",
+      "why": "\"87% confident\" reads as a measurement and almost never is one — usually a softmax score or a model's claim about itself, neither of which is a calibrated probability. Three levels cannot overclaim that way"
+    },
+    {
+      "dont": "a vague basis like \"model output\"",
+      "why": "it satisfies the type and defeats the purpose — say \"3 of 4 sources agree\" or \"single unverified source\""
+    },
+    {
+      "dont": "high confidence on every response",
+      "why": "an indicator that never varies is decoration that still changes behaviour"
+    }
+  ],
+  "stylesheet": "src/styles/confidence-indicator.css",
+  "tokens": [
+    "--border-width-default",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--icon-information",
+    "--icon-success",
+    "--icon-tertiary",
+    "--icon-warning",
+    "--radius-2xs",
+    "--spacing-12",
+    "--spacing-16",
+    "--spacing-2",
+    "--spacing-4",
+    "--spacing-8",
+    "--text-default",
+    "--text-secondary",
+    "--text-tertiary",
+    "--type-caption",
+    "--type-caption-line-height"
+  ],
+  "props": {
+    "level": {
+      "type": "ConfidenceLevel",
+      "required": true,
+      "origin": "own",
+      "values": [
+        "low",
+        "medium",
+        "high"
+      ]
+    },
+    "basis": {
+      "type": "string",
+      "required": true,
+      "origin": "own",
+      "description": "What the level is based on. REQUIRED, and the reason this component exists\nrather than a coloured dot: a confidence with no stated basis is a number\nthe reader has no way to weigh. \"3 of 4 sources agree\", \"no matching\nrecords found\", \"single unverified source\"."
+    },
+    "label": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Override the level's word. Keep it a word, not a percentage."
+    }
+  },
+  "propCounts": {
+    "own": 3,
+    "aria": 0,
+    "dom": 277,
+    "other": 0
+  }
+}

package/dist/meta/Input.json

@@ -232,13 +232,13 @@
       "description": "Identifies the element (or elements) whose contents or presence are controlled by the current\nelement."
     },
     "enterKeyHint": {
-      "type": "\"enter\" | \"done\" | \"go\" | \"next\" | \"previous\" | \"search\" | \"send\" | undefined",
+      "type": "\"done\" | \"enter\" | \"go\" | \"next\" | \"previous\" | \"search\" | \"send\" | undefined",
       "required": false,
       "origin": "aria",
       "description": "An enumerated attribute that defines what action label or icon to preset for the enter key on\nvirtual keyboards. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/enterkeyhint).",
       "values": [
-        "enter",
         "done",
+        "enter",
         "go",
         "next",
         "previous",

package/dist/meta/PhoneInput.json

@@ -122,6 +122,42 @@
       "origin": "own",
       "description": "Spread onto the dial-code `<button>`. This is how a country picker gets\nattached — see the note on scope below."
     },
+    "type": {
+      "type": "(string & {}) | \"search\" | \"text\" | \"url\" | \"tel\" | \"email\" | \"password\" | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The type of input to render. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdeftype).",
+      "tags": {
+        "default": "'text'"
+      },
+      "default": "tel"
+    },
+    "disabled": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "tags": {
+        "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
+      }
+    },
+    "form": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The `<form>` element to associate the input with.\nThe value of this attribute must be the id of a `<form>` in the same document.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form)."
+    },
+    "name": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The name of the input element, used when submitting an HTML form. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname)."
+    },
+    "value": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "aria",
+      "description": "The current value (controlled)."
+    },
     "defaultValue": {
       "type": "string | undefined",
       "required": false,
@@ -155,13 +191,13 @@
       "description": "Class names for the control box (`.ion-input`). Always lands here —\nnever on the form-field wrapper. Use `wrapperClassName` for that."
     },
     "enterKeyHint": {
-      "type": "\"enter\" | \"done\" | \"go\" | \"next\" | \"previous\" | \"search\" | \"send\" | undefined",
+      "type": "\"done\" | \"enter\" | \"go\" | \"next\" | \"previous\" | \"search\" | \"send\" | undefined",
       "required": false,
       "origin": "aria",
       "description": "An enumerated attribute that defines what action label or icon to preset for the enter key on\nvirtual keyboards. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/enterkeyhint).",
       "values": [
-        "enter",
         "done",
+        "enter",
         "go",
         "next",
         "previous",
@@ -359,36 +395,12 @@
       ],
       "default": "md"
     },
-    "type": {
-      "type": "(string & {}) | \"search\" | \"text\" | \"url\" | \"tel\" | \"email\" | \"password\" | undefined",
-      "required": false,
-      "origin": "aria",
-      "description": "The type of input to render. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdeftype).",
-      "tags": {
-        "default": "'text'"
-      },
-      "default": "tel"
-    },
     "autoComplete": {
       "type": "string | undefined",
       "required": false,
       "origin": "aria",
       "description": "Describes the type of autocomplete functionality the input should provide if any. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete)."
     },
-    "disabled": {
-      "type": "boolean | undefined",
-      "required": false,
-      "origin": "own",
-      "tags": {
-        "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
-      }
-    },
-    "form": {
-      "type": "string | undefined",
-      "required": false,
-      "origin": "aria",
-      "description": "The `<form>` element to associate the input with.\nThe value of this attribute must be the id of a `<form>` in the same document.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form)."
-    },
     "maxLength": {
       "type": "number | undefined",
       "required": false,
@@ -401,12 +413,6 @@
       "origin": "aria",
       "description": "The minimum number of characters required by the input. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefminlength)."
     },
-    "name": {
-      "type": "string | undefined",
-      "required": false,
-      "origin": "aria",
-      "description": "The name of the input element, used when submitting an HTML form. See\n[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname)."
-    },
     "pattern": {
       "type": "string | undefined",
       "required": false,
@@ -419,12 +425,6 @@
       "origin": "aria",
       "description": "Temporary text that occupies the text input when it is empty."
     },
-    "value": {
-      "type": "string | undefined",
-      "required": false,
-      "origin": "aria",
-      "description": "The current value (controlled)."
-    },
     "isDisabled": {
       "type": "boolean | undefined",
       "required": false,

package/dist/meta/StreamingText.json

@@ -0,0 +1,99 @@
+{
+  "name": "StreamingText",
+  "source": "src/components/StreamingText.tsx",
+  "propsType": "StreamingTextProps",
+  "description": "StreamingText — model output arriving a token at a time.\n\nIT IS NOT A LIVE REGION, AND THAT IS THE WHOLE DESIGN\n\nThe obvious implementation — `aria-live=\"polite\"` on the container — is the\none that makes a screen reader unusable. Every token mutation queues an\nannouncement, so the user hears the answer re-read, stuttered, dozens of\ntimes, and cannot get ahead of it. `aria-live=\"off\"` is not an oversight\nhere; it is the accessible choice.\n\nWhat it does instead: `aria-busy` while streaming, so assistive tech knows\nthe region is unsettled and can wait. The text is ordinary readable content\nthroughout — a screen-reader user navigates into it whenever they want,\nexactly like sighted users reading ahead of the cursor.\n\nANNOUNCING COMPLETION IS THE CALLER'S CALL, not this component's. Some\nsurfaces want \"response complete\"; a chat with ten turns on screen does not\nwant ten of them. Render your own `role=\"status\"` when you want it.\n\nTHE HEIGHT IS RESERVED, NOT ANIMATED. `minLines` holds space in `lh` units so\nthe content below stays still. A container that grows token by token drags\nthe whole page, which is worse for someone using magnification than the wait.\n\nThe cursor is CSS and `aria-hidden`. It stops blinking under\n`prefers-reduced-motion` — a blinking element is a WCAG 2.3.1 concern and a\ngenuine problem for some vestibular and attention conditions.",
+  "import": "import { StreamingText } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "Model output arriving a token at a time, in a container that does not move. Deliberately not a live region.",
+  "useWhen": [
+    "rendering a response that streams in rather than arriving whole",
+    "the reader should be able to start reading before generation finishes"
+  ],
+  "useInstead": [
+    {
+      "when": "the text is already complete",
+      "use": "Alert",
+      "why": "nothing about this component helps once there is nothing left to arrive"
+    },
+    {
+      "when": "you are showing progress through steps rather than producing text",
+      "use": "AgentActivity"
+    }
+  ],
+  "a11y": {
+    "role": "region when `label` is set, none otherwise",
+    "guarantees": [
+      "`aria-live=\"off\"`, deliberately — a polite live region re-announces the whole answer on every token, which makes a streaming response unusable with a screen reader",
+      "`aria-busy` while streaming, so assistive tech knows the region is unsettled",
+      "the text stays ordinary readable content throughout, so a screen-reader user can read ahead exactly as a sighted user does",
+      "the cursor is `aria-hidden`, is a styled box rather than a text character, and stops blinking under `prefers-reduced-motion` (WCAG 2.3.1)"
+    ],
+    "requires": [
+      "announcing completion yourself, with your own `role=\"status\"`, if the surface wants it — a chat with ten turns on screen does not want ten announcements",
+      "`label` when the region needs a name of its own"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "wrapping it in `aria-live=\"polite\"`",
+      "why": "every token queues an announcement; the user hears the answer stuttered dozens of times and cannot get ahead of it"
+    },
+    {
+      "dont": "letting the container grow token by token with no reserved height",
+      "do": "`minLines`",
+      "why": "the content below climbs the screen while someone is reading it, which is worse under magnification than the wait"
+    },
+    {
+      "dont": "a text-character cursor like ▌",
+      "why": "some screen readers read it aloud even inside an aria-hidden span"
+    }
+  ],
+  "stylesheet": "src/styles/streaming-text.css",
+  "tokens": [
+    "--font-family-sans",
+    "--ion-streaming-min-lines",
+    "--text-default",
+    "--text-tertiary",
+    "--type-body",
+    "--type-body-line-height"
+  ],
+  "props": {
+    "children": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "The text so far. Re-render with more of it; this component appends nothing."
+    },
+    "isStreaming": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "More is still arriving. Shows the cursor and marks the region busy."
+    },
+    "minLines": {
+      "type": "number | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Rows of height to hold while the text is short, so the page below does not\nclimb the screen as tokens arrive. Costs blank space at the start and buys\na layout that does not move under a reader."
+    },
+    "label": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Accessible name for the region."
+    },
+    "hideCursor": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Hide the trailing cursor. The text still marks itself busy."
+    }
+  },
+  "propCounts": {
+    "own": 5,
+    "aria": 0,
+    "dom": 277,
+    "other": 0
+  }
+}