@glyphui/ui 0.3.0 → 0.4.0

package/src/components/segmented-control/segmented-control.tsx

@@ -1,8 +1,10 @@
 import { ToggleGroup } from 'radix-ui'
-import type { ReactNode } from 'react'
+import { type ReactNode, useContext } from 'react'
 import { useComponentConfig } from '../../hooks/use-component-config'
+import { warnOnce } from '../../internal/dev'
 import { focusRing, themedBorder, transition } from '../../utils/styles'
 import { tv, type VariantProps } from '../../utils/tv'
+import { FieldContext } from '../field/field-context'
 
 export const segmentedControlStyles = tv({
   slots: {
@@ -40,7 +42,9 @@ export interface SegmentedControlProps<T extends string>
   value?: T
   defaultValue?: T
   onValueChange?: (value: T) => void
-  'aria-label': string
+  /** Required unless the control sits in a `<Field label>`, which labels it. */
+  'aria-label'?: string
+  'aria-labelledby'?: string
   className?: string
   id?: string
 }
@@ -52,7 +56,16 @@ export interface SegmentedControlProps<T extends string>
 export function SegmentedControl<T extends string>(inProps: SegmentedControlProps<T>) {
   const [props, slots] = useComponentConfig('SegmentedControl', inProps)
   const { options, value, defaultValue, onValueChange, size, fullWidth, className, ...rest } = props
+  const field = useContext(FieldContext)
   const s = segmentedControlStyles({ size, fullWidth })
+  const labelledBy = rest['aria-labelledby'] ?? (rest['aria-label'] ? undefined : field?.labelId)
+  if (!rest['aria-label'] && !labelledBy) {
+    warnOnce(
+      'segmented-control-label',
+      'SegmentedControl needs a label: pass aria-label, or place it in a <Field label="…">.',
+    )
+  }
+  const describedBy = [field?.descriptionId, field?.errorId].filter(Boolean).join(' ')
   return (
     <ToggleGroup.Root
       type="single"
@@ -62,6 +75,8 @@ export function SegmentedControl<T extends string>(inProps: SegmentedControlProp
       // Radix emits '' when the active item is clicked again; a segmented control never deselects.
       onValueChange={(next: string) => next && onValueChange?.(next as T)}
       className={s.root({ class: [slots.root, className] })}
+      aria-labelledby={labelledBy}
+      aria-describedby={describedBy || undefined}
       {...rest}
     >
       {options.map((option) => (

package/src/components/slider/slider.tsx

@@ -1,7 +1,7 @@
 import { Slider as SliderPrimitive } from 'radix-ui'
-import type { ReactNode } from 'react'
+import { type ReactNode, useContext } from 'react'
 import { useComponentConfig } from '../../hooks/use-component-config'
-import { useFieldControl } from '../field/field-context'
+import { FieldContext, useFieldControl } from '../field/field-context'
 import { sliderStyles } from './slider.styles'
 
 export type SliderValue = number | readonly [number, number]
@@ -31,7 +31,9 @@ export interface SliderProps<V extends SliderValue> {
   name?: string
   id?: string
   className?: string
+  /** Accessible name. Inside a `Field`, the field's label is used when this is not set. */
   'aria-label'?: string
+  'aria-labelledby'?: string
   'aria-describedby'?: string
   'aria-invalid'?: boolean
   /** Accessible names for range thumbs. Default: "Minimum", "Maximum". */
@@ -61,9 +63,13 @@ export function Slider<V extends SliderValue = number>(inProps: SliderProps<V>)
     className,
     thumbLabels = ['Minimum', 'Maximum'],
     'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledBy,
     'aria-describedby': ariaDescribedBy,
     'aria-invalid': ariaInvalid,
   } = props
+  const field = useContext(FieldContext)
+  // Thumbs are not labelable elements, so a Field's <label for> can't name them.
+  const labelledBy = ariaLabelledBy ?? (ariaLabel ? undefined : field?.labelId)
   const isRange = Array.isArray(value ?? defaultValue)
   const fromArray = (next: number[]) => (isRange ? [next[0], next[1]] : next[0]) as V
   const current = toArray(value) ?? toArray(defaultValue) ?? [min]
@@ -97,6 +103,7 @@ export function Slider<V extends SliderValue = number>(inProps: SliderProps<V>)
             key={index}
             id={index === 0 ? id : undefined}
             aria-label={isRange ? thumbLabels[index] : ariaLabel}
+            aria-labelledby={isRange ? undefined : labelledBy}
             aria-describedby={ariaDescribedBy}
             aria-invalid={ariaInvalid}
             className={s.thumb({ class: slots.thumb })}

package/src/components/stepper/stepper.styles.ts

@@ -41,7 +41,7 @@ export const stepperStyles = tv({
         title: 'text-foreground',
       },
       current: {
-        indicator: 'border-primary bg-surface text-primary ring-4 ring-primary/15',
+        indicator: 'border-primary bg-surface text-primary-text ring-4 ring-primary/15',
         connector: 'bg-border',
         title: 'text-foreground',
       },
@@ -53,7 +53,7 @@ export const stepperStyles = tv({
       error: {
         indicator: 'border-danger bg-danger text-danger-foreground',
         connector: 'bg-border',
-        title: 'text-danger',
+        title: 'text-danger-text',
       },
     },
     clickable: {

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

@@ -18,7 +18,7 @@ export const tagInputStyles = tv({
       'inline-flex size-4 shrink-0 cursor-pointer items-center justify-center rounded-pill text-muted-foreground hover:bg-border-strong/40 hover:text-foreground focus-visible:outline-2 focus-visible:outline-ring [&>svg]:size-3',
     input:
       'h-7 min-w-24 flex-1 bg-transparent px-1 text-foreground outline-none placeholder:text-faint-foreground disabled:cursor-not-allowed',
-    message: 'text-small font-medium text-danger',
+    message: 'text-small font-medium text-danger-text',
   },
   variants: {
     size: {

package/src/components/text/text.styles.ts

@@ -13,10 +13,10 @@ export const textStyles = tv({
       default: { base: 'text-foreground' },
       muted: { base: 'text-muted-foreground' },
       faint: { base: 'text-faint-foreground' },
-      primary: { base: 'text-primary' },
-      success: { base: 'text-success' },
-      warning: { base: 'text-warning' },
-      danger: { base: 'text-danger' },
+      primary: { base: 'text-primary-text' },
+      success: { base: 'text-success-text' },
+      warning: { base: 'text-warning-text' },
+      danger: { base: 'text-danger-text' },
     },
     weight: {
       regular: { base: 'font-normal' },

package/src/integrations/react-router.tsx

@@ -0,0 +1,39 @@
+import { Link, useLocation } from 'react-router'
+import type { GlyphRouter, IsActiveOptions, LinkComponentProps } from '../provider/glyph-context'
+
+const isOutsideApp = (href: string) =>
+  href.startsWith('#') || href.startsWith('//') || /^[a-z][a-z\d+.-]*:/i.test(href)
+
+/**
+ * React Router's `Link`, taking Glyph's `href` prop. Hash links, external URLs and `mailto:`
+ * stay plain anchors, so in-page anchors scroll and external links leave the app.
+ */
+export function RouterLink({ href, ...props }: LinkComponentProps) {
+  if (isOutsideApp(href)) return <a href={href} {...props} />
+  return <Link to={href} {...props} />
+}
+
+const trimSlash = (path: string) => (path.length > 1 ? path.replace(/\/+$/, '') : path)
+
+/** Whether an in-app `href` matches a pathname, with React Router's `NavLink` semantics. */
+export function matchPath(href: string, pathname: string, { end = false }: IsActiveOptions = {}) {
+  // Hash links, external URLs and protocol links never mark an item active.
+  if (!href || isOutsideApp(href)) return false
+  const target = trimSlash(new URL(href, 'http://glyph.local').pathname)
+  const current = trimSlash(pathname)
+  if (end || target === '/') return current === target
+  return current === target || current.startsWith(`${target}/`)
+}
+
+/** Marks a link active when the current location matches it, like React Router's `NavLink`. */
+export function useRouterIsActive(href: string, options?: IsActiveOptions): boolean {
+  const { pathname } = useLocation()
+  return matchPath(href, pathname, options)
+}
+
+/**
+ * Connects Glyph's navigation to React Router (v7 or later):
+ * `<GlyphProvider router={reactRouter}>`. Links render client-side, and Sidebar, Navbar
+ * and NavigationMenu items mark the current page automatically. Must render inside a router.
+ */
+export const reactRouter: GlyphRouter = { Link: RouterLink, useIsActive: useRouterIsActive }

package/src/integrations/vite.test-d.ts

@@ -0,0 +1,6 @@
+// Type-level contract: the plugin plugs into Vite without casts. Checked by `tsc`.
+import type { Plugin } from 'vite'
+import { glyphColorMode } from './vite'
+
+const plugin: Plugin = glyphColorMode({ defaultMode: 'dark' })
+void plugin

package/src/integrations/vite.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+import { getColorModeScript } from '../provider/color-mode-script'
+import { glyphColorMode } from './vite'
+
+describe('glyphColorMode', () => {
+  it('prepends the color-mode script to the head before other transforms', () => {
+    const plugin = glyphColorMode()
+    expect(plugin.name).toBe('glyph:color-mode')
+    expect(plugin.transformIndexHtml.order).toBe('pre')
+    expect(plugin.transformIndexHtml.handler()).toEqual([
+      { tag: 'script', children: getColorModeScript(), injectTo: 'head-prepend' },
+    ])
+  })
+
+  it('uses the same options as GlyphProvider', () => {
+    const [tag] = glyphColorMode({
+      defaultMode: 'dark',
+      storageKey: 'acme-mode',
+    }).transformIndexHtml.handler()
+    expect(tag?.children).toContain('"acme-mode"')
+    expect(tag?.children).toContain('d="dark"')
+  })
+
+  it('skips localStorage when persistence is off', () => {
+    const [tag] = glyphColorMode({ storageKey: null }).transformIndexHtml.handler()
+    expect(tag?.children).not.toContain('localStorage')
+  })
+})

package/src/integrations/vite.ts

@@ -0,0 +1,33 @@
+import { type ColorModeOptions, getColorModeScript } from '../provider/color-mode-script'
+
+/** 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 function glyphColorMode(options: ColorModeOptions = {}): GlyphVitePlugin {
+  const script = getColorModeScript(options)
+  return {
+    name: 'glyph:color-mode',
+    transformIndexHtml: {
+      order: 'pre',
+      handler: () => [{ tag: 'script', children: script, injectTo: 'head-prepend' }],
+    },
+  }
+}
+
+export type { ColorModeOptions }

package/src/internal/dev.ts

@@ -0,0 +1,12 @@
+// Bundlers replace process.env.NODE_ENV; the typeof guard keeps unbundled browsers safe.
+declare const process: { env: { NODE_ENV?: string } } | undefined
+
+const warned = new Set<string>()
+
+/** Logs a console warning once per key, in development only. */
+export function warnOnce(key: string, message: string): void {
+  if (typeof process === 'undefined' || process.env.NODE_ENV === 'production') return
+  if (warned.has(key)) return
+  warned.add(key)
+  console.warn(`[glyph] ${message}`)
+}

package/src/patterns/app-shell/app-shell.styles.ts

@@ -55,7 +55,7 @@ export const sidebarStyles = tv({
       'group-data-[collapsed=true]/sidebar:justify-center group-data-[collapsed=true]/sidebar:px-0',
     ],
     itemIcon: 'flex size-4 shrink-0 items-center justify-center [&>svg]:size-4',
-    itemLabel: 'min-w-0 flex-1 truncate text-left group-data-[collapsed=true]/sidebar:hidden',
+    itemLabel: 'min-w-0 flex-1 truncate text-left group-data-[collapsed=true]/sidebar:sr-only',
     itemBadge:
       'ml-auto font-mono text-caption text-faint-foreground tabular-nums group-data-[collapsed=true]/sidebar:hidden',
     footer: [

package/src/patterns/app-shell/navbar.tsx

@@ -5,13 +5,42 @@ import { Container, type ContainerProps } from '../../components/container'
 import { useComponentConfig } from '../../hooks/use-component-config'
 import { useScrolled } from '../../hooks/use-scrolled'
 import { MenuIcon, XIcon } from '../../internal/icons'
-import { useLinkComponent } from '../../provider/glyph-context'
+import { useIsActive, useLinkComponent } from '../../provider/glyph-context'
 import { navbarStyles } from './app-shell.styles'
 
 export interface NavLink {
   label: ReactNode
   href: string
+  /** Marks the current page. Computed from the provider's `router` when not set. */
   active?: boolean
+  /** With automatic matching, only the exact path is active (not its children). */
+  end?: boolean
+}
+
+function NavbarLink({
+  link,
+  className,
+  onClick,
+}: {
+  link: NavLink
+  className: string
+  onClick?: () => void
+}) {
+  const Link = useLinkComponent()
+  const active = useIsActive(link.href, {
+    explicit: link.active,
+    ...(link.end !== undefined && { end: link.end }),
+  })
+  return (
+    <Link
+      href={link.href}
+      aria-current={active ? 'page' : undefined}
+      className={className}
+      {...(onClick && { onClick })}
+    >
+      {link.label}
+    </Link>
+  )
 }
 
 export interface NavbarProps extends Omit<ComponentProps<'header'>, 'children'> {
@@ -44,7 +73,6 @@ export function Navbar(inProps: NavbarProps) {
   } = props
   const [open, setOpen] = useState(false)
   const scrolled = useScrolled(8, blurOnScroll)
-  const Link = useLinkComponent()
   const s = navbarStyles({ sticky, blur: blurOnScroll })
 
   return (
@@ -59,14 +87,7 @@ export function Navbar(inProps: NavbarProps) {
         {links.length > 0 && (
           <nav aria-label="Main" className={s.links({ class: slots.links })}>
             {links.map((link) => (
-              <Link
-                key={link.href}
-                href={link.href}
-                aria-current={link.active ? 'page' : undefined}
-                className={s.link({ class: slots.link })}
-              >
-                {link.label}
-              </Link>
+              <NavbarLink key={link.href} link={link} className={s.link({ class: slots.link })} />
             ))}
           </nav>
         )}
@@ -96,15 +117,12 @@ export function Navbar(inProps: NavbarProps) {
               </div>
               <nav aria-label="Main" className={s.panelLinks({ class: slots.panelLinks })}>
                 {links.map((link) => (
-                  <Link
+                  <NavbarLink
                     key={link.href}
-                    href={link.href}
-                    aria-current={link.active ? 'page' : undefined}
+                    link={link}
                     className={s.panelLink({ class: slots.panelLink })}
                     onClick={() => setOpen(false)}
-                  >
-                    {link.label}
-                  </Link>
+                  />
                 ))}
               </nav>
               {actions && (

package/src/patterns/app-shell/sidebar.tsx

@@ -4,7 +4,7 @@ import { Tooltip } from '../../components/tooltip'
 import { useComponentConfig } from '../../hooks/use-component-config'
 import { useMediaQuery } from '../../hooks/use-media-query'
 import { PanelLeftIcon } from '../../internal/icons'
-import { useLinkComponent } from '../../provider/glyph-context'
+import { useIsActive, useLinkComponent } from '../../provider/glyph-context'
 import { sidebarStyles } from './app-shell.styles'
 import { useAppShell } from './app-shell-context'
 
@@ -75,7 +75,10 @@ export interface SidebarItemProps {
   icon?: ReactNode
   /** Count or short status shown at the end. */
   badge?: ReactNode
+  /** Marks the current page. Computed from the provider's `router` when not set. */
   active?: boolean
+  /** With automatic matching, only the exact path is active (not its children). */
+  end?: boolean
   onClick?: (event: MouseEvent<HTMLElement>) => void
   className?: string
   children: ReactNode
@@ -85,11 +88,13 @@ export function SidebarItem({
   href,
   icon,
   badge,
-  active,
+  active: activeProp,
+  end,
   onClick,
   className,
   children,
 }: SidebarItemProps) {
+  const active = useIsActive(href, { explicit: activeProp, ...(end !== undefined && { end }) })
   const { collapsed, inDrawer, setMobileOpen } = useAppShell()
   const Link = useLinkComponent()
   const slots = useSlots()

package/src/patterns/chart/chart-parts.tsx

@@ -4,6 +4,11 @@ import { chartStyles } from './chart.styles'
 
 /** Theme colors a series can use by name. Any CSS color also works. */
 export type ChartColor =
+  | 'chart-1'
+  | 'chart-2'
+  | 'chart-3'
+  | 'chart-4'
+  | 'chart-5'
   | 'primary'
   | 'info'
   | 'success'
@@ -12,11 +17,12 @@ export type ChartColor =
   | 'foreground'
   | 'muted-foreground'
 
-const palette: ChartColor[] = ['primary', 'info', 'success', 'warning', 'danger']
+/** Series without a color use the theme's chart palette, in order. */
+const palette: ChartColor[] = ['chart-1', 'chart-2', 'chart-3', 'chart-4', 'chart-5']
 
 export function resolveColor(color: string | undefined, index: number): string {
   const value = color ?? palette[index % palette.length]!
-  return /^[a-z-]+$/.test(value) ? `var(--color-${value})` : value
+  return /^[a-z][a-z\d-]*$/.test(value) ? `var(--color-${value})` : value
 }
 
 export const defaultFormatter = (value: number) =>
@@ -135,6 +141,8 @@ export function ChartFrame({
           <span className={s.description({ class: slots.description })}>{description}</span>
         )}
       </figcaption>
+      {/* Screen readers get the data table below. Charts pass `accessibilityLayer={false}`
+          so recharts adds no focusable nodes inside this hidden plot. */}
       <div className={s.plot({ class: slots.plot })} aria-hidden="true">
         {children}
       </div>

package/src/patterns/chart/chart.tsx

@@ -135,7 +135,11 @@ export function LineChart<T extends object>(
   return (
     <ChartFrame {...frameProps(props)} legend={legend} table={table}>
       <R.ResponsiveContainer width="100%" height={props.height ?? 240}>
-        <R.LineChart data={props.data as T[]} margin={{ top: 8, right: 8, bottom: 0, left: 0 }}>
+        <R.LineChart
+          accessibilityLayer={false}
+          data={props.data as T[]}
+          margin={{ top: 8, right: 8, bottom: 0, left: 0 }}
+        >
           <Axes
             index={props.index}
             showGrid={props.showGrid}
@@ -169,7 +173,11 @@ export function AreaChart<T extends object>(props: CartesianChartProps<T> & { st
   return (
     <ChartFrame {...frameProps(props)} legend={legend} table={table}>
       <R.ResponsiveContainer width="100%" height={props.height ?? 240}>
-        <R.AreaChart data={props.data as T[]} margin={{ top: 8, right: 8, bottom: 0, left: 0 }}>
+        <R.AreaChart
+          accessibilityLayer={false}
+          data={props.data as T[]}
+          margin={{ top: 8, right: 8, bottom: 0, left: 0 }}
+        >
           <defs>
             {resolved.map((item, i) => (
               <linearGradient key={item.key} id={`${id}-${i}`} x1="0" x2="0" y1="0" y2="1">
@@ -216,7 +224,11 @@ export function BarChart<T extends object>(
   return (
     <ChartFrame {...frameProps(props)} legend={legend} table={table}>
       <R.ResponsiveContainer width="100%" height={props.height ?? 240}>
-        <R.BarChart data={props.data as T[]} margin={{ top: 8, right: 8, bottom: 0, left: 0 }}>
+        <R.BarChart
+          accessibilityLayer={false}
+          data={props.data as T[]}
+          margin={{ top: 8, right: 8, bottom: 0, left: 0 }}
+        >
           <Axes
             index={props.index}
             showGrid={props.showGrid}
@@ -286,9 +298,10 @@ export function DonutChart<T extends object>(props: DonutChartProps<T>) {
     >
       <div className="relative mx-auto" style={{ width: size, height: size }}>
         <R.ResponsiveContainer width="100%" height="100%">
-          <R.PieChart>
+          <R.PieChart accessibilityLayer={false}>
             {tooltip(valueFormatter, false)}
             <R.Pie
+              rootTabIndex={-1}
               data={rows}
               dataKey={value}
               nameKey={category}
@@ -346,7 +359,11 @@ export function Sparkline({
       style={{ height }}
     >
       <R.ResponsiveContainer width="100%" height="100%">
-        <R.AreaChart data={data} margin={{ top: 2, right: 2, bottom: 2, left: 2 }}>
+        <R.AreaChart
+          accessibilityLayer={false}
+          data={data}
+          margin={{ top: 2, right: 2, bottom: 2, left: 2 }}
+        >
           <defs>
             <linearGradient id={id} x1="0" x2="0" y1="0" y2="1">
               <stop offset="0%" stopColor={stroke} stopOpacity={area ? 0.25 : 0} />

package/src/patterns/form/form.tsx

@@ -1,6 +1,6 @@
 import { standardSchemaResolver } from '@hookform/resolvers/standard-schema'
 import type { StandardSchemaV1 } from '@standard-schema/spec'
-import type { ComponentProps, ReactNode } from 'react'
+import { type ComponentProps, type MouseEvent, type ReactNode, useCallback } from 'react'
 import {
   type Control,
   Controller,
@@ -11,6 +11,7 @@ import {
   type Resolver,
   type UseFormProps,
   type UseFormReturn,
+  useFormContext,
   useFormState,
   useForm as useHookForm,
 } from 'react-hook-form'
@@ -62,12 +63,29 @@ export interface FormProps<TInput extends FieldValues, TOutput>
   onSubmit: (values: TOutput) => SubmitResult<TInput> | Promise<SubmitResult<TInput>>
 }
 
+// biome-ignore lint/suspicious/noExplicitAny: keyed by any form's control object
+type AnyControl = Control<any, any, any>
+
+/** The rendered `<form>` of each form, so a FormSubmit outside it can submit it. */
+const formElements = new WeakMap<AnyControl, HTMLFormElement>()
+
 export function Form<TInput extends FieldValues, TOutput>({
   form,
   onSubmit,
   children,
+  ref,
   ...props
 }: FormProps<TInput, TOutput>) {
+  const control = form.control as AnyControl
+  const registerElement = useCallback(
+    (element: HTMLFormElement | null) => {
+      if (element) formElements.set(control, element)
+      else formElements.delete(control)
+      if (typeof ref === 'function') ref(element)
+      else if (ref) ref.current = element
+    },
+    [control, ref],
+  )
   const submit = form.handleSubmit(async (values) => {
     try {
       const result = await onSubmit(values)
@@ -85,7 +103,7 @@ export function Form<TInput extends FieldValues, TOutput>({
 
   return (
     <FormProvider {...form}>
-      <form noValidate onSubmit={submit} {...props}>
+      <form noValidate onSubmit={submit} ref={registerElement} {...props}>
         {children}
       </form>
     </FormProvider>
@@ -122,15 +140,39 @@ export function FormField<TInput extends FieldValues, TName extends FieldPath<TI
   )
 }
 
+export interface FormSubmitProps extends Omit<ButtonProps, 'type' | 'form'> {
+  /**
+   * The form to submit, for a button outside `<Form>` such as a Modal footer:
+   * `<FormSubmit form={form}>`. Not needed inside `<Form>`.
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: accepts any form regardless of its value types
+  form?: UseFormReturn<any, any, any>
+}
+
 /** Submit button that shows progress while the form submits. */
-export function FormSubmit(props: Omit<ButtonProps, 'type'>) {
-  const { isSubmitting } = useFormState()
-  return <Button type="submit" loading={isSubmitting} {...props} />
+export function FormSubmit({ form, onClick, ...props }: FormSubmitProps) {
+  const context = useFormContext()
+  const control = (form ?? context)?.control
+  if (!control) {
+    throw new Error(
+      'FormSubmit must be inside <Form> or receive form={form}, e.g. <FormSubmit form={form}> in a Modal footer.',
+    )
+  }
+  const { isSubmitting } = useFormState({ control })
+
+  if (!form) return <Button type="submit" loading={isSubmitting} onClick={onClick} {...props} />
+
+  // Outside <Form>, submit its element explicitly so validation and onSubmit run as usual.
+  const submitOutside = (event: MouseEvent<HTMLButtonElement>) => {
+    onClick?.(event)
+    if (!event.defaultPrevented) formElements.get(control)?.requestSubmit()
+  }
+  return <Button type="button" loading={isSubmitting} onClick={submitOutside} {...props} />
 }
 
 export const formErrorStyles = tv({
   slots: {
-    base: 'flex items-start gap-2 rounded-md border border-danger/30 bg-danger/8 px-3 py-2.5 text-small text-danger',
+    base: 'flex items-start gap-2 rounded-md border border-danger/30 bg-danger/8 px-3 py-2.5 text-small text-danger-text',
     icon: 'mt-0.5 size-4 shrink-0',
   },
 })

package/src/patterns/form/index.ts

@@ -6,6 +6,7 @@ export {
   type FormFieldProps,
   type FormProps,
   FormSubmit,
+  type FormSubmitProps,
   formErrorStyles,
   type SubmitResult,
   type UseFormOptions,

package/src/provider/color-mode-script.ts

@@ -0,0 +1,28 @@
+import type { ColorMode } from '@glyphui/tokens'
+
+// React-free on purpose: the Vite plugin imports this module in Node.
+
+export type ColorModePreference = ColorMode | 'system'
+
+export interface ColorModeOptions {
+  /** Used when nothing is stored yet. */
+  defaultMode?: ColorModePreference
+  /** localStorage key. Set to `null` to disable persistence. */
+  storageKey?: string | null
+}
+
+export const DARK_QUERY = '(prefers-color-scheme: dark)'
+export const DEFAULT_STORAGE_KEY = 'glyph-mode'
+
+/**
+ * A tiny inline script that sets `data-mode` on `<html>` before first paint, so dark-mode
+ * visitors never see a light flash. Use the same options as `GlyphProvider`.
+ */
+export function getColorModeScript({
+  defaultMode = 'system',
+  storageKey = DEFAULT_STORAGE_KEY,
+}: ColorModeOptions = {}): string {
+  return `(function(){try{var d=${JSON.stringify(defaultMode)},m=null;${
+    storageKey ? `m=localStorage.getItem(${JSON.stringify(storageKey)});` : ''
+  }if(m!=='light'&&m!=='dark'&&m!=='system')m=d;if(m==='system')m=matchMedia('${DARK_QUERY}').matches?'dark':'light';var r=document.documentElement;r.dataset.mode=m;r.style.colorScheme=m}catch(e){}})()`
+}