ionbase-ui 0.51.0 → 0.69.0

package/dist/meta/ProgressBar.json

@@ -0,0 +1,166 @@
+{
+  "name": "ProgressBar",
+  "source": "src/components/ProgressBar.tsx",
+  "propsType": "ProgressBarProps",
+  "description": "ProgressBar — a determinate or indeterminate measure of work.\n\nDETERMINATE AND INDETERMINATE ARE THE SAME COMPONENT ON PURPOSE\n\nWork that starts unmeasurable and becomes measurable is the common case — a\nupload that does not know its size until the first chunk lands. Splitting\nthem into two components would make that transition a swap, which remounts\nthe node and loses the live region with it.\n\nOmitting `value` is what makes it indeterminate. `aria-valuenow` is then\nomitted too, which is exactly what the ARIA spec asks for and is the detail\nhand-rolled progress bars get wrong most often — a bar reporting\n`aria-valuenow=\"0\"` forever tells a screen reader the work is stuck at zero,\nnot that it is unmeasured.\n\nWHY `label` IS REQUIRED\n\n`role=\"progressbar\"` announces a number. Without a name the user hears \"42\npercent\" with no indication of what is at 42 percent, which is worse than\nsilence because it sounds like information.",
+  "import": "import { ProgressBar } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "A determinate or indeterminate measure of work, with the name of the work attached. Omitting `value` is what makes it indeterminate.",
+  "useWhen": [
+    "work reports a fraction complete — an upload, an import, a multi-step job",
+    "work will become measurable but is not yet, and the bar should not remount when it does",
+    "a quota or usage figure is better read as a bar than a number"
+  ],
+  "useInstead": [
+    {
+      "when": "the wait is short and unmeasurable",
+      "use": "Spinner",
+      "why": "an indeterminate bar occupies a block of layout to say what a spinner says inline"
+    },
+    {
+      "when": "the region is being replaced by content",
+      "use": "Skeleton"
+    }
+  ],
+  "variants": {
+    "intent": {
+      "primary": {
+        "use": "the default — work proceeding normally"
+      },
+      "success": {
+        "use": "work that finished, where the bar stays on screen as a record"
+      },
+      "warning": {
+        "use": "a quota approaching its limit",
+        "note": "warning describes the VALUE, not a failure of the bar"
+      },
+      "error": {
+        "use": "a quota exceeded, or a job that failed part-way",
+        "note": "the bar is still reporting correctly — reserve this for the measured thing being bad"
+      }
+    },
+    "size": {
+      "sm": {
+        "use": "inside a row or a dense table cell"
+      },
+      "md": {
+        "use": "the default"
+      }
+    }
+  },
+  "a11y": {
+    "requires": [
+      "`label` — it is required, because role=\"progressbar\" announces a number and a number with no noun sounds like information while carrying none",
+      "`valueText` when a percentage is not what a person wants read aloud — \"3 of 12 files\""
+    ],
+    "notes": [
+      "indeterminate omits aria-valuenow entirely, as the ARIA spec asks; a bar reporting aria-valuenow=0 forever says the work is stuck rather than unmeasured",
+      "value is clamped to 0..max, so a caller cannot render a bar past its own end"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "<ProgressBar label=\"Loading\" value={0} /> while the total is unknown",
+      "do": "<ProgressBar label=\"Loading\" />",
+      "why": "value={0} announces \"0 percent\" indefinitely. Omitting value is how you say \"not measurable yet\""
+    },
+    {
+      "dont": "swapping a Spinner for a ProgressBar once the size is known",
+      "do": "one ProgressBar, with `value` appearing when it becomes known",
+      "why": "the swap remounts the node and takes the live region with it, so the transition is silent to a screen reader"
+    },
+    {
+      "dont": "intent=\"error\" because the request failed",
+      "do": "leave the bar and put the failure in an Alert",
+      "why": "intent describes the value being measured. A failed request is not a red measurement, it is a different message"
+    }
+  ],
+  "stylesheet": "src/styles/progress-bar.css",
+  "tokens": [
+    "--border-width-default",
+    "--font-family-sans",
+    "--ion-duration-base",
+    "--ion-duration-slow",
+    "--ion-ease-in-out",
+    "--ion-ease-out",
+    "--ion-progress-bar-fill",
+    "--ion-progress-bar-height",
+    "--ion-progress-bar-pct",
+    "--radius-full",
+    "--spacing-4",
+    "--spacing-8",
+    "--surface-error",
+    "--surface-muted",
+    "--surface-primary",
+    "--surface-success",
+    "--surface-warning",
+    "--text-default",
+    "--text-secondary",
+    "--type-body-sm",
+    "--type-body-sm-line-height"
+  ],
+  "props": {
+    "label": {
+      "type": "string",
+      "required": true,
+      "origin": "own",
+      "description": "What is progressing. Required — a bare bar announces a number and no noun."
+    },
+    "value": {
+      "type": "number | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "0 to `max`. Omit for an indeterminate bar."
+    },
+    "max": {
+      "type": "number | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Defaults to 100."
+    },
+    "intent": {
+      "type": "ProgressBarIntent | undefined",
+      "required": false,
+      "origin": "own",
+      "values": [
+        "primary",
+        "success",
+        "warning",
+        "error"
+      ]
+    },
+    "size": {
+      "type": "ProgressBarSize | undefined",
+      "required": false,
+      "origin": "own",
+      "values": [
+        "sm",
+        "md"
+      ]
+    },
+    "isLabelVisible": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Show the label as text above the track."
+    },
+    "isValueVisible": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Show the percentage beside the label. Determinate bars only."
+    },
+    "valueText": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Spoken instead of the percentage — \"3 of 12 files\". A percentage is rarely\nthe thing a person wants read aloud."
+    }
+  },
+  "propCounts": {
+    "own": 8,
+    "aria": 0,
+    "dom": 277,
+    "other": 0
+  }
+}

package/dist/meta/PromptInput.json

@@ -0,0 +1,212 @@
+{
+  "name": "PromptInput",
+  "source": "src/components/PromptInput.tsx",
+  "propsType": "PromptInputProps",
+  "description": "PromptInput — where a person writes to an agent.\n\nWHY IT IS NOT A TEXTAREA AND A BUTTON\n\nEvery composer is assembled that way, and every one re-implements the same\nfour bugs:\n\n  Enter during IME composition sends half a word. Japanese, Chinese and\n  Korean input confirm a candidate with Enter; a handler that does not check\n  `isComposing` sends the message mid-character. That excludes whole\n  languages from the product, silently, and nobody on an English keyboard\n  ever sees it.\n\n  The prompt is lost when sending fails. Clearing on submit is right —\n  waiting for the server makes the composer feel broken — but clearing and\n  never restoring destroys what may have been a long message. Uncontrolled,\n  a rejected `onSubmit` promise puts the text back.\n\n  The stop control lives somewhere else. While a run is going, the send\n  button's place is exactly where the user's pointer and attention already\n  are, so that is where `AgentStop` goes — the same control, the same\n  guarantees, not a second stop button with different ones.\n\n  The keyboard contract is invisible. \"Enter sends, Shift+Enter for a new\n  line\" is announced through `aria-describedby`, because a screen-reader\n  user who presses Enter expecting a newline has just sent a message.\n\nWHAT IT DOES NOT DO\n\nIt does not upload, pick models or render messages. `attachments` and\n`actions` are slots, because what a product attaches and which tools it\noffers are the product's decisions.",
+  "import": "import { PromptInput } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "Where a person writes to an agent: a growing text field, a send control that becomes the stop control while a run is going, and slots for attachments and tools.",
+  "useWhen": [
+    "a chat or assistant surface where the user's message starts a run",
+    "a command bar that sends free text to an agent"
+  ],
+  "useInstead": [
+    {
+      "when": "the text is a form value submitted with other fields",
+      "use": "Textarea",
+      "why": "Enter-to-send inside a form fights the form's own submit, and a single field of a larger form is not a composer"
+    },
+    {
+      "when": "the input is a single-line search",
+      "use": "Input",
+      "why": "a search box does not grow, does not stop runs, and Enter means search rather than send"
+    },
+    {
+      "when": "the run needs a stop control and was not started from this composer",
+      "use": "AgentStop",
+      "why": "the composer's stop belongs to the run it sent; a run started elsewhere keeps its stop beside its own activity"
+    }
+  ],
+  "variants": {
+    "submitKey": {
+      "enter": {
+        "use": "the default — chat. Enter sends, Shift+Enter is a new line"
+      },
+      "mod-enter": {
+        "use": "long messages, where a stray Enter is expensive. Cmd/Ctrl+Enter sends and Enter is a new line"
+      }
+    }
+  },
+  "slots": {
+    "actions": {
+      "accepts": "Button",
+      "note": "attach, a model picker, a tool toggle — at the start of the toolbar. Icon-only buttons need their own aria-label"
+    },
+    "attachments": {
+      "accepts": "Badge",
+      "note": "what is attached, above the text. Each removable item needs a remove control named for the file"
+    }
+  },
+  "a11y": {
+    "requires": [
+      "`label` — the accessible name of the field. A placeholder is not one: it disappears on the first keystroke"
+    ],
+    "guarantees": [
+      "the send key is described through aria-describedby, so a screen-reader user knows Enter sends before pressing it",
+      "Enter pressed while an IME is composing never sends — Japanese, Chinese and Korean input confirm candidates with Enter",
+      "while `isRunning` with `onStop`, the send control is replaced in place by AgentStop, with its guarantees: it keeps its place while stopping and announces once",
+      "focus stays in the field after sending, so the next message can be typed straight away"
+    ],
+    "notes": [
+      "the field stays editable while a run is going; only submitting is refused",
+      "uncontrolled, the field clears on send and a rejected onSubmit promise restores the text — unless the user has already started typing something new"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "<Textarea> beside a <Button> with an onKeyDown that checks for Enter",
+      "do": "<PromptInput label=\"Message\" onSubmit={send} />",
+      "why": "the hand-built version sends mid-character for IME users and loses the prompt when sending fails"
+    },
+    {
+      "dont": "a separate AgentStop elsewhere on screen as well as `isRunning` with `onStop`",
+      "why": "two stop controls for one run raises the question of whether they do different things"
+    },
+    {
+      "dont": "`isRunning` without `onStop`",
+      "why": "the send control disables and nothing replaces it — the user can see the agent working and has no way to stop it"
+    },
+    {
+      "dont": "controlled `value` cleared in onSubmit before the request settles",
+      "why": "controlled, restoring the text on failure is the caller's job; clearing early and not restoring loses the message"
+    }
+  ],
+  "stylesheet": "src/styles/prompt-input.css",
+  "tokens": [
+    "--border-default",
+    "--border-disabled",
+    "--border-focus",
+    "--border-strong",
+    "--border-width-default",
+    "--font-family-sans",
+    "--ion-duration-base",
+    "--ion-ease-out",
+    "--radius-lg",
+    "--spacing-32",
+    "--spacing-4",
+    "--spacing-8",
+    "--surface-default",
+    "--surface-disabled",
+    "--text-default",
+    "--text-disabled",
+    "--text-tertiary",
+    "--type-body",
+    "--type-body-line-height"
+  ],
+  "props": {
+    "label": {
+      "type": "string",
+      "required": true,
+      "origin": "own",
+      "description": "The accessible name of the text field. Required, and not a placeholder:\nplaceholder text disappears the moment the user types, and is not reliably\nannounced as a name."
+    },
+    "value": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Controlled text. Pass `onChange` with it."
+    },
+    "defaultValue": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Uncontrolled starting text."
+    },
+    "onChange": {
+      "type": "((value: string) => void) | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "onSubmit": {
+      "type": "((value: string) => void | Promise<unknown>) | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Fires with the text as typed. Uncontrolled, the field clears straight away;\nif the returned promise rejects, the text is put back — a prompt lost to a\nnetwork error is the one thing a composer must never do."
+    },
+    "submitKey": {
+      "type": "PromptInputSubmitKey | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Which key sends. `enter` sends on Enter with Shift+Enter for a new line —\na chat. `mod-enter` sends on Cmd/Ctrl+Enter and leaves Enter for new lines —\na composer where messages are long and a stray Enter is expensive.",
+      "values": [
+        "enter",
+        "mod-enter"
+      ]
+    },
+    "isRunning": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "A run is in progress. The send control becomes an `AgentStop` in the same\nplace, and submitting is refused. The field stays editable, so the user can\ndraft the next message while the agent works."
+    },
+    "onStop": {
+      "type": "(() => void) | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Called by the stop control while `isRunning`."
+    },
+    "isStopping": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Passed to the stop control once the stop has been requested."
+    },
+    "isDisabled": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "minRows": {
+      "type": "number | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Rows the field starts at."
+    },
+    "maxRows": {
+      "type": "number | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Rows the field grows to before it scrolls."
+    },
+    "actions": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Controls at the start of the toolbar — attach, a model picker, a tool\ntoggle. Icon-only controls here need their own `aria-label`."
+    },
+    "attachments": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "Rendered above the text — attached files, a quoted message."
+    },
+    "sendLabel": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Accessible name of the send control."
+    },
+    "className": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Class names for the outer box."
+    }
+  },
+  "propCounts": {
+    "own": 16,
+    "aria": 0,
+    "dom": 284,
+    "other": 0
+  }
+}

package/dist/meta/SegmentedControl.json

@@ -0,0 +1,217 @@
+{
+  "name": "SegmentedControl",
+  "source": "src/components/SegmentedControl.tsx",
+  "propsType": "SegmentedControlProps",
+  "description": "SegmentedControl — pick one of a few options, and see all of them.\n\nNOT TABS, ALTHOUGH IT LOOKS LIKE THE PILL TYPE, and the difference is the\ncontract. Tabs switch between panels: `tablist`, `tab`, `tabpanel`, and each\ntab controls a region. This sets a VALUE — a view mode, a time range, a\nunit — and controls no panel. It is a `radiogroup`, so it has one tab stop,\narrow keys move and select, and it submits with a form like any radio.\n\nBuilt from real radio inputs, visually hidden, not from buttons with\n`aria-pressed`. A row of toggle buttons is a tab stop per option and no\nmutual exclusion that assistive tech can announce; radios give \"2 of 3,\nselected\" for free.\n\nThe look is Tabs' pill track, token for token, so the two cannot drift\napart visually — which is exactly why the intent file spends its words on\nwhen to use which.",
+  "import": "import { SegmentedControl } from 'ionbase-ui';",
+  "status": "stable",
+  "summary": "Pick one of two to five options, all visible at once. A radio group drawn as a segmented track — it sets a value and controls no panel.",
+  "useWhen": [
+    "switching how the same content is shown — List / Board / Calendar",
+    "a short, fixed set of mutually exclusive settings — Day / Week / Month, °C / °F",
+    "a filter with a few exclusive choices where seeing every option matters"
+  ],
+  "useInstead": [
+    {
+      "when": "each option shows a different panel of content",
+      "use": "Tabs",
+      "why": "Tabs wires each tab to its panel with tablist/tabpanel semantics. A SegmentedControl controls no region, so a screen-reader user is never told which content changed"
+    },
+    {
+      "when": "there are more than five options, or the labels are long",
+      "use": "Select",
+      "why": "segments do not wrap; a track that overflows hides the options it exists to show"
+    },
+    {
+      "when": "the choice sits in a form with a visible question and descriptions per option",
+      "use": "RadioGroup",
+      "why": "same semantics, but room for a label and helper text on each option"
+    },
+    {
+      "when": "the setting is a single on/off",
+      "use": "Toggle"
+    },
+    {
+      "when": "the options trigger actions rather than set a value — Bold, Italic",
+      "use": "Button",
+      "why": "an action is not a selection; a radio group announces a state that does not exist"
+    }
+  ],
+  "composition": {
+    "order": [
+      "SegmentedControl",
+      "SegmentedControlItem"
+    ],
+    "example": "<SegmentedControl label=\"View\" defaultValue=\"list\"><SegmentedControlItem value=\"list\">List</SegmentedControlItem><SegmentedControlItem value=\"board\">Board</SegmentedControlItem></SegmentedControl>"
+  },
+  "variants": {
+    "size": {
+      "sm": {
+        "use": "toolbars and dense panel headers"
+      },
+      "md": {
+        "use": "the default"
+      },
+      "lg": {
+        "use": "a primary view switch at the top of a page"
+      }
+    }
+  },
+  "slots": {
+    "children": {
+      "accepts": "SegmentedControlItem",
+      "note": "two to five. One item is not a choice; six is a Select"
+    }
+  },
+  "a11y": {
+    "role": "radiogroup / radio",
+    "requires": [
+      "`label` — the group's accessible name. Hidden by default; `showLabel` renders it above the track"
+    ],
+    "guarantees": [
+      "one tab stop for the whole control; arrow keys move and select, skipping disabled segments",
+      "built from real radio inputs, so it announces \"2 of 3, selected\" and submits with a form under `name`",
+      "a disabled selected segment keeps its selected surface — a disabled control still has a value"
+    ],
+    "notes": [
+      "it looks exactly like Tabs' pill type on purpose, and behaves differently on purpose. Choose by what changes, not by how it looks"
+    ]
+  },
+  "antiPatterns": [
+    {
+      "dont": "a SegmentedControl that swaps the panel below it",
+      "do": "<Tabs type=\"pill\">",
+      "why": "the panel relationship is exactly what tabpanel semantics announce; without it the content changes silently"
+    },
+    {
+      "dont": "no defaultValue or value",
+      "why": "a segmented track with nothing selected reads as broken, not as a choice still to make"
+    },
+    {
+      "dont": "icon-only segments with no aria-label",
+      "do": "<SegmentedControlItem value=\"grid\" icon={<Grid />} aria-label=\"Grid view\" />",
+      "why": "each segment is a radio, and an unnamed radio is announced as just \"radio button\""
+    }
+  ],
+  "stylesheet": "src/styles/segmented-control.css",
+  "tokens": [
+    "--border-width-thick",
+    "--font-family-sans",
+    "--font-weight-medium",
+    "--icon-size-md",
+    "--icon-size-sm",
+    "--ion-duration-base",
+    "--ion-ease-out",
+    "--ion-segmented-font-size",
+    "--ion-segmented-icon-size",
+    "--ion-segmented-item-gap",
+    "--ion-segmented-item-height",
+    "--ion-segmented-item-padding-x",
+    "--ion-segmented-line-height",
+    "--radius-lg",
+    "--radius-md",
+    "--ring-focus",
+    "--spacing-12",
+    "--spacing-16",
+    "--spacing-2",
+    "--spacing-20",
+    "--spacing-24",
+    "--spacing-32",
+    "--spacing-4",
+    "--spacing-40",
+    "--spacing-6",
+    "--spacing-8",
+    "--surface-default",
+    "--surface-hover",
+    "--surface-muted",
+    "--surface-page",
+    "--text-default",
+    "--text-disabled",
+    "--text-tertiary",
+    "--type-body",
+    "--type-body-lg",
+    "--type-body-lg-line-height",
+    "--type-body-line-height",
+    "--type-body-sm",
+    "--type-body-sm-line-height"
+  ],
+  "props": {
+    "label": {
+      "type": "string",
+      "required": true,
+      "origin": "own",
+      "description": "The accessible name of the group. Required: \"List, Board, Calendar\" means\nnothing until something says they are views."
+    },
+    "showLabel": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Show `label` above the control, as a form field does. Hidden by default.",
+      "default": false
+    },
+    "value": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Controlled selected value. Pass `onChange` with it."
+    },
+    "defaultValue": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Uncontrolled starting value. One option should always be selected — a\nsegmented control with nothing chosen reads as broken, not as \"no choice\"."
+    },
+    "onChange": {
+      "type": "((value: string) => void) | undefined",
+      "required": false,
+      "origin": "own"
+    },
+    "size": {
+      "type": "SegmentedControlSize | undefined",
+      "required": false,
+      "origin": "own",
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    },
+    "isFullWidth": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Stretch to the container, with equal-width segments.",
+      "default": false
+    },
+    "isDisabled": {
+      "type": "boolean | undefined",
+      "required": false,
+      "origin": "own",
+      "default": false
+    },
+    "name": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own",
+      "description": "Submitted with a form under this name."
+    },
+    "children": {
+      "type": "React.ReactNode",
+      "required": false,
+      "origin": "own",
+      "description": "`SegmentedControlItem` elements. Two to five of them."
+    },
+    "className": {
+      "type": "string | undefined",
+      "required": false,
+      "origin": "own"
+    }
+  },
+  "propCounts": {
+    "own": 11,
+    "aria": 0,
+    "dom": 0,
+    "other": 0
+  }
+}