@adres/mgda-ui 0.0.0-stage → 0.0.1

package/src/components/source.tsx

@@ -0,0 +1,161 @@
+"use client"
+
+import * as React from "react"
+import { Link2 } from "lucide-react"
+import { cn } from "../lib/cn"
+import { Popover, PopoverAnchor, PopoverContent } from "./popover"
+import { Text } from "./text"
+
+const OPEN_DELAY_MS = 150
+/** Long enough to move the pointer from the pill into the preview. */
+const CLOSE_DELAY_MS = 120
+
+/** "zillow.com" from a URL; the input itself when it is not a valid URL. */
+export function sourceDomain(href: string) {
+  try {
+    return new URL(href).hostname.replace(/^www\./, "")
+  } catch {
+    return href
+  }
+}
+
+interface SourceContextValue {
+  href: string
+  domain: string
+  open: boolean
+  show: () => void
+  hide: () => void
+}
+
+const SourceContext = React.createContext<SourceContextValue | null>(null)
+
+function useSource(part: string) {
+  const context = React.useContext(SourceContext)
+  if (!context) throw new Error(`${part} must be used inside Source`)
+  return context
+}
+
+export interface SourceProps {
+  href: string
+  children: React.ReactNode
+}
+
+/**
+ * Source - a link to where an answer came from: a small pill labelled with
+ * the domain, previewing the page on hover and keyboard focus. Works from a
+ * URL alone, so it suits web search results.
+ *
+ * @example
+ *   <Source href="https://www.propertyfinder.ae/en/yas-island">
+ *     <SourceTrigger />
+ *     <SourceContent title="Yas Island townhouses" description="42 listings under AED 5M" />
+ *   </Source>
+ */
+export function Source({ href, children }: SourceProps) {
+  const [open, setOpen] = React.useState(false)
+  const timer = React.useRef<number | undefined>(undefined)
+
+  const schedule = React.useCallback((next: boolean, delay: number) => {
+    window.clearTimeout(timer.current)
+    timer.current = window.setTimeout(() => setOpen(next), delay)
+  }, [])
+  const show = React.useCallback(() => schedule(true, OPEN_DELAY_MS), [schedule])
+  const hide = React.useCallback(() => schedule(false, CLOSE_DELAY_MS), [schedule])
+  React.useEffect(() => () => window.clearTimeout(timer.current), [])
+
+  const value = React.useMemo(() => ({ href, domain: sourceDomain(href), open, show, hide }), [href, open, show, hide])
+
+  return (
+    <SourceContext.Provider value={value}>
+      <Popover open={open} onOpenChange={setOpen}>{children}</Popover>
+    </SourceContext.Provider>
+  )
+}
+
+function Favicon({ src, className }: { src?: string; className?: string }) {
+  const [failed, setFailed] = React.useState(false)
+  if (!src || failed) return <Link2 className={className} aria-hidden />
+  // eslint-disable-next-line @next/next/no-img-element -- framework-agnostic package
+  return <img src={src} alt="" className={cn("ax:rounded-full", className)} onError={() => setFailed(true)} />
+}
+
+export interface SourceTriggerProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+  /** Replaces the domain, e.g. a citation number. */
+  label?: React.ReactNode
+  /** Shows a favicon before the label. Pass an image URL to use it; otherwise a link icon. */
+  favicon?: string | boolean
+}
+
+/** The pill in running text. It is a real link to the source. */
+export const SourceTrigger = React.forwardRef<HTMLAnchorElement, SourceTriggerProps>(
+  ({ label, favicon, className, onMouseEnter, onMouseLeave, onFocus, onBlur, ...props }, ref) => {
+    const { href, domain, show, hide } = useSource("SourceTrigger")
+    const custom = label !== undefined
+    return (
+      <PopoverAnchor asChild>
+        <a
+          ref={ref}
+          href={href}
+          target="_blank"
+          rel="noopener noreferrer"
+          data-slot="source-trigger"
+          aria-label={custom ? `Source ${typeof label === "string" || typeof label === "number" ? `${label}, ` : ""}${domain}` : undefined}
+          onMouseEnter={(event) => { onMouseEnter?.(event); show() }}
+          onMouseLeave={(event) => { onMouseLeave?.(event); hide() }}
+          onFocus={(event) => { onFocus?.(event); show() }}
+          onBlur={(event) => { onBlur?.(event); hide() }}
+          className={cn(
+            "ax:mx-0.5 ax:inline-flex ax:h-5 ax:max-w-32 ax:items-center ax:gap-1 ax:overflow-hidden ax:rounded-full ax:bg-muted ax:align-text-top",
+            "ax:text-xs ax:tabular-nums ax:text-muted-foreground ax:no-underline ax:transition-colors",
+            "ax:hover:bg-muted-foreground/20 ax:hover:text-foreground ax:focus-visible:outline-none ax:focus-visible:ring-2 ax:focus-visible:ring-ring",
+            favicon ? "ax:ps-1 ax:pe-2" : "ax:px-1.5",
+            className,
+          )}
+          {...props}
+        >
+          {favicon && <Favicon src={typeof favicon === "string" ? favicon : undefined} className="ax:size-3.5 ax:shrink-0" />}
+          <span className="ax:truncate">{custom ? label : domain}</span>
+        </a>
+      </PopoverAnchor>
+    )
+  },
+)
+SourceTrigger.displayName = "SourceTrigger"
+
+export interface SourceContentProps {
+  title: string
+  description?: string
+  /** Image URL for the site's icon; a link icon otherwise. */
+  favicon?: string
+  className?: string
+}
+
+/** The hover preview: domain, title and description, all one link to the source. */
+export function SourceContent({ title, description, favicon, className }: SourceContentProps) {
+  const { href, domain, show, hide } = useSource("SourceContent")
+  return (
+    <PopoverContent
+      align="start"
+      className={cn("ax:w-80 ax:p-0 ax:shadow-xs", className)}
+      onOpenAutoFocus={(event) => event.preventDefault()}
+      onCloseAutoFocus={(event) => event.preventDefault()}
+      onMouseEnter={show}
+      onMouseLeave={hide}
+    >
+      <a
+        href={href}
+        target="_blank"
+        rel="noopener noreferrer"
+        tabIndex={-1}
+        className="ax:flex ax:flex-col ax:gap-xs ax:rounded-[inherit] ax:p-sm ax:no-underline ax:transition-colors ax:hover:bg-muted/50"
+      >
+        <span className="ax:flex ax:items-center ax:gap-1.5 ax:text-muted-foreground">
+          <Favicon src={favicon} className="ax:size-4 ax:shrink-0" />
+          <Text size="1" color="muted" truncate>{domain}</Text>
+        </span>
+        <Text as="span" size="2" weight="medium" className="ax:line-clamp-2">{title}</Text>
+        {description && <Text as="span" size="2" color="muted" className="ax:line-clamp-2">{description}</Text>}
+      </a>
+    </PopoverContent>
+  )
+}

package/src/components/spinner.stories.tsx

@@ -0,0 +1,19 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { Spinner } from "./spinner"
+
+const meta: Meta<typeof Spinner> = {
+  title: "Components/Spinner",
+  component: Spinner,
+  tags: ["autodocs"],
+  args: { size: "md" },
+}
+
+export default meta
+type Story = StoryObj<typeof Spinner>
+
+export const Default: Story = {}
+
+export const Large: Story = {
+  args: { size: "lg" },
+}

package/src/components/spinner.tsx

@@ -0,0 +1,76 @@
+"use client"
+
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+import { cn } from "../lib/cn"
+
+export type SpinnerSize = "sm" | "md" | "lg" | "xl"
+
+const spinnerVariants = cva(
+  cn(
+    "ax:animate-spin ax:text-primary",
+    // Slow the spin to a 3-second cycle when the OS requests reduced motion.
+    // We don't stop it: a stationary spinner is just a static circle and no
+    // longer reads as "loading". A slow rotation preserves the semantic.
+    "ax:motion-reduce:[animation-duration:3s]"
+  ),
+  {
+    variants: {
+      size: {
+        sm: "ax:size-3.5",
+        md: "ax:size-4",
+        lg: "ax:size-5",
+        xl: "ax:size-6",
+      },
+    },
+    defaultVariants: { size: "md" },
+  }
+)
+
+export interface SpinnerProps
+  extends React.SVGAttributes<SVGSVGElement>,
+    VariantProps<typeof spinnerVariants> {
+  /** Accessible label announced by screen readers via the live region.
+   *  Defaults to `"Loading"`. Use this for i18n or to be more specific
+   *  ("Saving", "Searching", "Fetching listings"). Ignored when
+   *  `decorative` is true. */
+  label?: string
+  /** Hide from assistive tech (`aria-hidden`, drops `role` and `aria-label`).
+   *  Use when a sibling element already announces the loading state - e.g.
+   *  inside a button with visible "Saving…" text - to avoid duplicate
+   *  screen-reader announcements. */
+  decorative?: boolean
+}
+
+export const Spinner = React.forwardRef<SVGSVGElement, SpinnerProps>(
+  ({ className, size, label, decorative = false, ...props }, ref) => {
+    const ariaProps = decorative
+      ? { "aria-hidden": true as const }
+      : { role: "status" as const, "aria-label": label ?? "Loading" }
+    return (
+      <svg
+        ref={ref}
+        viewBox="0 0 24 24"
+        fill="none"
+        {...ariaProps}
+        className={cn(spinnerVariants({ size }), className)}
+        {...props}
+      >
+        <circle
+          cx="12"
+          cy="12"
+          r="10"
+          strokeWidth="2.5"
+          className="ax:stroke-current ax:opacity-20"
+        />
+        <path
+          d="M22 12a10 10 0 0 0-10-10"
+          strokeWidth="2.5"
+          strokeLinecap="round"
+          className="ax:stroke-current"
+        />
+      </svg>
+    )
+  }
+)
+Spinner.displayName = "Spinner"

package/src/components/stat-strip.stories.tsx

@@ -0,0 +1,36 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { Handshake, ShoppingBag, TrendingUp, Users } from "lucide-react"
+import { StatStrip } from "./stat-strip"
+
+const ITEMS = [
+  { label: "Sold", value: "1,086", icon: <ShoppingBag aria-hidden /> },
+  { label: "On-Market", value: "1,854", icon: <TrendingUp aria-hidden /> },
+  { label: "Deals", value: "2,451", icon: <Handshake aria-hidden /> },
+  { label: "Active brokers", value: "275", icon: <Users aria-hidden /> },
+]
+
+const meta: Meta<typeof StatStrip> = {
+  title: "Components/StatStrip",
+  component: StatStrip,
+  tags: ["autodocs"],
+  argTypes: { tone: { control: "select", options: ["neutral", "primary", "secondary"] } },
+  args: { label: "Madhmoun MLS global stats", items: ITEMS, tone: "secondary" },
+}
+
+export default meta
+type Story = StoryObj<typeof StatStrip>
+
+export const Default: Story = {}
+
+export const Tones: Story = {
+  render: (args) => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "1rem" }}>
+      <StatStrip {...args} tone="neutral" />
+      <StatStrip {...args} tone="primary" />
+      <StatStrip {...args} tone="secondary" />
+    </div>
+  ),
+}
+
+export const WithoutLabel: Story = { args: { label: undefined, tone: "neutral" } }

package/src/components/stat-strip.test.tsx

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest"
+import * as React from "react"
+import { renderToStaticMarkup } from "react-dom/server"
+import { StatStrip } from "./stat-strip"
+
+const ITEMS = [{ label: "Sold", value: "1,086" }, { label: "Deals", value: "2,451" }]
+
+describe("StatStrip", () => {
+  it("pairs each label with its value in a definition list", () => {
+    const html = renderToStaticMarkup(<StatStrip items={ITEMS} />)
+    expect(html).toMatch(/<dl[^>]*>.*<dt[^>]*>Sold<\/dt><dd[^>]*>1,086<\/dd>.*<\/dl>/)
+  })
+
+  it("names the list with its label when one is given", () => {
+    const html = renderToStaticMarkup(<StatStrip label="Global stats" items={ITEMS} />)
+    const id = html.match(/<p id="([^"]+)"/)?.[1]
+    expect(id).toBeTruthy()
+    expect(html).toContain(`aria-labelledby="${id}"`)
+  })
+
+  it("applies the tone", () => {
+    expect(renderToStaticMarkup(<StatStrip tone="secondary" items={ITEMS} />)).toContain("ax:bg-secondary-weakest")
+    expect(renderToStaticMarkup(<StatStrip items={ITEMS} />)).toContain("ax:bg-muted")
+  })
+})

package/src/components/stat-strip.tsx

@@ -0,0 +1,85 @@
+import * as React from "react"
+import { tv, type VariantProps } from "tailwind-variants"
+import { cn } from "../lib/cn"
+
+export type StatStripTone = "neutral" | "primary" | "secondary"
+
+export interface StatStripItem {
+  label: string
+  value: React.ReactNode
+  /** Small leading icon. Mark it decorative; the label names the figure. */
+  icon?: React.ReactNode
+}
+
+/**
+ * Tones use the `weakest` fills with `-foreground` text, which the emphasis
+ * aliases keep legible in light and dark without `dark:` overrides.
+ */
+export const statStripVariants = tv({
+  slots: {
+    root: "ax:flex ax:flex-col ax:gap-xs ax:rounded-md ax:border ax:px-md ax:py-xs ax:sm:flex-row ax:sm:items-center ax:sm:gap-md",
+    label: "ax:t-label-xs ax:shrink-0",
+    list: "ax:grid ax:grid-cols-2 ax:gap-x-md ax:gap-y-xs ax:sm:flex ax:sm:flex-wrap ax:sm:gap-x-md",
+    // Labels and values never break; in a narrow two-column cell the value wraps under its label instead.
+    item: "ax:flex ax:min-w-0 ax:flex-wrap ax:items-center ax:gap-x-xs ax:sm:border-s ax:sm:ps-md ax:[&_svg]:size-3.5 ax:[&_svg]:shrink-0",
+  },
+  variants: {
+    tone: {
+      neutral: {
+        root: "ax:border-border ax:bg-muted ax:text-foreground",
+        item: "ax:sm:border-border",
+      },
+      primary: {
+        root: "ax:border-primary-weaker ax:bg-primary-weakest ax:text-primary-foreground",
+        item: "ax:sm:border-primary-weaker",
+      },
+      secondary: {
+        root: "ax:border-secondary-weaker ax:bg-secondary-weakest ax:text-secondary-foreground",
+        item: "ax:sm:border-secondary-weaker",
+      },
+    },
+  },
+  defaultVariants: { tone: "neutral" },
+}, { twMerge: false })
+
+export interface StatStripProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, "children">,
+    VariantProps<typeof statStripVariants> {
+  /** Leading caption naming the set, e.g. "Madhmoun MLS global stats". */
+  label?: React.ReactNode
+  items: StatStripItem[]
+}
+
+/**
+ * StatStrip - a compact, single-line bar of headline figures for the top of a
+ * dashboard. Renders a definition list so each label is tied to its value;
+ * collapses to two columns below `sm`.
+ *
+ * @example
+ *   <StatStrip
+ *     tone="secondary"
+ *     label="Madhmoun MLS global stats"
+ *     items={[{ label: "Sold", value: "1,086" }, { label: "Deals", value: "2,451" }]}
+ *   />
+ */
+export const StatStrip = React.forwardRef<HTMLDivElement, StatStripProps>(
+  ({ className, tone, label, items, ...props }, ref) => {
+    const styles = statStripVariants({ tone })
+    const labelId = React.useId()
+    return (
+      <div ref={ref} data-slot="stat-strip" className={cn(styles.root(), className)} {...props}>
+        {label && <p id={labelId} className={styles.label()}>{label}</p>}
+        <dl className={styles.list()} aria-labelledby={label ? labelId : undefined}>
+          {items.map((item) => (
+            <div key={item.label} className={styles.item()}>
+              {item.icon}
+              <dt className="ax:t-label-xs ax:font-normal ax:whitespace-nowrap">{item.label}</dt>
+              <dd className="ax:t-label-xs ax:font-bold ax:whitespace-nowrap ax:tabular-nums">{item.value}</dd>
+            </div>
+          ))}
+        </dl>
+      </div>
+    )
+  },
+)
+StatStrip.displayName = "StatStrip"

package/src/components/stats.stories.tsx

@@ -0,0 +1,24 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { Stats } from "./stats"
+
+const meta: Meta<typeof Stats> = {
+  title: "Components/Stats",
+  component: Stats,
+  tags: ["autodocs"],
+  args: {
+    eyebrow: "By the numbers",
+    title: "Trusted worldwide",
+    stats: [
+      { value: "10k+", label: "Teams" },
+      { value: "99.9%", label: "Uptime" },
+      { value: "50+", label: "Countries" },
+      { value: "4.9", label: "Rating" },
+    ],
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof Stats>
+
+export const Default: Story = {}

package/src/components/stats.tsx

@@ -0,0 +1,83 @@
+"use client"
+
+import * as React from "react"
+import { motion } from "motion/react"
+import { cn } from "../lib/cn"
+import { useReducedMotion } from "../hooks/use-reduced-motion"
+import { stagger, variants, viewport as defaultViewport } from "../lib/motion"
+
+export interface Stat {
+  value: React.ReactNode
+  label: string
+  description?: string
+  valueClassName?: string
+}
+
+export interface StatsProps extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
+  eyebrow?: React.ReactNode
+  title?: React.ReactNode
+  description?: React.ReactNode
+  stats: Stat[]
+}
+
+export function Stats({ className, eyebrow, title, description, stats, ...props }: StatsProps) {
+  const reduce = useReducedMotion()
+
+  return (
+    <section className={cn("ax:w-full ax:px-xl ax:md:px-3xl ax:py-5xl ax:md:py-6xl", className)} {...props}>
+      <div className="ax:mx-auto ax:max-w-420">
+        {(eyebrow || title || description) && (
+          <div className="ax:max-w-2xl ax:mb-4xl ax:space-y-sm">
+            {eyebrow && (
+              <span className="ax:inline-block ax:t-overline ax:text-primary">
+                {eyebrow}
+              </span>
+            )}
+            {title && (
+              <h2 className="ax:t-display-md ax:md:t-display-lg ax:text-foreground ax:[text-wrap:balance]">
+                {title}
+              </h2>
+            )}
+            {description && (
+              <p className="ax:t-body-md ax:text-muted-foreground ax:[text-wrap:pretty]">{description}</p>
+            )}
+          </div>
+        )}
+
+        <motion.dl
+          className={cn(
+            "ax:grid ax:gap-px ax:bg-border ax:rounded-xl ax:overflow-hidden ax:border ax:border-border",
+            stats.length === 2 && "ax:grid-cols-1 ax:sm:grid-cols-2",
+            stats.length === 3 && "ax:grid-cols-1 ax:sm:grid-cols-3",
+            stats.length === 4 && "ax:grid-cols-2 ax:lg:grid-cols-4",
+            stats.length > 4 && "ax:grid-cols-2 ax:md:grid-cols-3 ax:lg:grid-cols-4",
+          )}
+          {...(reduce ? {} : {
+            variants: stagger(),
+            initial: "hidden",
+            whileInView: "visible",
+            viewport: defaultViewport,
+          })}
+        >
+          {stats.map((stat, i) => (
+            <motion.div
+              key={i}
+              {...(reduce ? {} : { variants: variants.fadeUp })}
+              className="ax:flex ax:flex-col ax:gap-2xs ax:bg-card ax:px-xl ax:py-2xl"
+            >
+              <dt className="ax:t-overline ax:text-muted-foreground">
+                {stat.label}
+              </dt>
+              <dd className={cn("ax:t-display-lg ax:text-foreground ax:tabular-nums", stat.valueClassName)}>
+                {stat.value}
+              </dd>
+              {stat.description && (
+                <p className="ax:mt-2xs ax:t-caption ax:text-muted-foreground">{stat.description}</p>
+              )}
+            </motion.div>
+          ))}
+        </motion.dl>
+      </div>
+    </section>
+  )
+}

package/src/components/step-indicator.stories.tsx

@@ -0,0 +1,18 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { StepIndicator } from "./step-indicator"
+
+const meta: Meta<typeof StepIndicator> = {
+  title: "Components/StepIndicator",
+  component: StepIndicator,
+  tags: ["autodocs"],
+  args: {
+    steps: [{ label: "Account" }, { label: "Profile" }, { label: "Review" }],
+    currentStep: 1,
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof StepIndicator>
+
+export const Default: Story = {}

package/src/components/step-indicator.test.tsx

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest"
+import * as React from "react"
+import { renderToStaticMarkup } from "react-dom/server"
+import { StepIndicator } from "./step-indicator"
+
+describe("StepIndicator horizontal labels", () => {
+  it("anchors the first, middle, and last labels to the circle", () => {
+    const html = renderToStaticMarkup(
+      <StepIndicator
+        currentStep={1}
+        steps={[{ label: "Account" }, { label: "Profile" }, { label: "Review" }]}
+      />,
+    )
+    expect(html).toContain("ax:start-0")
+    expect(html).toContain("ax:start-1/2 ax:-translate-x-1/2 ax:rtl:translate-x-1/2")
+    expect(html).toContain("ax:end-0")
+  })
+})