@adres/mgda-ui 0.0.0-stage → 0.0.2

package/knowledge/avatar.md

@@ -0,0 +1,158 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: avatar
+  sourceFile: packages/design-system/src/components/avatar.tsx
+  client: true
+  category: web-app-core-primitives
+  categoryFromBarrel: web-app-core-primitives
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Avatar
+      kind: component
+      typeText: "ForwardRefExoticComponent<AvatarProps & RefAttributes<HTMLSpanElement>>"
+    - name: AvatarFallback
+      kind: component
+      typeText: "ForwardRefExoticComponent<Omit<AvatarFallbackProps & RefAttributes<HTMLSpanElement>, \"ref\"> & RefAttributes<HTMLSpanElement>>"
+    - name: AvatarFallbackProps
+      kind: type
+    - name: AvatarImage
+      kind: component
+      typeText: "ForwardRefExoticComponent<Omit<AvatarImageProps & RefAttributes<HTMLImageElement>, \"ref\"> & RefAttributes<HTMLImageElement>>"
+    - name: AvatarImageProps
+      kind: type
+    - name: AvatarProps
+      kind: type
+    - name: AvatarSize
+      kind: type
+    - name: AvatarStack
+      kind: component
+      typeText: "ForwardRefExoticComponent<AvatarStackProps & RefAttributes<HTMLDivElement>>"
+    - name: AvatarStackProps
+      kind: type
+  primaryExport: Avatar
+  subcomponents:
+    - AvatarFallback
+    - AvatarImage
+    - AvatarStack
+  props:
+    Avatar:
+      - name: size
+        type: "\"2xl\" | \"lg\" | \"md\" | \"sm\" | \"xl\" | \"xs\""
+        required: false
+        declaredIn: self
+        variantKey: true
+    AvatarStack:
+      - name: max
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Maximum number of children to render before collapsing the remainder into a `+N` fallback chip. When omitted, every child is shown."
+      - name: size
+        type: AvatarSize
+        required: false
+        declaredIn: self
+        doc: "Size applied to every Avatar child via context. Individual children can still override with their own `size` prop."
+        variantKey: true
+  extendsProps:
+    - "React.ComponentPropsWithoutRef<typeof AvatarPrimitive.Root>"
+    - "VariantProps<typeof avatarVariants>"
+  variants:
+    size:
+      kind: enum
+      options:
+        - xs
+        - sm
+        - md
+        - lg
+        - xl
+        - "2xl"
+      default: md
+      on: Avatar
+  variantSource: cva
+  compoundVariants: []
+  sizeMaps:
+    - STACK_OVERLAP
+  dataSlots:
+    - avatar
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - "@radix-ui/react-avatar"
+      - class-variance-authority
+      - react
+  contexts:
+    - name: AvatarStackContext
+      type: "{ size?: AvatarSize }"
+      default: null
+  stories:
+    - exportName: Default
+      id: components-avatar--default
+    - exportName: Fallback
+      id: components-avatar--fallback
+    - exportName: Stack
+      id: components-avatar--stack
+  storybookTitle: Components/Avatar
+  docsId: components-avatar--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: e7e5d86e9f90
+  factsHash: "6feb1a01b8e3"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A circular user or entity image with an automatic fallback (initials or icon), plus AvatarStack for overlapping groups."
+useWhen:
+  - "representing a person, team, or entity with a photo, with a graceful fallback when the image fails or has not loaded"
+  - "showing a group of collaborators, attendees, or contacts as an overlapping stack (AvatarStack)"
+useInstead:
+  - id: badge
+    when: "you need a small status indicator, not an image or initials"
+a11y:
+  notes:
+    - "AvatarImage renders nothing until the image loads, and AvatarFallback fills the gap during load or on error - always render both, or the avatar goes blank when the image can't load."
+    - "AvatarFallback carries no accessible name of its own - give the outer Avatar (or a wrapping element) an aria-label when the fallback content (initials or an icon) is not context enough on its own."
+  radixHandles: true
+pitfalls:
+  - "AvatarImage shows nothing at all while loading or on error, never a native broken-image glyph - Radix swaps straight to AvatarFallback, so both must be rendered as siblings or the avatar renders empty."
+  - "size lives on Avatar (or is inherited from an AvatarStack ancestor via context) - AvatarImage and AvatarFallback have no size prop of their own; they just fill whatever size Avatar renders at."
+  - "AvatarStack's max counts the fallback chip itself: visibleCount is max - 1, so max={1} renders zero real avatars plus a single \"+N\" chip - pass max >= 2 for a stack that should still show at least one real avatar."
+canonicalSnippet: |
+  import { Avatar, AvatarFallback, AvatarImage } from "@adres/mgda-ui"
+
+  <Avatar size="md">
+    <AvatarImage src="/avatars/jane.jpg" alt="Jane Cooper" />
+    <AvatarFallback>JC</AvatarFallback>
+  </Avatar>
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: e7e5d86e9f90
+---
+
+## Usage
+
+Always render `AvatarImage` and `AvatarFallback` together: Radix shows the
+fallback automatically while the image loads and if it fails, and shows the
+image once it succeeds - there's no in-between state where nothing renders as
+long as both are present.
+
+`size` lives on `Avatar` and cascades to `AvatarImage`/`AvatarFallback`
+automatically since they simply fill the parent's dimensions; set it once on
+the root rather than trying to size the image or fallback directly.
+
+Reach for `AvatarStack` for a group of collaborators, attendees, or contacts
+shown as overlapping circles - it sets `size` on every child `Avatar` via
+context (so you don't repeat it) and, when `max` is given and the group
+exceeds it, collapses the remainder into a "+N" `AvatarFallback` chip.
+
+## Anatomy
+
+| Part | Role |
+| --- | --- |
+| `Avatar` | The root. Owns `size`, or inherits it from an `AvatarStack` ancestor via context. |
+| `AvatarImage` | The photo. Renders only once it has loaded successfully. |
+| `AvatarFallback` | Shown while the image is loading or has errored - typically initials or an icon. |
+| `AvatarStack` | An overlapping horizontal group. Provides `size` to every child `Avatar` via context and can collapse overflow into a "+N" `AvatarFallback` chip. |

package/knowledge/badge.md

@@ -0,0 +1,172 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: badge
+  sourceFile: packages/design-system/src/components/badge.tsx
+  client: true
+  category: web-app-core-primitives
+  categoryFromBarrel: web-app-core-primitives
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Badge
+      kind: component
+      typeText: "ForwardRefExoticComponent<BadgeProps & RefAttributes<HTMLSpanElement>>"
+    - name: BadgeProps
+      kind: type
+    - name: badgeVariants
+      kind: variants
+      typeText: "(props?: (ConfigVariants<{ variant: { default: string; secondary: string; outline: string; muted: string; success: string; warning: string; destructive: string; accent: string; }; size: { sm: string; base: string; lg: st...[truncated]"
+  primaryExport: Badge
+  subcomponents: []
+  props:
+    Badge:
+      - name: size
+        type: "\"base\" | \"lg\" | \"sm\""
+        required: false
+        declaredIn: self
+        variantKey: true
+      - name: variant
+        type: "\"accent\" | \"default\" | \"destructive\" | \"muted\" | \"outline\" | \"secondary\" | \"success\" | \"warning\""
+        required: false
+        declaredIn: self
+        variantKey: true
+  extendsProps:
+    - "React.HTMLAttributes<HTMLSpanElement>"
+    - "VariantProps<typeof badgeVariants>"
+  variants:
+    variant:
+      kind: enum
+      options:
+        - default
+        - secondary
+        - outline
+        - muted
+        - success
+        - warning
+        - destructive
+        - accent
+      default: default
+      on: Badge
+    size:
+      kind: enum
+      options:
+        - sm
+        - base
+        - lg
+      default: base
+      on: Badge
+  variantSource: cva
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots:
+    - badge
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - class-variance-authority
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-badge--default
+    - exportName: Secondary
+      id: components-badge--secondary
+    - exportName: Success
+      id: components-badge--success
+  storybookTitle: Components/Badge
+  docsId: components-badge--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: d42002d6a70f
+  factsHash: a8f61aa739f6
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A small, non-interactive chip that labels status, category or a count."
+useWhen:
+  - "labelling state on a row or card - active, pending, overdue"
+  - "showing a small count, where a single digit should read as a circle"
+  - "tagging a category or type inline with text"
+useInstead:
+  - id: button
+    when: "the chip is interactive - it triggers an action or opens a menu"
+  - id: alert
+    when: "the message is a banner-level notification rather than an inline label"
+  - id: countdown-pill
+    when: "the label expresses time remaining and should tick down"
+related:
+  - alert
+  - countdown-pill
+  - button
+  - text
+tokens:
+  - "--radius-badge"
+  - "--primary-weaker"
+  - "--primary-foreground"
+  - "--secondary-weaker"
+  - "--secondary-foreground"
+  - "--neutral-weakest"
+  - "--neutral-foreground"
+  - "--success-weakest"
+  - "--success-foreground"
+  - "--warning-weakest"
+  - "--warning-foreground"
+  - "--destructive-weakest"
+  - "--destructive-foreground"
+  - "--accent-weakest"
+  - "--accent-foreground"
+  - "--border"
+  - "--ring"
+a11y:
+  notes:
+    - "Badge renders a plain span with no implicit ARIA role, so it contributes text content and nothing else."
+    - "Colour must not be the only carrier of meaning. A red badge reading \"3\" says nothing to a screen reader about being errors, so put the meaning in the text or in an accessible name on the surrounding control (WCAG 1.4.1)."
+  requiredProps:
+    - "none, but if the badge is the only indicator of a state, the meaning must appear in text somewhere"
+  keyboard:
+    - "Not focusable, by design. It takes no part in tab order."
+  radixHandles: false
+pitfalls:
+  - "Badge is a span, so it is not clickable or focusable. The base classes include a focus-visible ring, which makes it look like it could be interactive, but a span receives no focus without tabIndex. Adding onClick produces a mouse-only control that keyboard users cannot reach: use Button instead."
+  - "The default variant is a primary tint, not a neutral grey. For a plain, unemphatic chip reach for muted, otherwise every badge on the page competes with the primary action."
+  - "min-w on each size equals that size's box height, so single-character content renders as a circle and longer content stretches into a stadium. That is deliberate for counts, but it means a one-character label will not look the same shape as a two-character one."
+rtl: "Safe. Layout is inline-flex with gap and logical padding utilities, so it mirrors without changes."
+brandNotes: "Chip radius comes from --radius-badge alone. A brand that sets it fully round gets the circular count treatment the min-w sizing is tuned for; a brand that sets it small gets rectangular tags from the same component."
+canonicalSnippet: |
+  import { Badge } from "@adres/mgda-ui"
+
+  <Badge variant="success" size="base">Active</Badge>
+reviewedAt: 2026-08-19
+reviewedAgainstContractHash: d42002d6a70f
+---
+
+## Usage
+
+Badge is a label, not a control. It answers "what state is this row in" at a glance,
+and it is deliberately inert: no focus, no click, no role.
+
+The eight variants map to semantic roles rather than colours, so `success` stays
+legible in both light and dark without a `dark:` override. Each soft-filled variant
+uses a `weaker` or `weakest` emphasis alias that auto-inverts to a deep tint in dark
+mode, which is why the `-foreground` pair keeps its contrast in both.
+
+Reach for `muted` as the neutral default in dense UI. Save `default` for the one
+badge that should draw the eye, and treat `destructive` and `warning` as real signals
+rather than decoration.
+
+### Counts
+
+The `min-w` on every size matches its own box height, so a single digit renders as a
+circle:
+
+```tsx
+<Badge variant="destructive" size="sm">3</Badge>
+```
+
+Two or more characters expand past the circle into a stadium. That is the intended
+behaviour for notification counts, but it does mean badge width is content-dependent,
+so a column of counts will not align unless you constrain it yourself.

package/knowledge/bar-graph.md

@@ -0,0 +1,167 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: bar-graph
+  sourceFile: packages/design-system/src/components/bar-graph.tsx
+  client: true
+  category: web-app-patterns
+  categoryFromBarrel: web-app-patterns
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: BarGraph
+      kind: component
+      typeText: "ForwardRefExoticComponent<BarGraphProps & RefAttributes<HTMLDivElement>>"
+    - name: BarGraphDirection
+      kind: type
+    - name: BarGraphItem
+      kind: type
+    - name: BarGraphProps
+      kind: type
+    - name: BarGraphSize
+      kind: type
+  primaryExport: BarGraph
+  subcomponents: []
+  props:
+    BarGraph:
+      - name: bars
+        type: "BarGraphItem[]"
+        required: true
+        declaredIn: self
+        doc: "One item per bar, rendered in order."
+      - name: direction
+        type: BarGraphDirection
+        required: false
+        declaredIn: self
+        doc: "Growth direction. `horizontal` grows left → right (default); `vertical` grows bottom → top."
+      - name: labelAlign
+        type: "\"left\" | \"right\""
+        required: false
+        declaredIn: self
+        doc: "Horizontal-mode label alignment within its fixed-width column. `right` (default) sets a shared axis flush against the bars; `left` aligns with a left-aligned heading above the chart instead. No effect in `vertical` mode (labels there are centred under each bar)."
+      - name: max
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Ceiling value - each bar fills to `value / max`. Omit to let the tallest bar reach 100 % (relative comparison). Pass explicitly when bars are fractions of a known whole."
+      - name: showCount
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Render the raw value count beside / above each bar. Defaults to `true`."
+      - name: showPct
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Render the computed percentage beside / above each bar. Defaults to `true`."
+      - name: size
+        type: BarGraphSize
+        required: false
+        declaredIn: self
+        doc: "Visual density: drives bar thickness, chart height, and type scale."
+  extendsProps:
+    - "React.HTMLAttributes<HTMLDivElement>"
+  variants:
+    direction:
+      kind: enum
+      options:
+        - horizontal
+        - vertical
+      default: horizontal
+      on: BarGraph
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+      default: md
+      on: BarGraph
+    labelAlign:
+      kind: enum
+      options:
+        - left
+        - right
+      default: right
+      on: BarGraph
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps:
+    - H_TRACK_H
+    - LABEL_CLS
+    - LABEL_W
+    - STAT_CLS
+    - V_CHART_H
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-bargraph--default
+    - exportName: Vertical
+      id: components-bargraph--vertical
+  storybookTitle: Components/BarGraph
+  docsId: components-bargraph--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "2d7c0dfc611a"
+  factsHash: "948a45cd5c9b"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A labeled bar chart, horizontal or vertical, comparing several categories' values against a shared or independent maximum."
+useWhen:
+  - "comparing several distinct categories' values side by side - a breakdown by status, a quarter-over-quarter comparison"
+useInstead:
+  - id: activity-rings
+    when: "the values are 2-4 nested progress metrics toward their own individual goals, not independent categories to compare"
+  - id: progress
+    when: "there is only one bar - a single determinate value, not a comparison across categories"
+related:
+  - activity-rings
+  - progress
+a11y:
+  notes:
+    - "Purely visual - no ARIA roles or labels are added automatically. Pair it with a visible heading, or wrap it with your own accessible description, since a screen reader has no built-in way to read out each bar's label and value from this markup alone."
+  radixHandles: false
+pitfalls:
+  - "max defaults to the tallest bar's own value, making every chart relative to itself - two BarGraphs meant to be visually comparable, e.g. side by side on a dashboard, need an explicit, shared max, or their scales silently differ."
+  - "color is a raw Tailwind background utility string (e.g. \"ax:bg-chart-1\") supplied per bar, not a semantic variant - there is no built-in palette cycling, so passing the same color to two bars makes them visually indistinguishable even though their labels differ."
+  - "direction=\"vertical\" and the default horizontal layout use different visual axes (bottom-to-top growth vs. left-to-right) - switching direction on an existing chart changes which size map actually controls the chart's dimensions, so re-check sizing after switching."
+canonicalSnippet: |
+  import { BarGraph } from "@adres/mgda-ui"
+
+  <BarGraph
+    bars={[
+      { label: "Compliant", value: 42, color: "ax:bg-success" },
+      { label: "At risk", value: 8, color: "ax:bg-warning" },
+    ]}
+  />
+reviewedAt: 2026-09-29
+reviewedAgainstContractHash: "2d7c0dfc611a"
+---
+
+## Usage
+
+`BarGraph` compares several distinct categories' values side by side - a
+status breakdown, a quarter-over-quarter comparison. Reach for
+`ActivityRings` instead when the values are 2-4 nested progress metrics
+toward their own individual goals rather than independent categories, and
+`Progress` when there is only one value and no comparison to make.
+
+`max` defaults to the tallest bar's own value, so a single chart always
+scales to fill its space - pass `max` explicitly when two charts need to
+stay visually comparable against the same scale, or when bars represent
+fractions of a known whole rather than a relative comparison.
+
+`direction="horizontal"` (default) grows bars left-to-right with a label
+column on the left; `direction="vertical"` grows bottom-to-top with labels
+underneath. `size` scales bar thickness, chart height, and type together.
+`showPct`/`showCount` independently toggle the two stat readouts next to
+each bar.

package/knowledge/bento-grid.md

@@ -0,0 +1,115 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: bento-grid
+  sourceFile: packages/design-system/src/components/bento-grid.tsx
+  client: false
+  category: layout
+  categoryFromBarrel: layout
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: BentoGrid
+      kind: component
+      typeText: "ForwardRefExoticComponent<BentoGridProps & RefAttributes<HTMLDivElement>>"
+    - name: BentoGridProps
+      kind: type
+    - name: BentoItem
+      kind: component
+      typeText: "ForwardRefExoticComponent<BentoItemProps & RefAttributes<HTMLDivElement>>"
+    - name: BentoItemProps
+      kind: type
+  primaryExport: BentoGrid
+  subcomponents:
+    - BentoItem
+  props:
+    BentoGrid:
+      - name: cols
+        type: "2 | 3 | 4"
+        required: false
+        declaredIn: self
+        doc: "Number of columns at all breakpoints. Default: 3."
+    BentoItem:
+      - name: colSpan
+        type: "1 | 2 | 3 | 4"
+        required: false
+        declaredIn: self
+        doc: "How many grid columns this cell spans. Default: 1."
+      - name: rowSpan
+        type: "1 | 2 | 3"
+        required: false
+        declaredIn: self
+        doc: "How many grid rows this cell spans. Default: 1."
+  extendsProps:
+    - "React.HTMLAttributes<HTMLDivElement>"
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-bentogrid--default
+  storybookTitle: Components/BentoGrid
+  docsId: components-bentogrid--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: a67a28506ba1
+  factsHash: f13f1b759a10
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A CSS grid layout for asymmetric dashboard/marketing tiles, where cells span different column and row counts."
+useWhen:
+  - "a dashboard or landing section mixes a hero tile with several smaller cards in one asymmetric grid"
+  - "you need column/row spans without hand-writing Tailwind grid classes for every breakpoint"
+useInstead:
+  - id: card
+    when: "you only need a single, uniform card and not a mixed-span grid layout"
+related:
+  - card
+a11y:
+  notes:
+    - "BentoGrid and BentoItem render plain divs with no implicit landmark or list semantics - if the tiles are a list of equivalent items, wrap them in a `<ul>`/`<li>` or add appropriate ARIA roles yourself."
+  radixHandles: false
+pitfalls:
+  - "cols and colSpan/rowSpan map to fixed literal Tailwind classes (e.g. grid-cols-3, col-span-2) rather than arbitrary values, so a colSpan larger than the grid's cols visually overflows rather than clamping - keep item spans <= the grid's cols."
+canonicalSnippet: |
+  import { BentoGrid, BentoItem } from "@adres/mgda-ui"
+
+  <BentoGrid cols={3} className="ax:max-w-3xl">
+    <BentoItem colSpan={2} className="ax:p-lg">Wide feature</BentoItem>
+    <BentoItem className="ax:p-lg">Side card</BentoItem>
+    <BentoItem className="ax:p-lg">Analytics</BentoItem>
+    <BentoItem colSpan={2} className="ax:p-lg">Reports</BentoItem>
+  </BentoGrid>
+reviewedAt: 2026-09-01
+reviewedAgainstContractHash: a67a28506ba1
+---
+
+## Usage
+
+`BentoGrid` lays out `BentoItem` cells in a CSS grid where individual cells can
+span more than one column or row, producing the mixed hero-tile-plus-cards
+layout common on dashboards and marketing pages ("bento box" grids). Set the
+grid's overall column count once with `cols` (2, 3, or 4), then give any
+`BentoItem` a larger footprint with `colSpan` (1-4) and `rowSpan` (1-3).
+
+Keep item spans within the grid's `cols` - a `BentoItem colSpan={4}` inside a
+`cols={3}` grid overflows the row rather than clamping to fit.
+
+## Anatomy
+
+- `BentoGrid` - the grid container. Sets `grid-cols-*` and a fixed gap; accepts
+  all standard `div` attributes via `React.HTMLAttributes<HTMLDivElement>`.
+- `BentoItem` - a single cell. Renders a rounded, bordered card (`bg-card`,
+  `border-border`) and applies `col-span-*`/`row-span-*` from its props.
+  Content (text, icons, charts) goes directly inside as children.