@adres/mgda-ui 0.0.0-stage → 0.0.1

package/src/components/quota-bar.tsx

@@ -0,0 +1,191 @@
+"use client"
+
+import * as React from "react"
+import { Progress } from "./progress"
+import { cn } from "../lib/cn"
+
+export type QuotaBarShape = "bar" | "ring"
+
+export interface QuotaBarProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Current usage. */
+  used: number
+  /** Maximum allowed. When `used >= total`, the bar renders in the error
+   *  variant and the "full" state is shown. */
+  total: number
+  /** Compact mode - uses a smaller bar / ring. */
+  compact?: boolean
+  /** Visual shape. `bar` (default) is a horizontal Progress with the caption
+   *  underneath; `ring` puts a circular Progress on the inline-start side
+   *  with the caption stacked beside it and the pct% inside the ring. */
+  shape?: QuotaBarShape
+  /** Ring-only: pixel diameter override (passes through to Progress). */
+  ringSize?: number
+  /** Ring-only: stroke width in pixels. */
+  strokeWidth?: number
+  /** Unit label appended after the count - e.g. "seats", "licences", "GB".
+   *  Used in the "X / Y {unit} used" sentence. */
+  unit?: string
+  /** Label shown next to the count when the quota is *not* full.
+   *  Defaults to `"{remaining} remaining"`. */
+  remainingLabel?: (remaining: number) => string
+  /** Replaces the default "No {unit} remaining" string in the full state. */
+  fullLabel?: string
+  /** When the quota is full, the full-state CTA renders as a link to this
+   *  href. Use this OR `ctaOnClick`, not both. */
+  ctaHref?: string
+  /** When the quota is full, the full-state CTA renders as a button that
+   *  fires this callback (use for non-routing actions like opening a Drawer). */
+  ctaOnClick?: () => void
+  /** Visible text for the full-state CTA. Defaults to "Request More". */
+  ctaLabel?: string
+}
+
+/** Visual quota indicator - a Progress bar (or ring) plus a small
+ *  "{used} / {total}" caption and an optional CTA when full.
+ *  Domain-agnostic: pass `unit` to control the wording for your use case
+ *  (seats, licences, storage GB, emails sent this month, …).
+ *
+ *  Threshold ramp:
+ *    • < 90 % - `default` variant
+ *    • 90–99 % - `warning` variant, "remaining" text warning-tinted
+ *    • ≥ 100 % - `error` variant, "No {unit} remaining" + optional CTA */
+export const QuotaBar = React.forwardRef<HTMLDivElement, QuotaBarProps>(
+  (
+    {
+      used,
+      total,
+      compact,
+      shape = "bar",
+      ringSize,
+      strokeWidth,
+      unit = "items",
+      remainingLabel,
+      fullLabel,
+      ctaHref,
+      ctaOnClick,
+      ctaLabel = "Request More",
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    const isFull    = used >= total
+    const remaining = Math.max(0, total - used)
+    const pct       = total > 0 ? (used / total) * 100 : 0
+    const isWarn    = !isFull && pct >= 90
+    const remainingText = remainingLabel
+      ? remainingLabel(remaining)
+      : `${remaining} remaining`
+
+    const variant = isFull ? "error" : isWarn ? "warning" : "default"
+    const size: "sm" | "md" = compact ? "sm" : "md"
+
+    const ctaNode = !isFull ? null : ctaOnClick ? (
+      <button
+        type="button"
+        onClick={ctaOnClick}
+        className="ax:text-primary ax:hover:underline ax:focus-visible:outline-none ax:focus-visible:underline ax:cursor-pointer"
+      >
+        {ctaLabel}
+      </button>
+    ) : ctaHref ? (
+      <a
+        href={ctaHref}
+        className="ax:text-primary ax:hover:underline ax:focus-visible:outline-none ax:focus-visible:underline"
+      >
+        {ctaLabel}
+      </a>
+    ) : null
+
+    // ── Ring shape ────────────────────────────────────────────────────────────
+    if (shape === "ring") {
+      return (
+        <div
+          ref={ref}
+          className={cn("ax:flex ax:items-center ax:gap-md", className)}
+          {...props}
+        >
+          <div className="ax:relative ax:inline-flex ax:shrink-0">
+            <Progress
+              shape="ring"
+              value={used}
+              max={total}
+              size={size}
+              variant={variant}
+              ringSize={ringSize}
+              strokeWidth={strokeWidth}
+            />
+            {/* Center pct% - the ring conveys the proportion visually, this
+                gives a precise reading at a glance. Hidden when the ring is
+                tiny (compact, no override) since the text wouldn't fit. */}
+            {!(compact && !ringSize) && (
+              <span
+                aria-hidden="true"
+                className={cn(
+                  "ax:absolute ax:inset-0 ax:flex ax:items-center ax:justify-center",
+                  "ax:t-caption ax:font-medium",
+                  isFull ? "ax:text-destructive-strong" : isWarn ? "ax:text-warning-strong" : "ax:text-foreground",
+                )}
+              >
+                {Math.round(pct)}%
+              </span>
+            )}
+          </div>
+
+          <div className="ax:flex-1 ax:min-w-0 ax:flex ax:flex-col ax:gap-2xs ax:t-caption ax:text-muted-foreground">
+            {isFull ? (
+              <>
+                <span className="ax:text-destructive-strong ax:font-medium">
+                  {fullLabel ?? `No ${unit} remaining`}
+                </span>
+                {ctaNode}
+              </>
+            ) : (
+              <>
+                <span>
+                  {used} / {total} {unit} used
+                </span>
+                <span className={cn(isWarn && "ax:text-warning-strong ax:font-medium")}>
+                  {remainingText}
+                </span>
+              </>
+            )}
+          </div>
+        </div>
+      )
+    }
+
+    // ── Bar shape (default) ───────────────────────────────────────────────────
+    return (
+      <div ref={ref} className={cn("ax:flex ax:flex-col ax:gap-xs", className)} {...props}>
+        <Progress
+          value={used}
+          max={total}
+          size={size}
+          variant={variant}
+        />
+
+        <div className="ax:flex ax:items-center ax:justify-between ax:gap-xs ax:t-caption ax:text-muted-foreground">
+          {isFull ? (
+            <>
+              <span className="ax:text-destructive-strong ax:font-medium">
+                {fullLabel ?? `No ${unit} remaining`}
+              </span>
+              {ctaNode}
+            </>
+          ) : (
+            <>
+              <span>
+                {used} / {total} {unit} used
+              </span>
+              <span className={cn(isWarn && "ax:text-warning-strong ax:font-medium")}>
+                {remainingText}
+              </span>
+            </>
+          )}
+        </div>
+      </div>
+    )
+  },
+)
+QuotaBar.displayName = "QuotaBar"

package/src/components/quote.stories.tsx

@@ -0,0 +1,18 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { Quote } from "./quote"
+
+const meta: Meta<typeof Quote> = {
+  title: "Components/Quote",
+  component: Quote,
+  tags: ["autodocs"],
+  args: {
+    children: "Great products are built on great design systems.",
+    size: "md",
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof Quote>
+
+export const Default: Story = {}

package/src/components/quote.tsx

@@ -0,0 +1,43 @@
+"use client"
+
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+import { cn } from "../lib/cn"
+
+export const quoteVariants = cva(
+  "ax:italic",
+  {
+    variants: {
+      size: {
+        sm: "ax:t-body-sm",
+        md: "ax:t-body-md",
+        lg: "ax:t-body-lg",
+        xl: "ax:text-xl",
+      },
+      color: {
+        default: "ax:text-foreground",
+        muted:   "ax:text-muted-foreground",
+        accent:  "ax:text-accent-foreground",
+      },
+    },
+    defaultVariants: {
+      size: "md",
+      color: "default",
+    },
+  }
+)
+
+export interface QuoteProps
+  extends Omit<React.HTMLAttributes<HTMLQuoteElement>, "color">,
+    VariantProps<typeof quoteVariants> {}
+
+export const Quote = React.forwardRef<HTMLQuoteElement, QuoteProps>(
+  ({ className, size, color, ...props }, ref) => (
+    <q
+      ref={ref}
+      className={cn(quoteVariants({ size, color }), className)}
+      {...props}
+    />
+  )
+)
+Quote.displayName = "Quote"

package/src/components/radio-card.stories.tsx

@@ -0,0 +1,27 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { RadioCard, RadioCardDescription, RadioCardGroup, RadioCardTitle } from "./radio-card"
+
+const meta: Meta<typeof RadioCardGroup> = {
+  title: "Components/RadioCard",
+  component: RadioCardGroup,
+  tags: ["autodocs"],
+}
+
+export default meta
+type Story = StoryObj<typeof RadioCardGroup>
+
+export const Default: Story = {
+  render: () => (
+    <RadioCardGroup defaultValue="monthly" className="ax:max-w-md">
+      <RadioCard value="monthly">
+        <RadioCardTitle>Monthly</RadioCardTitle>
+        <RadioCardDescription>Pay as you go each month.</RadioCardDescription>
+      </RadioCard>
+      <RadioCard value="yearly">
+        <RadioCardTitle>Yearly</RadioCardTitle>
+        <RadioCardDescription>Save 20% with annual billing.</RadioCardDescription>
+      </RadioCard>
+    </RadioCardGroup>
+  ),
+}

package/src/components/radio-card.tsx

@@ -0,0 +1,225 @@
+"use client"
+
+import * as React from "react"
+import * as RadioGroupPrimitive from "@radix-ui/react-radio-group"
+import { Circle, CircleCheck } from "lucide-react"
+import { cva } from "class-variance-authority"
+import { cn } from "../lib/cn"
+
+export type RadioCardSize        = "sm" | "base" | "lg" | "xl"
+export type RadioCardOrientation = "horizontal" | "vertical"
+
+// ─── Context ──────────────────────────────────────────────────────────────────
+
+interface RadioCardGroupContext {
+  size:        RadioCardSize
+  compact:     boolean
+  orientation: RadioCardOrientation
+}
+
+const RadioCardGroupContext = React.createContext<RadioCardGroupContext>({
+  size:        "base",
+  compact:     false,
+  orientation: "vertical",
+})
+
+// ─── Group ────────────────────────────────────────────────────────────────────
+
+export interface RadioCardGroupProps
+  extends React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root> {
+  size?:        RadioCardSize
+  compact?:     boolean
+  orientation?: RadioCardOrientation
+}
+
+export const RadioCardGroup = React.forwardRef<
+  React.ElementRef<typeof RadioGroupPrimitive.Root>,
+  RadioCardGroupProps
+>(({ className, size = "base", compact = false, orientation = "vertical", ...props }, ref) => (
+  <RadioCardGroupContext.Provider value={{ size, compact, orientation }}>
+    <RadioGroupPrimitive.Root
+      ref={ref}
+      orientation={orientation}
+      className={cn(
+        compact
+          ? orientation === "horizontal" ? "ax:flex ax:flex-row" : "ax:flex ax:flex-col"
+          : "ax:grid ax:gap-3",
+        className
+      )}
+      {...props}
+    />
+  </RadioCardGroupContext.Provider>
+))
+RadioCardGroup.displayName = "RadioCardGroup"
+
+// ─── Card ─────────────────────────────────────────────────────────────────────
+
+// Checked background is intentionally omitted here: it's applied conditionally
+// below so compact and default modes can use different tint strengths.
+const radioCardVariants = cva(
+  [
+    "ax:relative ax:flex ax:items-start ax:cursor-pointer ax:border ax:border-border ax:bg-card",
+    "ax:transition-colors ax:transition-snappy",
+    // Selected border matches the selected title/icon colour (primary-strong /
+    // dark:primary) rather than the base --primary.
+    "ax:has-[[data-state=checked]]:border-primary",
+    "ax:dark:has-[[data-state=checked]]:border-primary",
+    // Hover only on unchecked cards - darker brand-aware border (≈30% foreground)
+    // for a clearly visible interactivity cue. `hover:z-10` lifts the hovered
+    // card above its compact-mode neighbours so the new border isn't clipped
+    // by the adjacent card's idle border.
+    "ax:[&:not(:has([data-state=checked]))]:hover:border-foreground/50",
+    "ax:[&:not(:has([data-state=checked]))]:hover:z-10",
+    "ax:has-[[data-disabled]]:cursor-not-allowed ax:has-[[data-disabled]]:opacity-50",
+    // Trailing radio indicator (top-right): a hollow ring shown BY DEFAULT that
+    // swaps to a filled check when the card is selected. Both glyphs share one
+    // stacked slot so the swap is layout-shift-free. State is driven from the
+    // card (ancestor) selectors (mirroring CheckboxCard) so source order
+    // resolves the overrides.
+    //   off ring: --input at rest, --foreground/40 on hover, hidden when checked
+    //   on check: hidden by default; primary-strong / dark:primary when checked,
+    //             mirrors the selected title colour
+    "ax:[&_[data-slot=radio-card-off]]:text-input",
+    "ax:[&:not(:has([data-state=checked])):hover_[data-slot=radio-card-off]]:text-foreground/40",
+    "ax:[&:has([data-state=checked])_[data-slot=radio-card-off]]:opacity-0",
+    "ax:[&_[data-slot=radio-card-on]]:text-primary-foreground ax:[&_[data-slot=radio-card-on]]:opacity-0",
+    "ax:dark:[&_[data-slot=radio-card-on]]:text-primary-foreground",
+    "ax:[&:has([data-state=checked])_[data-slot=radio-card-on]]:opacity-100",
+  ],
+  {
+    variants: {
+      size: {
+        sm:   "ax:p-3 ax:gap-3 ax:text-xs",
+        base: "ax:p-4 ax:gap-3 ax:text-sm",
+        lg:   "ax:p-5 ax:gap-4 ax:text-base",
+        xl:   "ax:px-7 ax:py-5 ax:gap-4 ax:text-base",
+      },
+    },
+    defaultVariants: { size: "base" },
+  }
+)
+
+// Default mode: subtle background tint on selection PLUS primary-coloured
+// title and icon (mirrors compact mode so both variants read the same way
+// at-a-glance: selected card → brand-tinted title + icon).
+const DEFAULT_CHECKED =
+  "ax:has-[[data-state=checked]]:bg-primary-muted " +
+  "ax:[&:has([data-state=checked])_[data-slot=radio-card-title]]:text-primary-foreground " +
+  "ax:[&:has([data-state=checked])_[data-slot=radio-card-icon]]:text-primary-foreground " +
+  // Dark mode: primary-strong is a mid sage that reads muddy on a dark card, so
+  // brighten the selected title + icon (matches the bright checked indicator).
+  "ax:dark:[&:has([data-state=checked])_[data-slot=radio-card-title]]:text-primary-foreground " +
+  "ax:dark:[&:has([data-state=checked])_[data-slot=radio-card-icon]]:text-primary-foreground"
+
+// Compact mode: primary-weakest background tint plus primary-coloured title and
+// icon on selection. The [&:has(...)_[data-slot]] form styles a DESCENDANT
+// matching data-slot whenever the label itself contains a checked radio.
+const COMPACT_CHECKED =
+  "ax:has-[[data-state=checked]]:bg-primary-muted " +
+  "ax:[&:has([data-state=checked])_[data-slot=radio-card-title]]:text-primary-foreground " +
+  "ax:[&:has([data-state=checked])_[data-slot=radio-card-icon]]:text-primary-foreground " +
+  // Dark mode: brighten the selected title + icon (see DEFAULT_CHECKED).
+  "ax:dark:[&:has([data-state=checked])_[data-slot=radio-card-title]]:text-primary-foreground " +
+  "ax:dark:[&:has([data-state=checked])_[data-slot=radio-card-icon]]:text-primary-foreground"
+
+const COMPACT_LAYOUT: Record<RadioCardOrientation, string> = {
+  horizontal: [
+    "ax:rounded-none",
+    "ax:first:rounded-l-(--input-radius) ax:last:rounded-r-(--input-radius)",
+    "ax:[&:not(:first-child)]:-ml-px",
+    "ax:has-[[data-state=checked]]:z-10",
+  ].join(" "),
+  vertical: [
+    "ax:rounded-none",
+    "ax:first:rounded-t-(--input-radius) ax:last:rounded-b-(--input-radius)",
+    "ax:[&:not(:first-child)]:-mt-px",
+    "ax:has-[[data-state=checked]]:z-10",
+  ].join(" "),
+}
+
+const INDICATOR_SIZE: Record<RadioCardSize, string> = {
+  sm:   "ax:size-3.5",
+  base: "ax:size-4",
+  lg:   "ax:size-4",
+  xl:   "ax:size-5",
+}
+
+export interface RadioCardProps
+  extends React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item> {
+  size?: RadioCardSize
+}
+
+export const RadioCard = React.forwardRef<
+  React.ElementRef<typeof RadioGroupPrimitive.Item>,
+  RadioCardProps
+>(({ className, size: sizeProp, children, ...props }, ref) => {
+  const { size: ctxSize, compact, orientation } = React.useContext(RadioCardGroupContext)
+  const size = sizeProp ?? ctxSize
+
+  return (
+    // No htmlFor needed: label activates its first labelable descendant (the button) on click.
+    <label
+      className={cn(
+        radioCardVariants({ size }),
+        compact ? [COMPACT_LAYOUT[orientation], COMPACT_CHECKED] : ["ax:rounded-(--input-radius)", DEFAULT_CHECKED],
+        className
+      )}
+    >
+      <div className="ax:flex-1 ax:min-w-0">{children}</div>
+      <span
+        aria-hidden="true"
+        className={cn("ax:relative ax:shrink-0 ax:mt-0", INDICATOR_SIZE[size])}
+      >
+        {/* Unchecked - hollow ring, shown by default. */}
+        <Circle
+          data-slot="radio-card-off"
+          className="ax:absolute ax:inset-0 ax:size-full ax:transition ax:transition-snappy"
+        />
+        {/* Checked - filled check, revealed on selection. */}
+        <CircleCheck
+          data-slot="radio-card-on"
+          className="ax:absolute ax:inset-0 ax:size-full ax:transition ax:transition-snappy"
+        />
+      </span>
+      <RadioGroupPrimitive.Item ref={ref} className="ax:sr-only" {...props} />
+    </label>
+  )
+})
+RadioCard.displayName = "RadioCard"
+
+// ─── Sub-components ───────────────────────────────────────────────────────────
+
+// data-slot is used by the compact checked selectors to colour title and icon primary.
+export const RadioCardIcon = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    data-slot="radio-card-icon"
+    className={cn("ax:shrink-0 ax:text-muted-foreground", className)}
+    {...props}
+  />
+))
+RadioCardIcon.displayName = "RadioCardIcon"
+
+export const RadioCardTitle = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => (
+  <p
+    ref={ref}
+    data-slot="radio-card-title"
+    className={cn("ax:t-label-sm ax:text-foreground", className)}
+    {...props}
+  />
+))
+RadioCardTitle.displayName = "RadioCardTitle"
+
+export const RadioCardDescription = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => (
+  <p ref={ref} className={cn("ax:text-[0.875em] ax:text-muted-foreground ax:mt-1", className)} {...props} />
+))
+RadioCardDescription.displayName = "RadioCardDescription"

package/src/components/radio-group.stories.tsx

@@ -0,0 +1,32 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { Label } from "./input"
+import { RadioGroup, RadioGroupItem } from "./radio-group"
+
+const meta: Meta<typeof RadioGroup> = {
+  title: "Components/RadioGroup",
+  component: RadioGroup,
+  tags: ["autodocs"],
+}
+
+export default meta
+type Story = StoryObj<typeof RadioGroup>
+
+export const Default: Story = {
+  render: () => (
+    <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>
+      <div className="ax:flex ax:items-center ax:gap-sm">
+        <RadioGroupItem value="compact" id="r3" />
+        <Label htmlFor="r3">Compact</Label>
+      </div>
+    </RadioGroup>
+  ),
+}

package/src/components/radio-group.tsx

@@ -0,0 +1,68 @@
+"use client"
+
+import * as React from "react"
+import * as RadioGroupPrimitive from "@radix-ui/react-radio-group"
+import { Circle } from "lucide-react"
+import { cva, type VariantProps } from "class-variance-authority"
+import { cn } from "../lib/cn"
+
+export const RadioGroup = React.forwardRef<
+  React.ElementRef<typeof RadioGroupPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root>
+>(({ className, ...props }, ref) => (
+  <RadioGroupPrimitive.Root
+    ref={ref}
+    className={cn("ax:grid ax:gap-2", className)}
+    {...props}
+  />
+))
+RadioGroup.displayName = RadioGroupPrimitive.Root.displayName
+
+const radioItemVariants = cva(
+  [
+    "ax:aspect-square ax:rounded-full ax:border ax:border-input",
+    "ax:transition-colors ax:transition-snappy",
+    "ax:focus:outline-none ax:focus-visible:ring-2 ax:focus-visible:ring-ring ax:focus-visible:ring-offset-2 ax:focus-visible:ring-offset-background",
+    "ax:cursor-pointer ax:disabled:cursor-not-allowed ax:disabled:opacity-50",
+    // primary-weak fill + primary-strong dot. The fill auto-inverts to a light-ish
+    // tint in dark, so the dot flips to a dark `primary-muted` there (dark: override)
+    // to keep contrast on that lighter fill. Mirrors Checkbox.
+    "ax:data-[state=checked]:bg-primary-weak ax:data-[state=checked]:border-primary-weak ax:data-[state=checked]:text-primary-strong ax:dark:data-[state=checked]:text-primary-muted",
+  ],
+  {
+    variants: {
+      size: {
+        sm:   "ax:size-3",
+        base: "ax:size-4",
+        lg:   "ax:size-5",
+      },
+    },
+    defaultVariants: { size: "base" },
+  }
+)
+
+const INDICATOR_SIZE: Record<NonNullable<VariantProps<typeof radioItemVariants>["size"]>, string> = {
+  sm:   "ax:size-1.5",
+  base: "ax:size-2",
+  lg:   "ax:size-2.5",
+}
+
+export interface RadioGroupItemProps
+  extends React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>,
+    VariantProps<typeof radioItemVariants> {}
+
+export const RadioGroupItem = React.forwardRef<
+  React.ElementRef<typeof RadioGroupPrimitive.Item>,
+  RadioGroupItemProps
+>(({ className, size, ...props }, ref) => (
+  <RadioGroupPrimitive.Item
+    ref={ref}
+    className={cn(radioItemVariants({ size }), className)}
+    {...props}
+  >
+    <RadioGroupPrimitive.Indicator className="ax:flex ax:items-center ax:justify-center">
+      <Circle className={cn(INDICATOR_SIZE[size ?? "base"], "ax:fill-current ax:text-current")} />
+    </RadioGroupPrimitive.Indicator>
+  </RadioGroupPrimitive.Item>
+))
+RadioGroupItem.displayName = RadioGroupPrimitive.Item.displayName

package/src/components/reasoning.stories.tsx

@@ -0,0 +1,50 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { Reasoning, ReasoningContent, ReasoningTrigger } from "./reasoning"
+import { Button } from "./button"
+import { Text } from "./text"
+
+const meta: Meta<typeof Reasoning> = {
+  title: "Components/Reasoning",
+  component: Reasoning,
+  tags: ["autodocs"],
+  decorators: [(Story) => <div style={{ maxWidth: 560 }}><Story /></div>],
+}
+
+export default meta
+type Story = StoryObj<typeof Reasoning>
+
+const THOUGHT =
+  "The buyer wants a Yas Island townhouse under AED 5M with a garden. 11 listings match. The cheapest asks AED 4.2M, " +
+  "and the median registered sale in Yas Acres is AED 4.6M, so it is priced below recent sales."
+
+export const Default: Story = {
+  render: () => (
+    <Reasoning>
+      <ReasoningTrigger>Show reasoning</ReasoningTrigger>
+      <ReasoningContent>{THOUGHT}</ReasoningContent>
+    </Reasoning>
+  ),
+}
+
+function StreamingDemo() {
+  const [text, setText] = React.useState("")
+  const streaming = text.length < THOUGHT.length && text.length > 0
+  React.useEffect(() => {
+    if (!streaming) return
+    const timer = window.setTimeout(() => setText(THOUGHT.slice(0, text.length + 4)), 40)
+    return () => window.clearTimeout(timer)
+  }, [text, streaming])
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: 12, alignItems: "flex-start" }}>
+      <Reasoning streaming={streaming}>
+        <ReasoningTrigger>{streaming ? "Thinking" : "Thought for 4 seconds"}</ReasoningTrigger>
+        <ReasoningContent>{text}</ReasoningContent>
+      </Reasoning>
+      {!streaming && text && <Text as="p" size="2">The AED 4.2M Yas Acres townhouse is the best value.</Text>}
+      <Button variant="outline" size="sm" disabled={streaming} onClick={() => setText(THOUGHT.slice(0, 4))}>Stream</Button>
+    </div>
+  )
+}
+
+export const Streaming: Story = { render: () => <StreamingDemo /> }