@adres/mgda-ui 0.0.0-stage → 0.0.1

package/knowledge/radio-group.md

@@ -0,0 +1,135 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: radio-group
+  sourceFile: packages/design-system/src/components/radio-group.tsx
+  client: true
+  category: web-app-form-controls
+  categoryFromBarrel: web-app-form-controls
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: RadioGroup
+      kind: component
+      typeText: "ForwardRefExoticComponent<Omit<RadioGroupProps & RefAttributes<HTMLDivElement>, \"ref\"> & RefAttributes<HTMLDivElement>>"
+    - name: RadioGroupItem
+      kind: component
+      typeText: "ForwardRefExoticComponent<RadioGroupItemProps & RefAttributes<HTMLButtonElement>>"
+    - name: RadioGroupItemProps
+      kind: type
+  primaryExport: RadioGroup
+  subcomponents:
+    - RadioGroupItem
+  props:
+    RadioGroupItem:
+      - name: size
+        type: "\"base\" | \"lg\" | \"sm\""
+        required: false
+        declaredIn: self
+        variantKey: true
+  extendsProps: []
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - base
+        - lg
+      default: base
+      on: RadioGroup
+  variantSource: cva
+  compoundVariants: []
+  sizeMaps:
+    - INDICATOR_SIZE
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - "@radix-ui/react-radio-group"
+      - class-variance-authority
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-radiogroup--default
+  storybookTitle: Components/RadioGroup
+  docsId: components-radiogroup--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: fba286141750
+  factsHash: f99370fdd642
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A set of mutually-exclusive radio buttons, built on Radix RadioGroup."
+useWhen:
+  - "a compact list of mutually-exclusive options, each paired with its own visible label"
+useInstead:
+  - id: radio-card
+    when: "the options deserve more visual weight than a plain dot and label row"
+  - id: segmented-control
+    when: "the options read better as a single connected control with a sliding indicator, not a stacked list"
+related:
+  - radio-card
+  - segmented-control
+a11y:
+  notes:
+    - "RadioGroupItem has no built-in label - pair each one with a real Label pointing at a matching id, the same pattern Checkbox uses."
+  keyboard:
+    - "Native Radix radio-group keyboard behavior: arrow keys move selection between items in the group, Tab enters or exits the group once."
+  radixHandles: true
+pitfalls:
+  - "RadioGroup renders no visible layout beyond a vertical grid gap - laying out each RadioGroupItem next to its Label (each in its own row) is left entirely to the consumer, unlike RadioCard, which bundles the label into the card."
+  - "size lives on RadioGroupItem, not RadioGroup - setting it once on the group has no effect; each item needs its own size prop for a consistent look."
+  - "value/defaultValue/onValueChange on RadioGroup, and value/id on RadioGroupItem, are all real Radix props, but the extractor did not resolve them into derived.props/extendsProps for this file (a bare pass-through Root plus inline generics) - the machine-checked canonicalSnippet below is intentionally minimal because of this; see the fuller example in ## Usage."
+canonicalSnippet: |
+  import { RadioGroup, RadioGroupItem } from "@adres/mgda-ui"
+
+  <RadioGroup>
+    <RadioGroupItem size="base" />
+  </RadioGroup>
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: fba286141750
+---
+
+## Usage
+
+`RadioGroup` is a set of mutually-exclusive options, each item paired with
+its own visible label - reach for `RadioCard` instead when the options
+deserve more visual weight, or `SegmentedControl` when they read better as
+one connected control with a sliding indicator rather than a stacked list.
+
+`value`/`defaultValue`/`onValueChange` on `RadioGroup`, and `value`/`id` on
+each `RadioGroupItem`, are all real Radix props - they just cannot appear in
+this file's machine-checked `canonicalSnippet` above (see the pitfall on
+why). The real, recommended usage pairs each item with a `Label`:
+
+```tsx
+import { Label, RadioGroup, RadioGroupItem } from "@adres/mgda-ui"
+
+<RadioGroup defaultValue="comfortable">
+  <div className="ax:flex ax:items-center ax:gap-sm">
+    <RadioGroupItem value="default" id="r1" />
+    <Label htmlFor="r1">Default</Label>
+  </div>
+  <div className="ax:flex ax:items-center ax:gap-sm">
+    <RadioGroupItem value="comfortable" id="r2" />
+    <Label htmlFor="r2">Comfortable</Label>
+  </div>
+</RadioGroup>
+```
+
+`RadioGroup` itself only renders a vertical gap - laying out each item next
+to its label, as above, is left to the consumer, unlike `RadioCard`, which
+bundles the label into the card itself.
+
+## Anatomy
+
+| Part | Role |
+| --- | --- |
+| `RadioGroup` | Root. Holds the selected value. A thin wrapper around Radix `Root` that adds only a vertical grid gap. |
+| `RadioGroupItem` | One selectable dot. `size` scales it; has no label of its own. |

package/knowledge/reasoning.md

@@ -0,0 +1,142 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: reasoning
+  sourceFile: packages/design-system/src/components/reasoning.tsx
+  client: true
+  category: web-app-ai
+  categoryFromBarrel: web-app-ai
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Reasoning
+      kind: component
+      typeText: "ForwardRefExoticComponent<ReasoningProps & RefAttributes<HTMLDivElement>>"
+    - name: ReasoningContent
+      kind: component
+      typeText: "ForwardRefExoticComponent<ReasoningContentProps & RefAttributes<HTMLDivElement>>"
+    - name: ReasoningContentProps
+      kind: type
+    - name: ReasoningProps
+      kind: type
+    - name: ReasoningTrigger
+      kind: component
+      typeText: "ForwardRefExoticComponent<ReasoningTriggerProps & RefAttributes<HTMLButtonElement>>"
+    - name: ReasoningTriggerProps
+      kind: type
+  primaryExport: Reasoning
+  subcomponents:
+    - ReasoningContent
+    - ReasoningTrigger
+  props:
+    Reasoning:
+      - name: defaultOpen
+        type: boolean
+        required: false
+        declaredIn: self
+      - name: onOpenChange
+        type: "((open: boolean) => void)"
+        required: false
+        declaredIn: self
+      - name: open
+        type: boolean
+        required: false
+        declaredIn: self
+      - name: streaming
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "True while the model is still reasoning: the panel opens, then closes when it turns false."
+    ReasoningContent:
+      - name: contentClassName
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Extra classes for the inner text block, inside the animated wrapper."
+  extendsProps:
+    - "React.HTMLAttributes<HTMLDivElement>"
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots:
+    - reasoning
+    - reasoning-content
+  dependsOn:
+    internal:
+      - shimmer-text
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts:
+    - name: ReasoningContext
+      type: ReasoningContextValue
+      default: null
+  stories:
+    - exportName: Default
+      id: components-reasoning--default
+    - exportName: Streaming
+      id: components-reasoning--streaming
+  storybookTitle: Components/Reasoning
+  docsId: components-reasoning--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: aa42ec0be8b4
+  factsHash: "0d9818571780"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: beta
+summary: "The model's thinking behind an answer in a collapsible panel that opens while it streams and folds away once the answer is ready."
+useWhen:
+  - "a reasoning model streams its thinking before the answer and people may want to read it"
+  - "a finished answer should keep its reasoning available but out of the way"
+useInstead:
+  - id: chain-of-thought
+    when: "the reasoning is a set of discrete steps, each with its own detail"
+  - id: thinking-steps
+    when: "only progress matters: a running summary over named steps"
+related:
+  - chat-message
+  - chain-of-thought
+  - thinking-steps
+a11y:
+  notes:
+    - "The trigger is a button with aria-expanded and aria-controls, so the panel toggles with Enter or Space."
+    - "Closed content stays in the DOM for the height animation but is inert and aria-hidden, so it cannot be focused or read."
+    - "The shimmer while streaming is decorative and stops under reduced motion; the label text says what is happening."
+  radixHandles: false
+pitfalls:
+  - "The panel follows streaming edges: it opens when streaming turns true and closes when it turns false. A manual toggle mid-stream holds until the next edge."
+  - "A controlled open always wins; handle streaming yourself when you pass open."
+  - "There is no built-in markdown; render rich reasoning yourself and pass it as children."
+  - "Change the trigger label with the state, such as \"Thinking\" while streaming and \"Thought for 4 seconds\" after."
+canonicalSnippet: |
+  import { Reasoning, ReasoningTrigger, ReasoningContent } from "@adres/mgda-ui"
+
+  <Reasoning streaming={thinking}>
+    <ReasoningTrigger>{thinking ? "Thinking" : "Show reasoning"}</ReasoningTrigger>
+    <ReasoningContent>{reasoningText}</ReasoningContent>
+  </Reasoning>
+reviewedAt: 2026-10-06
+reviewedAgainstContractHash: aa42ec0be8b4
+---
+
+## Usage
+
+`Reasoning` holds the open state. `ReasoningTrigger` is the muted label with
+a chevron that toggles it, and `ReasoningContent` is the reasoning text beside
+a thin rule, growing and shrinking with a short height animation.
+
+Pass `streaming` while the model is reasoning: the panel opens and the label
+shimmers, then the panel folds away when `streaming` turns false. Use
+`defaultOpen` to start open without streaming, or control it with `open` and
+`onOpenChange`. `contentClassName` styles the inner text block.
+
+## Anatomy
+
+- `Reasoning` - holds the open and streaming state.
+- `ReasoningTrigger` - muted label and chevron; shimmers while streaming.
+- `ReasoningContent` - the reasoning text beside a rule; inert while closed.

package/knowledge/search.md

@@ -0,0 +1,131 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: search
+  sourceFile: packages/design-system/src/components/search.tsx
+  client: true
+  category: web-app-core-primitives
+  categoryFromBarrel: web-app-core-primitives
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Search
+      kind: component
+      typeText: "ForwardRefExoticComponent<SearchProps & RefAttributes<HTMLInputElement>>"
+    - name: SearchProps
+      kind: type
+  primaryExport: Search
+  subcomponents: []
+  props:
+    Search:
+      - name: className
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Optional className applied to the outer `TextFieldRoot`. Useful for setting width (e.g. `\"ax:w-65\"`) or alignment helpers (`\"ax:ms-auto\"`)."
+      - name: clearable
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Show a trailing clear button when the input has a value. Defaults to `true` for controlled inputs (when `value` is set). Pass `false` to suppress entirely. When clicked, the input is cleared by calling either: • `onClear` (if provided), or • `onChange` with a synthetic event whose `target.value` is `\"\"`. The latter keeps controlled callers working without an extra prop."
+      - name: invalid
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Marks the input as invalid (red border + ring)."
+      - name: onClear
+        type: "(() => void)"
+        required: false
+        declaredIn: self
+        doc: "Called when the user clicks the clear button. Takes precedence over the default behaviour of dispatching an empty-string change event."
+      - name: size
+        type: InputSize
+        required: false
+        declaredIn: self
+        doc: "Visual density - passes through to the underlying `TextFieldRoot` / `Input`. Defaults to `md`."
+  extendsProps:
+    - "Omit<React.InputHTMLAttributes<HTMLInputElement>, \"type\" | \"size\">"
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+      default: md
+      on: Search
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal:
+      - input
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-search--default
+  storybookTitle: Components/Search
+  docsId: components-search--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "340492e4cb3b"
+  factsHash: "061ec021a274"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A styled search input: leading magnifying-glass icon and an optional trailing clear button, built on TextFieldRoot and Input."
+useWhen:
+  - "the field is a search or filter box, not a general text field"
+useInstead:
+  - id: input
+    when: "the field is a plain text field with no search icon or clear affordance"
+  - id: combobox
+    when: "typing should show a list of suggestions to pick from"
+related:
+  - input
+  - combobox
+a11y:
+  notes:
+    - "aria-label defaults to \"Search\" since the field usually has no visible Label - override it when the search scopes a specific list, e.g. \"Search students\"."
+    - "The clear button always carries its own aria-label (\"Clear search\") so it reads correctly even though it has no visible text."
+  keyboard:
+    - "Native input semantics; the clear button is a real button, so it is reachable and activates with Enter/Space."
+  radixHandles: false
+pitfalls:
+  - "clearable defaults to showing the button only in controlled mode (a value prop is set) - an uncontrolled Search using only defaultValue never shows the clear button unless clearable is passed explicitly."
+  - "The clear button's fallback behavior mutates the native input value and dispatches a synthetic input event to keep a controlled onChange in sync - if neither onClear nor onChange is provided, clicking clear does nothing but refocus the field."
+canonicalSnippet: |
+  import { Search } from "@adres/mgda-ui"
+
+  const searchLabel = "Search residents"
+
+  <Search
+    value={query}
+    onChange={(e) => setQuery(e.target.value)}
+    onClear={() => setQuery("")}
+    placeholder={searchLabel}
+    aria-label={searchLabel}
+  />
+reviewedAt: 2026-09-30
+reviewedAgainstContractHash: "340492e4cb3b"
+---
+
+## Usage
+
+`Search` is the shipped, correct way to build a search field - reach for it
+instead of assembling `TextFieldRoot` + `TextFieldSlot` + `Input` by hand any
+time the field is a search box. It always renders the leading magnifying-glass
+icon and `type="search"`.
+
+Pass `value` + `onChange` for a controlled search box, the common case - the
+clear button appears automatically once there is a value. Pass `onClear` when
+clearing needs to do more than reset the input (resetting a debounced query or
+a page number too); otherwise the built-in fallback dispatches a synthetic
+change event that keeps a controlled caller's state in sync without it.

package/knowledge/section-nav.md

@@ -0,0 +1,162 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: section-nav
+  sourceFile: packages/design-system/src/components/section-nav.tsx
+  client: true
+  category: web-app-layout-navigation
+  categoryFromBarrel: web-app-layout-navigation
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: SectionNav
+      kind: component
+      typeText: "ForwardRefExoticComponent<SectionNavProps & RefAttributes<HTMLElement>>"
+    - name: SectionNavItem
+      kind: type
+    - name: SectionNavProps
+      kind: type
+  primaryExport: SectionNav
+  subcomponents: []
+  props:
+    SectionNav:
+      - name: activationRatio
+        type: number
+        required: false
+        declaredIn: self
+        doc: "How far down the scroll root (0-1) a section's top must pass to count as the current one. Default `0.24`."
+      - name: items
+        type: "SectionNavItem[]"
+        required: true
+        declaredIn: self
+        doc: "Sections to list, in page order. Each `id` must match an element on the page."
+      - name: layout
+        type: "\"responsive\" | \"vertical\""
+        required: false
+        declaredIn: self
+        doc: "`vertical` (default) is a stacked list at every width. `responsive` runs as a horizontally scrolling row below `xl` and a stacked list from `xl` up, hiding the title in the row."
+      - name: onActiveChange
+        type: "((id: string) => void)"
+        required: false
+        declaredIn: self
+        doc: "Fires when the current section changes, from scrolling or from a click."
+      - name: scrollRoot
+        type: "HTMLElement | string"
+        required: false
+        declaredIn: self
+        doc: "The scrolling container the sections live in: a CSS selector, an element, or `null` (default) for the window."
+      - name: title
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Eyebrow title above the list. Pass `null` to hide it."
+  extendsProps:
+    - "Omit<React.HTMLAttributes<HTMLElement>, \"title\" | \"onSelect\">"
+  variants:
+    layout:
+      kind: enum
+      options:
+        - vertical
+        - responsive
+      default: vertical
+      on: SectionNav
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal:
+      - list-nav
+    lib:
+      - cn
+    hooks: []
+    external:
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-sectionnav--default
+    - exportName: InScrollContainer
+      id: components-sectionnav--in-scroll-container
+    - exportName: Responsive
+      id: components-sectionnav--responsive
+  storybookTitle: Components/SectionNav
+  docsId: components-sectionnav--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "9a3f2097e4ee"
+  factsHash: ead2951fb1f5
+# >>> AUTHORED - humans own everything below this line. <<<
+status: beta
+summary: "An in-page \"Jump to\" menu that lists a page's sections as anchor links and highlights the one currently in view."
+useWhen:
+  - "a long single page (docs, a policy, a listing detail) has named sections the reader wants to jump between"
+  - "the side or top nav should follow the reader's position as they scroll"
+useInstead:
+  - id: list-nav
+    when: "the items go to other pages or trigger actions rather than sections of the current page"
+  - id: tabs
+    when: "only one section should be visible at a time instead of one long scrolling page"
+  - id: sidebar
+    when: "it is the app's main cross-page navigation"
+related:
+  - list-nav
+  - tabs
+composesWith:
+  - list-nav
+tokens:
+  - "--primary-foreground"
+  - "--border"
+a11y:
+  notes:
+    - "Renders a nav landmark labelled \"Page sections\" by default - pass aria-label when a page has more than one SectionNav or another nav with the same name."
+    - "The current section is exposed through ListNavItem's active state (aria-current=\"page\"), updated on scroll and on click."
+    - "Every item is a real <a href=\"#id\">, so links work and are announced as links without JavaScript."
+  keyboard:
+    - "Native anchor semantics - Tab moves between items, Enter jumps to the section."
+  radixHandles: false
+pitfalls:
+  - "Each item id must match an element id on the page - a missing id is skipped silently and that item can never become active."
+  - "When the content scrolls inside a container rather than the window, pass scrollRoot (a selector or element); otherwise scroll-spy listens to the window and never updates."
+  - "A string scrollRoot is resolved once in an effect - if the container mounts later than SectionNav, scroll-spy does not attach. Pass the element itself in that case."
+  - "Define items outside render or memoize them - a new array every render re-attaches the scroll listener each time."
+canonicalSnippet: |
+  import { SectionNav } from "@adres/mgda-ui"
+
+  const items = [
+    { id: "overview", label: "Overview" },
+    { id: "eligibility", label: "Eligibility" },
+  ]
+
+  <div className="ax:flex ax:gap-xl">
+    <div className="ax:w-56 ax:shrink-0">
+      <div className="ax:sticky ax:top-md">
+        <SectionNav items={items} />
+      </div>
+    </div>
+    <div className="ax:flex-1">
+      <section id="overview">Overview</section>
+      <section id="eligibility">Eligibility</section>
+    </div>
+  </div>
+reviewedAt: 2026-10-26
+reviewedAgainstContractHash: "9a3f2097e4ee"
+---
+
+## Usage
+
+`SectionNav` is a table of contents for the current page. Give it the page's
+sections in order, each with the `id` of its element, and it renders a `ListNav`
+of anchor links. As the reader scrolls, the section whose top has passed
+`activationRatio` of the way down the viewport (or `scrollRoot`) is marked
+active with a primary start border and text.
+
+Place it in a sticky column beside the content for desktop reading. Use
+`layout="responsive"` when the same nav must also work on narrow screens: below
+`xl` it becomes a horizontally scrolling row with the title hidden, and from
+`xl` up it stacks as a list.
+
+`onActiveChange` reports the current section, for syncing other UI such as a
+progress indicator. The active state itself is managed internally and cannot be
+controlled from outside.