@adres/mgda-ui 0.0.0-stage → 0.0.2

package/knowledge/activity-rings.md

@@ -0,0 +1,123 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: activity-rings
+  sourceFile: packages/design-system/src/components/activity-rings.tsx
+  client: false
+  category: web-app-patterns
+  categoryFromBarrel: web-app-patterns
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: ActivityRing
+      kind: type
+    - name: ActivityRings
+      kind: component
+      typeText: "({ rings, size, strokeWidth, ariaLabel, }: ActivityRingsProps) => Element"
+    - name: ActivityRingsProps
+      kind: type
+  primaryExport: ActivityRings
+  subcomponents: []
+  props:
+    ActivityRings:
+      - name: ariaLabel
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Accessible label describing what the rings represent in aggregate."
+      - name: rings
+        type: "ActivityRing[]"
+        required: true
+        declaredIn: self
+        doc: "Rings rendered from the *outside in*. Pass 1-4 entries; the spacing is computed from the SVG box so a small set still looks balanced."
+      - name: size
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Visual diameter in CSS pixels. The internal SVG viewBox is always `0 0 120 120`; this prop just scales it."
+      - name: strokeWidth
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Stroke thickness for each ring in viewBox units. Defaults to 12."
+  extendsProps: []
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib: []
+    hooks: []
+    external:
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-activityrings--default
+    - exportName: SingleRing
+      id: components-activityrings--single-ring
+  storybookTitle: Components/ActivityRings
+  docsId: components-activityrings--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: a5e2d28bdfd3
+  factsHash: "3676e5cf0652"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "Concentric Apple-style progress arcs in a single SVG, for showing 2-4 simultaneous progress values at once."
+useWhen:
+  - "visualizing 2-4 related progress values together as one glanceable shape - a fitness-style summary, a multi-metric dashboard tile"
+useInstead:
+  - id: progress
+    when: "there is only one value to show - use Progress shape=\"ring\" instead, the single-arc equivalent"
+  - id: bar-graph
+    when: "comparing several distinct categories rather than 2-4 nested progress values toward their own individual goals"
+related:
+  - progress
+  - bar-graph
+a11y:
+  notes:
+    - "Renders role=\"img\" with a single ariaLabel describing the whole set - individual ring values are not exposed to assistive tech separately, so ariaLabel needs to summarize every ring's meaning and value in one sentence (e.g. \"Move 80%, Exercise 45%, Stand 100%\"), not just name the widget."
+  radixHandles: false
+pitfalls:
+  - "ActivityRings only knows about pct and className per ring - it computes no percentages and picks no colors itself; callers must already have turned domain data (course completion, fitness minutes) into a 0-1 fraction and a stroke class."
+  - "Rings render outside-in from the rings array in order - the first entry is the outermost, largest ring. Reordering the array changes which metric is visually biggest, not just its color."
+  - "This is a different component from Progress's shape=\"ring\" mode, where a previous single-arc component lived before being merged into Progress - ActivityRings only exists for the multi-ring case, not for showing just one value."
+canonicalSnippet: |
+  import { ActivityRings } from "@adres/mgda-ui"
+
+  const summary = "Move 80%, Exercise 45%, Stand 100%"
+
+  <ActivityRings
+    ariaLabel={summary}
+    rings={[
+      { pct: 0.8, className: "ax:stroke-chart-1" },
+      { pct: 0.45, className: "ax:stroke-chart-2" },
+      { pct: 1, className: "ax:stroke-chart-3" },
+    ]}
+  />
+reviewedAt: 2026-09-01
+reviewedAgainstContractHash: a5e2d28bdfd3
+---
+
+## Usage
+
+`ActivityRings` shows 2-4 related progress values together as one glanceable
+concentric shape - a fitness-style daily summary, a multi-metric dashboard
+tile. Reach for `Progress` with `shape="ring"` instead when there is only one
+value to show; that is the single-arc equivalent this component does not
+duplicate. Reach for `BarGraph` when the values are distinct categories being
+compared, not nested progress toward their own goals.
+
+The component is a pure visual primitive - it computes no percentages and
+assigns no colors. Compute each `pct` (a 0-1 fraction) and pick a stroke
+`className` per ring before passing them in. Rings render outside-in in
+array order, so the first entry is the largest, outermost ring - reordering
+changes which metric reads as biggest.
+
+`ariaLabel` is the only accessible description of the whole widget; since
+individual ring values are not separately exposed to assistive tech,
+summarize every ring's meaning and value in one sentence.

package/knowledge/alert.md

@@ -0,0 +1,184 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: alert
+  sourceFile: packages/design-system/src/components/alert.tsx
+  client: true
+  category: web-app-core-primitives
+  categoryFromBarrel: web-app-core-primitives
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Alert
+      kind: component
+      typeText: "ForwardRefExoticComponent<AlertProps & RefAttributes<HTMLDivElement>>"
+    - name: AlertDescription
+      kind: component
+      typeText: "ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>>"
+    - name: AlertProps
+      kind: type
+    - name: AlertSize
+      kind: type
+    - name: AlertTitle
+      kind: component
+      typeText: "ForwardRefExoticComponent<HTMLAttributes<HTMLHeadingElement> & RefAttributes<HTMLHeadingElement>>"
+  primaryExport: Alert
+  subcomponents:
+    - AlertDescription
+    - AlertTitle
+  props:
+    Alert:
+      - name: hideIcon
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Hide the leading icon AND snap content to the first column. Use when the alert appears inline next to another leading element that already conveys the meaning."
+      - name: icon
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Override the default variant icon with custom content (e.g. <Calendar />, <Sparkles />, <Lock />). The custom icon inherits the variant's color via the alert's `[&>svg]:text-*` selector - pass an SVG element. Remember to set `aria-hidden=\"true\"` on the icon yourself. Ignored when `hideIcon` is true."
+      - name: size
+        type: AlertSize
+        required: false
+        declaredIn: self
+        variantKey: true
+      - name: variant
+        type: "\"default\" | \"destructive\" | \"info\" | \"primary\" | \"success\" | \"warning\""
+        required: false
+        declaredIn: self
+        variantKey: true
+  extendsProps:
+    - "React.HTMLAttributes<HTMLDivElement>"
+    - "VariantProps<typeof alertVariants>"
+  variants:
+    variant:
+      kind: enum
+      options:
+        - default
+        - info
+        - primary
+        - success
+        - warning
+        - destructive
+      default: default
+      on: Alert
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+      default: md
+      on: Alert
+  variantSource: cva
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - class-variance-authority
+      - lucide-react
+      - react
+  contexts:
+    - name: AlertContext
+      type: "{ size: AlertSize }"
+      default: null
+  stories:
+    - exportName: Default
+      id: components-alert--default
+    - exportName: Success
+      id: components-alert--success
+    - exportName: Destructive
+      id: components-alert--destructive
+  storybookTitle: Components/Alert
+  docsId: components-alert--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "83fc1b1eacfe"
+  factsHash: f153284a377a
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A persistent, page or section-level message with a semantic color and leading icon - not for transient background-action feedback."
+useWhen:
+  - "surfacing a warning, error, success confirmation, or info message tied to a region of the page that should stay visible until dismissed or resolved"
+  - "explaining validation or system state above a form or panel"
+useInstead:
+  - id: toaster
+    when: "the message is transient feedback for something the user has already moved past - use toast() instead"
+  - id: empty-state
+    when: "there is no content at all, not a message about content"
+related:
+  - toaster
+  - badge
+tokens:
+  - "--primary-weakest"
+  - "--primary-weaker"
+  - "--primary-foreground"
+  - "--success-weakest"
+  - "--success-weaker"
+  - "--success-foreground"
+  - "--warning-weakest"
+  - "--warning-weaker"
+  - "--warning-foreground"
+  - "--destructive-weakest"
+  - "--destructive-weaker"
+  - "--destructive-foreground"
+  - "--card"
+  - "--foreground-strong"
+  - "--border"
+a11y:
+  notes:
+    - "role=\"alert\" is set unconditionally, which triggers an assertive screen-reader announcement the moment the element is inserted into the DOM - mounting an Alert dynamically (after an async action) announces it immediately; one already present at initial page load has no live announcement to trigger."
+    - "A custom icon passed via icon needs aria-hidden=\"true\" set by the caller - only the built-in variant icons get it automatically."
+  requiredProps:
+    - "AlertTitle is optional in the type system but should be included in practice - without it, an assertive announcement reads only the description, losing the headline."
+  keyboard:
+    - "Not interactive - no keyboard handling."
+  radixHandles: false
+pitfalls:
+  - "icon is ignored whenever hideIcon is true, so setting both has no visible effect - hideIcon wins."
+  - "AlertTitle and AlertDescription read their type scale from AlertContext, keyed to the parent Alert's size - they cannot be resized independently of it."
+  - "role=\"alert\" fires an assertive live-region announcement on mount - inserting several Alerts at once (e.g. a list of validation errors) announces all of them, which can overwhelm a screen reader user; consider one wrapping message for bulk validation instead."
+canonicalSnippet: |
+  import { Alert, AlertDescription, AlertTitle } from "@adres/mgda-ui"
+
+  <Alert variant="destructive">
+    <AlertTitle>Payment failed</AlertTitle>
+    <AlertDescription>Update your card details and try again.</AlertDescription>
+  </Alert>
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: "83fc1b1eacfe"
+---
+
+## Usage
+
+`Alert` is for a message tied to a region of the page that should stay visible
+- a validation summary above a form, a warning banner on a panel, a persistent
+success confirmation. It is not for transient feedback about something the
+user has already moved past; reach for `toast()` (`Toaster`) for that instead.
+
+`variant` picks both the color and the default leading icon: `default`/`info`
+are neutral, `primary` is an on-brand callout, and `success`/`warning`/
+`destructive` map to their respective severities. Override the icon with
+`icon`, or drop it entirely with `hideIcon` when the alert sits next to
+another element that already signals the same meaning.
+
+`size` (`sm`/`md`, default `md`) scales padding, gap, and the icon together
+with the type size of `AlertTitle`/`AlertDescription` - set it once on `Alert`
+rather than styling the sub-parts directly.
+
+## Anatomy
+
+| Part | Role |
+| --- | --- |
+| `Alert` | The container. Sets `role="alert"`, owns `variant`/`size`/`icon`/`hideIcon`, and renders the leading icon. |
+| `AlertTitle` | The headline. An `h5`, sized from the parent `Alert`'s `size` via context. |
+| `AlertDescription` | Supporting text. Renders a `div`, not a `p`, so it can host block-level children like lists or a button row. |
+
+`AlertContext` is why `AlertTitle`/`AlertDescription` never need their own
+`size` prop - they read it from the nearest `Alert` ancestor.

package/knowledge/answer-actions.md

@@ -0,0 +1,217 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: answer-actions
+  sourceFile: packages/design-system/src/components/answer-actions.tsx
+  client: true
+  category: web-app-ai
+  categoryFromBarrel: web-app-ai
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: AnswerActions
+      kind: component
+      typeText: "ForwardRefExoticComponent<AnswerActionsProps & RefAttributes<HTMLDivElement>>"
+    - name: AnswerActionsProps
+      kind: type
+    - name: AnswerFeedback
+      kind: type
+    - name: AnswerReport
+      kind: type
+    - name: FeedbackReasonChips
+      kind: component
+      typeText: "({ reasons, selected, onToggle, label, className, ...props }: FeedbackReasonChipsProps) => Element"
+    - name: FeedbackReasonChipsProps
+      kind: type
+  primaryExport: AnswerActions
+  subcomponents:
+    - FeedbackReasonChips
+  props:
+    AnswerActions:
+      - name: negativeReasons
+        type: "string[]"
+        required: true
+        declaredIn: self
+        doc: "Reasons offered after thumbs down; one or a comment is required to send."
+      - name: onCopyLink
+        type: "(() => void)"
+        required: false
+        declaredIn: self
+        doc: "Adds \"Copy link\" to the More menu."
+      - name: onFeedback
+        type: "((feedback: AnswerFeedback) => void)"
+        required: false
+        declaredIn: self
+        doc: "Sent feedback, for logging."
+      - name: onRegenerate
+        type: "(() => void)"
+        required: false
+        declaredIn: self
+      - name: onReport
+        type: "((report: AnswerReport) => void)"
+        required: false
+        declaredIn: self
+      - name: onUndo
+        type: "(() => void)"
+        required: false
+        declaredIn: self
+        doc: "The \"Undo\" link after sending was used."
+      - name: onVersionChange
+        type: "((version: number) => void)"
+        required: false
+        declaredIn: self
+      - name: positiveReasons
+        type: "string[]"
+        required: true
+        declaredIn: self
+        doc: "Reasons offered after thumbs up; optional to send."
+      - name: regenerateDisabled
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Keeps Regenerate in place but disabled, e.g. when no more versions can be made."
+      - name: regenerating
+        type: boolean
+        required: false
+        declaredIn: self
+      - name: reportDescription
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Who reads reports and what happens next."
+      - name: reportReasons
+        type: "{ value: string; label: string; }[]"
+        required: false
+        declaredIn: self
+        doc: "Adds \"Report a problem\" to the More menu, with these reasons."
+      - name: text
+        type: string
+        required: true
+        declaredIn: self
+        doc: "Text the Copy action copies (the visible version)."
+      - name: version
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Zero-based index of the visible version."
+      - name: versionCount
+        type: number
+        required: false
+        declaredIn: self
+    FeedbackReasonChips:
+      - name: label
+        type: string
+        required: true
+        declaredIn: self
+        doc: "Accessible name of the group."
+      - name: onToggle
+        type: "(reason: string) => void"
+        required: true
+        declaredIn: self
+      - name: reasons
+        type: "string[]"
+        required: true
+        declaredIn: self
+      - name: selected
+        type: "string[]"
+        required: true
+        declaredIn: self
+  extendsProps:
+    - "Omit<React.HTMLAttributes<HTMLDivElement>, \"onCopy\">"
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots:
+    - answer-actions
+  dependsOn:
+    internal:
+      - button
+      - dialog
+      - dropdown-menu
+      - input
+      - message-actions
+      - radio-group
+      - text
+      - text-link
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-answeractions--default
+    - exportName: WithVersions
+      id: components-answeractions--with-versions
+    - exportName: WithReport
+      id: components-answeractions--with-report
+  storybookTitle: Components/AnswerActions
+  docsId: components-answeractions--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "5504d1cb162b"
+  factsHash: "329e9db1fdd8"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: beta
+summary: "The full action row under an AI answer: copy, rate with a short reasons form, regenerate with a version pager, and report a problem, with undo for sent feedback."
+useWhen:
+  - "an assistant answer should collect feedback in one or two taps"
+  - "regenerated answers keep earlier versions people can page through"
+  - "people need a way to report a harmful or wrong answer"
+useInstead:
+  - id: message-actions
+    when: "only copy, thumbs and regenerate are needed, with no reasons form, versions or report"
+  - id: feedback-bar
+    when: "you only need one compact \"Was this helpful?\" prompt for a whole conversation or page"
+related:
+  - message-actions
+  - chat-message
+  - dialog
+a11y:
+  notes:
+    - "The row is role=\"toolbar\" labelled \"Answer actions\"; ratings are toggles with aria-pressed."
+    - "After a rating, focus moves to the first reason chip; reason chips are toggles in a labelled group."
+    - "The version count and the thanks line are polite live regions."
+    - "Report opens a dialog with a labelled radio group; Send stays disabled until a reason is picked."
+  radixHandles: true
+pitfalls:
+  - "Thumbs down requires a reason or a comment to send; thumbs up only offers the form (Skip)."
+  - "The More menu only appears with onCopyLink or reportReasons; pass reportDescription to say who reads reports."
+  - "The bar shows no toasts itself; confirm reports, undo or copied links from onReport, onUndo and onCopyLink."
+  - "Rating state is internal and resets on remount; key the bar by answer id."
+canonicalSnippet: |
+  import { AnswerActions } from "@adres/mgda-ui"
+
+  <AnswerActions
+    text={answer}
+    negativeReasons={["Wrong price", "Out of date"]}
+    positiveReasons={["Accurate", "Clear"]}
+    onFeedback={logFeedback}
+    onRegenerate={regenerate}
+  />
+reviewedAt: 2026-10-06
+reviewedAgainstContractHash: "5504d1cb162b"
+---
+
+## Usage
+
+`AnswerActions` builds on `MessageActions`. Copy copies `text`. A thumb opens a
+short form: reason chips from `negativeReasons` or `positiveReasons` and an
+optional comment. Down needs a reason or comment; up can be skipped. Sent
+feedback goes to `onFeedback` and shows a thanks line with Undo (`onUndo`).
+
+With `versionCount` above 1 and `onVersionChange`, a pager steps through
+regenerated versions; `regenerating` spins Regenerate and
+`regenerateDisabled` keeps it visible but off. `onCopyLink` and
+`reportReasons` fill the More menu; Report opens a dialog whose
+`reportDescription` says who reads reports, and `onReport` receives the
+reason and details.
+
+## Anatomy
+
+- `AnswerActions` - toolbar, reasons form, thanks line and report dialog.
+- `FeedbackReasonChips` - multi-select reason toggles, for custom feedback forms.

package/knowledge/aspect-ratio.md

@@ -0,0 +1,82 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: aspect-ratio
+  sourceFile: packages/design-system/src/components/aspect-ratio.tsx
+  client: true
+  category: web-app-core-primitives
+  categoryFromBarrel: web-app-core-primitives
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: AspectRatio
+      kind: component
+      radixSource: "@radix-ui/react-aspect-ratio#Root"
+      typeText: "ForwardRefExoticComponent<AspectRatioProps & RefAttributes<HTMLDivElement>>"
+  primaryExport: AspectRatio
+  subcomponents: []
+  props: {}
+  extendsProps: []
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib: []
+    hooks: []
+    external:
+      - "@radix-ui/react-aspect-ratio"
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-aspectratio--default
+    - exportName: Square
+      id: components-aspectratio--square
+  storybookTitle: Components/AspectRatio
+  docsId: components-aspectratio--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: a1a3f872053d
+  factsHash: d3670c113e24
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "Constrains a child to a fixed width-to-height ratio, a direct Radix Root re-export."
+useWhen:
+  - "an image, video, or map embed needs to keep a fixed aspect ratio (16/9, 1/1, 4/3) as its container resizes"
+a11y:
+  notes:
+    - "AspectRatio only controls layout - it adds no role or label, so the accessibility of its child (e.g. an img's alt text) is entirely on the caller."
+  radixHandles: true
+pitfalls:
+  - "AspectRatio is re-exported directly from Radix (export const AspectRatio = AspectRatioPrimitive.Root), so the extractor captured no props or extends clause at all - the validator will not let canonicalSnippet demonstrate the ratio prop even though it is the component's entire purpose. See the ## Usage example below for the real usage, written outside the machine-checked snippet."
+  - "The child must fill the container (typically w-full h-full plus object-cover for an image) - AspectRatio only sizes its own wrapper, not the child, which will not visually respect the ratio on its own."
+canonicalSnippet: |
+  import { AspectRatio } from "@adres/mgda-ui"
+
+  <AspectRatio>
+    <img src="/cover.jpg" alt="" className="ax:h-full ax:w-full ax:object-cover" />
+  </AspectRatio>
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: a1a3f872053d
+---
+
+## Usage
+
+`AspectRatio` wraps a child in a box that maintains a fixed width-to-height
+ratio as its container resizes - most commonly an image or video. Pass
+`ratio` (a number, width divided by height) and size the child to fill the
+wrapper:
+
+```tsx
+<AspectRatio ratio={16 / 9}>
+  <img src="/cover.jpg" alt="" className="ax:h-full ax:w-full ax:object-cover" />
+</AspectRatio>
+```
+
+`ratio` cannot appear in this file's machine-checked `canonicalSnippet` above
+- see the pitfall on why - but it is the whole reason to reach for this
+component; use the example above, not the bare one in the frontmatter, as the
+real usage reference.