@adres/mgda-ui 0.0.0-stage → 0.0.2

package/src/components/combobox.tsx

@@ -0,0 +1,407 @@
+"use client"
+
+import * as React from "react"
+import * as PopoverPrimitive from "@radix-ui/react-popover"
+import { Search as SearchIcon, X as ClearIcon } from "lucide-react"
+import { Spinner } from "./spinner"
+import { Input, TextFieldRoot, TextFieldSlot, type InputSize } from "./input"
+import { cn } from "../lib/cn"
+
+export interface ComboboxItem {
+  /** Unique, stable identifier. Also what `value` / `onValueChange` carry. */
+  value: string
+  label: string
+  /** Secondary text shown at the end of the row, e.g. a price or count. */
+  description?: string
+  /** Leading visual, e.g. an icon or a small Avatar. Mark decorative icons aria-hidden. */
+  icon?: React.ReactNode
+  /** Rows with the same group render under one heading, in first-seen order. */
+  group?: string
+  /** Extra text matched by the default filter but not shown. */
+  keywords?: string
+  disabled?: boolean
+}
+
+export type ComboboxSize = InputSize
+
+export interface ComboboxProps {
+  items: ComboboxItem[]
+  /** Selected item's value. Set it (with onValueChange) for a picker that shows the choice in the input. */
+  value?: string | null
+  onValueChange?: (value: string | null) => void
+  /** Called on every pick. Without `value`, the input clears after a pick (search launcher). */
+  onSelect?: (item: ComboboxItem) => void
+  /** Controlled query. Leave unset to let the combobox own it. */
+  query?: string
+  onQueryChange?: (query: string) => void
+  /** Return true to keep an item. Default: case-insensitive match on label, description and keywords. */
+  filter?: (item: ComboboxItem, query: string) => boolean
+  /** Shown instead of the item list while the query is empty, e.g. recent searches. */
+  startContent?: React.ReactNode
+  /** Shown when the query matches nothing. Receives the trimmed query. */
+  emptyMessage?: React.ReactNode | ((query: string) => React.ReactNode)
+  /** Show a pending row instead of results, e.g. while fetching remote items. */
+  loading?: boolean
+  loadingMessage?: React.ReactNode
+  /** Cap the rows shown per group (or overall when ungrouped). */
+  maxPerGroup?: number
+  /** Bold the matched part of each label. Default true. */
+  highlightMatches?: boolean
+  placeholder?: string
+  /** Accessible name. Required unless a <Label htmlFor={id}> names the input. */
+  "aria-label"?: string
+  id?: string
+  name?: string
+  size?: ComboboxSize
+  invalid?: boolean
+  disabled?: boolean
+  className?: string
+}
+
+export function defaultComboboxFilter(item: ComboboxItem, query: string) {
+  const haystack = `${item.label} ${item.description ?? ""} ${item.keywords ?? ""}`.toLowerCase()
+  return haystack.includes(query.toLowerCase())
+}
+
+/** Groups items in first-seen order, capping each group. Ungrouped items share one unnamed group. */
+export function groupComboboxItems(items: ComboboxItem[], maxPerGroup = Infinity) {
+  const groups: { name: string | undefined; items: ComboboxItem[] }[] = []
+  for (const item of items) {
+    let group = groups.find((entry) => entry.name === item.group)
+    if (!group) {
+      group = { name: item.group, items: [] }
+      groups.push(group)
+    }
+    if (group.items.length < maxPerGroup) group.items.push(item)
+  }
+  return groups
+}
+
+/** Splits a label around the first case-insensitive match so it can be emphasised. */
+export function splitComboboxMatch(text: string, query: string) {
+  const index = query ? text.toLowerCase().indexOf(query.toLowerCase()) : -1
+  if (index < 0) return null
+  return { before: text.slice(0, index), match: text.slice(index, index + query.length), after: text.slice(index + query.length) }
+}
+
+/** Next enabled index in `direction`, wrapping around; -1 when nothing is enabled. */
+export function nextEnabledIndex(items: ComboboxItem[], from: number, direction: 1 | -1) {
+  for (let step = 1; step <= items.length; step++) {
+    const index = (from + direction * step + items.length * step) % items.length
+    if (!items[index]?.disabled) return index
+  }
+  return -1
+}
+
+const SIZE_TEXT: Record<ComboboxSize, string> = {
+  sm: "ax:t-label-sm",
+  md: "ax:t-body-sm",
+  lg: "ax:t-body-md",
+}
+
+function Highlight({ text, query }: { text: string; query: string }) {
+  const parts = splitComboboxMatch(text, query)
+  if (!parts) return <>{text}</>
+  return (
+    <>
+      {parts.before}
+      <strong className="ax:font-semibold ax:text-foreground-strong">{parts.match}</strong>
+      {parts.after}
+    </>
+  )
+}
+
+/**
+ * Combobox - a text input with a filtered, keyboard-navigable list of options.
+ *
+ * Follows the WAI-ARIA combobox pattern: focus stays in the input while arrow
+ * keys move `aria-activedescendant` through the listbox, Enter picks, Escape
+ * closes. The list renders in a Popover portal anchored to the input, so
+ * overflow-hidden containers cannot clip it.
+ *
+ * @example
+ *   <Combobox
+ *     items={communities}
+ *     value={community}
+ *     onValueChange={setCommunity}
+ *     placeholder="Choose a community"
+ *     aria-label="Community"
+ *   />
+ */
+export function Combobox({
+  items,
+  value,
+  onValueChange,
+  onSelect,
+  query: queryProp,
+  onQueryChange,
+  filter = defaultComboboxFilter,
+  startContent,
+  emptyMessage = (query: string) => `No results for "${query}"`,
+  loading = false,
+  loadingMessage = "Searching",
+  maxPerGroup,
+  highlightMatches = true,
+  placeholder,
+  "aria-label": ariaLabel,
+  id,
+  name,
+  size = "md",
+  invalid,
+  disabled,
+  className,
+}: ComboboxProps) {
+  const autoId = React.useId()
+  const inputId = id ?? `${autoId}-input`
+  const listId = `${autoId}-listbox`
+  const anchorRef = React.useRef<HTMLDivElement>(null)
+  const inputRef = React.useRef<HTMLInputElement>(null)
+
+  const isPicker = value !== undefined
+  // Remote results may no longer include the picked item, so remember it to keep its label.
+  const [lastPicked, setLastPicked] = React.useState<ComboboxItem>()
+  const selected = isPicker
+    ? items.find((item) => item.value === value) ?? (lastPicked?.value === value ? lastPicked : undefined)
+    : undefined
+
+  const [ownQuery, setOwnQuery] = React.useState("")
+  const query = queryProp ?? ownQuery
+  const setQuery = (next: string) => {
+    if (queryProp === undefined) setOwnQuery(next)
+    onQueryChange?.(next)
+  }
+
+  const [open, setOpen] = React.useState(false)
+  const [editing, setEditing] = React.useState(false)
+  const [active, setActive] = React.useState(-1)
+
+  const trimmed = query.trim()
+  const showStart = !trimmed && startContent !== undefined
+  const matches = trimmed ? items.filter((item) => filter(item, trimmed)) : items
+  const groups = groupComboboxItems(showStart ? [] : matches, maxPerGroup)
+  const visible = groups.flatMap((group) => group.items)
+  const activeItem = open && active >= 0 ? visible[active] : undefined
+  const optionId = (item: ComboboxItem) => `${autoId}-option-${visible.indexOf(item)}`
+
+  // In picker mode the input shows the chosen label until the user starts editing.
+  const inputValue = isPicker && !editing ? selected?.label ?? "" : query
+
+  // Typing highlights the first enabled match so Enter picks it straight away. Results
+  // that arrive later (remote search) get the same treatment if nothing valid is highlighted.
+  const lastQuery = React.useRef(trimmed)
+  React.useEffect(() => {
+    if (!open || !trimmed) return
+    const queryChanged = lastQuery.current !== trimmed
+    lastQuery.current = trimmed
+    if (queryChanged || active < 0 || active >= visible.length) setActive(nextEnabledIndex(visible, -1, 1))
+  }, [open, trimmed, visible.length, active])
+
+  React.useEffect(() => {
+    if (!activeItem) return
+    document.getElementById(optionId(activeItem))?.scrollIntoView({ block: "nearest" })
+  })
+
+  function openList() {
+    if (disabled) return
+    setOpen(true)
+    const selectedIndex = selected ? visible.indexOf(selected) : -1
+    setActive((current) => (current >= 0 ? current : selectedIndex >= 0 ? selectedIndex : nextEnabledIndex(visible, -1, 1)))
+  }
+
+  function close() {
+    setOpen(false)
+    setEditing(false)
+    setActive(-1)
+  }
+
+  function pick(item: ComboboxItem) {
+    if (item.disabled) return
+    setLastPicked(item)
+    onSelect?.(item)
+    if (isPicker) onValueChange?.(item.value)
+    setQuery("")
+    close()
+  }
+
+  function onKeyDown(event: React.KeyboardEvent<HTMLInputElement>) {
+    switch (event.key) {
+      case "ArrowDown":
+      case "ArrowUp": {
+        event.preventDefault()
+        if (!open) return openList()
+        const direction = event.key === "ArrowDown" ? 1 : -1
+        setActive((current) => nextEnabledIndex(visible, current < 0 && direction < 0 ? 0 : current, direction))
+        return
+      }
+      case "Home":
+      case "End":
+        if (!open || !visible.length) return
+        event.preventDefault()
+        setActive(event.key === "Home" ? nextEnabledIndex(visible, -1, 1) : nextEnabledIndex(visible, 0, -1))
+        return
+      case "Enter":
+        if (open && activeItem) {
+          event.preventDefault()
+          pick(activeItem)
+        }
+        return
+      case "Escape":
+        if (open) {
+          event.preventDefault()
+          close()
+        }
+        return
+      case "Tab":
+        close()
+    }
+  }
+
+  const listContent = loading ? (
+    <div className="ax:flex ax:items-center ax:gap-xs ax:px-sm ax:py-sm ax:text-muted-foreground" role="status">
+      <Spinner size="sm" decorative className="ax:text-current" />
+      <span className={SIZE_TEXT[size]}>{loadingMessage}</span>
+    </div>
+  ) : showStart ? (
+    // Keep focus in the input when start content is clicked; keyboard users can still Tab into it.
+    <div onMouseDown={(event) => event.preventDefault()}>{startContent}</div>
+  ) : visible.length === 0 ? (
+    <p className={cn("ax:px-sm ax:py-sm ax:text-muted-foreground", SIZE_TEXT[size])}>
+      {typeof emptyMessage === "function" ? emptyMessage(trimmed) : emptyMessage}
+    </p>
+  ) : (
+    <div role="listbox" id={listId} aria-label={ariaLabel}>
+      {groups.map((group, groupIndex) => (
+        <div
+          key={group.name ?? `group-${groupIndex}`}
+          role={group.name ? "group" : undefined}
+          aria-labelledby={group.name ? `${autoId}-group-${groupIndex}` : undefined}
+          className="ax:py-2xs"
+        >
+          {group.name && (
+            <div id={`${autoId}-group-${groupIndex}`} className="ax:px-sm ax:pt-xs ax:pb-2xs ax:t-overline ax:text-muted-foreground">
+              {group.name}
+            </div>
+          )}
+          {group.items.map((item) => {
+            const isActive = activeItem === item
+            const isSelected = selected?.value === item.value
+            return (
+              <div
+                key={item.value}
+                id={optionId(item)}
+                role="option"
+                aria-selected={isPicker ? isSelected : isActive}
+                aria-disabled={item.disabled || undefined}
+                data-active={isActive || undefined}
+                onMouseDown={(event) => event.preventDefault()}
+                onMouseMove={() => !item.disabled && setActive(visible.indexOf(item))}
+                onClick={() => pick(item)}
+                className={cn(
+                  "ax:flex ax:cursor-pointer ax:select-none ax:items-center ax:gap-sm ax:rounded-(--input-radius) ax:px-sm ax:py-xs",
+                  "ax:text-foreground ax:transition-colors",
+                  SIZE_TEXT[size],
+                  isActive && "ax:bg-muted",
+                  isSelected && "ax:font-medium",
+                  item.disabled && "ax:cursor-not-allowed ax:opacity-50",
+                )}
+              >
+                {item.icon && (
+                  <span className="ax:flex ax:size-6 ax:shrink-0 ax:items-center ax:justify-center ax:text-muted-foreground ax:[&_svg]:size-4">
+                    {item.icon}
+                  </span>
+                )}
+                <span className="ax:min-w-0 ax:flex-1 ax:truncate">
+                  {highlightMatches ? <Highlight text={item.label} query={trimmed} /> : item.label}
+                </span>
+                {item.description && (
+                  <span className="ax:shrink-0 ax:t-caption ax:text-muted-foreground">{item.description}</span>
+                )}
+              </div>
+            )
+          })}
+        </div>
+      ))}
+    </div>
+  )
+
+  return (
+    <PopoverPrimitive.Root open={open} onOpenChange={(next) => (next ? openList() : close())} modal={false}>
+      <PopoverPrimitive.Anchor asChild>
+        <div ref={anchorRef} className={cn("ax:w-full", className)} data-slot="combobox">
+          <TextFieldRoot size={size} invalid={invalid}>
+            <TextFieldSlot>
+              <SearchIcon className="ax:size-4" aria-hidden />
+            </TextFieldSlot>
+            <Input
+              ref={inputRef}
+              id={inputId}
+              name={name}
+              type="text"
+              disabled={disabled}
+              aria-invalid={invalid || undefined}
+              value={inputValue}
+              placeholder={placeholder}
+              aria-label={ariaLabel}
+              role="combobox"
+              aria-expanded={open}
+              aria-controls={open && !showStart && visible.length > 0 ? listId : undefined}
+              aria-autocomplete="list"
+              aria-activedescendant={activeItem ? optionId(activeItem) : undefined}
+              autoComplete="off"
+              onChange={(event) => {
+                setEditing(true)
+                setQuery(event.target.value)
+                setOpen(true)
+              }}
+              onFocus={openList}
+              onClick={openList}
+              onKeyDown={onKeyDown}
+            />
+            {inputValue && !disabled && (
+              <TextFieldSlot>
+                <button
+                  type="button"
+                  aria-label={isPicker ? "Clear selection" : "Clear search"}
+                  onMouseDown={(event) => event.preventDefault()}
+                  onClick={() => {
+                    setQuery("")
+                    setEditing(true)
+                    if (isPicker) onValueChange?.(null)
+                    inputRef.current?.focus()
+                  }}
+                  className="ax:rounded-sm ax:text-muted-foreground ax:transition-colors ax:hover:text-foreground ax:focus-visible:outline-none ax:focus-visible:ring-2 ax:focus-visible:ring-ring"
+                >
+                  <ClearIcon className="ax:size-4" />
+                </button>
+              </TextFieldSlot>
+            )}
+          </TextFieldRoot>
+          <span className="ax:sr-only" aria-live="polite">
+            {open && trimmed && !loading ? `${visible.length} ${visible.length === 1 ? "result" : "results"}` : ""}
+          </span>
+        </div>
+      </PopoverPrimitive.Anchor>
+      <PopoverPrimitive.Portal>
+        <PopoverPrimitive.Content
+          // A listbox popup, not a dialog: focus never leaves the input.
+          role="presentation"
+          align="start"
+          sideOffset={6}
+          onOpenAutoFocus={(event) => event.preventDefault()}
+          onCloseAutoFocus={(event) => event.preventDefault()}
+          onInteractOutside={(event) => {
+            if (anchorRef.current?.contains(event.target as Node)) event.preventDefault()
+          }}
+          className={cn(
+            "ax:z-[1100] ax:w-(--radix-popper-anchor-width) ax:max-h-80 ax:overflow-y-auto",
+            "ax:rounded-(--input-radius) ax:border ax:border-border ax:bg-popover ax:p-2xs ax:text-popover-foreground ax:shadow-md ax:outline-none",
+            "ax:data-[state=open]:animate-in ax:data-[state=closed]:animate-out ax:data-[state=closed]:fade-out-0 ax:data-[state=open]:fade-in-0",
+            "ax:[animation-duration:var(--motion-fast)] ax:motion-reduce:animate-none",
+          )}
+        >
+          {listContent}
+        </PopoverPrimitive.Content>
+      </PopoverPrimitive.Portal>
+    </PopoverPrimitive.Root>
+  )
+}

package/src/components/countdown-pill.stories.tsx

@@ -0,0 +1,24 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { CountdownPill } from "./countdown-pill"
+
+const meta: Meta<typeof CountdownPill> = {
+  title: "Components/CountdownPill",
+  component: CountdownPill,
+  tags: ["autodocs"],
+  args: {
+    label: "Starts in",
+    value: "2h 15m",
+    tone: "info",
+    size: "md",
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof CountdownPill>
+
+export const Default: Story = {}
+
+export const Critical: Story = {
+  args: { tone: "critical", value: "5m", label: "Ends in" },
+}

package/src/components/countdown-pill.tsx

@@ -0,0 +1,129 @@
+"use client"
+
+import * as React from "react"
+import { Clock } from "lucide-react"
+import { cn } from "../lib/cn"
+
+export type CountdownTone = "neutral" | "info" | "success" | "warning" | "critical"
+export type CountdownSize = "sm" | "md" | "lg"
+
+export interface CountdownPillProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** The countdown text itself - the bit that gets emphasized.
+   *  e.g. `"2h 15m"`, `"3 days"`, `"Live now"`. */
+  value: string
+  /** Optional context label rendered before the value.
+   *  e.g. `"Starts in"`, `"Bidding ends in"`. */
+  label?: string
+  /** Visual urgency tier. Drives the value (and icon) color so the consumer
+   *  can dial attention up or down without changing markup. */
+  tone?: CountdownTone
+  /** Visual density. */
+  size?: CountdownSize
+  /** Optional icon override. Defaults to a Clock glyph. Pass `null` to omit. */
+  icon?: React.ReactNode | null
+}
+
+// Value uses raw `text-* font-bold` (not `t-h*` tokens) on purpose: the
+// typography tokens hard-code `text-foreground-strong`, which would override
+// the semantic tone color and defeat the urgency cue.
+
+const VALUE_CLASS: Record<CountdownSize, string> = {
+  sm: "ax:text-sm ax:font-bold",
+  md: "ax:text-2xl ax:font-bold",      // 24px
+  lg: "ax:text-4xl ax:font-bold",      // 36px
+}
+
+const LABEL_CLASS: Record<CountdownSize, string> = {
+  sm: "ax:t-caption",
+  md: "ax:t-label-sm",
+  lg: "ax:t-overline",
+}
+
+const ICON_CLASS: Record<CountdownSize, string> = {
+  sm: "ax:size-3.5 ax:[&>svg]:size-3.5",
+  md: "ax:size-4 ax:[&>svg]:size-4",
+  lg: "ax:size-5 ax:[&>svg]:size-5",
+}
+
+const GAP_CLASS: Record<CountdownSize, string> = {
+  sm: "ax:gap-2xs",
+  md: "ax:gap-xs",
+  lg: "ax:gap-sm",
+}
+
+const TONE_VALUE: Record<CountdownTone, string> = {
+  neutral:  "ax:text-foreground",
+  info:     "ax:text-primary",
+  success:  "ax:text-success-foreground",
+  warning:  "ax:text-warning-foreground",
+  critical: "ax:text-destructive-foreground",
+}
+
+// `neutral` keeps the icon muted so it doesn't compete with the label/value;
+// every other tone matches the value color so the icon, label, and value
+// read as a single urgency unit.
+const TONE_ICON: Record<CountdownTone, string> = {
+  neutral:  "ax:text-muted-foreground",
+  info:     "ax:text-primary",
+  success:  "ax:text-success-foreground",
+  warning:  "ax:text-warning-foreground",
+  critical: "ax:text-destructive-foreground",
+}
+
+/** Inline countdown display for time-to-event copy (sessions, deadlines,
+ *  auctions). Designed to *raise* attention: pairs a muted context label
+ *  with a large, tone-colored value. Three sizes and five urgency tones.
+ *
+ *  The component is presentational only. Compute the `value` string and
+ *  pick a `tone` in the consumer. Use [[getCountdownLabel]] to format an
+ *  ISO timestamp into a label like `"Starts in 2h 15m"`. */
+export const CountdownPill = React.forwardRef<HTMLDivElement, CountdownPillProps>(
+  ({ value, label, tone = "neutral", size = "md", icon, className, ...props }, ref) => {
+    const iconNode = icon === null ? null : icon ?? <Clock />
+
+    return (
+      <div
+        ref={ref}
+        className={cn("ax:inline-flex ax:items-center", GAP_CLASS[size], className)}
+        {...props}
+      >
+        {iconNode && (
+          <span className={cn("ax:shrink-0", ICON_CLASS[size], TONE_ICON[tone])}>
+            {iconNode}
+          </span>
+        )}
+        {label && (
+          <span className={cn(LABEL_CLASS[size], "ax:text-muted-foreground")}>
+            {label}
+          </span>
+        )}
+        <span className={cn(VALUE_CLASS[size], TONE_VALUE[tone])}>
+          {value}
+        </span>
+      </div>
+    )
+  },
+)
+CountdownPill.displayName = "CountdownPill"
+
+/** Format an ISO timestamp into a countdown label.
+ *
+ *   • Past / now    → the `ongoingLabel` you pass (e.g. `"Live now"`)
+ *   • Within 24h    → `"2h 15m"`
+ *   • Further out   → `"3 days"`
+ *
+ * Urgency tone is intentionally NOT inferred. Pick it in the consumer
+ * based on your own thresholds and pass it via the `tone` prop. */
+export function getCountdownLabel(dateIso: string, ongoingLabel: string, now = Date.now()): string {
+  const diff = new Date(dateIso).getTime() - now
+  if (diff <= 0) return ongoingLabel
+
+  const hours = Math.floor(diff / (1000 * 60 * 60))
+  if (hours < 24) {
+    const mins = Math.floor((diff % (1000 * 60 * 60)) / (1000 * 60))
+    return `${hours}h ${mins}m`
+  }
+
+  const days = Math.floor(hours / 24)
+  return `${days} day${days !== 1 ? "s" : ""}`
+}

package/src/components/cta.stories.tsx

@@ -0,0 +1,29 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { CTA } from "./cta"
+import { Button } from "./button"
+
+const meta: Meta<typeof CTA> = {
+  title: "Components/CTA",
+  component: CTA,
+  tags: ["autodocs"],
+  args: {
+    title: "Ready to get started?",
+    description: "Join thousands of teams building with Adres.",
+    actions: (
+      <>
+        <Button>Start free trial</Button>
+        <Button variant="outline">Talk to sales</Button>
+      </>
+    ),
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof CTA>
+
+export const Default: Story = {}
+
+export const Primary: Story = {
+  args: { emphasis: "primary" },
+}

package/src/components/cta.tsx

@@ -0,0 +1,52 @@
+"use client"
+
+import * as React from "react"
+import { cn } from "../lib/cn"
+
+export interface CTAProps extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
+  title: React.ReactNode
+  description?: React.ReactNode
+  actions: React.ReactNode
+  /** Visual emphasis - 'subtle' uses muted surface, 'primary' uses brand surface. */
+  emphasis?: "subtle" | "primary"
+}
+
+/**
+ * CTA - closing call-to-action section for marketing pages.
+ * Two emphasis levels so it can adapt to where it sits on the page.
+ */
+export const CTA = React.forwardRef<HTMLElement, CTAProps>(
+  ({ className, title, description, actions, emphasis = "subtle", ...props }, ref) => (
+    <section
+      ref={ref}
+      className={cn("ax:w-full ax:px-xl ax:md:px-3xl ax:py-5xl", className)}
+      {...props}
+    >
+      <div
+        className={cn(
+          "ax:mx-auto ax:max-w-5xl ax:rounded-xl ax:px-2xl ax:md:px-4xl ax:py-4xl ax:md:py-5xl",
+          "ax:flex ax:flex-col ax:items-center ax:text-center ax:gap-xl",
+          emphasis === "primary"
+            ? "ax:bg-primary ax:text-primary-foreground"
+            : "ax:bg-muted ax:text-foreground"
+        )}
+      >
+        <h2 className="ax:t-display-md ax:md:t-display-lg ax:[text-wrap:balance]">
+          {title}
+        </h2>
+        {description && (
+          <p
+            className={cn(
+              "ax:t-body-md ax:md:t-body-lg ax:[text-wrap:pretty] ax:max-w-2xl",
+              emphasis === "primary" ? "ax:text-primary-foreground/80" : "ax:text-muted-foreground"
+            )}
+          >
+            {description}
+          </p>
+        )}
+        <div className="ax:flex ax:flex-wrap ax:gap-sm ax:justify-center ax:pt-xs">{actions}</div>
+      </div>
+    </section>
+  )
+)
+CTA.displayName = "CTA"

package/src/components/data-list.stories.tsx

@@ -0,0 +1,50 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { DataList, DataListItem, DataListLabel, DataListValue } from "./data-list"
+
+const meta: Meta<typeof DataList> = {
+  title: "Components/DataList",
+  component: DataList,
+  tags: ["autodocs"],
+}
+
+export default meta
+type Story = StoryObj<typeof DataList>
+
+export const Default: Story = {
+  render: () => (
+    <DataList className="ax:max-w-md">
+      <DataListItem>
+        <DataListLabel>Status</DataListLabel>
+        <DataListValue>Active</DataListValue>
+      </DataListItem>
+      <DataListItem>
+        <DataListLabel>Plan</DataListLabel>
+        <DataListValue>Professional</DataListValue>
+      </DataListItem>
+      <DataListItem>
+        <DataListLabel>Renewal</DataListLabel>
+        <DataListValue>Sep 1, 2026</DataListValue>
+      </DataListItem>
+    </DataList>
+  ),
+}
+
+/** Short facts in columns, label above value, without dividers. */
+export const Grid: Story = {
+  render: () => (
+    <DataList orientation="grid" columns={4} size="sm">
+      {[
+        ["Trade licence", "2120561384412A"],
+        ["Brokerage licence", "8812612491127"],
+        ["Licence expiry", "15 May 2028"],
+        ["Phone", "00 1098231807"],
+      ].map(([label, value]) => (
+        <DataListItem key={label}>
+          <DataListLabel>{label}</DataListLabel>
+          <DataListValue>{value}</DataListValue>
+        </DataListItem>
+      ))}
+    </DataList>
+  ),
+}