@adres/mgda-ui 0.0.0-stage → 0.0.1

package/src/components/select.tsx

@@ -0,0 +1,198 @@
+"use client"
+
+import * as React from "react"
+import * as SelectPrimitive from "@radix-ui/react-select"
+import { Check, ChevronDown, ChevronUp } from "lucide-react"
+import { cn } from "../lib/cn"
+
+export const Select = SelectPrimitive.Root
+export const SelectGroup = SelectPrimitive.Group
+export const SelectValue = SelectPrimitive.Value
+
+// Sizes mirror Button so a Select sits at the same height + interior padding
+// as a Button at the matching size.
+export type SelectTriggerSize = "sm" | "md" | "lg"
+
+const TRIGGER_HEIGHT: Record<SelectTriggerSize, string> = {
+  sm: "ax:h-2xl",  // 32px
+  md: "ax:h-3xl",  // 40px
+  lg: "ax:h-4xl",  // 48px
+}
+
+const TRIGGER_PADDING_X: Record<SelectTriggerSize, string> = {
+  sm: "ax:px-sm",
+  md: "ax:px-md",
+  lg: "ax:px-xl",
+}
+
+const TRIGGER_TEXT: Record<SelectTriggerSize, string> = {
+  sm: "ax:t-label-sm",
+  md: "ax:t-label-sm",
+  lg: "ax:text-base",
+}
+
+export interface SelectTriggerProps
+  extends React.ComponentPropsWithoutRef<typeof SelectPrimitive.Trigger> {
+  size?: SelectTriggerSize
+  /** Drop the border - for inline / sidebar triggers that shouldn't read as a field. */
+  borderless?: boolean
+  /** Drop the solid background so the trigger blends into its surface. */
+  transparent?: boolean
+}
+
+export const SelectTrigger = React.forwardRef<
+  React.ElementRef<typeof SelectPrimitive.Trigger>,
+  SelectTriggerProps
+>(({ className, size = "md", borderless = false, transparent = false, children, ...props }, ref) => (
+  <SelectPrimitive.Trigger
+    ref={ref}
+    className={cn(
+      "ax:flex ax:w-full ax:items-center ax:justify-between ax:gap-xs ax:rounded-(--input-radius) ax:py-xs",
+      "ax:text-foreground ax:placeholder:text-muted-foreground",
+      "ax:transition-[border-color,box-shadow] ax:transition-snappy",
+      "ax:focus:outline-none ax:focus:ring-2 ax:focus:ring-ring ax:focus:ring-offset-1 ax:focus:ring-offset-background ax:focus:border-transparent",
+      "ax:cursor-pointer ax:disabled:cursor-not-allowed ax:disabled:opacity-50",
+      "ax:data-[placeholder]:text-muted-foreground",
+      // leading-snug on the value span: t-label-sm is leading-none, and line-clamp-1
+      // sets overflow-hidden: a 1.0 line-height would shave descenders (g, y, p).
+      // flex-1 + text-start keep the value filling the trigger and left-aligned so
+      // a truncated value (…) doesn't drift to centre against the chevron.
+      "ax:[&>span]:line-clamp-1 ax:[&>span]:leading-snug ax:[&>span]:min-w-0 ax:[&>span]:flex-1 ax:[&>span]:text-start",
+      borderless ? "ax:border-0" : "ax:border ax:border-input",
+      transparent ? "ax:bg-transparent" : "ax:bg-background",
+      TRIGGER_HEIGHT[size],
+      TRIGGER_PADDING_X[size],
+      TRIGGER_TEXT[size],
+      className
+    )}
+    {...props}
+  >
+    {children}
+    <SelectPrimitive.Icon asChild>
+      <ChevronDown className="ax:size-4 ax:shrink-0 ax:text-muted-foreground" />
+    </SelectPrimitive.Icon>
+  </SelectPrimitive.Trigger>
+))
+SelectTrigger.displayName = SelectPrimitive.Trigger.displayName
+
+export const SelectScrollUpButton = React.forwardRef<
+  React.ElementRef<typeof SelectPrimitive.ScrollUpButton>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.ScrollUpButton>
+>(({ className, ...props }, ref) => (
+  <SelectPrimitive.ScrollUpButton
+    ref={ref}
+    className={cn("ax:flex ax:cursor-default ax:items-center ax:justify-center ax:py-1", className)}
+    {...props}
+  >
+    <ChevronUp className="ax:size-4" />
+  </SelectPrimitive.ScrollUpButton>
+))
+SelectScrollUpButton.displayName = SelectPrimitive.ScrollUpButton.displayName
+
+export const SelectScrollDownButton = React.forwardRef<
+  React.ElementRef<typeof SelectPrimitive.ScrollDownButton>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.ScrollDownButton>
+>(({ className, ...props }, ref) => (
+  <SelectPrimitive.ScrollDownButton
+    ref={ref}
+    className={cn("ax:flex ax:cursor-default ax:items-center ax:justify-center ax:py-1", className)}
+    {...props}
+  >
+    <ChevronDown className="ax:size-4" />
+  </SelectPrimitive.ScrollDownButton>
+))
+SelectScrollDownButton.displayName = SelectPrimitive.ScrollDownButton.displayName
+
+export const SelectContent = React.forwardRef<
+  React.ElementRef<typeof SelectPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Content>
+>(({ className, children, position = "popper", ...props }, ref) => (
+  <SelectPrimitive.Portal>
+    <SelectPrimitive.Content
+      ref={ref}
+      className={cn(
+        "ax:relative ax:z-[1100] ax:max-h-96 ax:min-w-[8rem] ax:overflow-hidden",
+        "ax:rounded-(--input-radius) ax:border ax:border-border ax:bg-popover ax:text-popover-foreground ax:shadow-md",
+        "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:data-[state=closed]:zoom-out-[0.96] ax:data-[state=open]:zoom-in-[0.96]",
+        "ax:data-[side=bottom]:slide-in-from-top-1",
+        "ax:data-[side=left]:slide-in-from-right-1",
+        "ax:data-[side=right]:slide-in-from-left-1",
+        "ax:data-[side=top]:slide-in-from-bottom-1",
+        "ax:[animation-duration:var(--motion-fast)] ax:[animation-timing-function:var(--motion-ease-out)]",
+        "ax:motion-reduce:animate-none",
+        position === "popper" && [
+          "ax:data-[side=bottom]:translate-y-1",
+          "ax:data-[side=left]:-translate-x-1",
+          "ax:data-[side=right]:translate-x-1",
+          "ax:data-[side=top]:-translate-y-1",
+        ],
+        className
+      )}
+      position={position}
+      {...props}
+    >
+      <SelectScrollUpButton />
+      <SelectPrimitive.Viewport
+        className={cn(
+          "ax:p-2xs",
+          position === "popper" && "ax:h-[var(--radix-select-trigger-height)] ax:w-full ax:min-w-[var(--radix-select-trigger-width)]"
+        )}
+      >
+        {children}
+      </SelectPrimitive.Viewport>
+      <SelectScrollDownButton />
+    </SelectPrimitive.Content>
+  </SelectPrimitive.Portal>
+))
+SelectContent.displayName = SelectPrimitive.Content.displayName
+
+export const SelectLabel = React.forwardRef<
+  React.ElementRef<typeof SelectPrimitive.Label>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Label>
+>(({ className, ...props }, ref) => (
+  <SelectPrimitive.Label
+    ref={ref}
+    className={cn("ax:px-2 ax:py-1.5 ax:t-overline ax:text-muted-foreground", className)}
+    {...props}
+  />
+))
+SelectLabel.displayName = SelectPrimitive.Label.displayName
+
+export const SelectItem = React.forwardRef<
+  React.ElementRef<typeof SelectPrimitive.Item>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Item>
+>(({ className, children, ...props }, ref) => (
+  <SelectPrimitive.Item
+    ref={ref}
+    className={cn(
+      "ax:relative ax:flex ax:w-full ax:cursor-pointer ax:select-none ax:items-center ax:rounded-(--input-radius) ax:py-1.5 ax:pl-2 ax:pr-8",
+      "ax:t-body-sm ax:text-foreground ax:outline-none",
+      "ax:focus:bg-muted ax:focus:text-foreground",
+      "ax:data-[disabled]:pointer-events-none ax:data-[disabled]:opacity-50",
+      className
+    )}
+    {...props}
+  >
+    <span className="ax:absolute ax:right-2 ax:flex ax:size-3.5 ax:items-center ax:justify-center">
+      <SelectPrimitive.ItemIndicator>
+        <Check className="ax:size-4" />
+      </SelectPrimitive.ItemIndicator>
+    </span>
+    <SelectPrimitive.ItemText>{children}</SelectPrimitive.ItemText>
+  </SelectPrimitive.Item>
+))
+SelectItem.displayName = SelectPrimitive.Item.displayName
+
+export const SelectSeparator = React.forwardRef<
+  React.ElementRef<typeof SelectPrimitive.Separator>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Separator>
+>(({ className, ...props }, ref) => (
+  <SelectPrimitive.Separator
+    ref={ref}
+    className={cn("ax:-mx-1 ax:my-1 ax:h-px ax:bg-border", className)}
+    {...props}
+  />
+))
+SelectSeparator.displayName = SelectPrimitive.Separator.displayName

package/src/components/separator.stories.tsx

@@ -0,0 +1,22 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { Separator } from "./separator"
+
+const meta: Meta<typeof Separator> = {
+  title: "Components/Separator",
+  component: Separator,
+  tags: ["autodocs"],
+}
+
+export default meta
+type Story = StoryObj<typeof Separator>
+
+export const Default: Story = {
+  render: () => (
+    <div className="ax:w-64 ax:space-y-md">
+      <p className="ax:t-body-sm">Section one</p>
+      <Separator />
+      <p className="ax:t-body-sm">Section two</p>
+    </div>
+  ),
+}

package/src/components/separator.tsx

@@ -0,0 +1,23 @@
+"use client"
+
+import * as React from "react"
+import * as SeparatorPrimitive from "@radix-ui/react-separator"
+import { cn } from "../lib/cn"
+
+export const Separator = React.forwardRef<
+  React.ElementRef<typeof SeparatorPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof SeparatorPrimitive.Root>
+>(({ className, orientation = "horizontal", decorative = true, ...props }, ref) => (
+  <SeparatorPrimitive.Root
+    ref={ref}
+    decorative={decorative}
+    orientation={orientation}
+    className={cn(
+      "ax:shrink-0 ax:bg-border",
+      orientation === "horizontal" ? "ax:h-px ax:w-full" : "ax:h-full ax:w-px",
+      className
+    )}
+    {...props}
+  />
+))
+Separator.displayName = SeparatorPrimitive.Root.displayName

package/src/components/shimmer-text.stories.tsx

@@ -0,0 +1,23 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { ShimmerText } from "./shimmer-text"
+
+const meta: Meta<typeof ShimmerText> = {
+  title: "Components/ShimmerText",
+  component: ShimmerText,
+  tags: ["autodocs"],
+  args: { children: "Searching listings on Yas Island", duration: 2.5, spread: 20 },
+  argTypes: {
+    as: { control: "select", options: ["span", "p", "div", "strong", "h1", "h2", "h3", "h4", "h5", "h6"] },
+    duration: { control: { type: "range", min: 0.5, max: 8, step: 0.5 } },
+    spread: { control: { type: "range", min: 5, max: 45, step: 1 } },
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof ShimmerText>
+
+export const Default: Story = {}
+
+export const Heading: Story = { args: { as: "h3", className: "ax:t-h3", children: "Preparing your report" } }
+
+export const SlowWide: Story = { args: { duration: 5, spread: 40, children: "Comparing registered sales" } }

package/src/components/shimmer-text.test.tsx

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest"
+import * as React from "react"
+import { renderToStaticMarkup } from "react-dom/server"
+import { ShimmerText, shimmerGradient } from "./shimmer-text"
+
+describe("shimmerGradient", () => {
+  it("brightens the centre and spreads the highlight either side", () => {
+    expect(shimmerGradient(20)).toContain("hsl(var(--muted-foreground)) 30%, hsl(var(--foreground)) 50%, hsl(var(--muted-foreground)) 70%")
+  })
+
+  it("clamps the spread to 5-45", () => {
+    expect(shimmerGradient(0)).toContain(" 45%, ")
+    expect(shimmerGradient(99)).toContain(" 5%, ")
+  })
+})
+
+describe("ShimmerText", () => {
+  it("renders a span with the gradient inline, so class merging cannot drop it", () => {
+    const html = renderToStaticMarkup(<ShimmerText className="ax:bg-primary">Thinking</ShimmerText>)
+    expect(html).toMatch(/^<span/)
+    expect(html).toContain("background-image:linear-gradient")
+    expect(html).toContain("background-size:200% auto")
+  })
+
+  it("takes the element, duration and caller styles", () => {
+    const html = renderToStaticMarkup(<ShimmerText as="p" duration={4} style={{ letterSpacing: "1px" }}>Searching</ShimmerText>)
+    expect(html).toMatch(/^<p/)
+    expect(html).toContain("animation-duration:4s")
+    expect(html).toContain("letter-spacing:1px")
+  })
+
+  it("stops the sweep under reduced motion", () => {
+    expect(renderToStaticMarkup(<ShimmerText>Thinking</ShimmerText>)).toContain("ax:motion-reduce:animate-none")
+  })
+})

package/src/components/shimmer-text.tsx

@@ -0,0 +1,43 @@
+"use client"
+
+import * as React from "react"
+import { cn } from "../lib/cn"
+
+export type ShimmerTextAs = "span" | "p" | "div" | "strong" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6"
+
+export interface ShimmerTextProps extends React.HTMLAttributes<HTMLElement> {
+  as?: ShimmerTextAs
+  /** Seconds for one sweep. */
+  duration?: number
+  /** Width of the highlight as a percentage either side of centre, clamped to 5-45. */
+  spread?: number
+}
+
+/** The gradient behind the text: muted, bright at centre, muted. */
+export function shimmerGradient(spread: number) {
+  const s = Math.min(Math.max(spread, 5), 45)
+  return `linear-gradient(to right, hsl(var(--muted-foreground)) ${50 - s}%, hsl(var(--foreground)) 50%, hsl(var(--muted-foreground)) ${50 + s}%)`
+}
+
+/**
+ * ShimmerText - text with a highlight sweeping across it, for work in
+ * progress such as "Thinking" or "Searching listings". The sweep stops under
+ * reduced motion; the text stays readable.
+ *
+ * @example
+ *   <ShimmerText>Searching listings</ShimmerText>
+ *   <ShimmerText as="p" duration={4} spread={30}>Comparing registered sales</ShimmerText>
+ */
+export const ShimmerText = React.forwardRef<HTMLElement, ShimmerTextProps>(
+  ({ as: Tag = "span", duration = 2.5, spread = 20, className, style, ...props }, ref) => (
+    <Tag
+      ref={ref as React.Ref<never>}
+      data-slot="shimmer-text"
+      // Gradient and size go inline: cn's tailwind-merge drops bg-linear-to-r beside other bg-* classes.
+      style={{ backgroundImage: shimmerGradient(spread), backgroundSize: "200% auto", animationDuration: `${duration}s`, ...style }}
+      className={cn("ax:bg-clip-text ax:text-transparent ax:animate-text-shimmer ax:motion-reduce:animate-none", className)}
+      {...props}
+    />
+  ),
+)
+ShimmerText.displayName = "ShimmerText"

package/src/components/sidebar.stories.tsx

@@ -0,0 +1,25 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { Sidebar, SidebarItem, SidebarSection } from "./sidebar"
+
+const meta: Meta<typeof Sidebar> = {
+  title: "Components/Sidebar",
+  component: Sidebar,
+  tags: ["autodocs"],
+}
+
+export default meta
+type Story = StoryObj<typeof Sidebar>
+
+export const Default: Story = {
+  render: () => (
+    <div className="ax:h-[320px] ax:border ax:border-border ax:rounded-md ax:overflow-hidden">
+      <Sidebar>
+        <SidebarSection label="Main">
+          <SidebarItem href="#" active>Dashboard</SidebarItem>
+          <SidebarItem href="#">Projects</SidebarItem>
+        </SidebarSection>
+      </Sidebar>
+    </div>
+  ),
+}

package/src/components/sidebar.tsx

@@ -0,0 +1,234 @@
+"use client"
+
+import * as React from "react"
+import { Slot } from "@radix-ui/react-slot"
+import { motion, AnimatePresence } from "motion/react"
+import { cn } from "../lib/cn"
+import { useReducedMotion } from "../hooks/use-reduced-motion"
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "./tooltip"
+
+// ─── Sidebar ──────────────────────────────────────────────────────────────────
+
+export interface SidebarProps extends React.HTMLAttributes<HTMLElement> {
+  /** Sidebar width in rem; default 16rem (256px). */
+  width?: number
+  /** Collapsed state - controlled. When undefined, sidebar is always open. */
+  collapsed?: boolean
+  /** Optional logo / brand mark slot at the top. */
+  brand?: React.ReactNode
+  /** Optional footer slot (typically a `SidebarUserCard`). */
+  footer?: React.ReactNode
+}
+
+/**
+ * Sidebar - primary app-shell navigation surface.
+ *
+ * Vertical column with brand, scrollable nav body, and footer. Uses logical
+ * properties (`border-e`) so the column sits on the inline-start edge in LTR
+ * and flips to inline-end in RTL automatically. Animates collapsed/expanded
+ * state via motion (suppressed under reduced motion).
+ */
+export const Sidebar = React.forwardRef<HTMLElement, SidebarProps>(
+  ({ className, width = 16, collapsed, brand, footer, children, ...props }, ref) => {
+    const reduce = useReducedMotion()
+    const collapsedWidth = 4
+
+    const targetWidth = collapsed ? `${collapsedWidth}rem` : `${width}rem`
+
+    const inner = (
+      <>
+        {brand && <div className="ax:h-5xl ax:px-md ax:flex ax:items-center">{brand}</div>}
+        <nav className="ax:flex-1 ax:overflow-y-auto ax:p-sm">{children}</nav>
+        {footer && <div className="ax:border-t ax:border-border ax:p-sm">{footer}</div>}
+      </>
+    )
+
+    const baseClasses = cn(
+      "ax:shrink-0 ax:h-full ax:overflow-hidden ax:border-e ax:border-border ax:bg-card ax:text-card-foreground",
+      "ax:flex ax:flex-col",
+      className
+    )
+
+    return (
+      // TooltipProvider here so collapsed SidebarItems can show labels-as-tooltips
+      // without requiring the consumer to wrap their app root themselves.
+      <TooltipProvider delayDuration={200}>
+        {reduce ? (
+          <aside
+            ref={ref}
+            aria-label="Primary"
+            style={{ width: targetWidth }}
+            className={baseClasses}
+            {...props}
+          >
+            {inner}
+          </aside>
+        ) : (
+          <motion.aside
+            ref={ref as React.Ref<HTMLElement>}
+            aria-label="Primary"
+            initial={false}
+            animate={{ width: targetWidth }}
+            transition={{ type: "spring", stiffness: 320, damping: 32 }}
+            className={baseClasses}
+            {...(props as Record<string, unknown>)}
+          >
+            {inner}
+          </motion.aside>
+        )}
+      </TooltipProvider>
+    )
+  }
+)
+Sidebar.displayName = "Sidebar"
+
+// ─── SidebarItem ──────────────────────────────────────────────────────────────
+
+export interface SidebarItemProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+  icon?: React.ReactNode
+  active?: boolean
+  collapsed?: boolean
+  /**
+   * Render as the child element (e.g. a Next.js `<Link>`). The child receives
+   * the className, ref, and event props so it behaves as the sidebar row while
+   * keeping its own navigation behaviour.
+   */
+  asChild?: boolean
+}
+
+/**
+ * SidebarItem - a row inside `Sidebar`.
+ *
+ * Renders an `<a>` by default. Use `asChild` to wrap a Next.js `<Link>` (or
+ * any custom navigation component) without losing the visual treatment.
+ *
+ * Active state: tinted background + matching text + a 2px start-edge bar
+ * (`border-s-2 border-primary`). Inactive rows reserve the same 2px so
+ * activating doesn't shift the label horizontally.
+ *
+ * When `collapsed` is true the label is hidden and the `children` are
+ * surfaced as a Tooltip on the inline-end side. Keep `children` to a
+ * short string when collapsed mode is in play.
+ */
+export const SidebarItem = React.forwardRef<HTMLAnchorElement, SidebarItemProps>(
+  ({ className, icon, active, collapsed, asChild, children, ...props }, ref) => {
+    const Comp = asChild ? Slot : "a"
+
+    const row = (
+      <Comp
+        ref={ref as React.Ref<HTMLAnchorElement>}
+        aria-current={active ? "page" : undefined}
+        className={cn(
+          "ax:group ax:flex ax:items-center ax:gap-sm ax:rounded-md ax:ps-xs ax:pe-xs ax:py-xs ax:t-label-sm ax:cursor-pointer",
+          // Reserve the 2px start-edge bar on every row so the active state
+          // doesn't nudge content horizontally.
+          "ax:border-s-2 ax:border-transparent",
+          "ax:transition-colors ax:transition-snappy",
+          "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-card",
+          active
+            ? "ax:bg-card ax:text-primary-foreground ax:border-primary"
+            : "ax:text-foreground ax:hover:bg-muted ax:hover:text-foreground-strong",
+          collapsed && "ax:justify-center ax:ps-2xs ax:pe-2xs",
+          className
+        )}
+        {...props}
+      >
+        {icon && <span className="ax:size-4 ax:shrink-0 ax:flex ax:items-center ax:justify-center ax:[&>svg]:size-4 ax:[&>svg]:shrink-0">{icon}</span>}
+        <AnimatePresence initial={false}>
+          {!collapsed && (
+            <motion.span
+              initial={{ opacity: 0, width: 0 }}
+              animate={{ opacity: 1, width: "auto" }}
+              exit={{ opacity: 0, width: 0 }}
+              transition={{ duration: 0.15 }}
+              className="ax:overflow-hidden ax:whitespace-nowrap"
+            >
+              {children}
+            </motion.span>
+          )}
+        </AnimatePresence>
+      </Comp>
+    )
+
+    if (collapsed) {
+      return (
+        <Tooltip>
+          <TooltipTrigger asChild>{row}</TooltipTrigger>
+          {/* `side="right"` flips to the inline-end in RTL because Radix uses
+              physical sides; we mirror with a logical `rtl:` rule on the parent. */}
+          <TooltipContent side="right">{children}</TooltipContent>
+        </Tooltip>
+      )
+    }
+
+    return row
+  }
+)
+SidebarItem.displayName = "SidebarItem"
+
+// ─── SidebarSection ───────────────────────────────────────────────────────────
+
+export const SidebarSection = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement> & { label?: React.ReactNode; collapsed?: boolean }
+>(
+  ({ className, label, collapsed, children, ...props }, ref) => (
+    <div ref={ref} className={cn("ax:flex ax:flex-col ax:gap-0.5 ax:py-xs", className)} {...props}>
+      {label && !collapsed && (
+        <div className="ax:px-xs ax:pb-xs ax:t-caption ax:text-foreground/50 ax:font-medium">
+          {label}
+        </div>
+      )}
+      {children}
+    </div>
+  )
+)
+SidebarSection.displayName = "SidebarSection"
+
+// ─── SidebarUserCard ──────────────────────────────────────────────────────────
+//
+// Conventional footer block: avatar + name + role + optional action slot.
+// Matches the pattern called out in the TPB spec ("User avatar + name +
+// 'Company Admin' role label, settings, logout"). Collapses to just the
+// avatar when the sidebar is collapsed.
+
+// `role` is our domain prop (the sub-label under the name); the HTML
+// attribute of the same name is omitted to keep the type clean.
+export interface SidebarUserCardProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "role"> {
+  /** Avatar element (typically `<Avatar>` from the DS). */
+  avatar: React.ReactNode
+  /** Display name. */
+  name: React.ReactNode
+  /** Role / sub-label rendered under the name (e.g. "Company Admin"). */
+  role?: React.ReactNode
+  /** Trailing slot - typically a DropdownMenu trigger for settings/logout. */
+  action?: React.ReactNode
+  /** Hides the name/role/action when the parent Sidebar is collapsed. */
+  collapsed?: boolean
+}
+
+export const SidebarUserCard = React.forwardRef<HTMLDivElement, SidebarUserCardProps>(
+  ({ className, avatar, name, role, action, collapsed, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn(
+        "ax:flex ax:items-center ax:gap-sm",
+        collapsed && "ax:justify-center",
+        className
+      )}
+      {...props}
+    >
+      <div className="ax:shrink-0">{avatar}</div>
+      {!collapsed && (
+        <>
+          <div className="ax:min-w-0 ax:flex-1">
+            <div className="ax:t-label-sm ax:text-foreground ax:truncate">{name}</div>
+            {role && <div className="ax:t-caption ax:text-muted-foreground ax:truncate">{role}</div>}
+          </div>
+          {action && <div className="ax:shrink-0">{action}</div>}
+        </>
+      )}
+    </div>
+  )
+)
+SidebarUserCard.displayName = "SidebarUserCard"

package/src/components/skeleton.stories.tsx

@@ -0,0 +1,22 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { Skeleton } from "./skeleton"
+
+const meta: Meta<typeof Skeleton> = {
+  title: "Components/Skeleton",
+  component: Skeleton,
+  tags: ["autodocs"],
+}
+
+export default meta
+type Story = StoryObj<typeof Skeleton>
+
+export const Default: Story = {
+  render: () => (
+    <div className="ax:space-y-sm ax:w-64">
+      <Skeleton className="ax:h-4 ax:w-full" />
+      <Skeleton className="ax:h-4 ax:w-3/4" />
+      <Skeleton className="ax:h-20 ax:w-full ax:rounded-md" />
+    </div>
+  ),
+}