@adres/mgda-ui 0.0.0-stage → 0.0.1

package/knowledge/thinking-steps.md

@@ -0,0 +1,140 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: thinking-steps
+  sourceFile: packages/design-system/src/components/thinking-steps.tsx
+  client: true
+  category: web-app-ai
+  categoryFromBarrel: web-app-ai
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: StreamingCursor
+      kind: component
+      typeText: "ForwardRefExoticComponent<HTMLAttributes<HTMLSpanElement> & RefAttributes<HTMLSpanElement>>"
+    - name: ThinkingStep
+      kind: type
+    - name: ThinkingSteps
+      kind: component
+      typeText: "ForwardRefExoticComponent<ThinkingStepsProps & RefAttributes<HTMLDivElement>>"
+    - name: ThinkingStepsProps
+      kind: type
+    - name: thinkingStepsSummary
+      kind: function
+      typeText: "({ running, done, total }: { running: boolean; done: number; total: number; }) => string"
+    - name: ThinkingStepStatus
+      kind: type
+  primaryExport: ThinkingSteps
+  subcomponents:
+    - StreamingCursor
+  props:
+    ThinkingSteps:
+      - name: running
+        type: boolean
+        required: true
+        declaredIn: self
+        doc: "True while the assistant is still working; the list opens and the summary shimmers."
+      - name: steps
+        type: "ThinkingStep[]"
+        required: true
+        declaredIn: self
+        doc: "Steps to show so far, in order. Leave out steps that have not started."
+      - name: total
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Steps planned in all, for \"step 2 of 4\". Defaults to `steps.length`."
+  extendsProps:
+    - "Omit<React.HTMLAttributes<HTMLDivElement>, \"dir\">"
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots:
+    - streaming-cursor
+    - thinking-steps
+  dependsOn:
+    internal:
+      - shimmer-text
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Running
+      id: components-thinkingsteps--running
+    - exportName: Done
+      id: components-thinkingsteps--done
+    - exportName: Cursor
+      id: components-thinkingsteps--cursor
+  storybookTitle: Components/ThinkingSteps
+  docsId: components-thinkingsteps--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: eb86f6ca5461
+  factsHash: "460b11735eb4"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: beta
+summary: "Shows what an assistant is doing before it answers: a muted one-line summary that toggles the step list, shimmering while running and folded away once done. StreamingCursor marks text still being written."
+useWhen:
+  - "an assistant runs searches or tools before answering and people should see progress"
+  - "a finished answer should keep a record of the steps it took, folded away"
+  - "streamed text needs a caret at the point it is still being written (StreamingCursor)"
+useInstead:
+  - id: step-indicator
+    when: "the steps are a form or wizard the person moves through"
+  - id: progress
+    when: "only a percentage matters, not named steps"
+related:
+  - chat-message
+  - shimmer-text
+  - skeleton
+a11y:
+  notes:
+    - "The summary is a button with aria-expanded and aria-controls, so the step list toggles with Enter or Space."
+    - "Each step's label says whether it is done or running; the shimmer is decorative and stops under reduced motion."
+    - "Announce phase changes (working, writing, done) in a separate polite live region; the summary itself is not live."
+    - "StreamingCursor is aria-hidden."
+  radixHandles: false
+pitfalls:
+  - "Pass only steps that have started; future steps belong in total, not steps."
+  - "Word labels by tense: present while running (\"Searching listings\"), past once done (\"Searched 128 listings\")."
+  - "The list follows running: it reopens when running turns true again, overriding a manual close."
+canonicalSnippet: |
+  import { ThinkingSteps } from "@adres/mgda-ui"
+
+  <ThinkingSteps
+    running={working}
+    total={3}
+    steps={[
+      { label: "Searched 128 listings", status: "done" },
+      { label: "Comparing registered sales", status: "running" },
+    ]}
+  />
+reviewedAt: 2026-10-06
+reviewedAgainstContractHash: "eb86f6ca5461"
+---
+
+## Usage
+
+`ThinkingSteps` sits at the top of an assistant turn while it works. The
+muted summary reads "Working, step 2 of 3" with a shimmer while `running`,
+then "Used 3 steps" once done; its chevron toggles the step list, which hangs
+off a thin rule. The list opens while running and folds away when finished;
+people can reopen it. Pass the steps that have
+started, each with a `label` and a `status` of `done` or `running`, and
+`total` for the planned count. `thinkingStepsSummary` returns the header text
+for custom layouts.
+
+The shimmer is `ShimmerText`, its own component, for other in-progress text.
+`StreamingCursor` is a small blinking block to place at the end of text that
+is still streaming; it stops blinking under reduced motion.
+
+## Anatomy
+
+- `ThinkingSteps` - summary toggle and an ordered step list beside a thin rule.
+- `StreamingCursor` - decorative caret for streaming text.

package/knowledge/toaster.md

@@ -0,0 +1,127 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: toaster
+  sourceFile: packages/design-system/src/components/toaster.tsx
+  client: true
+  category: web-app-feedback
+  categoryFromBarrel: web-app-feedback
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: toast
+      kind: function
+      typeText: "((message: titleT, data?: ExternalToast | undefined) => string | number) & { success: (message: string | number | bigint | boolean | ReactElement<unknown, string | JSXElementConstructor<any>> | ... 5 more ... | undefined...[truncated]"
+    - name: Toaster
+      kind: component
+      typeText: "() => Element"
+  primaryExport: Toaster
+  subcomponents: []
+  props: {}
+  extendsProps: []
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib: []
+    hooks: []
+    external:
+      - react
+      - sonner
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-toaster--default
+    - exportName: WithDescription
+      id: components-toaster--with-description
+    - exportName: Success
+      id: components-toaster--success
+    - exportName: Error
+      id: components-toaster--error
+    - exportName: Action
+      id: components-toaster--action
+  storybookTitle: Components/Toaster
+  docsId: components-toaster--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "53b4d1a7ef2b"
+  factsHash: c989fa2a8c82
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "The app-level toast host, mounted once, plus the toast() function that fires them."
+useWhen:
+  - "confirming a background action succeeded or failed without interrupting the user"
+  - "reporting the result of something the user has already moved on from"
+useInstead:
+  - id: alert
+    when: "the message belongs to a region of the page and must stay visible"
+  - id: dialog
+    when: "the user has to acknowledge or decide something before continuing"
+  - id: empty-state
+    when: "you are explaining why a surface has no content"
+related:
+  - alert
+  - dialog
+  - spinner
+tokens:
+  - "--card"
+  - "--card-foreground"
+  - "--border"
+  - "--foreground"
+  - "--muted"
+  - "--muted-foreground"
+  - "--primary"
+  - "--primary-foreground"
+a11y:
+  notes:
+    - "sonner renders the stack in an aria-live region, so announcements happen without extra work."
+    - "A toast disappears on a timer, so it must never be the only place a message appears. Anything the user has to act on belongs in Alert or Dialog."
+    - "Toast text has to stand alone. \"Saved\" announced out of context says nothing about what was saved."
+  requiredProps:
+    - "none: Toaster takes no props at all"
+  keyboard:
+    - "The close button is keyboard reachable. Focus is deliberately not moved to the toast when it appears, which is correct for a non-blocking notification."
+  radixHandles: false
+pitfalls:
+  - "Toaster accepts no props. Position (bottom-right), richColors (off) and the close button are hardcoded, so an app cannot move or restyle toasts by passing anything. Changing that means editing the design system."
+  - "Mount Toaster exactly once, near the app root. A second mount produces duplicate toasts from a single toast() call, which is easy to do by accident by adding it to a layout that is itself nested."
+  - "toast is a plain function re-exported from sonner, not a component. Import it from @adres/mgda-ui so the app does not take its own sonner dependency that could drift to a different version."
+  - "Calling toast() during a server render does nothing. It needs a client component and a mounted Toaster."
+rtl: "sonner positions the stack with physical right and bottom offsets, so toasts stay bottom-right under RTL rather than mirroring. Acceptable today, but worth revisiting with the i18n work."
+brandNotes: "Toast surfaces bind to the brand through classNames on the card, border, muted and primary tokens, so a brand re-skins them by redefining those. richColors is deliberately off so sonner's own palette never overrides brand tokens."
+canonicalSnippet: |
+  import { Toaster, toast } from "@adres/mgda-ui"
+
+  // Once, near the app root:
+  <Toaster />
+
+  // Then from any client component:
+  toast.success("Changes saved")
+reviewedAt: 2026-08-19
+reviewedAgainstContractHash: 53b4d1a7ef2b
+---
+
+## Usage
+
+Toaster is two things with one import: a host you mount once, and the `toast()`
+function you call from anywhere.
+
+It is deliberately closed. Position, colour strategy and the close button are decided
+by the design system rather than the app, so toasts look identical across every
+consuming surface and every brand. If you find yourself wanting a prop here, the
+question to ask is whether the whole system should change, not this one screen.
+
+Everything visual is bound to semantic tokens through sonner's `classNames`, and
+`richColors` is off precisely so sonner's built-in palette can never win over a
+brand's.
+
+### Choosing a toast over an alert
+
+A toast is for something already finished, where the user does not need to respond.
+The moment the message needs to persist, be acted on, or be found again later, it is
+an `Alert` (page or region level) or a `Dialog` (blocking). Being on a timer is the
+whole point, and also the whole limitation.

package/knowledge/toggle.md

@@ -0,0 +1,113 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: toggle
+  sourceFile: packages/design-system/src/components/toggle.tsx
+  client: true
+  category: web-app-form-controls
+  categoryFromBarrel: web-app-form-controls
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Toggle
+      kind: component
+      typeText: "ForwardRefExoticComponent<ToggleProps & RefAttributes<HTMLButtonElement>>"
+    - name: ToggleProps
+      kind: type
+    - name: ToggleSize
+      kind: type
+  primaryExport: Toggle
+  subcomponents: []
+  props:
+    Toggle:
+      - name: label
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Optional caption rendered to the inline-start (left) of the switch. When set, the switch and text are wrapped in a <label> so the text is clickable and names the control - no separate `aria-label` needed."
+      - name: labelClassName
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Classes for the wrapping <label> (only used when `label` is set). `className` still targets the switch track itself."
+      - name: size
+        type: ToggleSize
+        required: false
+        declaredIn: self
+  extendsProps:
+    - "React.ComponentPropsWithoutRef<typeof TogglePrimitive.Root>"
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+      default: md
+      on: Toggle
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps:
+    - THUMB
+    - THUMB_TRANSLATE
+    - TRACK
+  dataSlots:
+    - toggle-label
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - "@radix-ui/react-switch"
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-toggle--default
+  storybookTitle: Components/Toggle
+  docsId: components-toggle--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "6bd837db3ae8"
+  factsHash: a4a364bb1ace
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A binary on/off switch (built on Radix Switch), with an optional inline caption label."
+useWhen:
+  - "an immediate on/off setting that takes effect right away, such as a settings toggle"
+useInstead:
+  - id: checkbox
+    when: "the control is a form-bound selection to submit, not an immediate setting"
+related:
+  - checkbox
+a11y:
+  notes:
+    - "Passing label wraps the switch and text in a real label element, giving the control an accessible name and a larger clickable hit target for free - prefer this over a separate visual caption plus a manual aria-label."
+    - "Without label, the bare switch has no accessible name of its own - pair it with your own aria-label or a separate label pointing at it when composing a custom layout."
+  keyboard:
+    - "Native Radix switch semantics - Space toggles it; it takes part in tab order automatically."
+  radixHandles: true
+pitfalls:
+  - "className targets the switch track itself even when label is set - use labelClassName to style the wrapping label element, not className, or the caption's layout will not change."
+  - "A separate, unexported Switch component still exists in source (switch.tsx) on the same Radix primitive, but it is not barrel-exported and has none of Toggle's size or label features - Toggle is the one to use; Switch cannot even be imported from the package."
+  - "size's default is \"md\", matching Button/Input's naming, but Checkbox's equivalent middle size is instead called \"base\" - the two sibling boolean controls do not share size vocabulary."
+canonicalSnippet: |
+  import { Toggle } from "@adres/mgda-ui"
+
+  <Toggle label="Enable notifications" checked={enabled} onCheckedChange={setEnabled} />
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: "6bd837db3ae8"
+---
+
+## Usage
+
+`Toggle` is for a setting that takes effect immediately - not a value that
+waits to be submitted with a form (reach for `Checkbox` for that instead).
+
+Pass `label` for a captioned control: the text renders to the left of the
+switch, and the two are wrapped in a real `label` element so the text is
+clickable and names the control with no separate `aria-label` needed. Omit
+`label` to render the bare switch and compose your own layout, such as a
+settings row with `justify-between` and a label elsewhere in the row.

package/knowledge/tool-call-card.md

@@ -0,0 +1,241 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: tool-call-card
+  sourceFile: packages/design-system/src/components/tool-call-card.tsx
+  client: true
+  category: web-app-ai
+  categoryFromBarrel: web-app-ai
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: formatToolValue
+      kind: function
+      typeText: "(value: unknown) => ReactNode"
+    - name: TOOL_CALL_STATUS
+      kind: const
+      typeText: "Record<ToolCallStatus, { label: string; variant: NonNullable<\"default\" | \"success\" | \"warning\" | \"destructive\" | \"secondary\" | \"outline\" | \"muted\" | \"accent\" | null | undefined>; }>"
+    - name: ToolCallCard
+      kind: component
+      typeText: "ForwardRefExoticComponent<ToolCallCardProps & RefAttributes<HTMLDivElement>>"
+    - name: ToolCallCardProps
+      kind: type
+    - name: ToolCallField
+      kind: type
+    - name: toolCallNeedsAttention
+      kind: function
+      typeText: "\"awaiting-approval\" | (status: ToolCallStatus) => status is \"error\""
+    - name: ToolCallStatus
+      kind: type
+    - name: ToolPart
+      kind: type
+    - name: ToolPartCardProps
+      kind: type
+    - name: toolPartToCallCard
+      kind: function
+      typeText: "(part: ToolPart) => ToolPartCardProps"
+  primaryExport: ToolCallCard
+  subcomponents: []
+  props:
+    ToolCallCard:
+      - name: callId
+        type: string
+        required: false
+        declaredIn: self
+        doc: "The call's id, shown small at the foot of the details for support and debugging."
+      - name: children
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "The approval body shown while `awaiting-approval`, in place of the fields."
+      - name: compact
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Tighter header for a run of several calls."
+      - name: defaultOpen
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Whether the body starts open. Defaults to open while awaiting approval or after an error."
+      - name: durationMs
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Shown once the call succeeds."
+      - name: error
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Shown when the call fails, with Retry when `onRetry` is set."
+      - name: icon
+        type: "ElementType<any, keyof IntrinsicElements>"
+        required: true
+        declaredIn: self
+        doc: "The tool's icon; replaced by a spinner while running."
+      - name: input
+        type: "ToolCallField[]"
+        required: false
+        declaredIn: self
+      - name: onCancel
+        type: "(() => void)"
+        required: false
+        declaredIn: self
+        doc: "Adds Cancel while running."
+      - name: onRetry
+        type: "(() => void)"
+        required: false
+        declaredIn: self
+      - name: output
+        type: "ToolCallField[]"
+        required: false
+        declaredIn: self
+        doc: "Shown once the call succeeds."
+      - name: status
+        type: ToolCallStatus
+        required: true
+        declaredIn: self
+      - name: subtitle
+        type: string
+        required: false
+        declaredIn: self
+        doc: "One line under the title: the result summary, or why it stopped."
+      - name: title
+        type: string
+        required: true
+        declaredIn: self
+        doc: "What the call does in plain words, in the tense of its status (\"Searching listings\", \"Searched listings\")."
+      - name: toolName
+        type: string
+        required: false
+        declaredIn: self
+        doc: "The technical tool name, shown in mono from `sm` up."
+  extendsProps:
+    - "Omit<React.HTMLAttributes<HTMLDivElement>, \"title\">"
+  variants:
+    status:
+      kind: enum
+      options:
+        - success
+        - error
+        - running
+        - awaiting-approval
+        - declined
+        - cancelled
+      default: null
+      on: ToolCallCard
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps:
+    - TOOL_CALL_STATUS
+    - TOOL_PART_STATUS
+  dataSlots:
+    - tool-call-card
+  dependsOn:
+    internal:
+      - alert
+      - badge
+      - button
+      - spinner
+      - text
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Success
+      id: components-toolcallcard--success
+    - exportName: Running
+      id: components-toolcallcard--running
+    - exportName: Failed
+      id: components-toolcallcard--failed
+    - exportName: AwaitingApproval
+      id: components-toolcallcard--awaiting-approval
+    - exportName: Compact
+      id: components-toolcallcard--compact
+    - exportName: FromAiSdkToolPart
+      id: components-toolcallcard--from-ai-sdk-tool-part
+  storybookTitle: Components/ToolCallCard
+  docsId: components-toolcallcard--documentation
+  argTypeOptions:
+    status:
+      - awaiting-approval
+      - running
+      - success
+      - error
+      - declined
+      - cancelled
+  resolvedCleanly: true
+  contractHash: c4d73f54fa01
+  factsHash: "88de79332830"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: beta
+summary: "One tool call made by an assistant: what it did in plain words, live status, and its inputs and results as labelled fields on demand, with an approval step for calls that change something."
+useWhen:
+  - "an assistant calls a tool (search, lookup, booking) and people should see what it did"
+  - "a tool with side effects needs the person to approve, change or decline it first"
+  - "a tool call failed and should say why and offer Retry"
+  - "several calls in one turn should show as compact rows"
+useInstead:
+  - id: thinking-steps
+    when: "only a short list of what the assistant did matters, not each call's inputs and results"
+  - id: alert
+    when: "a message about the conversation, not a single tool call"
+related:
+  - chat-message
+  - thinking-steps
+a11y:
+  notes:
+    - "The status badge is a polite live region, so status changes are announced."
+    - "The details toggle has aria-expanded and aria-controls and names the call (\"Show details for Searched listings\")."
+    - "The card is aria-busy while running; the spinner and tool icon are decorative."
+    - "Approval and errors open the body automatically so the decision or error is reachable."
+  radixHandles: false
+pitfalls:
+  - "Word the title in the tense of its status; only use the past tense once the call succeeded."
+  - "Pass an approval body as children; without it, awaiting-approval shows the inputs with no way to decide."
+  - "Results and duration only show on success; error text only shows on error."
+  - "toolPartToCallCard titles the call from its tool id; pass your own plain-words title in the right tense when you have one."
+canonicalSnippet: |
+  import { ToolCallCard } from "@adres/mgda-ui"
+  import { Search } from "lucide-react"
+
+  <ToolCallCard
+    icon={Search}
+    title="Searched listings"
+    toolName="search_listings"
+    status="success"
+    subtitle="12 townhouses under AED 5M"
+    durationMs={1400}
+    input={[{ label: "Community", value: "Yas Island" }]}
+    output={[{ label: "Matches", value: "12" }]}
+  />
+reviewedAt: 2026-10-06
+reviewedAgainstContractHash: "c4d73f54fa01"
+---
+
+## Usage
+
+`ToolCallCard` shows one call in a light bordered card. The header has the
+tool's `icon` (a spinner while running), a plain-words `title`, the technical `toolName`, a one-line
+`subtitle`, the duration once done, and a status badge for `awaiting-approval`,
+`running`, `success`, `error`, `declined` or `cancelled`. The chevron opens the
+body with `input` and, after success, `output` as key and value lines in a
+bordered mono box. On error
+the body leads with `error` and a Retry button (`onRetry`). While running,
+`onCancel` adds Cancel.
+
+For tools with side effects, pass the approval UI (what will happen, Approve,
+Decline, any editable choice) as `children`; it replaces the fields while
+`awaiting-approval`. Use `compact` for a run of several calls in one turn.
+`TOOL_CALL_STATUS` and `toolCallNeedsAttention` are exported for custom rows.
+
+Using the Vercel AI SDK? `toolPartToCallCard(part)` maps a tool part to
+props: its `state` to `status`, `input` and `output` records to fields (nested
+values pretty-printed as JSON), `errorText` to `error` and `toolCallId` to
+`callId`, shown at the foot of the details. Pass the `icon` yourself:
+`<ToolCallCard icon={Search} {...toolPartToCallCard(part)} />`.