@adres/mgda-ui 0.0.0-stage → 0.0.1

package/src/components/kpi-card.tsx

@@ -0,0 +1,284 @@
+"use client"
+
+import * as React from "react"
+import { TrendingDown, TrendingUp } from "lucide-react"
+import { Card, CardContent } from "./card"
+import { Skeleton } from "./skeleton"
+import { cn } from "../lib/cn"
+
+export type KpiCardSize = "mini" | "sm" | "md" | "lg"
+
+// ─── Group context ────────────────────────────────────────────────────────────
+//
+// `KpiCardGroup compact` merges its children into a single visual block:
+// the cards lose their individual rounding/shadow and overlap their borders
+// (`-mt-px` on mobile, `-ms-px` on desktop). Children read this via context
+// so the parent grouping is fully declarative; consumers don't need to thread
+// per-card props.
+
+interface KpiCardGroupContextValue {
+  compact: boolean
+  columns?: 2 | 3 | 4
+}
+
+const KpiCardGroupContext = React.createContext<KpiCardGroupContextValue>({ compact: false })
+
+export interface KpiCardGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Merge children into a borderless single-block layout. */
+  compact?: boolean
+  /** Lay the cards out in a fixed N-column grid instead of a single flex row.
+   *  With `compact`, the grid renders as a seamless bordered "table" - 1px
+   *  hairline dividers between cells inside a rounded outer frame. Give a card
+   *  `sm:col-span-*` to make a row span fewer, wider columns (e.g. a 4-column
+   *  grid whose second row is two `col-span-2` cells). */
+  columns?: 2 | 3 | 4
+}
+
+const GRID_COLS: Record<2 | 3 | 4, string> = {
+  2: "ax:sm:grid-cols-2",
+  3: "ax:sm:grid-cols-3",
+  4: "ax:sm:grid-cols-4",
+}
+
+export const KpiCardGroup = React.forwardRef<HTMLDivElement, KpiCardGroupProps>(
+  ({ compact = false, columns, className, children, ...props }, ref) => (
+    <KpiCardGroupContext.Provider value={{ compact, columns }}>
+      <div
+        ref={ref}
+        className={cn(
+          columns
+            ? compact
+              // Seamless bordered "table": the container paints the seams:
+              // `bg-border` shows through the `gap-px` as 1px dividers, clipped
+              // to a rounded outer frame. Cards inside drop their own chrome.
+              ? cn("ax:grid ax:grid-cols-1 ax:gap-px ax:overflow-hidden ax:rounded-md ax:border ax:border-border ax:bg-border", GRID_COLS[columns])
+              // Non-compact: a plain N-column grid of separate cards.
+              : cn("ax:grid ax:gap-md ax:grid-cols-1", GRID_COLS[columns])
+            : compact
+              // Stacks vertically on mobile, becomes a horizontal row at `sm` and up.
+              ? "ax:flex ax:flex-col ax:sm:flex-row"
+              : "ax:grid ax:gap-md ax:sm:grid-cols-2 ax:lg:grid-cols-4",
+          className,
+        )}
+        {...props}
+      >
+        {children}
+      </div>
+    </KpiCardGroupContext.Provider>
+  ),
+)
+KpiCardGroup.displayName = "KpiCardGroup"
+
+// ─── KpiCard ──────────────────────────────────────────────────────────────────
+
+export interface KpiCardProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Overline label sitting above the value. */
+  title: string
+  /** The metric itself. Strings are useful for pre-formatted values
+   *  ("76 %", "1.2k"). Numbers get a `0` fallback for the empty state. */
+  value: string | number
+  /** Optional period-over-period delta as a percentage. Positive → success
+   *  pill with an up-arrow; negative → destructive pill with a down-arrow.
+   *  `0` and `undefined` both render no delta - zero isn't a trend. */
+  change?: number
+  /** Optional suffix appended to the value (e.g. "%", "h"). Rendered in a
+   *  smaller muted style so it doesn't compete with the number. */
+  suffix?: string
+  /** Optional topic icon - rendered muted, top-end of the card. */
+  icon?: React.ReactNode
+  /** Optional context line under the value (e.g. "vs last 30 days"). */
+  description?: React.ReactNode
+  /** Visual density. `md` is the default. */
+  size?: KpiCardSize
+  /** While true, swaps the title/value/delta for skeleton placeholders. */
+  loading?: boolean
+}
+
+// ─── Size tokens ──────────────────────────────────────────────────────────────
+//
+// Trend value uses raw `text-* font-bold` (not `t-h*`) on purpose: the
+// typography tokens hard-code `text-foreground-strong`, which would override
+// the semantic `text-success-strong` / `text-destructive-strong` color on the trend pill.
+
+const CARD_PADDING: Record<KpiCardSize, string> = {
+  mini: "ax:p-md", // 16px (same footprint as sm; mini shrinks the value, not the card)
+  sm: "ax:p-md",   // 16px
+  md: "ax:p-lg",   // 20px
+  lg: "ax:p-xl",   // 24px
+}
+
+const VALUE_CLASS: Record<KpiCardSize, string> = {
+  mini: "ax:t-h2",        // text-lg (18px) - a compact metric
+  sm: "ax:t-h1",          // text-2xl (24px)
+  md: "ax:t-display-md",  // text-3xl (30px)
+  lg: "ax:t-display-lg",  // text-4xl (36px)
+}
+
+// Vertical gap between the label, value, and description. `mini` halves the
+// default (gap-sm = 12px → 6px) to sit its smaller value tight to the label.
+const CONTENT_GAP: Record<KpiCardSize, string> = {
+  mini: "ax:gap-1.5",  // 6px
+  sm: "ax:gap-0",     // 12px
+  md: "ax:gap-0",
+  lg: "ax:gap-0",
+}
+
+const SUFFIX_CLASS: Record<KpiCardSize, string> = {
+  mini: "ax:t-caption",
+  sm: "ax:t-body-sm",
+  md: "ax:t-h5",
+  lg: "ax:t-h4",
+}
+
+const TREND_CLASS: Record<KpiCardSize, string> = {
+  mini: "ax:text-xs ax:font-semibold",
+  sm: "ax:text-sm ax:font-semibold",
+  md: "ax:text-base ax:font-semibold",
+  lg: "ax:text-lg ax:font-semibold",
+}
+
+const TREND_ICON_CLASS: Record<KpiCardSize, string> = {
+  mini: "ax:size-3",
+  sm: "ax:size-3.5",
+  md: "ax:size-4",
+  lg: "ax:size-5",
+}
+
+const ICON_CLASS: Record<KpiCardSize, string> = {
+  mini: "ax:size-3 ax:[&>svg]:size-3",
+  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 SKELETON_VALUE_HEIGHT: Record<KpiCardSize, string> = {
+  mini: "ax:h-5",
+  sm: "ax:h-6",
+  md: "ax:h-7",
+  lg: "ax:h-9",
+}
+
+// Compact-group layout: cards round only their outer edges and overlap
+// borders by 1px so the seam between two cards renders as a single line
+// rather than a doubled-up border.
+const COMPACT_CARD_LAYOUT = [
+  "ax:flex-1 ax:min-w-0",
+  // Drop shadow + per-card rounding when inside a compact group. `bg-card`
+  // restores the solid fill that the flat `level0` elevation clears, so the
+  // merged block keeps its surface while staying shadowless.
+  "ax:rounded-none ax:shadow-none ax:bg-card",
+  // Mobile (stacked): round top of first card, bottom of last; overlap rows.
+  "ax:first:rounded-t-md ax:last:rounded-b-md",
+  "ax:[&:not(:first-child)]:-mt-px",
+  // Desktop (row): round inline-start of first, inline-end of last;
+  //                overlap columns instead of rows.
+  "ax:sm:first:rounded-t-none ax:sm:last:rounded-b-none",
+  "ax:sm:first:rounded-s-md ax:sm:last:rounded-e-md",
+  "ax:sm:[&:not(:first-child)]:mt-0 ax:sm:[&:not(:first-child)]:-ms-px",
+].join(" ")
+
+// Grid-table layout (compact + columns): cells carry no chrome of their own:
+// the group's rounded frame and gap-px hairlines draw every edge, so a card is
+// just a filled rectangle.
+const GRID_TABLE_CARD_LAYOUT = "ax:min-w-0 ax:border-0 ax:rounded-none ax:shadow-none ax:bg-card"
+
+/** Single-metric card with optional trend delta. A common dashboard
+ *  primitive: pairs a big number with a label and (optionally) a
+ *  period-over-period change. The empty state ("No data yet") activates
+ *  only when the numeric value is `0` and no `change` is provided. */
+export const KpiCard = React.forwardRef<HTMLDivElement, KpiCardProps>(
+  (
+    {
+      title,
+      value,
+      change,
+      suffix,
+      icon,
+      description,
+      size = "md",
+      loading,
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    const { compact, columns } = React.useContext(KpiCardGroupContext)
+    const gridTable = compact && columns != null
+
+    const numericValue = typeof value === "number" ? value : Number(value)
+    const isEmpty = numericValue === 0
+    const hasChange = change !== undefined && change !== 0 && !isEmpty
+    const isPositive = (change ?? 0) > 0
+
+    // When an onClick is provided the card becomes interactive: resting
+    // shadow-xs lifts to shadow-md on hover, cursor flips to pointer.
+    // Compact cards are excluded: they have no individual shadow.
+    const isClickable = !compact && typeof props.onClick === "function"
+
+    const cardClasses = cn(
+      CARD_PADDING[size],
+      gridTable ? GRID_TABLE_CARD_LAYOUT : compact && COMPACT_CARD_LAYOUT,
+      className,
+    )
+
+    if (loading) {
+      return (
+        <Card ref={ref} elevation={compact ? "level0" : "level2"} interactive={isClickable} className={cardClasses} {...props}>
+          <CardContent className={cn("ax:p-0 ax:flex ax:flex-col", CONTENT_GAP[size])}>
+            <Skeleton className="ax:h-3 ax:w-24" />
+            <div className="ax:flex ax:items-end ax:justify-between ax:gap-sm">
+              <Skeleton className={cn(SKELETON_VALUE_HEIGHT[size], "ax:w-32")} />
+              <Skeleton className="ax:h-4 ax:w-12" />
+            </div>
+          </CardContent>
+        </Card>
+      )
+    }
+
+    return (
+      <Card ref={ref} elevation={compact ? "level0" : "level2"} interactive={isClickable} className={cardClasses} {...props}>
+        <CardContent className={cn("ax:p-0 ax:flex ax:flex-col", CONTENT_GAP[size])}>
+          <div className="ax:flex ax:items-start ax:justify-between ax:gap-sm">
+            <p className="ax:t-overline ax:text-muted-foreground">{title}</p>
+            {icon && (
+              <span className={cn("ax:shrink-0 ax:text-muted-foreground ax:[&>svg]:shrink-0", ICON_CLASS[size])}>
+                {icon}
+              </span>
+            )}
+          </div>
+
+          <div className={cn("ax:flex ax:items-end ax:gap-sm", compact ? "ax:justify-start" : "ax:justify-between")}>
+            <p className={cn(VALUE_CLASS[size], "ax:font-semibold ax:text-foreground")}>
+              {isEmpty ? "0" : value}
+              {suffix && <span className={cn(SUFFIX_CLASS[size], "ax:text-muted-foreground ax:ms-1")}>{suffix}</span>}
+            </p>
+
+            {hasChange ? (
+              <div
+                className={cn(
+                  "ax:flex ax:items-center ax:gap-1",
+                  TREND_CLASS[size],
+                  isPositive ? "ax:text-success-foreground" : "ax:text-destructive-foreground",
+                )}
+              >
+                {isPositive ? (
+                  <TrendingUp className={cn(TREND_ICON_CLASS[size], "ax:shrink-0")} />
+                ) : (
+                  <TrendingDown className={cn(TREND_ICON_CLASS[size], "ax:shrink-0")} />
+                )}
+                <span>{Math.abs(change ?? 0)}%</span>
+              </div>
+            ) : isEmpty ? (
+              <span className="ax:t-caption ax:text-muted-foreground">No data yet</span>
+            ) : null}
+          </div>
+
+          {description && !isEmpty && (
+            <p className="ax:t-caption ax:text-muted-foreground">{description}</p>
+          )}
+        </CardContent>
+      </Card>
+    )
+  },
+)
+KpiCard.displayName = "KpiCard"

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

@@ -0,0 +1,22 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { ListNav, ListNavItem } from "./list-nav"
+
+const meta: Meta<typeof ListNav> = {
+  title: "Components/ListNav",
+  component: ListNav,
+  tags: ["autodocs"],
+}
+
+export default meta
+type Story = StoryObj<typeof ListNav>
+
+export const Default: Story = {
+  render: () => (
+    <ListNav title="Settings">
+      <ListNavItem active>General</ListNavItem>
+      <ListNavItem>Notifications</ListNavItem>
+      <ListNavItem>Billing</ListNavItem>
+    </ListNav>
+  ),
+}

package/src/components/list-nav.tsx

@@ -0,0 +1,145 @@
+"use client"
+
+import * as React from "react"
+import { Slot, Slottable } from "@radix-ui/react-slot"
+import { cn } from "../lib/cn"
+
+export type ListNavSize = "base" | "lg"
+
+// Size is shared from ListNav to its items via context, so `<ListNav size="lg">`
+// sets the density for the whole list; a single item can still override it.
+interface ListNavContextValue {
+  size: ListNavSize
+}
+const ListNavContext = React.createContext<ListNavContextValue>({ size: "base" })
+
+// Per-size item padding + type. `lg` widens the row into a comfortable ~44px
+// tap target for touchscreens; `base` stays compact for dense desktop lists.
+const ITEM_SIZE: Record<ListNavSize, string> = {
+  base: "ax:px-xs ax:py-2xs ax:t-label-sm",
+  lg:   "ax:px-sm ax:py-sm  ax:t-label-md",
+}
+// Leading icon (and the inset placeholder) column width per size.
+const ICON_BOX: Record<ListNavSize, string> = {
+  base: "ax:size-4",
+  lg:   "ax:size-5",
+}
+
+// ─── ListNav ──────────────────────────────────────────────────────────────────
+
+export interface ListNavProps extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
+  /** Optional eyebrow-style title rendered above the list (uses `t-overline`). */
+  title?: React.ReactNode
+  /** Row density. `base` (default) is compact; `lg` adds padding for a larger,
+   *  touch-friendly tap target. Cascades to all items via context. */
+  size?: ListNavSize
+}
+
+/**
+ * ListNav - vertical list of selectable items with an optional eyebrow title.
+ *
+ * Use for in-page section jumpers, dense filter lists, or any sidebar-adjacent
+ * nav where items don't need an icon column. For app-shell navigation with
+ * brand, collapse, and tooltips, reach for `Sidebar` instead.
+ *
+ * Compose multiple `ListNav`s vertically when grouping is needed: each owns
+ * its own title.
+ */
+export const ListNav = React.forwardRef<HTMLElement, ListNavProps>(
+  ({ className, title, size = "base", children, ...props }, ref) => (
+    <ListNavContext.Provider value={{ size }}>
+      <nav
+        ref={ref}
+        className={cn("ax:flex ax:flex-col", className)}
+        {...props}
+      >
+        {title && (
+          // Title x-padding tracks the item padding so it stays flush with rows.
+          <p className={cn("ax:t-overline ax:text-foreground-strong ax:pt-sm ax:pb-sm", size === "lg" ? "ax:px-sm" : "ax:px-xs")}>
+            {title}
+          </p>
+        )}
+        <div className="ax:flex ax:flex-col">{children}</div>
+      </nav>
+    </ListNavContext.Provider>
+  )
+)
+ListNav.displayName = "ListNav"
+
+// ─── ListNavItem ──────────────────────────────────────────────────────────────
+
+export interface ListNavItemProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  active?: boolean
+  /** Optional leading icon. */
+  icon?: React.ReactNode
+  /**
+   * Reserves the leading icon column even when no icon is provided. Use when
+   * mixing items with and without icons in the same list, so labels stay
+   * aligned. Has no effect if `icon` is set.
+   */
+  inset?: boolean
+  /** Trailing slot - typically a Badge, count, or shortcut hint. */
+  trailing?: React.ReactNode
+  /**
+   * Render as the child element (e.g. a Next.js `<Link>`). The child receives
+   * the className, ref, and event props so it behaves as a list-nav row while
+   * keeping its own navigation behaviour.
+   */
+  asChild?: boolean
+  /** Overrides the row density inherited from `ListNav` for this item. */
+  size?: ListNavSize
+}
+
+export const ListNavItem = React.forwardRef<HTMLButtonElement, ListNavItemProps>(
+  ({ className, active, icon, inset, trailing, asChild, type, size: sizeProp, children, ...props }, ref) => {
+    const { size: ctxSize } = React.useContext(ListNavContext)
+    const size = sizeProp ?? ctxSize
+    const Comp = asChild ? Slot : "button"
+    // `type="button"` only makes sense on a real <button>; if `asChild` wraps
+    // an <a> or <Link>, applying it would emit invalid HTML.
+    const buttonOnly = asChild ? {} : { type: type ?? "button" }
+
+    return (
+      <Comp
+        ref={ref as React.Ref<HTMLButtonElement>}
+        aria-current={active ? "page" : undefined}
+        className={cn(
+          "ax:w-full ax:text-start ax:flex ax:items-center ax:gap-sm ax:rounded-(--input-radius) ax:cursor-pointer",
+          ITEM_SIZE[size],
+          "ax:transition-colors",
+          "ax:focus-visible:outline-none ax:focus-visible:ring-2 ax:focus-visible:ring-ring ax:focus-visible:ring-offset-2 ax:focus-visible:ring-offset-background",
+          active
+            // `bg-primary-weakest` auto-inverts to a deep tint in dark; keep it
+            // translucent there (/25). `text-primary-foreground` flips near-white in
+            // dark (washed-out), so use a bright branded sage (`-strong`) instead.
+            ? "ax:bg-primary-muted ax:text-primary-foreground ax:dark:text-primary-strong ax:font-medium"
+            : "ax:text-muted-foreground ax:hover:text-foreground ax:hover:bg-muted",
+          className,
+        )}
+        {...buttonOnly}
+        {...props}
+      >
+        {icon ? (
+          <span className={cn("ax:shrink-0 ax:flex ax:items-center ax:justify-center ax:[&>svg]:size-full ax:[&>svg]:shrink-0", ICON_BOX[size])}>
+            {icon}
+          </span>
+        ) : inset ? (
+          // Empty placeholder occupying the icon column so labels stay aligned
+          // with sibling rows that DO have an icon.
+          <span aria-hidden="true" className={cn("ax:shrink-0", ICON_BOX[size])} />
+        ) : null}
+        {asChild ? (
+          // Slot needs exactly one slottable child: the consumer's element (e.g. an <a>)
+          // receives the icon and trailing siblings around its own content.
+          <Slottable>{children}</Slottable>
+        ) : (
+          // leading-snug (not the row's t-label-sm leading-none): `truncate` clips
+          // with overflow-hidden, and a 1.0 line-height would shave descenders.
+          <span className="ax:flex-1 ax:truncate ax:leading-snug">{children}</span>
+        )}
+        {trailing && <span className="ax:shrink-0 ax:flex ax:items-center">{trailing}</span>}
+      </Comp>
+    )
+  }
+)
+ListNavItem.displayName = "ListNavItem"

package/src/components/logo-cloud.stories.tsx

@@ -0,0 +1,23 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { LogoCloud } from "./logo-cloud"
+
+const meta: Meta<typeof LogoCloud> = {
+  title: "Components/LogoCloud",
+  component: LogoCloud,
+  tags: ["autodocs"],
+  args: {
+    eyebrow: "Trusted by teams at",
+    items: [
+      { name: "Acme", logo: <span className="ax:t-h5">Acme</span> },
+      { name: "Globex", logo: <span className="ax:t-h5">Globex</span> },
+      { name: "Initech", logo: <span className="ax:t-h5">Initech</span> },
+      { name: "Umbrella", logo: <span className="ax:t-h5">Umbrella</span> },
+    ],
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof LogoCloud>
+
+export const Default: Story = {}

package/src/components/logo-cloud.tsx

@@ -0,0 +1,42 @@
+import * as React from "react"
+import { cn } from "../lib/cn"
+
+export interface LogoCloudItem {
+  name: string
+  logo: React.ReactNode
+}
+
+export interface LogoCloudProps extends React.HTMLAttributes<HTMLElement> {
+  eyebrow?: React.ReactNode
+  items: LogoCloudItem[]
+}
+
+export function LogoCloud({ className, eyebrow, items, ...props }: LogoCloudProps) {
+  return (
+    <section className={cn("ax:w-full ax:px-xl ax:md:px-3xl ax:py-4xl ax:md:py-5xl", className)} {...props}>
+      <div className="ax:mx-auto ax:max-w-420">
+        {eyebrow && (
+          <p className="ax:text-center ax:t-overline ax:text-muted-foreground ax:mb-2xl">
+            {eyebrow}
+          </p>
+        )}
+        <div
+          className={cn(
+            "ax:grid ax:grid-cols-2 ax:gap-x-2xl ax:gap-y-xl ax:items-center",
+            "ax:sm:grid-cols-3 ax:md:grid-cols-4 ax:lg:grid-cols-6"
+          )}
+        >
+          {items.map((item) => (
+            <div
+              key={item.name}
+              title={item.name}
+              className="ax:flex ax:items-center ax:justify-center ax:opacity-50 ax:grayscale ax:hover:opacity-80 ax:hover:grayscale-0 ax:transition-[opacity,filter] ax:transition-smooth"
+            >
+              {item.logo}
+            </div>
+          ))}
+        </div>
+      </div>
+    </section>
+  )
+}

package/src/components/media-gallery.stories.tsx

@@ -0,0 +1,25 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { MediaGallery, type MediaItem } from "./media-gallery"
+
+const media: MediaItem[] = [
+  { type: "image", src: "https://picsum.photos/800/600?random=1", label: "Property exterior" },
+  { type: "image", src: "https://picsum.photos/800/600?random=2", label: "Living room" },
+  { type: "image", src: "https://picsum.photos/800/600?random=3", label: "Kitchen" },
+]
+
+const meta: Meta<typeof MediaGallery> = {
+  title: "Components/MediaGallery",
+  component: MediaGallery,
+  tags: ["autodocs"],
+  args: {
+    title: "Gallery",
+    media,
+    thumbnailCount: 3,
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof MediaGallery>
+
+export const Default: Story = {}