@adres/mgda-ui 0.0.0-stage → 0.0.2

package/src/index.ts

@@ -0,0 +1,343 @@
+// ─── Web App - Layout & Navigation ───────────────────────────────────────────
+export {
+  Sidebar, SidebarItem, SidebarSection, SidebarUserCard,
+  type SidebarProps, type SidebarItemProps, type SidebarUserCardProps,
+} from "./components/sidebar"
+export {
+  NavSidebar,
+  type NavSidebarProps, type NavSection, type NavItem, type NavSubItem,
+} from "./components/nav-sidebar"
+export { ListNav, ListNavItem, type ListNavProps, type ListNavItemProps, type ListNavSize } from "./components/list-nav"
+export { SectionNav, type SectionNavProps, type SectionNavItem } from "./components/section-nav"
+export { CardsNav, type CardsNavItem, type CardsNavProps, type CardsNavSize } from "./components/cards-nav"
+export {
+  BulletList, BulletListItem,
+  type BulletListProps, type BulletListItemProps, type BulletListSize,
+} from "./components/bullet-list"
+export { BoxList, type BoxListItem, type BoxListProps, type BoxListSize } from "./components/box-list"
+export { TopNav, Breadcrumbs, type TopNavProps, type BreadcrumbsProps } from "./components/top-nav"
+export { PageHeader, type PageHeaderProps } from "./components/page-header"
+export { EntityHeader, entityHeaderVariants, entityInitials, type EntityHeaderProps, type EntityHeaderSize } from "./components/entity-header"
+export { StatStrip, statStripVariants, type StatStripProps, type StatStripItem, type StatStripTone } from "./components/stat-strip"
+export { Tabs, TabsList, TabsTrigger, TabsContent, type TabsProps, type TabsSize } from "./components/tabs"
+
+// ─── Web App - Core Primitives ────────────────────────────────────────────────
+export { Button, buttonVariants, type ButtonProps } from "./components/button"
+export {
+  ButtonGroup, ButtonGroupItem,
+  type ButtonGroupProps, type ButtonGroupItemProps,
+  type ButtonGroupSize, type ButtonGroupVariant, type ButtonGroupSelected,
+} from "./components/button-group"
+export {
+  Input, TextFieldRoot, TextFieldSlot,
+  Textarea,
+  Label, Field,
+  type InputProps, type InputSize,
+  type TextFieldRootProps, type TextFieldSlotProps,
+  type TextareaProps, type TextareaResize, type TextareaSize,
+  type LabelProps, type FieldProps,
+} from "./components/input"
+export { Search, type SearchProps } from "./components/search"
+export { Combobox, type ComboboxProps, type ComboboxItem, type ComboboxSize } from "./components/combobox"
+export { Card, CardHeader, CardBanner, CardTitle, CardDescription, CardContent, CardFooter, cardCn, type CardProps, type CardHeaderProps, type CardBannerProps, type CardHeaderSize, type CardVariant, type CardPadding, type CardGap, type CardElevation } from "./components/card"
+export { Calendar, type CalendarProps, type CalendarMode, type CalendarValue, type DateRange } from "./components/calendar"
+export { Inset, type InsetProps, type InsetSide, type InsetClip } from "./components/inset"
+export { Badge, badgeVariants, type BadgeProps } from "./components/badge"
+export { Alert, AlertTitle, AlertDescription, type AlertProps } from "./components/alert"
+export { Separator } from "./components/separator"
+export {
+  Avatar, AvatarImage, AvatarFallback, AvatarStack,
+  type AvatarProps, type AvatarImageProps, type AvatarFallbackProps, type AvatarStackProps,
+  type AvatarSize,
+} from "./components/avatar"
+export {
+  Skeleton, SkeletonText,
+  type SkeletonProps, type SkeletonTextProps, type SkeletonVariant,
+} from "./components/skeleton"
+export { EmptyState, type EmptyStateProps } from "./components/empty-state"
+export { AspectRatio } from "./components/aspect-ratio"
+export {
+  Blockquote, BlockquoteCaption, BlockquoteFigure,
+  type BlockquoteProps, type BlockquoteCaptionProps, type BlockquoteFigureProps,
+  type BlockquoteSize, type BlockquoteColor,
+} from "./components/blockquote"
+export { Quote, quoteVariants, type QuoteProps } from "./components/quote"
+export { Text, type TextProps, type TextAs, type TextSize, type TextWeight, type TextAlign, type TextColor, type TextWrap } from "./components/text"
+export { Heading, headingVariants, type HeadingProps, type HeadingAs, type HeadingSize, type HeadingColor, type HeadingAlign, type HeadingWrap } from "./components/heading"
+export { TextLink, textLinkVariants, type TextLinkProps, type TextLinkColor, type TextLinkUnderline, type TextLinkSize } from "./components/text-link"
+
+// ─── Web App - Overlays ───────────────────────────────────────────────────────
+export {
+  Drawer,
+  DrawerTrigger,
+  DrawerClose,
+  DrawerContent,
+  DrawerHeader,
+  DrawerBody,
+  DrawerFooter,
+  DrawerTitle,
+  DrawerDescription,
+  type DrawerProps,
+  type DrawerContentProps,
+  type DrawerSide,
+  type DrawerSize,
+} from "./components/drawer"
+export {
+  Dialog,
+  DialogTrigger,
+  DialogPortal,
+  DialogClose,
+  DialogOverlay,
+  DialogContent,
+  DialogHeader,
+  DialogFooter,
+  DialogTitle,
+  DialogDescription,
+  type DialogContentProps,
+  type DialogSize,
+} from "./components/dialog"
+export {
+  Tooltip,
+  TooltipTrigger,
+  TooltipContent,
+  TooltipProvider,
+  type TooltipContentProps,
+} from "./components/tooltip"
+export {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+  PopoverAnchor,
+  PopoverClose,
+  type PopoverContentProps,
+  type PopoverSize,
+} from "./components/popover"
+export {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuCheckboxItem,
+  DropdownMenuRadioItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuGroup,
+  DropdownMenuPortal,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
+  DropdownMenuRadioGroup,
+  DropdownMenuShortcut,
+  type DropdownMenuContentProps,
+  type DropdownMenuItemProps,
+} from "./components/dropdown-menu"
+
+// ─── Web App - Form Controls ──────────────────────────────────────────────────
+export {
+  SegmentedControl, SegmentedControlItem,
+  type SegmentedControlProps, type SegmentedControlItemProps, type SegmentedControlSize,
+} from "./components/segmented-control"
+export {
+  Select,
+  SelectGroup,
+  SelectValue,
+  SelectTrigger,
+  SelectContent,
+  SelectLabel,
+  SelectItem,
+  SelectSeparator,
+  SelectScrollUpButton,
+  SelectScrollDownButton,
+  type SelectTriggerProps,
+  type SelectTriggerSize,
+} from "./components/select"
+export {
+  SelectButton,
+  type SelectButtonProps,
+  type SelectButtonSize,
+} from "./components/select-button"
+export {
+  InputButton,
+  type InputButtonProps,
+  type InputButtonSize,
+  type InputButtonVariant,
+} from "./components/input-button"
+export { Toggle, type ToggleProps, type ToggleSize } from "./components/toggle"
+export { Slider, type SliderProps, type SliderSize, type SliderValueLabel } from "./components/slider"
+export { Checkbox, type CheckboxProps } from "./components/checkbox"
+export {
+  CheckboxCardGroup, CheckboxCard, CheckboxCardTitle, CheckboxCardDescription,
+  type CheckboxCardGroupProps, type CheckboxCardProps,
+  type CheckboxCardSize, type CheckboxCardOrientation,
+} from "./components/checkbox-card"
+export { RadioGroup, RadioGroupItem, type RadioGroupItemProps } from "./components/radio-group"
+export {
+  RadioCardGroup, RadioCard, RadioCardIcon, RadioCardTitle, RadioCardDescription,
+  type RadioCardGroupProps, type RadioCardProps, type RadioCardSize,
+} from "./components/radio-card"
+
+// ─── Web App - Data ───────────────────────────────────────────────────────────
+export { Accordion, AccordionItem, AccordionTrigger, AccordionContent, type AccordionProps } from "./components/accordion"
+export {
+  DataTable,
+  rowStyle,
+  type DataTableProps, type ColumnDef,
+  type DataTableSize, type DataTableAlign,
+} from "./components/data-table"
+export {
+  DataList, DataListItem, DataListLabel, DataListValue,
+  type DataListProps, type DataListSize, type DataListOrientation, type DataListColumns,
+} from "./components/data-list"
+export {
+  Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, TableCaption,
+  type TableProps, type TableSize, type TableVariant,
+} from "./components/table"
+
+// ─── Web App - Media ─────────────────────────────────────────────────────────
+export {
+  Slideshow, SlideshowSlide,
+  type SlideshowProps, type SlideshowSlideProps, type SlideshowVariant,
+} from "./components/slideshow"
+export {
+  MediaGallery, Lightbox,
+  type MediaGalleryProps, type LightboxProps, type MediaItem, type MediaKind,
+} from "./components/media-gallery"
+
+// ─── Web App - Feedback ───────────────────────────────────────────────────────
+export { Toaster, toast } from "./components/toaster"
+export {
+  Progress,
+  type ProgressProps, type ProgressSize, type ProgressVariant, type ProgressShape,
+} from "./components/progress"
+export { Spinner, type SpinnerProps, type SpinnerSize } from "./components/spinner"
+
+// ─── Web App - Patterns ──────────────────────────────────────────────────────
+// Higher-level compositions built on top of the core primitives. Generic
+// enough to be reused across brands; domain wording is parameterised.
+export {
+  KpiCard, KpiCardGroup,
+  type KpiCardProps, type KpiCardGroupProps, type KpiCardSize,
+} from "./components/kpi-card"
+export {
+  CountdownPill,
+  getCountdownLabel,
+  type CountdownPillProps,
+  type CountdownTone,
+  type CountdownSize,
+} from "./components/countdown-pill"
+export {
+  StepIndicator,
+  type StepIndicatorProps, type StepIndicatorStep,
+  type StepIndicatorSize, type StepIndicatorOrientation,
+} from "./components/step-indicator"
+export { NumberStepper, type NumberStepperProps, type NumberStepperSize } from "./components/number-stepper"
+export {
+  EmailChipsInput,
+  type EmailChipsInputProps,
+  type EmailChipsInputVariant,
+  type EmailChip,
+} from "./components/email-chips-input"
+export {
+  Dropzone,
+  type DropzoneProps, type DropzoneError, type DropzoneErrorReason,
+} from "./components/dropzone"
+export { QuotaBar, type QuotaBarProps, type QuotaBarShape } from "./components/quota-bar"
+export {
+  Pagination, type PaginationProps,
+  PaginationContent,
+  PaginationItem,
+  PaginationLink, type PaginationLinkProps, paginationLinkVariants,
+  PaginationPrevious,
+  PaginationNext, type PaginationNavLinkProps,
+  PaginationEllipsis,
+} from "./components/pagination"
+export {
+  ActivityRings,
+  type ActivityRing,
+  type ActivityRingsProps,
+} from "./components/activity-rings"
+export {
+  BarGraph,
+  type BarGraphProps,
+  type BarGraphItem,
+  type BarGraphSize,
+  type BarGraphDirection,
+} from "./components/bar-graph"
+
+// ─── Web App - AI ────────────────────────────────────────────────────────────
+// Parts for assistant and chat surfaces. Domain data stays with the caller.
+export {
+  MessageAction, MessageActions,
+  type MessageActionProps, type MessageActionsProps, type MessageRating,
+} from "./components/message-actions"
+export {
+  ChatMessage, ChatAvatar, ChatDivider,
+  type ChatMessageProps, type ChatMessageFrom, type ChatMessageStatus,
+  type ChatAvatarProps, type ChatDividerProps,
+} from "./components/chat-message"
+export {
+  ChatContainerRoot, ChatContainerContent, ChatScrollButton, useChatContainer,
+  type ChatContainerRootProps, type ChatContainerContentProps, type ChatScrollButtonProps, type ChatContainerState,
+} from "./components/chat-container"
+export {
+  SuggestionChips, StarterPrompts,
+  type SuggestionChipsProps, type StarterPromptsProps, type StarterPromptItem,
+} from "./components/prompt-suggestions"
+export {
+  PromptInput, PromptInputAction, AttachmentChip, characterCountTone, formatFileSize,
+  type PromptInputProps, type PromptInputSize, type PromptInputActionProps, type AttachmentChipProps, type CharacterCountTone,
+} from "./components/prompt-input"
+export {
+  ThinkingSteps, StreamingCursor, thinkingStepsSummary,
+  type ThinkingStepsProps, type ThinkingStep, type ThinkingStepStatus,
+} from "./components/thinking-steps"
+export {
+  ShimmerText, shimmerGradient, type ShimmerTextProps, type ShimmerTextAs,
+} from "./components/shimmer-text"
+export { ThinkingBar, type ThinkingBarProps } from "./components/thinking-bar"
+export {
+  ChainOfThought, ChainOfThoughtStep, ChainOfThoughtTrigger, ChainOfThoughtContent, ChainOfThoughtItem,
+  type ChainOfThoughtProps, type ChainOfThoughtStepProps, type ChainOfThoughtTriggerProps,
+  type ChainOfThoughtContentProps, type ChainOfThoughtItemProps,
+} from "./components/chain-of-thought"
+export {
+  Reasoning, ReasoningTrigger, ReasoningContent,
+  type ReasoningProps, type ReasoningTriggerProps, type ReasoningContentProps,
+} from "./components/reasoning"
+export {
+  ToolCallCard, TOOL_CALL_STATUS, toolCallNeedsAttention, toolPartToCallCard, formatToolValue,
+  type ToolCallCardProps, type ToolCallStatus, type ToolCallField, type ToolPart, type ToolPartCardProps,
+} from "./components/tool-call-card"
+export {
+  CitationMarker, UnsupportedClaim, SourceCard, SourceList, SourceAvatar, isStale, formatSourceDate,
+  type CitationSource, type CitationSourceKind, type CitationMarkerProps, type UnsupportedClaimProps,
+  type SourceCardProps, type SourceListProps, type SourceAvatarProps,
+} from "./components/citations"
+export {
+  Source, SourceTrigger, SourceContent, sourceDomain,
+  type SourceProps, type SourceTriggerProps, type SourceContentProps,
+} from "./components/source"
+export {
+  AnswerActions, FeedbackReasonChips,
+  type AnswerActionsProps, type AnswerFeedback, type AnswerReport, type FeedbackReasonChipsProps,
+} from "./components/answer-actions"
+export { FeedbackBar, type FeedbackBarProps } from "./components/feedback-bar"
+
+// ─── Layout ───────────────────────────────────────────────────────────────────
+export { BentoGrid, BentoItem, type BentoGridProps, type BentoItemProps } from "./components/bento-grid"
+
+// ─── Marketing ────────────────────────────────────────────────────────────────
+export { Hero, type HeroProps, type HeroLayout, type HeroStat } from "./components/hero"
+export { CTA, type CTAProps } from "./components/cta"
+export { FeatureGrid, type Feature, type FeatureGridProps } from "./components/feature-grid"
+export { Pricing, type PricingProps, type PricingTier } from "./components/pricing"
+export { Testimonials, type TestimonialsProps, type Testimonial } from "./components/testimonials"
+export { Stats, type StatsProps, type Stat } from "./components/stats"
+export { LogoCloud, type LogoCloudProps, type LogoCloudItem } from "./components/logo-cloud"
+export { Footer, type FooterProps, type FooterColumn, type FooterLink } from "./components/footer"
+
+// ─── Utilities & Hooks ────────────────────────────────────────────────────────
+export { cn } from "./lib/cn"
+export { useReducedMotion } from "./hooks/use-reduced-motion"
+export { useInView } from "./hooks/use-in-view"
+export { transitions, variants, stagger, viewport, hover } from "./lib/motion"

package/src/lib/cn.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest"
+import { cn } from "./cn"
+
+describe("cn", () => {
+  it("joins plain class names", () => {
+    expect(cn("px-2", "py-1")).toBe("px-2 py-1")
+  })
+
+  it("drops falsy conditional values", () => {
+    expect(cn("px-2", false && "hidden", undefined, null, "font-medium")).toBe(
+      "px-2 font-medium",
+    )
+  })
+
+  it("resolves conflicting Tailwind utilities with last wins", () => {
+    expect(cn("px-2", "px-4")).toBe("px-4")
+    expect(cn("text-foreground/60", "text-foreground")).toBe("text-foreground")
+  })
+
+  it("resolves conflicting ax-prefixed utilities with last wins", () => {
+    expect(cn("ax:px-2", "ax:px-4")).toBe("ax:px-4")
+    expect(cn("ax:text-foreground/60", "ax:text-foreground")).toBe("ax:text-foreground")
+    expect(cn("ax:hover:bg-primary", "ax:hover:bg-primary-strong")).toBe("ax:hover:bg-primary-strong")
+  })
+
+  it("merges the DS named spacing tokens like built-in values", () => {
+    expect(cn("ax:px-sm", "ax:px-0")).toBe("ax:px-0")
+    expect(cn("ax:py-5xl", "ax:py-0")).toBe("ax:py-0")
+    expect(cn("ax:p-xl", "ax:p-md")).toBe("ax:p-md")
+    expect(cn("ax:gap-md", "ax:gap-2")).toBe("ax:gap-2")
+    expect(cn("ax:size-3xl", "ax:size-2xl")).toBe("ax:size-2xl")
+    expect(cn("ax:h-3xl", "ax:h-auto")).toBe("ax:h-auto")
+    expect(cn("ax:-mx-sm", "ax:-mx-md")).toBe("ax:-mx-md")
+  })
+
+  it("keeps an axis-specific spacing token that refines a shorthand", () => {
+    expect(cn("ax:p-xl", "ax:px-md")).toBe("ax:p-xl ax:px-md")
+  })
+
+  it("merges CSS-variable radius shorthand with other radius values", () => {
+    expect(cn("ax:rounded-(--button-radius)", "ax:rounded-full")).toBe("ax:rounded-full")
+    expect(cn("ax:rounded-full", "ax:rounded-(--input-radius)")).toBe("ax:rounded-(--input-radius)")
+  })
+
+  it("lets a later t-* utility replace an earlier one", () => {
+    expect(cn("ax:t-body-md", "ax:t-label-sm")).toBe("ax:t-label-sm")
+    expect(cn("ax:t-h1", "ax:t-display-md")).toBe("ax:t-display-md")
+  })
+
+  it("keeps weight and size utilities on either side of a t-* utility", () => {
+    expect(cn("ax:font-medium", "ax:t-body-sm")).toBe("ax:font-medium ax:t-body-sm")
+    expect(cn("ax:text-sm", "ax:t-body-md")).toBe("ax:text-sm ax:t-body-md")
+  })
+
+  it("keeps a t-* utility when a later utility only refines it", () => {
+    expect(cn("ax:t-body-md", "ax:font-medium")).toBe("ax:t-body-md ax:font-medium")
+    expect(cn("ax:t-body-md", "ax:text-muted-foreground")).toBe("ax:t-body-md ax:text-muted-foreground")
+  })
+
+  it("keeps an ax utility when an unprefixed class conflicts", () => {
+    expect(cn("ax:px-2", "px-4")).toBe("ax:px-2 px-4")
+    expect(cn("px-4", "ax:px-2")).toBe("px-4 ax:px-2")
+    expect(cn("ax:hover:bg-primary", "hover:bg-primary-strong")).toBe(
+      "ax:hover:bg-primary hover:bg-primary-strong",
+    )
+  })
+})

package/src/lib/cn.ts

@@ -0,0 +1,81 @@
+import { clsx, type ClassValue } from "clsx"
+import { extendTailwindMerge } from "tailwind-merge"
+
+/** Named spacing tokens from `--spacing-*` in base.css (`ax:px-sm`, `ax:size-3xl`). */
+const SPACING_TOKENS = ["2xs", "xs", "sm", "md", "lg", "xl", "2xl", "3xl", "4xl", "5xl", "6xl"]
+
+/** The `@utility t-*` scale in typography.css. */
+const TYPE_SCALE = [
+  "display-3xl", "display-2xl", "display-xl", "display-lg", "display-md", "display-sm",
+  "h1", "h2", "h3", "h4", "h5", "h6",
+  "body-2xl", "body-xl", "body-lg", "body-md", "body-sm", "body-xs",
+  "label-lg", "label-md", "label-sm", "label-xs", "label-2xs",
+  "caption", "overline", "code", "micro",
+]
+
+/** Tailwind v4 CSS-variable shorthand, e.g. `rounded-(--button-radius)`. tailwind-merge v2 predates it. */
+const isCssVariable = (value: string) => /^\(--[\w-]+\)$/.test(value)
+
+/**
+ * Tailwind v4 writes the library prefix as a leading variant (`ax:px-4`).
+ * Strip it before conflict detection so `ax:px-2` and `ax:px-4` collapse.
+ * Unprefixed classes are merged in their own group so `px-4` cannot remove `ax:px-2`.
+ *
+ * The DS's own tokens are registered so they merge like built-in values;
+ * without this, `ax:px-sm` and `ax:px-0` both survive and stylesheet order,
+ * not call order, decides which one applies.
+ */
+const twMerge = extendTailwindMerge<"ds-type">({
+  experimentalParseClassName({ className, parseClassName }) {
+    return parseClassName(className.startsWith("ax:") ? className.slice(3) : className)
+  },
+  extend: {
+    theme: {
+      spacing: [...SPACING_TOKENS, isCssVariable],
+      borderRadius: [isCssVariable],
+    },
+    // `t-*` classes only replace each other. They set different properties
+    // (body sizes set size and leading, headings also weight and tracking), and
+    // components layer `font-medium` on top of them on purpose, so a `t-*`
+    // class must not remove the size or weight utilities around it.
+    classGroups: {
+      "ds-type": [{ t: TYPE_SCALE }],
+    },
+  },
+})
+
+/**
+ * `cn` - class-name composer.
+ *
+ * Combines `clsx` (conditional class lists) with `tailwind-merge`
+ * (last-wins resolution of conflicting Tailwind utilities).
+ *
+ * @example
+ *   cn("px-2", isLarge && "px-4")          // → "px-4"
+ *   cn("ax:px-2", "ax:px-4")               // → "ax:px-4"
+ *   cn("ax:px-sm", "ax:px-0")              // → "ax:px-0"
+ *   cn("ax:t-body-md", "ax:t-label-sm")    // → "ax:t-label-sm"
+ *   cn("ax:px-2", "px-4")                  // → "ax:px-2 px-4"
+ *   cn("ax:text-foreground/60", className) // later `ax:` class wins
+ */
+export function cn(...inputs: ClassValue[]): string {
+  const tokens = clsx(inputs).split(/\s+/).filter(Boolean)
+  const plain: string[] = []
+  const prefixed: string[] = []
+  for (const token of tokens) {
+    if (token.startsWith("ax:")) prefixed.push(token)
+    else plain.push(token)
+  }
+
+  const plainKept = new Set(twMerge(plain).split(/\s+/).filter(Boolean))
+  const prefixedKept = new Set(twMerge(prefixed).split(/\s+/).filter(Boolean))
+  const seen = new Set<string>()
+  const kept: string[] = []
+  for (const token of tokens) {
+    const group = token.startsWith("ax:") ? prefixedKept : plainKept
+    if (!group.has(token) || seen.has(token)) continue
+    seen.add(token)
+    kept.push(token)
+  }
+  return kept.join(" ")
+}

package/src/lib/motion.ts

@@ -0,0 +1,109 @@
+// Single source of truth for all motion primitives in the design system.
+// Import from here; never hardcode animation values in components.
+//
+// Guiding principles
+// ──────────────────
+// • Enter with ease-out  - fast start, smooth deceleration into place (feels responsive)
+// • Exit  with ease-in   - gentle start, fast departure (gets out of the way)
+// • State transitions use ease-in-out - balanced arc between two visible positions
+// • Exits are ~70 % of the enter duration - exits should never overstay
+// • Durations scale with surface size - micro < standard < large
+
+// ─── Named easing curves (mirror the CSS custom properties in base.css) ───────
+
+export const easing = {
+  /** Enter: fast start → smooth deceleration. Use when elements arrive on screen. */
+  out:   [0.22, 1, 0.36, 1] as const,
+  /** Exit: gentle start → fast departure. Use when elements leave the screen. */
+  in:    [0.55, 0, 1, 0.45] as const,
+  /** State: balanced arc. Use when an element moves between two visible positions. */
+  inOut: [0.45, 0, 0.55, 1] as const,
+} as const
+
+// ─── Duration + easing presets ────────────────────────────────────────────────
+
+export const transitions = {
+  /** Micro-interactions: hover states, small feedbacks, icon swaps. */
+  snappy: { duration: 0.16, ease: easing.out },
+
+  /** Standard UI: dropdowns, tooltips, badges, small panels. */
+  smooth: { duration: 0.28, ease: easing.out },
+
+  /** Large surfaces: drawers, modals, marketing sections. */
+  slow:   { duration: 0.42, ease: easing.out },
+
+  /** Exit counterpart of `smooth` - 70 % duration, ease-in so it leaves quickly. */
+  exit:   { duration: 0.20, ease: easing.in  },
+
+  /** Exit counterpart of `slow` - use for large surfaces leaving. */
+  exitSlow: { duration: 0.28, ease: easing.in },
+
+  /** Spring - bouncy interactive elements (cards on hover, spring pop). */
+  spring:  { type: "spring" as const, stiffness: 260, damping: 28, mass: 0.9 },
+
+  /** Springy - snappier spring for rapid interactions. */
+  springy: { type: "spring" as const, stiffness: 380, damping: 22, mass: 0.7 },
+}
+
+const T = transitions
+
+// ─── Named variants ───────────────────────────────────────────────────────────
+// Each `visible` state bakes in its transition so children work correctly inside
+// stagger containers without needing a separate `transition` prop.
+
+export const variants = {
+  fadeUp: {
+    hidden:  { opacity: 0, y: 20 },
+    visible: { opacity: 1, y: 0,     transition: T.slow },
+  },
+  fadeIn: {
+    hidden:  { opacity: 0 },
+    visible: { opacity: 1,           transition: T.smooth },
+  },
+  scaleIn: {
+    hidden:  { opacity: 0, scale: 0.95 },
+    visible: { opacity: 1, scale: 1,   transition: T.smooth },
+  },
+  springPop: {
+    hidden:  { opacity: 0, scale: 0.8 },
+    visible: { opacity: 1, scale: 1,   transition: T.springy },
+  },
+  slideLeft: {
+    hidden:  { opacity: 0, x: -24 },
+    visible: { opacity: 1, x: 0,       transition: T.slow },
+  },
+  slideRight: {
+    hidden:  { opacity: 0, x: 24 },
+    visible: { opacity: 1, x: 0,       transition: T.slow },
+  },
+  slideUp: {
+    hidden:  { opacity: 0, y: 32 },
+    visible: { opacity: 1, y: 0,       transition: T.slow },
+  },
+}
+
+// ─── Stagger container ────────────────────────────────────────────────────────
+
+// Returns a stagger container variant. Use on a parent `motion.*`; put `variants`
+// on children: they'll animate with the correct stagger delay automatically.
+export function stagger(delayChildren = 0, staggerChildren = 0.08) {
+  return {
+    hidden: {},
+    visible: { transition: { delayChildren, staggerChildren } },
+  }
+}
+
+// ─── Viewport config ──────────────────────────────────────────────────────────
+
+// Default viewport config for whileInView animations.
+export const viewport = { once: true, margin: "-60px 0px" } as const
+
+// ─── Hover presets ────────────────────────────────────────────────────────────
+
+// whileHover target states. Pair with a `transition` on the same element.
+// e.g. whileHover={hover.lift} transition={transitions.spring}
+export const hover = {
+  lift:  { y: -4 },
+  scale: { scale: 1.04 },
+  float: { y: -6, scale: 1.02 },
+}

package/src/lib/prefix-utilities.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest"
+import { prefixUtilities } from "./prefix-utilities"
+
+describe("prefixUtilities", () => {
+  it("prefixes a single utility", () => {
+    expect(prefixUtilities("px-4").text).toBe("ax:px-4")
+  })
+
+  it("puts ax before variants and arbitrary values", () => {
+    expect(prefixUtilities("sm:flex-row").text).toBe("ax:sm:flex-row")
+    expect(prefixUtilities("hover:bg-primary").text).toBe("ax:hover:bg-primary")
+    expect(prefixUtilities("dark:bg-black/40").text).toBe("ax:dark:bg-black/40")
+    expect(prefixUtilities("focus-visible:ring-2").text).toBe("ax:focus-visible:ring-2")
+    expect(prefixUtilities("rounded-(--input-radius)").text).toBe("ax:rounded-(--input-radius)")
+    expect(prefixUtilities("has-[input:disabled]:opacity-50").text).toBe(
+      "ax:has-[input:disabled]:opacity-50",
+    )
+  })
+
+  it("leaves the dark theme hook and elevation classes unchanged", () => {
+    const result = prefixUtilities("px-4 dark elevation-0")
+    expect(result.text).toBe("ax:px-4 dark elevation-0")
+    expect(result.skipped).toEqual(["dark", "elevation-0"])
+  })
+
+  it("leaves the docs prose class unchanged", () => {
+    expect(prefixUtilities("prose-docs").text).toBe("prose-docs")
+  })
+
+  it("leaves fumadocs utilities unchanged", () => {
+    expect(prefixUtilities("bg-fd-background text-fd-foreground").text).toBe(
+      "bg-fd-background text-fd-foreground",
+    )
+  })
+
+  it("prefixes utilities inside @apply and keeps the directive", () => {
+    expect(prefixUtilities("@apply t-label-sm;").text).toBe("@apply ax:t-label-sm;")
+    expect(
+      prefixUtilities(
+        "@apply font-display text-8xl font-semibold leading-24 tracking-tighter text-foreground-strong;",
+      ).text,
+    ).toBe(
+      "@apply ax:font-display ax:text-8xl ax:font-semibold ax:leading-24 ax:tracking-tighter ax:text-foreground-strong;",
+    )
+  })
+
+  it("does not double-prefix and keeps surrounding whitespace", () => {
+    expect(prefixUtilities("  ax:px-4\npx-2  ").text).toBe("  ax:px-4\nax:px-2  ")
+  })
+
+  it("leaves a token it does not recognize and reports it", () => {
+    const result = prefixUtilities("px-4 {not-a-class}")
+    expect(result.text).toBe("ax:px-4 {not-a-class}")
+    expect(result.skipped).toEqual(["{not-a-class}"])
+  })
+})