@glyphui/ui 0.3.0 → 0.5.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({
+export const formErrorStyles = /* @__PURE__ */ 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){}})()`
+}

package/src/provider/color-mode.tsx

@@ -8,8 +8,19 @@ import {
   useMemo,
   useState,
 } from 'react'
-
-export type ColorModePreference = ColorMode | 'system'
+import {
+  type ColorModeOptions,
+  type ColorModePreference,
+  DARK_QUERY,
+  DEFAULT_STORAGE_KEY,
+  getColorModeScript,
+} from './color-mode-script'
+
+export {
+  type ColorModeOptions,
+  type ColorModePreference,
+  getColorModeScript,
+} from './color-mode-script'
 
 export interface ColorModeContextValue {
   /** What the user chose. */
@@ -21,16 +32,8 @@ export interface ColorModeContextValue {
 
 const ColorModeContext = createContext<ColorModeContextValue | null>(null)
 
-const DARK_QUERY = '(prefers-color-scheme: dark)'
 const isBrowser = typeof window !== 'undefined'
 
-export interface ColorModeOptions {
-  /** Used when nothing is stored yet. */
-  defaultMode?: ColorModePreference
-  /** localStorage key. Set to `null` to disable persistence. */
-  storageKey?: string | null
-}
-
 function readStoredMode(storageKey: string | null): ColorModePreference | null {
   if (!isBrowser || !storageKey) return null
   try {
@@ -59,7 +62,7 @@ function suppressTransitions(): () => void {
 export function ColorModeProvider({
   children,
   defaultMode = 'system',
-  storageKey = 'glyph-mode',
+  storageKey = DEFAULT_STORAGE_KEY,
 }: ColorModeOptions & { children: ReactNode }) {
   const [mode, setModeState] = useState<ColorModePreference>(
     () => readStoredMode(storageKey) ?? defaultMode,
@@ -112,15 +115,6 @@ export function useColorMode(): ColorModeContextValue {
  * Inline script that sets `data-mode` on `<html>` before first paint, so a dark-mode
  * visitor never sees a light flash. Put it in `<head>`.
  */
-export function getColorModeScript({
-  defaultMode = 'system',
-  storageKey = 'glyph-mode',
-}: 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){}})()`
-}
-
 /** `<script>` element version of `getColorModeScript` for SSR frameworks. */
 export function ColorModeScript(props: ColorModeOptions) {
   return (

package/src/provider/glyph-context.ts

@@ -1,4 +1,4 @@
-import type { Theme } from '@glyphui/tokens'
+import type { MotionLevel, Theme } from '@glyphui/tokens'
 import {
   createContext,
   type ElementType,
@@ -22,9 +22,31 @@ export interface LinkComponentProps {
  */
 export type LinkComponent = ElementType<LinkComponentProps>
 
+export interface IsActiveOptions {
+  /** Match only this exact path, not its children. Default false. */
+  end?: boolean
+}
+
+/**
+ * A hook that reports whether `href` is the current location. Glyph calls it once per
+ * navigation item on every render, so it must follow the rules of hooks.
+ */
+export type UseIsActive = (href: string, options?: IsActiveOptions) => boolean
+
+/** Connects Glyph's navigation components to your router. */
+export interface GlyphRouter {
+  /** Renders links client-side. */
+  Link: LinkComponent
+  /** Marks Sidebar, Navbar and NavigationMenu items active automatically. */
+  useIsActive?: UseIsActive
+}
+
 export interface GlyphContextValue {
   theme: Theme
   linkComponent: LinkComponent
+  useIsActive: UseIsActive
+  /** Overrides the theme's motion level for the whole app. */
+  motion?: MotionLevel | undefined
 }
 
 export const GlyphContext = createContext<GlyphContextValue | null>(null)
@@ -40,3 +62,21 @@ export function useGlyph(): GlyphContextValue {
 export function useLinkComponent(): LinkComponent {
   return useContext(GlyphContext)?.linkComponent ?? 'a'
 }
+
+export const neverActive: UseIsActive = () => 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.
+ */
+export function useIsActive(
+  href: string | undefined,
+  options?: IsActiveOptions & { explicit?: boolean | undefined },
+): boolean {
+  const isActive = useContext(GlyphContext)?.useIsActive ?? neverActive
+  const { explicit, ...matchOptions } = options ?? {}
+  // Always call the router hook so the hook order never changes between renders.
+  const matched = isActive(href ?? '', matchOptions)
+  if (explicit !== undefined) return explicit
+  return href ? matched : false
+}

package/src/provider/glyph-provider.tsx

@@ -1,13 +1,19 @@
-import type { Theme } from '@glyphui/tokens'
+import type { MotionLevel, Theme } from '@glyphui/tokens'
 import { Tooltip } from 'radix-ui'
-import { type ReactNode, useMemo } from 'react'
+import { lazy, type ReactNode, Suspense, useMemo } from 'react'
 import { ConfirmProvider } from '../components/alert-dialog/confirm'
-import { Toaster, type ToasterProps } from '../components/toast/toast'
+import type { ToasterProps } from '../components/toast/toast'
+import { MotionRootAttribute, MotionScope } from '../motion/motion-root'
 import { glyph } from '../themes'
 import { type ColorModePreference, ColorModeProvider } from './color-mode'
-import { GlyphContext, type LinkComponent } from './glyph-context'
+import { GlyphContext, type GlyphRouter, type LinkComponent, neverActive } from './glyph-context'
 import { ThemeStyle } from './theme-style'
 
+// Only apps that turn on `toaster` load the toast UI.
+const Toaster = lazy(() =>
+  import('../components/toast/toast').then((m) => ({ default: m.Toaster })),
+)
+
 export interface GlyphProviderProps {
   children: ReactNode
   /** The theme for the whole app. Defaults to the `glyph` preset. */
@@ -16,13 +22,24 @@ export interface GlyphProviderProps {
   defaultMode?: ColorModePreference
   /** localStorage key for the user's color mode. `null` disables persistence. */
   storageKey?: string | null
-  /** Your router's link, used by Navbar, Sidebar and other navigation components. */
+  /**
+   * Your router: its link component, plus an optional `useIsActive` hook that marks the
+   * current page in Sidebar, Navbar and NavigationMenu. React Router:
+   * `import { reactRouter } from '@glyphui/ui/react-router'`.
+   */
+  router?: GlyphRouter
+  /** Your router's link only. Prefer `router`, which also handles active items. */
   linkComponent?: LinkComponent
   /**
    * Mounts a themed `<Toaster />` so `toast()` works anywhere. `true` for defaults, or pass
    * Toaster props (e.g. `{ position: 'top-center' }`). Off by default.
    */
   toaster?: boolean | ToasterProps
+  /**
+   * Overrides the theme's motion level everywhere, e.g. `"none"` in tests or for a user
+   * setting. Visitors who ask for reduced motion never get animation either way.
+   */
+  motion?: MotionLevel
 }
 
 /** Provides the theme, color mode, tooltips, `useConfirm()` and (optionally) toasts. Render once at the root. */
@@ -31,10 +48,17 @@ export function GlyphProvider({
   theme = glyph,
   defaultMode,
   storageKey,
-  linkComponent = 'a',
+  router,
+  linkComponent,
   toaster = false,
+  motion,
 }: GlyphProviderProps) {
-  const value = useMemo(() => ({ theme, linkComponent }), [theme, linkComponent])
+  const Link = router?.Link ?? linkComponent ?? 'a'
+  const useIsActive = router?.useIsActive ?? neverActive
+  const value = useMemo(
+    () => ({ theme, linkComponent: Link, useIsActive, motion }),
+    [theme, Link, useIsActive, motion],
+  )
   return (
     <ColorModeProvider
       {...(defaultMode !== undefined && { defaultMode })}
@@ -42,13 +66,20 @@ export function GlyphProvider({
     >
       <GlyphContext.Provider value={value}>
         <ThemeStyle theme={theme} />
-        <Tooltip.Provider delayDuration={300}>
-          {/* useConfirm() works anywhere without setup; the dialog only mounts while open. */}
-          <ConfirmProvider>
-            {children}
-            {toaster && <Toaster {...(toaster === true ? {} : toaster)} />}
-          </ConfirmProvider>
-        </Tooltip.Provider>
+        <MotionRootAttribute />
+        <MotionScope>
+          <Tooltip.Provider delayDuration={300}>
+            {/* useConfirm() works anywhere without setup; the dialog only mounts while open. */}
+            <ConfirmProvider>
+              {children}
+              {toaster && (
+                <Suspense fallback={null}>
+                  <Toaster {...(toaster === true ? {} : toaster)} />
+                </Suspense>
+              )}
+            </ConfirmProvider>
+          </Tooltip.Provider>
+        </MotionScope>
       </GlyphContext.Provider>
     </ColorModeProvider>
   )

package/src/provider/index.ts

@@ -9,9 +9,13 @@ export {
 } from './color-mode'
 export {
   type GlyphContextValue,
+  type GlyphRouter,
+  type IsActiveOptions,
   type LinkComponent,
   type LinkComponentProps,
+  type UseIsActive,
   useGlyph,
+  useIsActive,
   useLinkComponent,
 } from './glyph-context'
 export { GlyphProvider, type GlyphProviderProps } from './glyph-provider'

package/src/provider/theme-scope.tsx

@@ -1,8 +1,9 @@
 import { type ColorMode, scopeSelector, type Theme } from '@glyphui/tokens'
 import { Slot } from 'radix-ui'
 import { type ComponentProps, useContext, useMemo } from 'react'
+import { ScopedMotionConfig } from '../motion/motion-root'
 import { cn } from '../utils/cn'
-import { GlyphContext } from './glyph-context'
+import { GlyphContext, neverActive } from './glyph-context'
 import { ThemeStyle } from './theme-style'
 
 export interface ThemeScopeProps extends ComponentProps<'div'> {
@@ -16,21 +17,29 @@ export interface ThemeScopeProps extends ComponentProps<'div'> {
 export function ThemeScope({ theme, mode, asChild, children, ...props }: ThemeScopeProps) {
   const parent = useContext(GlyphContext)
   const value = useMemo(
-    () => ({ theme, linkComponent: parent?.linkComponent ?? 'a' }),
-    [theme, parent?.linkComponent],
+    () => ({
+      theme,
+      linkComponent: parent?.linkComponent ?? 'a',
+      useIsActive: parent?.useIsActive ?? neverActive,
+      motion: parent?.motion,
+    }),
+    [theme, parent?.linkComponent, parent?.useIsActive, parent?.motion],
   )
   const Comp = asChild ? Slot.Root : 'div'
   return (
     <GlyphContext.Provider value={value}>
       <ThemeStyle theme={theme} selector={scopeSelector(theme)} />
-      <Comp
-        data-glyph-theme={theme.name}
-        data-mode={mode}
-        {...props}
-        className={cn('bg-background font-sans text-foreground', props.className)}
-      >
-        {children}
-      </Comp>
+      <ScopedMotionConfig>
+        <Comp
+          data-glyph-theme={theme.name}
+          data-mode={mode}
+          data-motion={parent?.motion ?? theme.motion.level ?? 'subtle'}
+          {...props}
+          className={cn('bg-background font-sans text-foreground', props.className)}
+        >
+          {children}
+        </Comp>
+      </ScopedMotionConfig>
     </GlyphContext.Provider>
   )
 }

package/src/themes.ts

@@ -10,7 +10,7 @@ import { defineTheme, presets as tokenPresets } from '@glyphui/tokens'
 export const glyph = tokenPresets.glyph
 
 /** Zero radius, heavy borders, hard offset shadows, loud color. */
-export const brutalist = defineTheme({
+export const brutalist = /* @__PURE__ */ defineTheme({
   name: 'brutalist',
   extends: tokenPresets.brutalist,
   components: {
@@ -27,7 +27,7 @@ export const brutalist = defineTheme({
 })
 
 /** Serif display type, warm paper neutrals, deep green ink, hairlines instead of shadows. */
-export const editorial = defineTheme({
+export const editorial = /* @__PURE__ */ defineTheme({
   name: 'editorial',
   extends: tokenPresets.editorial,
   components: {
@@ -38,7 +38,7 @@ export const editorial = defineTheme({
 })
 
 /** Pill shapes, lavender and mint, chunky rounded type, springy motion. */
-export const playful = defineTheme({
+export const playful = /* @__PURE__ */ defineTheme({
   name: 'playful',
   extends: tokenPresets.playful,
   components: {

package/src/utils/styles.ts

@@ -6,8 +6,22 @@ export const focusRing =
 export const themedBorder = 'border-(length:--glyph-border-width)'
 
 export const transition =
-  'transition-[color,background-color,border-color,box-shadow,transform,opacity] duration-(--glyph-duration-base) ease-standard'
+  'transition-[color,background-color,border-color,box-shadow,transform,translate,scale,opacity] duration-(--glyph-duration-base) ease-standard'
+
+/**
+ * Enter and exit for anything Radix positions next to a trigger: springs out of the trigger
+ * (pair with the primitive's transform-origin class) and leaves quickly. Distance and scale
+ * follow the motion level; the side moves it toward the trigger.
+ */
+export const popoverMotion =
+  'animate-pop-in data-[state=closed]:animate-pop-out data-[side=bottom]:[--glyph-motion-y:calc(var(--glyph-motion-distance)*-1)] data-[side=top]:[--glyph-motion-y:var(--glyph-motion-distance)] data-[side=left]:[--glyph-motion-x:var(--glyph-motion-distance)] data-[side=right]:[--glyph-motion-x:calc(var(--glyph-motion-distance)*-1)]'
 
 /** Popover surfaces: Select, Tooltip-like menus. */
-export const popover =
-  'z-50 overflow-hidden rounded-[min(var(--radius-md),var(--radius-lg))] border-(length:--glyph-border-width) border-border bg-raised text-foreground shadow-lg animate-pop-in'
+export const popover = `z-50 overflow-hidden rounded-[min(var(--radius-md),var(--radius-lg))] border-(length:--glyph-border-width) border-border bg-raised text-foreground shadow-lg ${popoverMotion}`
+
+/** Dimmed backdrop behind dialogs and sheets. */
+export const overlayMotion =
+  'data-[state=open]:animate-fade-in data-[state=closed]:animate-fade-out'
+
+/** Centered dialogs: rise and scale in on the theme's spring, settle out quickly. */
+export const dialogMotion = 'animate-dialog-in data-[state=closed]:animate-dialog-out'