@adres/mgda-ui 0.0.0-stage → 0.0.2

package/knowledge/prompt-suggestions.md

@@ -0,0 +1,168 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: prompt-suggestions
+  sourceFile: packages/design-system/src/components/prompt-suggestions.tsx
+  client: true
+  category: web-app-ai
+  categoryFromBarrel: web-app-ai
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: StarterPromptItem
+      kind: type
+    - name: StarterPrompts
+      kind: component
+      typeText: "ForwardRefExoticComponent<StarterPromptsProps & RefAttributes<HTMLDivElement>>"
+    - name: StarterPromptsProps
+      kind: type
+    - name: SuggestionChips
+      kind: component
+      typeText: "ForwardRefExoticComponent<SuggestionChipsProps & RefAttributes<HTMLDivElement>>"
+    - name: SuggestionChipsProps
+      kind: type
+  primaryExport: StarterPrompts
+  subcomponents:
+    - SuggestionChips
+  props:
+    StarterPrompts:
+      - name: label
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Accessible name of the group."
+      - name: onPick
+        type: "(prompt: string) => void"
+        required: true
+        declaredIn: self
+      - name: starters
+        type: "StarterPromptItem[]"
+        required: true
+        declaredIn: self
+    SuggestionChips:
+      - name: disabled
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "E.g. while the assistant replies."
+      - name: insert
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Chips put the prompt in the composer for editing instead of sending it."
+      - name: label
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Accessible name of the chip group."
+      - name: loading
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Swaps each chip for a skeleton and marks the group busy."
+      - name: onPick
+        type: "(prompt: string) => void"
+        required: true
+        declaredIn: self
+      - name: onRefresh
+        type: "(() => void)"
+        required: false
+        declaredIn: self
+        doc: "Adds an \"Other suggestions\" button under the row."
+      - name: suggestions
+        type: "string[]"
+        required: true
+        declaredIn: self
+      - name: wrap
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Wrap onto several lines instead of one horizontally scrolling row."
+  extendsProps:
+    - "Omit<React.HTMLAttributes<HTMLDivElement>, \"onSelect\">"
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots:
+    - starter-prompts
+    - suggestion-chips
+  dependsOn:
+    internal:
+      - button
+      - skeleton
+      - text
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-suggestionchips--default
+    - exportName: Wrapped
+      id: components-suggestionchips--wrapped
+    - exportName: Loading
+      id: components-suggestionchips--loading
+    - exportName: InsertTemplates
+      id: components-suggestionchips--insert-templates
+    - exportName: Starters
+      id: components-suggestionchips--starters
+  storybookTitle: Components/SuggestionChips
+  docsId: components-suggestionchips--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: ac0e5c863c02
+  factsHash: "84189d4e0c67"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: beta
+summary: "Prompt suggestions for an assistant: a row of follow-up chips that send or insert a prompt, and an empty-state grid of starter prompts."
+useWhen:
+  - "an assistant should offer follow-up questions after an answer"
+  - "an empty chat needs a few ways to start, each with a short title and the full prompt"
+  - "template prompts should drop into the composer for editing instead of sending"
+useInstead:
+  - id: toggle
+    when: "the chips filter or select values rather than send a prompt"
+  - id: badge
+    when: "the chips are static labels, not actions"
+related:
+  - chat-message
+  - button
+a11y:
+  notes:
+    - "Each chip is a button whose name is the full prompt; insert-mode chips are named \"Edit prompt: ...\"."
+    - "Chip rows are role=\"group\" with a label, and aria-busy while loading; a live region announces loading."
+    - "StarterPrompts icons are decorative; the title names the starter."
+  radixHandles: false
+pitfalls:
+  - "Pass the same suggestions while loading; their count sets how many skeletons show."
+  - "Disable the chips while the assistant is replying so a second prompt is not sent mid-answer."
+  - "Without wrap the row scrolls horizontally; use wrap when every chip must stay visible."
+canonicalSnippet: |
+  import { StarterPrompts, SuggestionChips } from "@adres/mgda-ui"
+
+  <StarterPrompts starters={starters} onPick={send} />
+  <SuggestionChips suggestions={followUps} onPick={send} disabled={replying} onRefresh={nextRound} />
+reviewedAt: 2026-10-06
+reviewedAgainstContractHash: ac0e5c863c02
+---
+
+## Usage
+
+`SuggestionChips` renders prompts as rounded outline buttons, in one
+horizontally scrolling row or wrapped with `wrap`. `onPick` receives the
+prompt. `loading` swaps the chips for skeletons, `disabled` locks them while
+the assistant replies, `onRefresh` adds an "Other suggestions" button under
+the row, and `insert` marks chips as templates to edit in the composer.
+
+`StarterPrompts` is the empty-state version: a two-column grid of starters,
+each an optional icon, a short title and the full prompt it sends.
+
+## Anatomy
+
+- `StarterPrompts` - empty-state grid of titled starters.
+- `SuggestionChips` - follow-up or template chip row with loading and refresh.

package/knowledge/quota-bar.md

@@ -0,0 +1,160 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: quota-bar
+  sourceFile: packages/design-system/src/components/quota-bar.tsx
+  client: true
+  category: web-app-patterns
+  categoryFromBarrel: web-app-patterns
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: QuotaBar
+      kind: component
+      typeText: "ForwardRefExoticComponent<QuotaBarProps & RefAttributes<HTMLDivElement>>"
+    - name: QuotaBarProps
+      kind: type
+    - name: QuotaBarShape
+      kind: type
+  primaryExport: QuotaBar
+  subcomponents: []
+  props:
+    QuotaBar:
+      - name: compact
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Compact mode - uses a smaller bar / ring."
+      - name: ctaHref
+        type: string
+        required: false
+        declaredIn: self
+        doc: "When the quota is full, the full-state CTA renders as a link to this href. Use this OR `ctaOnClick`, not both."
+      - name: ctaLabel
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Visible text for the full-state CTA. Defaults to \"Request More\"."
+      - name: ctaOnClick
+        type: "(() => void)"
+        required: false
+        declaredIn: self
+        doc: "When the quota is full, the full-state CTA renders as a button that fires this callback (use for non-routing actions like opening a Drawer)."
+      - name: fullLabel
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Replaces the default \"No {unit} remaining\" string in the full state."
+      - name: remainingLabel
+        type: "((remaining: number) => string)"
+        required: false
+        declaredIn: self
+        doc: "Label shown next to the count when the quota is *not* full. Defaults to `\"{remaining} remaining\"`."
+      - name: ringSize
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Ring-only: pixel diameter override (passes through to Progress)."
+      - name: shape
+        type: QuotaBarShape
+        required: false
+        declaredIn: self
+        doc: "Visual shape. `bar` (default) is a horizontal Progress with the caption underneath; `ring` puts a circular Progress on the inline-start side with the caption stacked beside it and the pct% inside the ring."
+      - name: strokeWidth
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Ring-only: stroke width in pixels."
+      - name: total
+        type: number
+        required: true
+        declaredIn: self
+        doc: "Maximum allowed. When `used >= total`, the bar renders in the error variant and the \"full\" state is shown."
+      - name: unit
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Unit label appended after the count - e.g. \"seats\", \"licences\", \"GB\". Used in the \"X / Y {unit} used\" sentence."
+      - name: used
+        type: number
+        required: true
+        declaredIn: self
+        doc: "Current usage."
+  extendsProps:
+    - "React.HTMLAttributes<HTMLDivElement>"
+  variants:
+    shape:
+      kind: enum
+      options:
+        - bar
+        - ring
+      default: bar
+      on: QuotaBar
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal:
+      - progress
+    lib:
+      - cn
+    hooks: []
+    external:
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-quotabar--default
+  storybookTitle: Components/QuotaBar
+  docsId: components-quotabar--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "0ed32271b362"
+  factsHash: "846a55440f72"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A usage-vs-limit indicator: a Progress bar or ring plus a used/total-with-unit caption, with automatic warning and full states and an optional CTA."
+useWhen:
+  - "showing usage against a limit with domain-specific wording - seats, licenses, storage, monthly sends - not a generic progress value"
+useInstead:
+  - id: progress
+    when: "there is no usage/limit framing or CTA needed, just a raw percentage"
+related:
+  - progress
+a11y:
+  notes:
+    - "The centered percentage text inside the ring shape is aria-hidden - Progress underneath already exposes the real value via role=\"progressbar\" and aria-valuenow, so the visible percentage text is not a duplicate accessible announcement."
+    - "The full-state CTA renders as a real link (ctaHref) or button (ctaOnClick), never a styled span - it stays keyboard-focusable and operable like any other link or button."
+  radixHandles: false
+pitfalls:
+  - "The variant and its warning/error coloring are entirely computed from used/total - there is no variant prop to override; a used value that exceeds total is clamped visually by the underlying Progress, but isFull and the caption text still key off the raw used >= total comparison."
+  - "Pass ctaHref or ctaOnClick, never both - the component does not validate this itself, so supplying both means ctaOnClick's button rendering wins (checked first) and ctaHref is silently ignored."
+  - "The percentage text inside a ring shape is hidden specifically for compact rings with no ringSize override, since the text would not fit - it is not hidden for compact bars, or for a compact ring given an explicit ringSize override."
+  - "remainingLabel and fullLabel let you fully localize or rephrase the non-full and full-state text, but the \"{used} / {total} {unit} used\" sentence itself has no override prop - customizing it means composing your own layout with Progress directly instead."
+canonicalSnippet: |
+  import { QuotaBar } from "@adres/mgda-ui"
+
+  <QuotaBar used={8} total={10} unit="seats" ctaHref="/billing/upgrade" />
+reviewedAt: 2026-09-01
+reviewedAgainstContractHash: "0ed32271b362"
+---
+
+## Usage
+
+`QuotaBar` shows usage against a limit with domain-appropriate wording -
+seats, licenses, storage, emails sent this month - built on `Progress`
+underneath plus a "{used} / {total} {unit} used" caption. Reach for
+`Progress` directly instead when there is no usage/limit framing or CTA
+needed, just a raw percentage.
+
+The visual state escalates automatically from the `used`/`total` ratio:
+`default` below 90%, `warning` from 90% up to (not including) full, and
+`error` once `used >= total`, which also swaps in the full-state message and
+an optional CTA - pass `ctaHref` or `ctaOnClick`, not both.
+
+`shape="bar"` (default) stacks the caption underneath a horizontal Progress;
+`shape="ring"` places a circular Progress beside the caption with the
+percentage rendered inside the ring - hidden only when `compact` and no
+`ringSize` override is given, since the text would not fit at that size.

package/knowledge/quote.md

@@ -0,0 +1,116 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: quote
+  sourceFile: packages/design-system/src/components/quote.tsx
+  client: true
+  category: web-app-core-primitives
+  categoryFromBarrel: web-app-core-primitives
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Quote
+      kind: component
+      typeText: "ForwardRefExoticComponent<QuoteProps & RefAttributes<HTMLQuoteElement>>"
+    - name: QuoteProps
+      kind: type
+    - name: quoteVariants
+      kind: variants
+      typeText: "(props?: (ConfigVariants<{ size: { sm: string; md: string; lg: string; xl: string; }; color: { default: string; muted: string; accent: string; }; }> & ClassProp) | undefined) => string"
+  primaryExport: Quote
+  subcomponents: []
+  props:
+    Quote:
+      - name: color
+        type: "\"accent\" | \"default\" | \"muted\""
+        required: false
+        declaredIn: self
+        variantKey: true
+      - name: size
+        type: "\"lg\" | \"md\" | \"sm\" | \"xl\""
+        required: false
+        declaredIn: self
+        variantKey: true
+  extendsProps:
+    - "Omit<React.HTMLAttributes<HTMLQuoteElement>, \"color\">"
+    - "VariantProps<typeof quoteVariants>"
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+        - xl
+      default: md
+      on: Quote
+    color:
+      kind: enum
+      options:
+        - default
+        - muted
+        - accent
+      default: default
+      on: Quote
+  variantSource: cva
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - class-variance-authority
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-quote--default
+  storybookTitle: Components/Quote
+  docsId: components-quote--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: e61f900e390e
+  factsHash: "1a61a7972f80"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A short, inline quotation - renders the native q element, which browsers add quotation marks to automatically."
+useWhen:
+  - "quoting a short phrase or sentence inline within surrounding text"
+useInstead:
+  - id: blockquote
+    when: "the quotation is long enough to stand as its own block, especially with attribution"
+  - id: text
+    when: "the content is not actually a quotation"
+related:
+  - blockquote
+  - text
+a11y:
+  notes:
+    - "Renders the native q element - browsers insert quotation marks automatically via default CSS, so do not add literal quote characters in the children or they will be doubled."
+  radixHandles: false
+pitfalls:
+  - "Wrapping the children in your own \"...\" characters double-quotes the text, since q already inserts marks via browser default styles."
+  - "color's default/muted/accent options are not shared with Blockquote's primary/neutral - the two quote-flavored primitives use different color vocabularies."
+canonicalSnippet: |
+  import { Quote } from "@adres/mgda-ui"
+
+  <p>
+    As the saying goes, <Quote>less is more</Quote>.
+  </p>
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: e61f900e390e
+---
+
+## Usage
+
+`Quote` is for a short quotation embedded inline within a sentence - it
+renders the native `<q>` element, so the browser adds quotation marks
+automatically rather than the component inserting literal characters. Do not
+wrap the children in your own quote marks, or they will be doubled.
+
+Reach for `Blockquote` instead once the quotation is long enough to stand on
+its own as a block, especially with attribution.

package/knowledge/radio-card.md

@@ -0,0 +1,172 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: radio-card
+  sourceFile: packages/design-system/src/components/radio-card.tsx
+  client: true
+  category: web-app-form-controls
+  categoryFromBarrel: web-app-form-controls
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: RadioCard
+      kind: component
+      typeText: "ForwardRefExoticComponent<RadioCardProps & RefAttributes<HTMLButtonElement>>"
+    - name: RadioCardDescription
+      kind: component
+      typeText: "ForwardRefExoticComponent<HTMLAttributes<HTMLParagraphElement> & RefAttributes<HTMLParagraphElement>>"
+    - name: RadioCardGroup
+      kind: component
+      typeText: "ForwardRefExoticComponent<RadioCardGroupProps & RefAttributes<HTMLDivElement>>"
+    - name: RadioCardGroupProps
+      kind: type
+    - name: RadioCardIcon
+      kind: component
+      typeText: "ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>>"
+    - name: RadioCardOrientation
+      kind: type
+    - name: RadioCardProps
+      kind: type
+    - name: RadioCardSize
+      kind: type
+    - name: RadioCardTitle
+      kind: component
+      typeText: "ForwardRefExoticComponent<HTMLAttributes<HTMLParagraphElement> & RefAttributes<HTMLParagraphElement>>"
+  primaryExport: RadioCard
+  subcomponents:
+    - RadioCardDescription
+    - RadioCardGroup
+    - RadioCardIcon
+    - RadioCardTitle
+  props:
+    RadioCard:
+      - name: size
+        type: RadioCardSize
+        required: false
+        declaredIn: self
+        variantKey: true
+    RadioCardGroup:
+      - name: compact
+        type: boolean
+        required: false
+        declaredIn: self
+      - name: orientation
+        type: RadioCardOrientation
+        required: false
+        declaredIn: self
+      - name: size
+        type: RadioCardSize
+        required: false
+        declaredIn: self
+        variantKey: true
+  extendsProps:
+    - "React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>"
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - base
+        - lg
+        - xl
+      default: base
+      on: RadioCard
+  variantSource: cva
+  compoundVariants: []
+  sizeMaps:
+    - COMPACT_LAYOUT
+    - INDICATOR_SIZE
+  dataSlots:
+    - radio-card-icon
+    - radio-card-off
+    - radio-card-on
+    - radio-card-title
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - "@radix-ui/react-radio-group"
+      - class-variance-authority
+      - lucide-react
+      - react
+  contexts:
+    - name: RadioCardGroupContext
+      type: RadioCardGroupContext
+      default: null
+  stories:
+    - exportName: Default
+      id: components-radiocard--default
+  storybookTitle: Components/RadioCard
+  docsId: components-radiocard--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "37b2d466668c"
+  factsHash: "88b41ad8dceb"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A large clickable card acting as a radio button - a bordered surface with a title/description and a trailing indicator, for single-select option grids."
+useWhen:
+  - "presenting mutually-exclusive options as prominent cards rather than plain radio buttons - pricing tiers, plan selection, any single choice worth describing"
+useInstead:
+  - id: radio-group
+    when: "a compact list of options fits plain radio buttons and labels better than a full card"
+  - id: checkbox-card
+    when: "more than one option can be selected at once"
+related:
+  - radio-group
+  - checkbox-card
+a11y:
+  notes:
+    - "The actual Radix radio item is visually hidden (sr-only) inside a real label, so clicking anywhere on the card selects it, and the accessible name comes from RadioCardTitle/RadioCardDescription's text content."
+    - "RadioCardGroup is a real Radix RadioGroup.Root, so it already provides single-select group semantics and roving-tabindex - no extra role or ARIA is needed beyond what is built in."
+  keyboard:
+    - "Native Radix radio-group keyboard behavior: arrow keys move selection between cards, Tab enters or exits the group once."
+  radixHandles: true
+pitfalls:
+  - "size options include xl, unlike CheckboxCard which stops at lg - the two sibling card patterns do not share an identical size scale."
+  - "RadioCardIcon exists specifically for an optional leading icon and drives its own checked-state color via data-slot - a plain icon element dropped in without RadioCardIcon will not pick up the selected-state tint."
+  - "compact mode collapses the cards into a connected strip (shared borders, only the first and last corners rounded), the same pattern CheckboxCard uses - size alone does not change this shape."
+canonicalSnippet: |
+  import { RadioCard, RadioCardDescription, RadioCardGroup, RadioCardTitle } from "@adres/mgda-ui"
+
+  <RadioCardGroup defaultValue="monthly" className="ax:max-w-md">
+    <RadioCard value="monthly">
+      <RadioCardTitle>Monthly</RadioCardTitle>
+      <RadioCardDescription>Pay as you go each month.</RadioCardDescription>
+    </RadioCard>
+    <RadioCard value="yearly">
+      <RadioCardTitle>Yearly</RadioCardTitle>
+      <RadioCardDescription>Save 20% with annual billing.</RadioCardDescription>
+    </RadioCard>
+  </RadioCardGroup>
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: "37b2d466668c"
+---
+
+## Usage
+
+`RadioCard` turns a radio option into a full clickable card - reach for it
+when mutually-exclusive choices deserve more visual weight than plain radio
+buttons (pricing tiers, plan selection, any single choice worth describing).
+For a multi-select version of the same pattern, use `CheckboxCard` instead.
+
+`RadioCardGroup` is a real Radix `RadioGroup.Root`, so `value`,
+`defaultValue`, and `onValueChange` all work exactly as they would on a plain
+`RadioGroup` - the group already provides single-select semantics and
+roving-tabindex keyboard navigation.
+
+Set `compact` to collapse the cards into a connected strip with shared
+borders instead of a spaced grid, the same pattern `CheckboxCard` uses.
+
+## Anatomy
+
+| Part | Role |
+| --- | --- |
+| `RadioCardGroup` | The Radix RadioGroup root. Owns `size`, `compact`, `orientation`, plus the usual `value`/`onValueChange`. |
+| `RadioCard` | One card. Wraps a visually-hidden Radix radio item in a real `<label>`, so the whole card is the click target. |
+| `RadioCardIcon` | Optional leading icon. Its `data-slot` drives the checked-state color tint. |
+| `RadioCardTitle` | The card's heading. Same checked-state tint mechanism as `RadioCardIcon`. |
+| `RadioCardDescription` | Supporting text below the title. |