@dtsports/design-system 0.2.0

package/src/components/select.tsx

@@ -0,0 +1,169 @@
+"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/utils";
+
+/**
+ * Select — keyboard-accessible dropdown built on Radix.
+ *
+ *   <Select value={v} onValueChange={setV}>
+ *     <SelectTrigger><SelectValue placeholder="Pick a venue" /></SelectTrigger>
+ *     <SelectContent>
+ *       <SelectItem value="astoria">Astoria Turf</SelectItem>
+ *       …
+ *     </SelectContent>
+ *   </Select>
+ *
+ * Native <select> is fine for tiny lists in dense forms; reach for this
+ * when you want typeahead, item groups, or styled portals.
+ */
+export const Select = SelectPrimitive.Root;
+export const SelectGroup = SelectPrimitive.Group;
+export const SelectValue = SelectPrimitive.Value;
+
+export const SelectTrigger = React.forwardRef<
+  React.ElementRef<typeof SelectPrimitive.Trigger>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Trigger>
+>(({ className, children, ...props }, ref) => (
+  <SelectPrimitive.Trigger
+    ref={ref}
+    className={cn(
+      "flex h-8 pointer-coarse:h-11 w-full items-center justify-between gap-2 rounded-sm border border-border-strong bg-background px-2.5 text-sm",
+      "placeholder:text-text-subtle",
+      "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+      "disabled:cursor-not-allowed disabled:opacity-50",
+      "[&>span]:line-clamp-1",
+      className
+    )}
+    {...props}
+  >
+    {children}
+    <SelectPrimitive.Icon asChild>
+      <ChevronDown
+        className="h-3.5 w-3.5 opacity-60 shrink-0"
+        strokeWidth={1.75}
+      />
+    </SelectPrimitive.Icon>
+  </SelectPrimitive.Trigger>
+));
+SelectTrigger.displayName = "SelectTrigger";
+
+export const SelectScrollUpButton = React.forwardRef<
+  React.ElementRef<typeof SelectPrimitive.ScrollUpButton>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.ScrollUpButton>
+>(({ className, ...props }, ref) => (
+  <SelectPrimitive.ScrollUpButton
+    ref={ref}
+    className={cn(
+      "flex cursor-default items-center justify-center py-1",
+      className
+    )}
+    {...props}
+  >
+    <ChevronUp className="h-3 w-3" strokeWidth={1.75} />
+  </SelectPrimitive.ScrollUpButton>
+));
+SelectScrollUpButton.displayName = "SelectScrollUpButton";
+
+export const SelectScrollDownButton = React.forwardRef<
+  React.ElementRef<typeof SelectPrimitive.ScrollDownButton>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.ScrollDownButton>
+>(({ className, ...props }, ref) => (
+  <SelectPrimitive.ScrollDownButton
+    ref={ref}
+    className={cn(
+      "flex cursor-default items-center justify-center py-1",
+      className
+    )}
+    {...props}
+  >
+    <ChevronDown className="h-3 w-3" strokeWidth={1.75} />
+  </SelectPrimitive.ScrollDownButton>
+));
+SelectScrollDownButton.displayName = "SelectScrollDownButton";
+
+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(
+        "relative z-50 max-h-80 min-w-[8rem] overflow-hidden rounded-md border border-border-strong bg-background text-foreground shadow-md",
+        "data-[state=open]:animate-fade-in",
+        position === "popper" &&
+          "data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1",
+        className
+      )}
+      position={position}
+      {...props}
+    >
+      <SelectScrollUpButton />
+      <SelectPrimitive.Viewport
+        className={cn(
+          "p-1",
+          position === "popper" &&
+            "h-[var(--radix-select-trigger-height)] w-full min-w-[var(--radix-select-trigger-width)]"
+        )}
+      >
+        {children}
+      </SelectPrimitive.Viewport>
+      <SelectScrollDownButton />
+    </SelectPrimitive.Content>
+  </SelectPrimitive.Portal>
+));
+SelectContent.displayName = "SelectContent";
+
+export const SelectLabel = React.forwardRef<
+  React.ElementRef<typeof SelectPrimitive.Label>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Label>
+>(({ className, ...props }, ref) => (
+  <SelectPrimitive.Label
+    ref={ref}
+    className={cn(
+      "py-1.5 pl-7 pr-2 text-[10px] font-semibold uppercase tracking-[0.06em] text-text-muted",
+      className
+    )}
+    {...props}
+  />
+));
+SelectLabel.displayName = "SelectLabel";
+
+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(
+      "relative flex w-full cursor-default select-none items-center rounded-sm py-1.5 pointer-coarse:min-h-11 pl-7 pr-2 text-sm outline-none transition-colors",
+      "focus:bg-bg-subtle focus:text-foreground",
+      "data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
+      className
+    )}
+    {...props}
+  >
+    <span className="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
+      <SelectPrimitive.ItemIndicator>
+        <Check className="h-3 w-3" strokeWidth={2.5} />
+      </SelectPrimitive.ItemIndicator>
+    </span>
+    <SelectPrimitive.ItemText>{children}</SelectPrimitive.ItemText>
+  </SelectPrimitive.Item>
+));
+SelectItem.displayName = "SelectItem";
+
+export const SelectSeparator = React.forwardRef<
+  React.ElementRef<typeof SelectPrimitive.Separator>,
+  React.ComponentPropsWithoutRef<typeof SelectPrimitive.Separator>
+>(({ className, ...props }, ref) => (
+  <SelectPrimitive.Separator
+    ref={ref}
+    className={cn("-mx-1 my-1 h-px bg-border", className)}
+    {...props}
+  />
+));
+SelectSeparator.displayName = "SelectSeparator";

package/src/components/separator.tsx

@@ -0,0 +1,34 @@
+"use client";
+
+import * as React from "react";
+import * as SeparatorPrimitive from "@radix-ui/react-separator";
+import { cn } from "../lib/utils";
+
+/**
+ * Separator — a thin divider (`<hr>` for horizontal, vertical bar for
+ * vertical). Decorative by default. Set `decorative={false}` when the
+ * separator semantically separates content groups (screen readers will
+ * announce it).
+ */
+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(
+        "shrink-0 bg-border",
+        orientation === "horizontal" ? "h-px w-full" : "h-full w-px",
+        className
+      )}
+      {...props}
+    />
+  )
+);
+Separator.displayName = "Separator";

package/src/components/sidebar.tsx

@@ -0,0 +1,168 @@
+"use client";
+
+import * as React from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cn } from "../lib/utils";
+
+/**
+ * Sidebar primitives — composable nav sidebar.
+ *
+ *   <Sidebar>
+ *     <SidebarHeader><BrandMark /></SidebarHeader>
+ *     <SidebarBody>
+ *       <SidebarSection label="Today">
+ *         <SidebarItem asChild active>
+ *           <Link href="/admin">
+ *             <LayoutDashboard className="h-4 w-4" strokeWidth={1.75} />
+ *             <span className="flex-1 truncate">Today</span>
+ *           </Link>
+ *         </SidebarItem>
+ *       </SidebarSection>
+ *     </SidebarBody>
+ *     <SidebarFooter>v0.1</SidebarFooter>
+ *   </Sidebar>
+ *
+ * For non-Next contexts, pass `href` prop directly; SidebarItem renders
+ * an <a> by default.
+ */
+export const Sidebar = React.forwardRef<
+  HTMLElement,
+  React.HTMLAttributes<HTMLElement>
+>(({ className, ...props }, ref) => (
+  <aside
+    ref={ref}
+    aria-label="Sidebar navigation"
+    className={cn(
+      "hidden lg:flex flex-col w-56 shrink-0 border-r border-border bg-bg-subtle/40 sticky top-0 h-screen",
+      className
+    )}
+    {...props}
+  />
+));
+Sidebar.displayName = "Sidebar";
+
+export const SidebarHeader = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn("px-5 py-4 border-b border-border", className)}
+    {...props}
+  />
+));
+SidebarHeader.displayName = "SidebarHeader";
+
+export const SidebarBody = React.forwardRef<
+  HTMLElement,
+  React.HTMLAttributes<HTMLElement>
+>(({ className, ...props }, ref) => (
+  <nav
+    ref={ref}
+    className={cn("flex-1 overflow-y-auto scrollbar-thin py-3 px-2", className)}
+    {...props}
+  />
+));
+SidebarBody.displayName = "SidebarBody";
+
+export const SidebarFooter = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn("px-3 py-3 border-t border-border", className)}
+    {...props}
+  />
+));
+SidebarFooter.displayName = "SidebarFooter";
+
+export interface SidebarSectionProps extends React.HTMLAttributes<HTMLDivElement> {
+  label?: React.ReactNode;
+}
+
+export const SidebarSection = React.forwardRef<
+  HTMLDivElement,
+  SidebarSectionProps
+>(({ className, label, children, ...props }, ref) => (
+  <div ref={ref} className={cn("mt-4 first:mt-0", className)} {...props}>
+    {label && (
+      <div className="px-2.5 pb-1 text-[10px] font-semibold uppercase tracking-[0.06em] text-text-subtle">
+        {label}
+      </div>
+    )}
+    <ul className="space-y-0.5">
+      {React.Children.map(children, (child) =>
+        child == null || child === false ? null : <li>{child}</li>
+      )}
+    </ul>
+  </div>
+));
+SidebarSection.displayName = "SidebarSection";
+
+export interface SidebarItemProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+  active?: boolean;
+  /** Lucide icon (or any node). Rendered before the label. */
+  icon?: React.ReactNode;
+  /** Right-aligned badge (e.g., warning count). */
+  badge?: React.ReactNode;
+  /** Use Radix Slot to render a custom element (e.g., Next.js Link). */
+  asChild?: boolean;
+}
+
+export const SidebarItem = React.forwardRef<
+  HTMLAnchorElement,
+  SidebarItemProps
+>(
+  (
+    { asChild, active, icon, badge, className, children, href, ...rest },
+    ref
+  ) => {
+    const baseClasses = cn(
+      "group flex items-center gap-2.5 rounded-sm px-2.5 py-1.5 text-sm transition-colors",
+      "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+      active
+        ? "bg-bg-subtle text-foreground font-medium border-l-2 border-l-brand-forest -ml-px pl-[10px]"
+        : "text-text-muted hover:bg-bg-muted hover:text-foreground",
+      className
+    );
+
+    if (asChild) {
+      const SlotComp = Slot as React.ElementType;
+      return (
+        <SlotComp
+          ref={ref}
+          className={baseClasses}
+          aria-current={active ? "page" : undefined}
+          {...rest}
+        >
+          {children}
+        </SlotComp>
+      );
+    }
+
+    return (
+      <a
+        ref={ref}
+        href={href}
+        className={baseClasses}
+        aria-current={active ? "page" : undefined}
+        {...rest}
+      >
+        {icon && (
+          <span
+            className={cn(
+              "shrink-0 flex items-center",
+              active ? "text-brand-forest" : "text-text-muted"
+            )}
+          >
+            {icon}
+          </span>
+        )}
+        <span className="flex-1 truncate">{children}</span>
+        {badge && <span className="shrink-0">{badge}</span>}
+      </a>
+    );
+  }
+);
+SidebarItem.displayName = "SidebarItem";

package/src/components/skeleton.tsx

@@ -0,0 +1,85 @@
+import * as React from "react";
+import { cn } from "../lib/utils";
+
+/**
+ * Skeleton — per design.md §12
+ * Use over spinners. Pulse opacity 0.5 → 1, 1.5s. Respects prefers-reduced-motion.
+ */
+export function Skeleton({
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cn("animate-pulse rounded bg-bg-muted", className)}
+      aria-hidden="true"
+      {...props}
+    />
+  );
+}
+
+/**
+ * SkeletonList — loading placeholder echoing a row list (§3.14:
+ * skeletons echo the final shape). Use as the `loading` slot of
+ * ThreeState for list views.
+ */
+export function SkeletonList({
+  rows = 3,
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement> & { rows?: number }) {
+  return (
+    <div
+      className={cn("space-y-2", className)}
+      role="status"
+      aria-label="Loading"
+      {...props}
+    >
+      {Array.from({ length: rows }, (_, i) => (
+        <div key={i} className="flex items-center gap-3">
+          <Skeleton className="h-8 w-8 rounded-full shrink-0" />
+          <div className="flex-1 space-y-1.5">
+            <Skeleton className="h-3 w-2/5" />
+            <Skeleton className="h-3 w-3/5" />
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * SkeletonTable — loading placeholder echoing a data table. Match
+ * `columns` to the real table so the layout doesn't jump on load.
+ */
+export function SkeletonTable({
+  rows = 5,
+  columns = 4,
+  className,
+  ...props
+}: React.HTMLAttributes<HTMLDivElement> & {
+  rows?: number;
+  columns?: number;
+}) {
+  return (
+    <div
+      className={cn("space-y-2", className)}
+      role="status"
+      aria-label="Loading"
+      {...props}
+    >
+      <div className="flex gap-4 border-b border-border pb-2">
+        {Array.from({ length: columns }, (_, i) => (
+          <Skeleton key={i} className="h-3 flex-1" />
+        ))}
+      </div>
+      {Array.from({ length: rows }, (_, r) => (
+        <div key={r} className="flex gap-4 py-1">
+          {Array.from({ length: columns }, (_, c) => (
+            <Skeleton key={c} className="h-4 flex-1" />
+          ))}
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/slider.tsx

@@ -0,0 +1,58 @@
+"use client";
+
+import * as React from "react";
+import * as SliderPrimitive from "@radix-ui/react-slider";
+import { cn } from "../lib/utils";
+
+/**
+ * Slider — Radix-backed range input. Keyboard: arrows step, PageUp/Down
+ * big-step, Home/End min/max. Pass `aria-label` (or wire a Label to the
+ * thumb via `aria-labelledby`) — the a11y suite enforces a name.
+ *
+ *   <Slider aria-label="Max price" min={0} max={50} step={5}
+ *           defaultValue={[20]} />
+ *
+ * Supports multiple thumbs by passing more values: defaultValue={[10, 30]}.
+ */
+export const Slider = React.forwardRef<
+  React.ElementRef<typeof SliderPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof SliderPrimitive.Root>
+>(({ className, "aria-label": ariaLabel, ...props }, ref) => {
+  const values = props.value ?? props.defaultValue ?? [0];
+  // role="slider" lives on each Radix THUMB, not the root — a label on
+  // the root is invisible to screen readers, so name the thumbs.
+  const thumbLabel = (i: number) =>
+    values.length > 1
+      ? `${ariaLabel} (${i + 1} of ${values.length})`
+      : ariaLabel;
+  return (
+    <SliderPrimitive.Root
+      ref={ref}
+      className={cn(
+        "relative flex w-full touch-none select-none items-center",
+        // Comfortable grab zone without visual bulk.
+        "h-5 pointer-coarse:h-11",
+        "data-[disabled]:opacity-50 data-[disabled]:pointer-events-none",
+        className
+      )}
+      {...props}
+    >
+      <SliderPrimitive.Track className="relative h-1 w-full grow overflow-hidden rounded-full bg-bg-muted">
+        <SliderPrimitive.Range className="absolute h-full bg-brand-forest" />
+      </SliderPrimitive.Track>
+      {values.map((_, i) => (
+        <SliderPrimitive.Thumb
+          key={i}
+          aria-label={thumbLabel(i)}
+          className={cn(
+            "block h-4 w-4 rounded-full border-2 border-brand-forest bg-background shadow-sm transition-colors",
+            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+            // Invisible hit-area extension: 24px desktop / 44px touch.
+            "relative after:absolute after:-inset-1 pointer-coarse:after:-inset-3.5"
+          )}
+        />
+      ))}
+    </SliderPrimitive.Root>
+  );
+});
+Slider.displayName = "Slider";

package/src/components/spec.tsx

@@ -0,0 +1,59 @@
+import * as React from "react";
+import { cn } from "../lib/utils";
+
+/**
+ * SpecList + Spec — semantic key-value display (`<dl>` / `<dt>` / `<dd>`).
+ * Use for game detail "About this game" panels, settings summaries,
+ * receipts.
+ *
+ *   <SpecList columns={2}>
+ *     <Spec label="Format">5v5</Spec>
+ *     <Spec label="Capacity">10 players</Spec>
+ *     <Spec label="Start"><Timestamp iso={…} /></Spec>
+ *   </SpecList>
+ */
+const COLUMNS_MAP = {
+  1: "grid-cols-1",
+  2: "grid-cols-2",
+  3: "grid-cols-3",
+  4: "grid-cols-4",
+} as const;
+
+const GAP_MAP = {
+  2: "gap-2",
+  3: "gap-3",
+  4: "gap-4",
+  6: "gap-6",
+} as const;
+
+export interface SpecListProps extends React.HTMLAttributes<HTMLDListElement> {
+  columns?: keyof typeof COLUMNS_MAP;
+  gap?: keyof typeof GAP_MAP;
+}
+
+export const SpecList = React.forwardRef<HTMLDListElement, SpecListProps>(
+  ({ className, columns = 2, gap = 4, ...props }, ref) => (
+    <dl
+      ref={ref}
+      className={cn("grid", COLUMNS_MAP[columns], GAP_MAP[gap], className)}
+      {...props}
+    />
+  )
+);
+SpecList.displayName = "SpecList";
+
+export interface SpecProps extends React.HTMLAttributes<HTMLDivElement> {
+  label: React.ReactNode;
+}
+
+export const Spec = React.forwardRef<HTMLDivElement, SpecProps>(
+  ({ className, label, children, ...props }, ref) => (
+    <div ref={ref} className={cn("", className)} {...props}>
+      <dt className="text-[10px] font-medium uppercase tracking-[0.04em] text-text-muted">
+        {label}
+      </dt>
+      <dd className="text-sm mt-0.5 text-foreground">{children}</dd>
+    </div>
+  )
+);
+Spec.displayName = "Spec";

package/src/components/spinner.tsx

@@ -0,0 +1,36 @@
+import { Loader2 } from "lucide-react";
+import { cn } from "../lib/utils";
+
+/**
+ * Spinner — tiny inline loader for buttons + per-row "working" state.
+ * Prefer Skeleton for full-region loading (per design.md §3.14).
+ *
+ * Honors prefers-reduced-motion via globals.css.
+ */
+const SIZE_MAP = {
+  sm: "h-3 w-3",
+  default: "h-4 w-4",
+  lg: "h-5 w-5",
+} as const;
+
+export interface SpinnerProps {
+  size?: keyof typeof SIZE_MAP;
+  className?: string;
+  /** Accessible label (default "Loading") */
+  label?: string;
+}
+
+export function Spinner({
+  size = "default",
+  className,
+  label = "Loading",
+}: SpinnerProps) {
+  return (
+    <Loader2
+      role="status"
+      aria-label={label}
+      className={cn("animate-spin", SIZE_MAP[size], className)}
+      strokeWidth={2}
+    />
+  );
+}

package/src/components/stack.tsx

@@ -0,0 +1,80 @@
+import * as React from "react";
+import { cn } from "../lib/utils";
+
+/**
+ * Stack — flexbox with consistent gap. Use Stack when you'd otherwise
+ * reach for `flex flex-col gap-3` (or `space-y-3`); it documents intent
+ * and keeps gap tokens consistent across the app.
+ *
+ *   <Stack gap={2}>          // vertical, gap-2
+ *   <Stack direction="row" gap={4} align="center" justify="between">
+ */
+const GAP_MAP = {
+  0: "gap-0",
+  0.5: "gap-0.5",
+  1: "gap-1",
+  1.5: "gap-1.5",
+  2: "gap-2",
+  2.5: "gap-2.5",
+  3: "gap-3",
+  4: "gap-4",
+  5: "gap-5",
+  6: "gap-6",
+  8: "gap-8",
+  10: "gap-10",
+} as const;
+
+const ALIGN_MAP = {
+  start: "items-start",
+  center: "items-center",
+  end: "items-end",
+  baseline: "items-baseline",
+  stretch: "items-stretch",
+} as const;
+
+const JUSTIFY_MAP = {
+  start: "justify-start",
+  center: "justify-center",
+  end: "justify-end",
+  between: "justify-between",
+  around: "justify-around",
+  evenly: "justify-evenly",
+} as const;
+
+export interface StackProps extends React.HTMLAttributes<HTMLDivElement> {
+  direction?: "column" | "row";
+  gap?: keyof typeof GAP_MAP;
+  align?: keyof typeof ALIGN_MAP;
+  justify?: keyof typeof JUSTIFY_MAP;
+  wrap?: boolean;
+}
+
+export const Stack = React.forwardRef<HTMLDivElement, StackProps>(
+  (
+    {
+      className,
+      direction = "column",
+      gap = 3,
+      align,
+      justify,
+      wrap,
+      ...props
+    },
+    ref
+  ) => (
+    <div
+      ref={ref}
+      className={cn(
+        "flex",
+        direction === "column" ? "flex-col" : "flex-row",
+        GAP_MAP[gap],
+        align && ALIGN_MAP[align],
+        justify && JUSTIFY_MAP[justify],
+        wrap && "flex-wrap",
+        className
+      )}
+      {...props}
+    />
+  )
+);
+Stack.displayName = "Stack";