@glyphui/ui 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,81 @@
+import { Dialog } from 'radix-ui'
+import { type ComponentProps, type ReactNode, useMemo, useState } from 'react'
+import { useComponentConfig } from '../../hooks/use-component-config'
+import { useControllableState } from '../../hooks/use-controllable-state'
+import { type AppShellVariants, appShellStyles } from './app-shell.styles'
+import { AppShellContext } from './app-shell-context'
+import { SidebarTrigger } from './sidebar'
+
+export interface AppShellProps extends Omit<ComponentProps<'div'>, 'children'>, AppShellVariants {
+  /** A `<Sidebar>`. Shown fixed on desktop and in a drawer on mobile. */
+  sidebar: ReactNode
+  children: ReactNode
+  collapsed?: boolean
+  defaultCollapsed?: boolean
+  onCollapsedChange?: (collapsed: boolean) => void
+  /** Shown next to the menu button in the mobile top bar. */
+  mobileBrand?: ReactNode
+}
+
+/**
+ * App layout: sidebar plus main content. Handles desktop collapse to an icon rail,
+ * the mobile drawer (focus-trapped, closes on navigation), and the mobile top bar.
+ *
+ * `layout="page"` fills the viewport; `layout="embedded"` fills its parent.
+ */
+export function AppShell(inProps: AppShellProps) {
+  const [props, slots] = useComponentConfig('AppShell', inProps)
+  const {
+    sidebar,
+    children,
+    collapsed: collapsedProp,
+    defaultCollapsed = false,
+    onCollapsedChange,
+    mobileBrand,
+    layout,
+    className,
+    ...rest
+  } = props
+  const [collapsed, setCollapsed] = useControllableState({
+    value: collapsedProp,
+    defaultValue: defaultCollapsed,
+    onChange: onCollapsedChange,
+  })
+  const [mobileOpen, setMobileOpen] = useState(false)
+  const s = appShellStyles({ layout })
+
+  const desktop = useMemo(
+    () => ({ collapsed, setCollapsed, mobileOpen, setMobileOpen, inDrawer: false }),
+    [collapsed, setCollapsed, mobileOpen],
+  )
+  const drawer = useMemo(() => ({ ...desktop, collapsed: false, inDrawer: true }), [desktop])
+
+  return (
+    <AppShellContext.Provider value={desktop}>
+      <div data-slot="app-shell" className={s.root({ class: [slots.root, className] })} {...rest}>
+        <div className={s.sidebar({ class: slots.sidebar })}>{sidebar}</div>
+
+        <Dialog.Root open={mobileOpen} onOpenChange={setMobileOpen}>
+          <Dialog.Portal>
+            <Dialog.Overlay className={s.overlay({ class: slots.overlay })} />
+            <Dialog.Content
+              className={s.drawer({ class: slots.drawer })}
+              aria-describedby={undefined}
+            >
+              <Dialog.Title className="sr-only">Navigation</Dialog.Title>
+              <AppShellContext.Provider value={drawer}>{sidebar}</AppShellContext.Provider>
+            </Dialog.Content>
+          </Dialog.Portal>
+        </Dialog.Root>
+
+        <div data-slot="app-shell-main" className={s.main({ class: slots.main })}>
+          <div className={s.mobileBar({ class: slots.mobileBar })}>
+            <SidebarTrigger />
+            {mobileBrand}
+          </div>
+          {children}
+        </div>
+      </div>
+    </AppShellContext.Provider>
+  )
+}

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

@@ -0,0 +1,16 @@
+export { AppShell, type AppShellProps } from './app-shell'
+export { appShellStyles, navbarStyles, pageHeaderStyles, sidebarStyles } from './app-shell.styles'
+export { type AppShellContextValue, useAppShell } from './app-shell-context'
+export { Navbar, type NavbarProps, type NavLink } from './navbar'
+export { PageHeader, type PageHeaderProps } from './page-header'
+export {
+  Sidebar,
+  SidebarContent,
+  SidebarFooter,
+  SidebarHeader,
+  SidebarItem,
+  type SidebarItemProps,
+  SidebarSection,
+  type SidebarSectionProps,
+  SidebarTrigger,
+} from './sidebar'

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

@@ -0,0 +1,119 @@
+import { Dialog } from 'radix-ui'
+import { type ComponentProps, type ReactNode, useState } from 'react'
+import { IconButton } from '../../components/button'
+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 { navbarStyles } from './app-shell.styles'
+
+export interface NavLink {
+  label: ReactNode
+  href: string
+  active?: boolean
+}
+
+export interface NavbarProps extends Omit<ComponentProps<'header'>, 'children'> {
+  brand: ReactNode
+  links?: readonly NavLink[]
+  /** Right side on desktop; bottom of the menu panel on mobile. */
+  actions?: ReactNode
+  /** Stick to the top of the viewport. Default true. */
+  sticky?: boolean
+  /** Transparent at the top; translucent with blur and a border once scrolled. Default true. */
+  blurOnScroll?: boolean
+  containerSize?: ContainerProps['size']
+}
+
+/**
+ * Site header from data: brand, links, actions. Responsive out of the box: links collapse
+ * into a focus-trapped menu panel on small screens.
+ */
+export function Navbar(inProps: NavbarProps) {
+  const [props, slots] = useComponentConfig('Navbar', inProps)
+  const {
+    brand,
+    links = [],
+    actions,
+    sticky = true,
+    blurOnScroll = true,
+    containerSize,
+    className,
+    ...rest
+  } = props
+  const [open, setOpen] = useState(false)
+  const scrolled = useScrolled(8, blurOnScroll)
+  const Link = useLinkComponent()
+  const s = navbarStyles({ sticky, blur: blurOnScroll })
+
+  return (
+    <header
+      data-slot="navbar"
+      data-scrolled={scrolled}
+      className={s.root({ class: [slots.root, className] })}
+      {...rest}
+    >
+      <Container size={containerSize} className={s.inner({ class: slots.inner })}>
+        <div className={s.brand({ class: slots.brand })}>{brand}</div>
+        {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>
+            ))}
+          </nav>
+        )}
+        {actions && <div className={s.actions({ class: slots.actions })}>{actions}</div>}
+
+        <Dialog.Root open={open} onOpenChange={setOpen}>
+          <Dialog.Trigger asChild>
+            <IconButton
+              icon={<MenuIcon />}
+              aria-label="Open menu"
+              className={s.menuButton({ class: slots.menuButton })}
+            />
+          </Dialog.Trigger>
+          <Dialog.Portal>
+            <Dialog.Overlay className={s.overlay({ class: slots.overlay })} />
+            <Dialog.Content
+              className={s.panel({ class: slots.panel })}
+              aria-describedby={undefined}
+            >
+              <div className={s.panelHeader({ class: slots.panelHeader })}>
+                <Dialog.Title asChild>
+                  <div className={s.brand({ class: slots.brand })}>{brand}</div>
+                </Dialog.Title>
+                <Dialog.Close asChild>
+                  <IconButton icon={<XIcon />} aria-label="Close menu" />
+                </Dialog.Close>
+              </div>
+              <nav aria-label="Main" className={s.panelLinks({ class: slots.panelLinks })}>
+                {links.map((link) => (
+                  <Link
+                    key={link.href}
+                    href={link.href}
+                    aria-current={link.active ? 'page' : undefined}
+                    className={s.panelLink({ class: slots.panelLink })}
+                    onClick={() => setOpen(false)}
+                  >
+                    {link.label}
+                  </Link>
+                ))}
+              </nav>
+              {actions && (
+                <div className={s.panelActions({ class: slots.panelActions })}>{actions}</div>
+              )}
+            </Dialog.Content>
+          </Dialog.Portal>
+        </Dialog.Root>
+      </Container>
+    </header>
+  )
+}

package/src/patterns/app-shell/page-header.tsx

@@ -0,0 +1,30 @@
+import type { ComponentProps, ReactNode } from 'react'
+import { useComponentConfig } from '../../hooks/use-component-config'
+import { pageHeaderStyles } from './app-shell.styles'
+
+export interface PageHeaderProps extends Omit<ComponentProps<'div'>, 'title'> {
+  title: ReactNode
+  description?: ReactNode
+  eyebrow?: ReactNode
+  /** Buttons aligned to the end on desktop. */
+  actions?: ReactNode
+}
+
+/** Title block at the top of a page: optional eyebrow, title, description, actions. */
+export function PageHeader(inProps: PageHeaderProps) {
+  const [props, slots] = useComponentConfig('PageHeader', inProps)
+  const { title, description, eyebrow, actions, className, ...rest } = props
+  const s = pageHeaderStyles()
+  return (
+    <div data-slot="page-header" className={s.root({ class: [slots.root, className] })} {...rest}>
+      <div className={s.text({ class: slots.text })}>
+        {eyebrow && <p className={s.eyebrow({ class: slots.eyebrow })}>{eyebrow}</p>}
+        <h1 className={s.title({ class: slots.title })}>{title}</h1>
+        {description && (
+          <p className={s.description({ class: slots.description })}>{description}</p>
+        )}
+      </div>
+      {actions && <div className={s.actions({ class: slots.actions })}>{actions}</div>}
+    </div>
+  )
+}

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

@@ -0,0 +1,163 @@
+import type { ComponentProps, MouseEvent, ReactNode } from 'react'
+import { IconButton, type IconButtonProps } from '../../components/button'
+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 { sidebarStyles } from './app-shell.styles'
+import { useAppShell } from './app-shell-context'
+
+const s = sidebarStyles()
+
+function useSlots() {
+  return useComponentConfig('Sidebar', {})[1]
+}
+
+/** Navigation sidebar. Place inside `AppShell`'s `sidebar` prop. */
+export function Sidebar({ className, ...props }: ComponentProps<'aside'>) {
+  const { collapsed } = useAppShell()
+  const slots = useSlots()
+  return (
+    <aside
+      data-slot="sidebar"
+      data-collapsed={collapsed}
+      className={s.root({ class: [slots.root, className] })}
+      {...props}
+    />
+  )
+}
+
+export function SidebarHeader({ className, ...props }: ComponentProps<'div'>) {
+  const slots = useSlots()
+  return (
+    <div
+      data-slot="sidebar-header"
+      className={s.header({ class: [slots.header, className] })}
+      {...props}
+    />
+  )
+}
+
+export function SidebarContent({ className, ...props }: ComponentProps<'nav'>) {
+  const slots = useSlots()
+  return (
+    <nav
+      data-slot="sidebar-content"
+      aria-label="Main"
+      className={s.content({ class: [slots.content, className] })}
+      {...props}
+    />
+  )
+}
+
+export interface SidebarSectionProps extends ComponentProps<'div'> {
+  label?: ReactNode
+}
+
+export function SidebarSection({ label, className, children, ...props }: SidebarSectionProps) {
+  const slots = useSlots()
+  return (
+    <div
+      data-slot="sidebar-section"
+      className={s.section({ class: [slots.section, className] })}
+      {...props}
+    >
+      {label && <p className={s.sectionLabel({ class: slots.sectionLabel })}>{label}</p>}
+      {children}
+    </div>
+  )
+}
+
+export interface SidebarItemProps {
+  /** Renders a link through the provider's `linkComponent`. Without it, renders a button. */
+  href?: string
+  icon?: ReactNode
+  /** Count or short status shown at the end. */
+  badge?: ReactNode
+  active?: boolean
+  onClick?: (event: MouseEvent<HTMLElement>) => void
+  className?: string
+  children: ReactNode
+}
+
+export function SidebarItem({
+  href,
+  icon,
+  badge,
+  active,
+  onClick,
+  className,
+  children,
+}: SidebarItemProps) {
+  const { collapsed, inDrawer, setMobileOpen } = useAppShell()
+  const Link = useLinkComponent()
+  const slots = useSlots()
+
+  const handleClick = (event: MouseEvent<HTMLElement>) => {
+    onClick?.(event)
+    if (inDrawer) setMobileOpen(false)
+  }
+
+  const content = (
+    <>
+      {icon && (
+        <span className={s.itemIcon({ class: slots.itemIcon })} aria-hidden="true">
+          {icon}
+        </span>
+      )}
+      <span className={s.itemLabel({ class: slots.itemLabel })}>{children}</span>
+      {badge !== undefined && (
+        <span className={s.itemBadge({ class: slots.itemBadge })}>{badge}</span>
+      )}
+    </>
+  )
+  const shared = {
+    'data-slot': 'sidebar-item',
+    'aria-current': active ? ('page' as const) : undefined,
+    className: s.item({ class: [slots.item, className] }),
+  }
+
+  const element = href ? (
+    <Link href={href} onClick={handleClick} {...shared}>
+      {content}
+    </Link>
+  ) : (
+    <button type="button" onClick={handleClick} {...shared}>
+      {content}
+    </button>
+  )
+
+  return (
+    <Tooltip content={children} side="right" disabled={!collapsed}>
+      {element}
+    </Tooltip>
+  )
+}
+
+export function SidebarFooter({ className, ...props }: ComponentProps<'div'>) {
+  const slots = useSlots()
+  return (
+    <div
+      data-slot="sidebar-footer"
+      className={s.footer({ class: [slots.footer, className] })}
+      {...props}
+    />
+  )
+}
+
+/** Collapses the sidebar on desktop; opens the navigation drawer on mobile. */
+export function SidebarTrigger(props: Partial<IconButtonProps>) {
+  const { collapsed, setCollapsed, setMobileOpen, inDrawer } = useAppShell()
+  const desktop = useMediaQuery('(min-width: 48rem)')
+  if (inDrawer) return null
+  return (
+    <IconButton
+      icon={<PanelLeftIcon />}
+      aria-label={desktop ? (collapsed ? 'Expand sidebar' : 'Collapse sidebar') : 'Open navigation'}
+      size="sm"
+      onClick={() => (desktop ? setCollapsed(!collapsed) : setMobileOpen(true))}
+      {...props}
+    />
+  )
+}

package/src/patterns/async/async.tsx

@@ -0,0 +1,83 @@
+import { type DependencyList, type ReactNode, useCallback, useEffect, useState } from 'react'
+import { EmptyState, ErrorState, LoadingState } from './states'
+
+export type AsyncStatus = 'pending' | 'error' | 'success'
+
+/**
+ * The shape of an async result. TanStack Query's `useQuery()` result matches it, as does
+ * Glyph's own `useAsync()`.
+ */
+export interface AsyncResult<T> {
+  status: AsyncStatus
+  data?: T | undefined
+  error?: unknown
+  refetch?: () => unknown
+}
+
+export interface AsyncProps<T> {
+  result: AsyncResult<T>
+  /** Rendered once data is ready and not empty. */
+  children: (data: NonNullable<T>) => ReactNode
+  /** Treat ready data as empty. Defaults to: an empty array. */
+  isEmpty?: (data: NonNullable<T>) => boolean
+  loading?: ReactNode
+  empty?: ReactNode
+  error?: ReactNode | ((error: unknown, retry: (() => unknown) | undefined) => ReactNode)
+}
+
+const defaultIsEmpty = (data: unknown) => Array.isArray(data) && data.length === 0
+
+/**
+ * Renders the right UI for every state of an async result: loading, error (with retry),
+ * empty, or your content. One convention for every data-driven screen.
+ *
+ * ```tsx
+ * <Async result={useQuery(...)} empty={<EmptyState title="No invoices yet" />}>
+ *   {(invoices) => <InvoiceList invoices={invoices} />}
+ * </Async>
+ * ```
+ */
+export function Async<T>({
+  result,
+  children,
+  isEmpty = defaultIsEmpty,
+  loading,
+  empty,
+  error,
+}: AsyncProps<T>) {
+  if (result.status === 'pending') return loading ?? <LoadingState />
+  if (result.status === 'error') {
+    if (typeof error === 'function') return error(result.error, result.refetch)
+    return error ?? <ErrorState error={result.error} onRetry={result.refetch} />
+  }
+  const data = result.data
+  if (data === undefined || data === null || isEmpty(data)) {
+    return empty ?? <EmptyState title="Nothing here yet" />
+  }
+  return children(data)
+}
+
+/**
+ * Runs an async function and tracks its state as an `AsyncResult`. Re-runs when `deps`
+ * change; stale responses are ignored. For caching and deduping, use TanStack Query.
+ */
+export function useAsync<T>(fn: () => Promise<T>, deps: DependencyList): AsyncResult<T> {
+  const [state, setState] = useState<Omit<AsyncResult<T>, 'refetch'>>({ status: 'pending' })
+  const [run, setRun] = useState(0)
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: caller controls re-runs through deps
+  useEffect(() => {
+    let active = true
+    setState((prev) => ({ ...prev, status: 'pending' }))
+    fn().then(
+      (data) => active && setState({ status: 'success', data }),
+      (error: unknown) => active && setState({ status: 'error', error }),
+    )
+    return () => {
+      active = false
+    }
+  }, [...deps, run])
+
+  const refetch = useCallback(() => setRun((n) => n + 1), [])
+  return { ...state, refetch }
+}

package/src/patterns/async/index.ts

@@ -0,0 +1,10 @@
+export { Async, type AsyncProps, type AsyncResult, type AsyncStatus, useAsync } from './async'
+export {
+  EmptyState,
+  ErrorState,
+  type ErrorStateProps,
+  LoadingState,
+  type LoadingStateProps,
+  type StateProps,
+  stateStyles,
+} from './states'

package/src/patterns/async/states.tsx

@@ -0,0 +1,128 @@
+import type { ComponentProps, ReactNode } from 'react'
+import { Button } from '../../components/button'
+import { Spinner } from '../../components/spinner'
+import { useComponentConfig } from '../../hooks/use-component-config'
+import { AlertIcon, InboxIcon } from '../../internal/icons'
+import { tv } from '../../utils/tv'
+
+export const stateStyles = tv({
+  slots: {
+    root: 'flex flex-col items-center justify-center gap-3 px-6 py-12 text-center',
+    icon: 'flex size-10 items-center justify-center rounded-md border border-border bg-surface text-muted-foreground shadow-xs [&>svg]:size-5',
+    text: 'grid max-w-sm gap-1',
+    title: 'text-body font-medium text-foreground',
+    description: 'text-small text-muted-foreground',
+    action: 'mt-1 flex items-center gap-2',
+  },
+  variants: {
+    tone: {
+      neutral: {},
+      danger: { icon: 'border-danger/30 bg-danger/10 text-danger' },
+    },
+  },
+})
+
+export interface StateProps extends Omit<ComponentProps<'div'>, 'title'> {
+  icon?: ReactNode
+  title: ReactNode
+  description?: ReactNode
+  action?: ReactNode
+}
+
+/** Shown when a list or page has no content yet. Say what will appear and how to add it. */
+export function EmptyState(inProps: StateProps) {
+  const [props, slots] = useComponentConfig('EmptyState', inProps)
+  const { icon = <InboxIcon />, title, description, action, className, ...rest } = props
+  const s = stateStyles({ tone: 'neutral' })
+  return (
+    <div data-slot="empty-state" className={s.root({ class: [slots.root, className] })} {...rest}>
+      <div className={s.icon({ class: slots.icon })} aria-hidden="true">
+        {icon}
+      </div>
+      <div className={s.text({ class: slots.text })}>
+        <p className={s.title({ class: slots.title })}>{title}</p>
+        {description && (
+          <p className={s.description({ class: slots.description })}>{description}</p>
+        )}
+      </div>
+      {action && <div className={s.action({ class: slots.action })}>{action}</div>}
+    </div>
+  )
+}
+
+export interface ErrorStateProps extends Omit<StateProps, 'title'> {
+  title?: ReactNode
+  /** The caught error. Its message is shown when no `description` is given. */
+  error?: unknown
+  /** Shows a "Try again" button. */
+  onRetry?: (() => unknown) | undefined
+}
+
+function messageOf(error: unknown): string | undefined {
+  if (error instanceof Error) return error.message
+  if (typeof error === 'string') return error
+  return undefined
+}
+
+/** Shown when loading failed. Explains what went wrong and offers a retry. */
+export function ErrorState(inProps: ErrorStateProps) {
+  const [props, slots] = useComponentConfig('EmptyState', inProps)
+  const {
+    icon = <AlertIcon />,
+    title = 'Couldn’t load this',
+    description,
+    error,
+    onRetry,
+    action,
+    className,
+    ...rest
+  } = props
+  const s = stateStyles({ tone: 'danger' })
+  const detail = description ?? messageOf(error)
+  return (
+    <div
+      data-slot="error-state"
+      role="alert"
+      className={s.root({ class: [slots.root, className] })}
+      {...rest}
+    >
+      <div className={s.icon({ class: slots.icon })} aria-hidden="true">
+        {icon}
+      </div>
+      <div className={s.text({ class: slots.text })}>
+        <p className={s.title({ class: slots.title })}>{title}</p>
+        {detail && <p className={s.description({ class: slots.description })}>{detail}</p>}
+      </div>
+      {(action || onRetry) && (
+        <div className={s.action({ class: slots.action })}>
+          {onRetry && (
+            <Button variant="outline" size="sm" onClick={() => onRetry()}>
+              Try again
+            </Button>
+          )}
+          {action}
+        </div>
+      )}
+    </div>
+  )
+}
+
+export interface LoadingStateProps extends ComponentProps<'div'> {
+  label?: string
+}
+
+/** A centered spinner with a label, for content that has no natural skeleton. */
+export function LoadingState({ label = 'Loading…', className, ...props }: LoadingStateProps) {
+  const s = stateStyles()
+  return (
+    <div
+      data-slot="loading-state"
+      role="status"
+      className={s.root({ class: className })}
+      {...props}
+    >
+      <Spinner size="lg" className="text-faint-foreground" />
+      <p className={s.description()}>{label}</p>
+    </div>
+  )
+}