@glyphui/ui 0.3.0 → 0.4.0

package/dist/{tv-DBAGlgXJ.js → tv-DLbT66dC.js}

@@ -14,6 +14,18 @@ function useGlyph() {
 function useLinkComponent() {
 	return useContext(GlyphContext)?.linkComponent ?? "a";
 }
+const neverActive = () => false;
+/**
+* Whether `href` is the current page, using the router passed to `GlyphProvider`.
+* Returns `explicit` when it is set, so an `active` prop always wins.
+*/
+function useIsActive(href, options) {
+	const isActive = useContext(GlyphContext)?.useIsActive ?? neverActive;
+	const { explicit, ...matchOptions } = options ?? {};
+	const matched = isActive(href ?? "", matchOptions);
+	if (explicit !== void 0) return explicit;
+	return href ? matched : false;
+}
 //#endregion
 //#region src/hooks/use-component-config.ts
 /**
@@ -55,4 +67,4 @@ const twMergeConfig = { extend: { theme: {
 /** `tailwind-variants` preconfigured with Glyph's merge rules. All component styles use this. */
 const tv = createTV({ twMergeConfig });
 //#endregion
-export { themedBorder as a, GlyphContext as c, popover as i, useGlyph as l, twMergeConfig as n, transition as o, focusRing as r, useComponentConfig as s, tv as t, useLinkComponent as u };
+export { themedBorder as a, GlyphContext as c, useIsActive as d, useLinkComponent as f, popover as i, neverActive as l, twMergeConfig as n, transition as o, focusRing as r, useComponentConfig as s, tv as t, useGlyph as u };

package/dist/vite.d.ts

@@ -0,0 +1,27 @@
+import { t as ColorModeOptions } from "./color-mode-script-KdwItKN2.js";
+//#region src/integrations/vite.d.ts
+/** The subset of Vite's `Plugin` this plugin uses, so `vite` stays an optional peer. */
+export interface GlyphVitePlugin {
+  name: string;
+  transformIndexHtml: {
+    order: 'pre';
+    handler: () => {
+      tag: 'script';
+      children: string;
+      injectTo: 'head-prepend';
+    }[];
+  };
+}
+/**
+ * Injects Glyph's color-mode script into `index.html` so dark-mode visitors never see a
+ * light flash. Pass the same `defaultMode` and `storageKey` as `GlyphProvider`.
+ *
+ * ```ts
+ * // vite.config.ts
+ * import { glyphColorMode } from '@glyphui/ui/vite'
+ * export default defineConfig({ plugins: [react(), tailwindcss(), glyphColorMode()] })
+ * ```
+ */
+export declare function glyphColorMode(options?: ColorModeOptions): GlyphVitePlugin;
+//#endregion
+export type { ColorModeOptions };

package/dist/vite.js

@@ -0,0 +1,29 @@
+"use client";
+import { r as getColorModeScript } from "./color-mode-script-Bf7LYkOj.js";
+//#region src/integrations/vite.ts
+/**
+* Injects Glyph's color-mode script into `index.html` so dark-mode visitors never see a
+* light flash. Pass the same `defaultMode` and `storageKey` as `GlyphProvider`.
+*
+* ```ts
+* // vite.config.ts
+* import { glyphColorMode } from '@glyphui/ui/vite'
+* export default defineConfig({ plugins: [react(), tailwindcss(), glyphColorMode()] })
+* ```
+*/
+function glyphColorMode(options = {}) {
+	const script = getColorModeScript(options);
+	return {
+		name: "glyph:color-mode",
+		transformIndexHtml: {
+			order: "pre",
+			handler: () => [{
+				tag: "script",
+				children: script,
+				injectTo: "head-prepend"
+			}]
+		}
+	};
+}
+//#endregion
+export { glyphColorMode };

package/fonts.css

@@ -0,0 +1,10 @@
+/*
+ * Geist and Geist Mono, the fonts the default `glyph` theme uses. Import once, before the
+ * Glyph stylesheet:
+ *
+ *   @import "@glyphui/ui/fonts.css";
+ *   @import "tailwindcss";
+ *   @import "@glyphui/ui/styles.css";
+ */
+@import "@fontsource-variable/geist";
+@import "@fontsource-variable/geist-mono";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glyphui/ui",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "React components on Tailwind CSS v4 that take their entire look from one theme file. Forms, data tables, app layouts and async states included.",
   "license": "MIT",
   "author": "Mohak Gupta (https://github.com/khalmohak)",
@@ -24,7 +24,8 @@
     "theme",
     "dark-mode",
     "forms",
-    "data-table"
+    "data-table",
+    "react-router"
   ],
   "type": "module",
   "sideEffects": [
@@ -51,19 +52,33 @@
       "types": "./dist/chart.d.ts",
       "default": "./dist/chart.js"
     },
+    "./react-router": {
+      "@glyphui/source": "./src/integrations/react-router.tsx",
+      "types": "./dist/react-router.d.ts",
+      "default": "./dist/react-router.js"
+    },
+    "./vite": {
+      "@glyphui/source": "./src/integrations/vite.ts",
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.js"
+    },
     "./styles.css": "./styles.css",
+    "./fonts.css": "./fonts.css",
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
     "src",
     "styles.css",
+    "fonts.css",
     "!src/**/*.test.tsx",
     "!src/**/*.test-d.tsx",
     "!src/test"
   ],
   "dependencies": {
-    "@glyphui/tokens": "^0.3.0",
+    "@fontsource-variable/geist": "^5.3.0",
+    "@fontsource-variable/geist-mono": "^5.3.0",
+    "@glyphui/tokens": "^0.4.0",
     "@standard-schema/spec": "^1.1.0",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
@@ -83,8 +98,10 @@
     "react": ">=19",
     "react-dom": ">=19",
     "react-hook-form": "^7.55.0",
+    "react-router": ">=7",
     "recharts": "^3.0.0",
-    "tailwindcss": ">=4.1"
+    "tailwindcss": ">=4.1",
+    "vite": ">=5"
   },
   "peerDependenciesMeta": {
     "@hookform/resolvers": {
@@ -96,8 +113,14 @@
     "react-hook-form": {
       "optional": true
     },
+    "react-router": {
+      "optional": true
+    },
     "recharts": {
       "optional": true
+    },
+    "vite": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -110,13 +133,16 @@
     "@testing-library/user-event": "^14.6.7",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.7",
+    "@vitest/coverage-v8": "3.2.7",
     "jsdom": "^27.4.0",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "react-hook-form": "^7.89.0",
+    "react-router": "^7.18.4",
     "recharts": "^3.10.1",
     "tsdown": "^0.23.0",
     "typescript": "~5.9.3",
+    "vite": "^7.3.6",
     "vitest": "^3.2.7",
     "zod": "^4.6.5"
   },
@@ -128,6 +154,7 @@
     "build": "tsdown",
     "typecheck": "tsc",
     "test": "vitest run",
-    "check:exports": "attw --pack . --profile esm-only --exclude-entrypoints ./styles.css"
+    "test:coverage": "vitest run --coverage",
+    "check:exports": "attw --pack . --profile esm-only --exclude-entrypoints ./styles.css ./fonts.css"
   }
 }

package/src/components/badge/badge.styles.ts

@@ -1,7 +1,7 @@
 import { themedBorder } from '../../utils/styles'
 import { tv, type VariantProps } from '../../utils/tv'
 
-// Tinted text is mixed toward the foreground so it stays readable on light and dark surfaces.
+// Tinted text uses the theme's status text colors, which stay readable on tinted backgrounds.
 const tones = {
   neutral: {
     soft: 'bg-muted text-muted-foreground',
@@ -9,34 +9,29 @@ const tones = {
     outline: 'border-border-strong text-foreground',
   },
   primary: {
-    soft: 'bg-primary/14 text-[color-mix(in_oklab,var(--color-primary)_62%,var(--color-foreground))]',
+    soft: 'bg-primary/14 text-primary-text',
     solid: 'bg-primary text-primary-foreground',
-    outline:
-      'border-primary/50 text-[color-mix(in_oklab,var(--color-primary)_62%,var(--color-foreground))]',
+    outline: 'border-primary/50 text-primary-text',
   },
   success: {
-    soft: 'bg-success/14 text-[color-mix(in_oklab,var(--color-success)_62%,var(--color-foreground))]',
+    soft: 'bg-success/14 text-success-text',
     solid: 'bg-success text-success-foreground',
-    outline:
-      'border-success/50 text-[color-mix(in_oklab,var(--color-success)_62%,var(--color-foreground))]',
+    outline: 'border-success/50 text-success-text',
   },
   warning: {
-    soft: 'bg-warning/16 text-[color-mix(in_oklab,var(--color-warning)_62%,var(--color-foreground))]',
+    soft: 'bg-warning/14 text-warning-text',
     solid: 'bg-warning text-warning-foreground',
-    outline:
-      'border-warning/50 text-[color-mix(in_oklab,var(--color-warning)_62%,var(--color-foreground))]',
+    outline: 'border-warning/50 text-warning-text',
   },
   danger: {
-    soft: 'bg-danger/14 text-[color-mix(in_oklab,var(--color-danger)_62%,var(--color-foreground))]',
+    soft: 'bg-danger/14 text-danger-text',
     solid: 'bg-danger text-danger-foreground',
-    outline:
-      'border-danger/50 text-[color-mix(in_oklab,var(--color-danger)_62%,var(--color-foreground))]',
+    outline: 'border-danger/50 text-danger-text',
   },
   info: {
-    soft: 'bg-info/14 text-[color-mix(in_oklab,var(--color-info)_62%,var(--color-foreground))]',
+    soft: 'bg-info/14 text-info-text',
     solid: 'bg-info text-info-foreground',
-    outline:
-      'border-info/50 text-[color-mix(in_oklab,var(--color-info)_62%,var(--color-foreground))]',
+    outline: 'border-info/50 text-info-text',
   },
 } as const
 

package/src/components/banner/banner.styles.ts

@@ -15,16 +15,16 @@ export const bannerStyles = tv({
       neutral: { root: 'border-border bg-subtle text-foreground', icon: 'text-muted-foreground' },
       primary: { root: 'border-primary bg-primary text-primary-foreground' },
       info: {
-        root: 'border-info/25 bg-info/10 text-[color-mix(in_oklab,var(--color-info)_55%,var(--color-foreground))]',
+        root: 'border-info/25 bg-info/10 text-info-text',
       },
       success: {
-        root: 'border-success/25 bg-success/10 text-[color-mix(in_oklab,var(--color-success)_55%,var(--color-foreground))]',
+        root: 'border-success/25 bg-success/10 text-success-text',
       },
       warning: {
-        root: 'border-warning/30 bg-warning/14 text-[color-mix(in_oklab,var(--color-warning)_50%,var(--color-foreground))]',
+        root: 'border-warning/30 bg-warning/14 text-warning-text',
       },
       danger: {
-        root: 'border-danger/25 bg-danger/10 text-[color-mix(in_oklab,var(--color-danger)_55%,var(--color-foreground))]',
+        root: 'border-danger/25 bg-danger/10 text-danger-text',
       },
     },
   },

package/src/components/button/button.styles.ts

@@ -22,7 +22,9 @@ export const buttonStyles = tv({
       },
       ghost: { base: 'text-muted-foreground hover:bg-muted hover:text-foreground' },
       danger: { base: 'bg-danger text-danger-foreground shadow-sm hover:bg-danger/88' },
-      link: { base: 'h-auto px-0 text-primary underline-offset-4 shadow-none hover:underline' },
+      link: {
+        base: 'h-auto px-0 text-primary-text underline-offset-4 shadow-none hover:underline',
+      },
     },
     size: {
       sm: { base: 'h-(--glyph-control-sm) px-3 text-small', icon: 'size-3.5' },

package/src/components/calendar/calendar.styles.ts

@@ -29,10 +29,11 @@ export const calendarStyles = tv({
       transition,
       focusRing,
     ],
-    today: '[&>button]:font-semibold [&>button]:text-primary',
+    // Selected days keep primary-foreground on primary, whatever else applies to them.
+    today: '[&>button]:font-semibold [&:not([data-selected])>button]:text-primary-text',
     selected:
       '[&>button]:bg-primary [&>button]:text-primary-foreground [&>button]:hover:bg-primary/90',
-    outside: '[&>button]:text-faint-foreground [&>button]:opacity-60',
+    outside: '[&:not([data-selected])>button]:text-faint-foreground',
     disabled: '[&>button]:pointer-events-none [&>button]:opacity-35 [&>button]:line-through',
     rangeStart: 'rounded-l-md bg-primary/14',
     rangeMiddle:

package/src/components/dropdown-menu/dropdown-menu.styles.ts

@@ -27,8 +27,8 @@ export const dropdownMenuStyles = tv({
     tone: {
       default: {},
       danger: {
-        item: 'text-danger data-highlighted:bg-danger/10',
-        icon: 'text-danger',
+        item: 'text-danger-text data-highlighted:bg-danger/10',
+        icon: 'text-danger-text',
       },
     },
     inset: { true: { item: 'pl-8', label: 'pl-8' } },

package/src/components/eyebrow/eyebrow.styles.ts

@@ -5,7 +5,7 @@ export const eyebrowStyles = tv({
   variants: {
     tone: {
       muted: { base: 'text-muted-foreground' },
-      primary: { base: 'text-primary' },
+      primary: { base: 'text-primary-text' },
     },
   },
   defaultVariants: { tone: 'muted' },

package/src/components/field/field-context.ts

@@ -2,6 +2,8 @@ import { createContext, useContext } from 'react'
 
 export interface FieldContextValue {
   id: string
+  /** Id of the visible label, for controls labelled by reference (aria-labelledby). */
+  labelId: string | undefined
   descriptionId: string | undefined
   errorId: string | undefined
   invalid: boolean

package/src/components/field/field.styles.ts

@@ -4,10 +4,12 @@ export const fieldStyles = tv({
   slots: {
     root: 'grid gap-1.5',
     label: '',
-    required: 'text-danger',
+    labelRow: 'flex items-center justify-between gap-2',
+    labelAction: 'text-small',
+    required: 'text-danger-text',
     text: 'grid gap-0.5',
     description: 'text-small text-faint-foreground',
-    error: 'text-small font-medium text-danger',
+    error: 'text-small font-medium text-danger-text',
   },
   variants: {
     orientation: {

package/src/components/field/field.tsx

@@ -6,6 +6,11 @@ import { FieldContext } from './field-context'
 
 export interface FieldProps extends Omit<ComponentProps<'div'>, 'children'>, FieldVariants {
   label?: ReactNode
+  /**
+   * Shown at the end of the label row, outside the label, so it is not part of the
+   * control's accessible name. For example a "Forgot password?" link.
+   */
+  labelAction?: ReactNode
   description?: ReactNode
   /** Error message. Marks the control invalid and is announced to screen readers. */
   error?: ReactNode
@@ -27,6 +32,7 @@ export function Field(inProps: FieldProps) {
   const [props, slots] = useComponentConfig('Field', inProps)
   const {
     label,
+    labelAction,
     description,
     error,
     required = false,
@@ -40,17 +46,18 @@ export function Field(inProps: FieldProps) {
   const generated = useId()
   const id = controlId ?? generated
   const invalid = Boolean(error)
+  const labelId = label ? `${id}-label` : undefined
   const descriptionId = description ? `${id}-description` : undefined
   const errorId = invalid ? `${id}-error` : undefined
   const s = fieldStyles({ orientation })
 
   const context = useMemo(
-    () => ({ id, descriptionId, errorId, invalid, required, disabled }),
-    [id, descriptionId, errorId, invalid, required, disabled],
+    () => ({ id, labelId, descriptionId, errorId, invalid, required, disabled }),
+    [id, labelId, descriptionId, errorId, invalid, required, disabled],
   )
 
-  const labelNode = label ? (
-    <Label htmlFor={id} className={s.label({ class: slots.label })}>
+  const labelElement = label ? (
+    <Label id={labelId} htmlFor={id} className={s.label({ class: slots.label })}>
       {label}
       {required && (
         <span className={s.required({ class: slots.required })} aria-hidden="true">
@@ -59,6 +66,20 @@ export function Field(inProps: FieldProps) {
       )}
     </Label>
   ) : null
+  const labelNode =
+    labelElement && labelAction ? (
+      <div data-slot="field-label-row" className={s.labelRow({ class: slots.labelRow })}>
+        {labelElement}
+        <span
+          data-slot="field-label-action"
+          className={s.labelAction({ class: slots.labelAction })}
+        >
+          {labelAction}
+        </span>
+      </div>
+    ) : (
+      labelElement
+    )
 
   const messages = (
     <>

package/src/components/file-upload/file-upload.styles.ts

@@ -16,9 +16,9 @@ export const fileUploadStyles = tv({
     ],
     icon: 'flex size-10 items-center justify-center rounded-md border border-border bg-surface text-muted-foreground shadow-xs [&>svg]:size-5',
     title: 'text-small font-medium text-foreground',
-    highlight: 'text-primary',
+    highlight: 'text-primary-text',
     hint: 'text-caption text-faint-foreground',
-    rejections: 'grid gap-1 text-small font-medium text-danger',
+    rejections: 'grid gap-1 text-small font-medium text-danger-text',
     list: 'grid gap-2',
     item: [
       'grid grid-cols-[auto_1fr_auto] items-center gap-3 rounded-md border-border bg-surface px-3 py-2.5',
@@ -29,7 +29,7 @@ export const fileUploadStyles = tv({
     fileText: 'grid min-w-0 gap-1',
     fileName: 'truncate text-small font-medium text-foreground',
     fileMeta: 'text-caption tabular-nums text-faint-foreground',
-    fileError: 'text-caption font-medium text-danger',
+    fileError: 'text-caption font-medium text-danger-text',
     progress: 'h-1 overflow-hidden rounded-pill bg-muted',
     progressBar:
       'h-full rounded-pill bg-primary transition-[width] duration-(--glyph-duration-base)',

package/src/components/link/link.styles.ts

@@ -17,7 +17,7 @@ export const linkStyles = tv({
     tone: {
       default: { base: 'text-foreground' },
       muted: { base: 'text-muted-foreground hover:text-foreground' },
-      primary: { base: 'text-primary' },
+      primary: { base: 'text-primary-text' },
     },
     underline: {
       hover: {

package/src/components/modal/modal.styles.ts

@@ -8,6 +8,8 @@ export const modalStyles = tv({
     header: '',
     body: 'grid gap-4',
     footer: '',
+    /** Wraps body and footer when `onSubmit` is set; `contents` keeps the dialog layout. */
+    form: 'contents',
   },
 })
 

package/src/components/modal/modal.tsx

@@ -1,4 +1,4 @@
-import type { ReactNode } from 'react'
+import type { FormEvent, ReactNode } from 'react'
 import { useComponentConfig } from '../../hooks/use-component-config'
 import {
   Dialog,
@@ -14,7 +14,7 @@ import {
 } from '../dialog'
 import { modalStyles } from './modal.styles'
 
-export interface ModalProps extends Omit<DialogContentProps, 'title' | 'children'> {
+export interface ModalProps extends Omit<DialogContentProps, 'title' | 'children' | 'onSubmit'> {
   open?: boolean
   defaultOpen?: boolean
   onOpenChange?: (open: boolean) => void
@@ -27,6 +27,12 @@ export interface ModalProps extends Omit<DialogContentProps, 'title' | 'children
   footer?: ReactNode
   /** Close when the backdrop is clicked. Default true. */
   closeOnOverlayClick?: boolean
+  /**
+   * Turns the body and footer into one `<form>`, so a `type="submit"` button in the footer
+   * submits the fields in the body. The page does not reload. With `@glyphui/ui/form`, use
+   * `<Form>` in the body and `<FormSubmit form={form}>` in the footer instead.
+   */
+  onSubmit?: (event: FormEvent<HTMLFormElement>) => void
   children?: ReactNode
 }
 
@@ -45,12 +51,21 @@ export function Modal(inProps: ModalProps) {
     trigger,
     footer,
     closeOnOverlayClick = true,
+    onSubmit,
     onPointerDownOutside,
     className,
     children,
     ...rest
   } = props
   const s = modalStyles()
+  const content = (
+    <>
+      {children && <DialogBody className={s.body({ class: slots.body })}>{children}</DialogBody>}
+      {footer && (
+        <DialogFooter className={s.footer({ class: slots.footer })}>{footer}</DialogFooter>
+      )}
+    </>
+  )
 
   return (
     <Dialog
@@ -73,9 +88,19 @@ export function Modal(inProps: ModalProps) {
           <DialogTitle>{title}</DialogTitle>
           {description && <DialogDescription>{description}</DialogDescription>}
         </DialogHeader>
-        {children && <DialogBody className={s.body({ class: slots.body })}>{children}</DialogBody>}
-        {footer && (
-          <DialogFooter className={s.footer({ class: slots.footer })}>{footer}</DialogFooter>
+        {onSubmit ? (
+          <form
+            data-slot="modal-form"
+            className={s.form({ class: slots.form })}
+            onSubmit={(event) => {
+              event.preventDefault()
+              onSubmit(event)
+            }}
+          >
+            {content}
+          </form>
+        ) : (
+          content
         )}
       </DialogContent>
     </Dialog>

package/src/components/navigation-menu/navigation-menu.tsx

@@ -1,7 +1,7 @@
 import { NavigationMenu as NavPrimitive } from 'radix-ui'
 import type { ComponentProps, ReactNode } from 'react'
 import { useComponentConfig } from '../../hooks/use-component-config'
-import { useLinkComponent } from '../../provider/glyph-context'
+import { useIsActive, useLinkComponent } from '../../provider/glyph-context'
 import { navigationMenuStyles } from './navigation-menu.styles'
 
 const s = navigationMenuStyles()
@@ -132,25 +132,35 @@ export interface NavigationMenuLinkProps
   href?: string
 }
 
-/** A top-level link (no panel). Set `active` for the current page. */
+/**
+ * A top-level link (no panel). Marked active automatically from the provider's `router`;
+ * set `active` to override.
+ */
 export function NavigationMenuLink({
   href,
+  active: activeProp,
   className,
   children,
   ...props
 }: NavigationMenuLinkProps) {
   const slots = useSlots()
   const Link = useLinkComponent()
+  const active = useIsActive(href, { explicit: activeProp })
   const cls = s.link({ class: [slots.link, className] })
   if (href === undefined) {
     return (
-      <NavPrimitive.Link data-slot="navigation-menu-link" className={cls} {...props}>
+      <NavPrimitive.Link
+        data-slot="navigation-menu-link"
+        className={cls}
+        active={active}
+        {...props}
+      >
         {children}
       </NavPrimitive.Link>
     )
   }
   return (
-    <NavPrimitive.Link data-slot="navigation-menu-link" asChild {...props}>
+    <NavPrimitive.Link data-slot="navigation-menu-link" asChild active={active} {...props}>
       <Link href={href} className={cls}>
         {children}
       </Link>

package/src/components/password-input/password-input.styles.ts

@@ -16,9 +16,9 @@ export const passwordInputStyles = tv({
   },
   variants: {
     strength: {
-      weak: { label: 'text-danger' },
-      fair: { label: 'text-warning' },
-      strong: { label: 'text-success' },
+      weak: { label: 'text-danger-text' },
+      fair: { label: 'text-warning-text' },
+      strong: { label: 'text-success-text' },
     },
   },
 })

package/src/components/prose/prose.tsx

@@ -20,7 +20,7 @@ export const proseStyles = tv({
       // Text
       '[&_p]:my-[1em] [&_p]:text-pretty',
       '[&_strong]:font-semibold [&_strong]:text-foreground',
-      '[&_a]:font-medium [&_a]:text-primary [&_a]:underline [&_a]:decoration-primary/40 [&_a]:underline-offset-4 [&_a:hover]:decoration-primary',
+      '[&_a]:font-medium [&_a]:text-primary-text [&_a]:underline [&_a]:decoration-primary/40 [&_a]:underline-offset-4 [&_a:hover]:decoration-primary',
       // Lists
       '[&_ul]:my-[1em] [&_ul]:list-disc [&_ul]:pl-[1.5em] [&_ol]:my-[1em] [&_ol]:list-decimal [&_ol]:pl-[1.5em]',
       '[&_li]:my-[0.35em] [&_li]:pl-[0.25em] [&_li::marker]:text-faint-foreground',

package/src/components/scroll-area/scroll-area.tsx

@@ -1,5 +1,5 @@
 import { ScrollArea as ScrollAreaPrimitive } from 'radix-ui'
-import type { ComponentProps } from 'react'
+import { type ComponentProps, useEffect, useRef, useState } from 'react'
 import { useComponentConfig } from '../../hooks/use-component-config'
 import type { StylesEntry } from '../../utils/registry'
 import { focusRing } from '../../utils/styles'
@@ -31,6 +31,24 @@ export interface ScrollAreaProps extends ComponentProps<typeof ScrollAreaPrimiti
   viewportClassName?: string
 }
 
+/** True while the element's content overflows it, so keyboard users need to reach it. */
+function useOverflowing<E extends HTMLElement>() {
+  const ref = useRef<E>(null)
+  const [overflowing, setOverflowing] = useState(false)
+  useEffect(() => {
+    const el = ref.current
+    if (!el) return
+    const measure = () =>
+      setOverflowing(el.scrollHeight > el.clientHeight || el.scrollWidth > el.clientWidth)
+    measure()
+    const observer = new ResizeObserver(measure)
+    observer.observe(el)
+    if (el.firstElementChild) observer.observe(el.firstElementChild)
+    return () => observer.disconnect()
+  }, [])
+  return [ref, overflowing] as const
+}
+
 /**
  * A scrollable region with slim, theme-colored scrollbars. Give it a height (or width)
  * with `className`, e.g. `h-72`.
@@ -39,6 +57,7 @@ export function ScrollArea(inProps: ScrollAreaProps) {
   const [props, slots] = useComponentConfig('ScrollArea', inProps)
   const { orientation = 'vertical', viewportClassName, className, children, ...rest } = props
   const s = scrollAreaStyles()
+  const [viewportRef, overflowing] = useOverflowing<HTMLDivElement>()
   const bar = (o: 'vertical' | 'horizontal') => (
     <ScrollAreaPrimitive.Scrollbar
       data-slot="scroll-area-scrollbar"
@@ -55,7 +74,10 @@ export function ScrollArea(inProps: ScrollAreaProps) {
       {...rest}
     >
       <ScrollAreaPrimitive.Viewport
+        ref={viewportRef}
         data-slot="scroll-area-viewport"
+        // Scrollable regions must be reachable by keyboard to scroll with arrow keys.
+        tabIndex={overflowing ? 0 : undefined}
         className={s.viewport({ class: [slots.viewport, viewportClassName] })}
       >
         {children}