@glyphui/ui 0.2.0 → 0.4.0

package/src/components/tree-view/tree-view.tsx

@@ -0,0 +1,274 @@
+import {
+  type ComponentProps,
+  type KeyboardEvent,
+  type MouseEvent,
+  type ReactNode,
+  useCallback,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+import { useComponentConfig } from '../../hooks/use-component-config'
+import { useControllableState } from '../../hooks/use-controllable-state'
+import { type TreeViewVariants, treeViewStyles } from './tree-view.styles'
+
+export interface TreeNode {
+  id: string
+  label: ReactNode
+  icon?: ReactNode
+  children?: readonly TreeNode[]
+  disabled?: boolean
+  /** Text used for type-to-find when `label` is not a string. */
+  textValue?: string
+}
+
+export interface TreeViewProps
+  extends Omit<ComponentProps<'div'>, 'onSelect' | 'children' | 'defaultValue'>,
+    TreeViewVariants {
+  nodes: readonly TreeNode[]
+  /** Ids of expanded nodes (controlled). */
+  expanded?: readonly string[]
+  defaultExpanded?: readonly string[]
+  onExpandedChange?: (expanded: string[]) => void
+  /** Id of the selected node (controlled). `null` for none. */
+  selected?: string | null
+  defaultSelected?: string | null
+  onSelect?: (id: string, node: TreeNode) => void
+  /** Required: describes the tree, e.g. "Project files". */
+  'aria-label': string
+}
+
+interface VisibleNode {
+  node: TreeNode
+  level: number
+  parentId: string | null
+}
+
+function flattenVisible(nodes: readonly TreeNode[], expanded: ReadonlySet<string>): VisibleNode[] {
+  const out: VisibleNode[] = []
+  const walk = (list: readonly TreeNode[], level: number, parentId: string | null) => {
+    for (const node of list) {
+      out.push({ node, level, parentId })
+      if (node.children?.length && expanded.has(node.id)) walk(node.children, level + 1, node.id)
+    }
+  }
+  walk(nodes, 1, null)
+  return out
+}
+
+function textOf(node: TreeNode): string {
+  return (node.textValue ?? (typeof node.label === 'string' ? node.label : '')).toLowerCase()
+}
+
+const NO_IDS: readonly string[] = []
+
+/**
+ * An accessible tree for file browsers and nested navigation. Arrow keys move and
+ * expand/collapse, Home/End jump, typing a letter finds the next match, Enter or Space selects.
+ */
+export function TreeView(inProps: TreeViewProps) {
+  const [props, slots] = useComponentConfig('TreeView', inProps)
+  const {
+    nodes,
+    expanded: expandedProp,
+    defaultExpanded = NO_IDS,
+    onExpandedChange,
+    selected: selectedProp,
+    defaultSelected = null,
+    onSelect,
+    size,
+    className,
+    ...rest
+  } = props
+
+  const [expandedList, setExpandedList] = useControllableState<readonly string[]>({
+    value: expandedProp,
+    defaultValue: defaultExpanded,
+    onChange: onExpandedChange as ((value: readonly string[]) => void) | undefined,
+  })
+  const [selected, setSelected] = useControllableState<string | null>({
+    value: selectedProp,
+    defaultValue: defaultSelected,
+  })
+  const expanded = useMemo(() => new Set(expandedList), [expandedList])
+  const visible = useMemo(() => flattenVisible(nodes, expanded), [nodes, expanded])
+  const [focusedId, setFocusedId] = useState<string | null>(null)
+  const refs = useRef(new Map<string, HTMLDivElement>())
+  const baseId = useId()
+
+  // The single tabbable item: the focused one, else the selected one if visible, else the first.
+  const tabbableId =
+    (focusedId && visible.some((v) => v.node.id === focusedId) && focusedId) ||
+    (selected && visible.some((v) => v.node.id === selected) && selected) ||
+    visible[0]?.node.id
+
+  const focus = useCallback((id: string | undefined) => {
+    if (!id) return
+    setFocusedId(id)
+    refs.current.get(id)?.focus()
+  }, [])
+
+  const toggle = useCallback(
+    (id: string, open?: boolean) => {
+      const isOpen = expanded.has(id)
+      const next = open ?? !isOpen
+      if (next === isOpen) return
+      setExpandedList(next ? [...expandedList, id] : expandedList.filter((x) => x !== id))
+    },
+    [expanded, expandedList, setExpandedList],
+  )
+
+  const select = useCallback(
+    (node: TreeNode) => {
+      if (node.disabled) return
+      setSelected(node.id)
+      onSelect?.(node.id, node)
+    },
+    [onSelect, setSelected],
+  )
+
+  const onKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    const index = visible.findIndex((v) => v.node.id === tabbableId)
+    const current = visible[index]
+    if (!current) return
+    const { node } = current
+    const hasChildren = Boolean(node.children?.length)
+    const isOpen = expanded.has(node.id)
+    let handled = true
+
+    switch (event.key) {
+      case 'ArrowDown':
+        focus(visible[index + 1]?.node.id)
+        break
+      case 'ArrowUp':
+        focus(visible[index - 1]?.node.id)
+        break
+      case 'ArrowRight':
+        if (hasChildren && !isOpen) toggle(node.id, true)
+        else if (hasChildren) focus(node.children?.[0]?.id)
+        break
+      case 'ArrowLeft':
+        if (hasChildren && isOpen) toggle(node.id, false)
+        else if (current.parentId) focus(current.parentId)
+        break
+      case 'Home':
+        focus(visible[0]?.node.id)
+        break
+      case 'End':
+        focus(visible.at(-1)?.node.id)
+        break
+      case 'Enter':
+      case ' ':
+        select(node)
+        break
+      default:
+        handled = false
+        if (event.key.length === 1 && /\S/.test(event.key) && !event.metaKey && !event.ctrlKey) {
+          const char = event.key.toLowerCase()
+          const ordered = [...visible.slice(index + 1), ...visible.slice(0, index + 1)]
+          const match = ordered.find((v) => textOf(v.node).startsWith(char))
+          if (match) {
+            focus(match.node.id)
+            handled = true
+          }
+        }
+    }
+    if (handled) event.preventDefault()
+  }
+
+  const s = treeViewStyles({ size })
+
+  /** Clicks bubble from nested items; only handle the item whose own row was clicked. */
+  const onItemClick = (event: MouseEvent<HTMLDivElement>, node: TreeNode, hasChildren: boolean) => {
+    const row = (event.target as HTMLElement).closest('[data-slot=tree-row]')
+    if (row?.parentElement !== event.currentTarget) return
+    focus(node.id)
+    if (hasChildren) toggle(node.id)
+    select(node)
+  }
+
+  const renderNodes = (list: readonly TreeNode[], level: number): ReactNode =>
+    list.map((node, i) => {
+      const hasChildren = Boolean(node.children?.length)
+      const isOpen = hasChildren && expanded.has(node.id)
+      return (
+        // Keyboard interaction is handled once on the tree (roving focus), not per item.
+        // biome-ignore lint/a11y/useKeyWithClickEvents: see above
+        <div
+          key={node.id}
+          ref={(el) => {
+            if (el) refs.current.set(node.id, el)
+            else refs.current.delete(node.id)
+          }}
+          role="treeitem"
+          data-slot="tree-item"
+          // Name the item by its label only, not by the nested items it contains.
+          aria-labelledby={`${baseId}-${node.id}`}
+          aria-level={level}
+          aria-setsize={list.length}
+          aria-posinset={i + 1}
+          aria-expanded={hasChildren ? isOpen : undefined}
+          aria-selected={selected === node.id}
+          aria-disabled={node.disabled || undefined}
+          tabIndex={node.id === tabbableId ? 0 : -1}
+          onFocus={(event) => {
+            if (event.target === event.currentTarget) setFocusedId(node.id)
+          }}
+          onClick={(event) => onItemClick(event, node, hasChildren)}
+          className={s.item({ class: slots.item })}
+        >
+          <div
+            data-slot="tree-row"
+            data-state={isOpen ? 'open' : 'closed'}
+            className={s.row({ class: slots.row })}
+            style={{ paddingInlineStart: `calc(${level - 1} * 1rem + 0.25rem)` }}
+          >
+            {hasChildren ? (
+              <svg
+                data-slot="tree-chevron"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                aria-hidden="true"
+                className={s.chevron({ class: slots.chevron })}
+              >
+                <path d="m9 18 6-6-6-6" />
+              </svg>
+            ) : (
+              <span className={s.spacer({ class: slots.spacer })} />
+            )}
+            {node.icon && (
+              <span className={s.icon({ class: slots.icon })} aria-hidden="true">
+                {node.icon}
+              </span>
+            )}
+            <span id={`${baseId}-${node.id}`} className={s.label({ class: slots.label })}>
+              {node.label}
+            </span>
+          </div>
+          {isOpen && (
+            // biome-ignore lint/a11y/useSemanticElements: role="group" is the WAI-ARIA tree pattern for child items
+            <div role="group" className={s.group({ class: slots.group })}>
+              {renderNodes(node.children ?? [], level + 1)}
+            </div>
+          )}
+        </div>
+      )
+    })
+
+  return (
+    <div
+      role="tree"
+      data-slot="tree-view"
+      onKeyDown={onKeyDown}
+      className={s.root({ class: [slots.root, className] })}
+      {...rest}
+    >
+      {renderNodes(nodes, 1)}
+    </div>
+  )
+}

package/src/components/visually-hidden/index.ts

@@ -0,0 +1 @@
+export { VisuallyHidden } from './visually-hidden'

package/src/components/visually-hidden/visually-hidden.tsx

@@ -0,0 +1,10 @@
+import { VisuallyHidden as VisuallyHiddenPrimitive } from 'radix-ui'
+import type { ComponentProps } from 'react'
+
+/**
+ * Hides content visually while keeping it available to screen readers, e.g. a label for an
+ * icon-only control or extra context in a table cell.
+ */
+export function VisuallyHidden(props: ComponentProps<typeof VisuallyHiddenPrimitive.Root>) {
+  return <VisuallyHiddenPrimitive.Root data-slot="visually-hidden" {...props} />
+}

package/src/index.ts

@@ -26,28 +26,42 @@ export * from './components/banner'
 export * from './components/blockquote'
 export * from './components/breadcrumb'
 export * from './components/button'
+export * from './components/calendar'
 export * from './components/card'
+export * from './components/carousel'
 export * from './components/checkbox'
 export * from './components/code'
+export * from './components/collapsible'
 export * from './components/combobox'
 export * from './components/command-menu'
 export * from './components/container'
+export * from './components/context-menu'
+export * from './components/copy-button'
+export * from './components/date-picker'
 export * from './components/description-list'
 export * from './components/dialog'
 export * from './components/dropdown-menu'
 export * from './components/eyebrow'
 export * from './components/field'
+export * from './components/file-upload'
 export * from './components/grid'
 export * from './components/heading'
+export * from './components/hover-card'
 export * from './components/input'
+export * from './components/input-otp'
 export * from './components/kbd'
 export * from './components/label'
 export * from './components/link'
+export * from './components/modal'
+export * from './components/navigation-menu'
+export * from './components/number-input'
 export * from './components/pagination'
+export * from './components/password-input'
 export * from './components/popover'
 export * from './components/progress'
 export * from './components/prose'
 export * from './components/radio-group'
+export * from './components/resizable'
 export * from './components/scroll-area'
 export * from './components/section'
 export * from './components/segmented-control'
@@ -59,13 +73,19 @@ export * from './components/slider'
 export * from './components/spinner'
 export * from './components/stack'
 export * from './components/stat-card'
+export * from './components/stepper'
 export * from './components/switch'
 export * from './components/table'
 export * from './components/tabs'
+export * from './components/tag-input'
 export * from './components/text'
 export * from './components/textarea'
+export * from './components/timeline'
 export * from './components/toast'
+export * from './components/toggle'
 export * from './components/tooltip'
+export * from './components/tree-view'
+export * from './components/visually-hidden'
 export * from './hooks'
 // Patterns
 export * from './patterns/app-shell'

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()