Components

Every component below comes from zidane-ui and paints from the theme tokens, so it matches the desktop app in every theme. To import one module alone, see Entry points.

import { buttonClass, IconButton, Menu, MenuRow, Segmented } from 'zidane-ui'

Buttons#

buttonClass({ variant, size }) returns a class string, so the same look fits a <button>, an <a> or a router link.

Icon buttons and toggles#

IconButton is the square icon control. IconToggle is its on/off variant for toolbars, placed in a .zg-segment.

IconToggle takes active, onClick, icon (a class), label, badge? and size? ('xs' | 'sm', default sm).

Segments and tabs#

Segmented is a single choice on one track. TabPill is a closable tab in a .zg-segment, with a CountBadge in its trailing slot.

Surfaces and empty states#

Tray is the bed. Raised is a card or control lifted off it. Both take <div> props plus radius ('sm' | 'md' | 'lg' | 'xl', default lg). Raised adds live (one step up while a run streams).

Lighter surfaces are classes: .zg-track-chip, .zg-well, .zg-fill.

Error boundaries#

ErrorBoundary keeps a throw in one region from blanking the others: <ErrorBoundary region="Sidebar" resetKey={sessionId}>. The region shows ErrorFallback (what failed, the message, Try again) until Try again or a new resetKey. fallback replaces it (null renders nothing), actions adds buttons, framed={false} drops the tray.

Each distinct error is logged once to the console through reportRendererError(error, { source }). installRendererErrorHandlers() does the same for the window's uncaught errors and unhandled rejections. configureErrorReports({ sink, showStacks }) at boot sends every report to your log too, and shows the JS and component stacks in the fallback (a development build).

Menus and rows#

MenuRow is the row of every menu, list, picker and nav in the app. Menu gives rows their padding and role ('menu' | 'listbox' | 'group'). Put it in a .zg-float surface or a Popover. Your menu code handles the keyboard. Move active with the arrow keys.

MenuSection (label, trailing) groups rows and MenuSeparator divides them. MenuNote (icon) is a hint or empty state inside a menu. MenuSwitch (on) is the switch glyph alone.

Floating surfaces#

Floating surfaces use the overlay tone, position against their anchor (flipping and clamping to the viewport) and close on Escape or an outside click.

side: 'top' | 'bottom' | 'left' | 'right'. align: 'start' | 'center' | 'end'. RowActionsMenu items: { id, label, onSelect, destructive?, disabled?, shortcut? }.

To build your own, use the parts of Popover: FloatingSurface, usePopover and useAnchoredPosition.

Dialogs and overlays#

Overlay owns the layer: portal, scrim, enter and exit, Escape, focus return, scroll lock. Put the state it passes on your surface's data-state. ConfirmDialog is a confirmation surface for it that focuses its confirm button on mount.

useLightbox() returns { open(items, index, origin?), close, element }. Render element once. Call open with { key, name, src?, body? } items to page through images or text previews. The image grows out of the origin element.

An image in the lightbox shows in ZoomableImage, the kit's image viewer, which you can also use on its own. It fills its parent. The wheel and a trackpad pinch zoom toward the pointer, from fit up to 8× the image's real size. A drag pans while zoomed in, and a double-click switches between fit and the real size. While zoomed, a chip shows the share of the real size; click it to go back to fit. Right-click the image to copy it as an image (PNG), as Base64 or as a data URL. Its ref (ZoomableImageHandle) has zoomIn, zoomOut, reset and zoomed, for an owner that handles the keys: the lightbox maps + / − / 0 to them, and the arrow keys still step. MediaNav draws the lightbox's ‹ › chips (and an optional "n / N" chip) over any box, for your own media sets.

Code, copy and keys#

const agent = createAgent({ ...basic, provider })
await agent.run({ prompt: 'build a REST API' })

cat packages/server/src/handlers/very-long-folder-name/another-nested-directory/session-title-generator.ts | head -n 200 # a long line scrolls inside the frame

$ bun test
41 passed

Forms#

The desktop app's settings layout: sections of rows, each row a label, an optional description and one control.

For your own fields: INPUT_CLASS and TEXTAREA_CLASS.

List furniture#

Motion#

Helpers for a status glyph swapping, a count rolling, a chip growing. All hold still when html[data-motion] is off or reduced (motion switch).

Lower-level motion modules, also exported from zidane-ui, for your own components:

The springs and provider modules import the motion peer, as do Grow, Overlay, FloatingSurface and Lightbox.

Hooks#

From zidane-ui:

import type { CSSProperties } from 'react'
import { useResizeDrag } from 'zidane-ui'
import { useRef, useState } from 'react'

export function Sidebar() {
  const el = useRef<HTMLDivElement>(null)
  const [width, setWidth] = useState(260)
  const drag = useResizeDrag({ value: width, min: 200, max: 480, defaultValue: 260, edge: 'end', target: { ref: el, cssVar: '--sidebar-w' }, onCommit: setWidth })
  return (
    <div ref={el} style={{ '--sidebar-w': `${width}px`, width: 'var(--sidebar-w)' } as CSSProperties}>
      <div {...drag.handleProps} data-active={drag.active} className="zg-resize-handle" />
    </div>
  )
}

Path helpers#

From zidane-ui, browser-safe (no node:path): basename(path), splitPath(path) ({ dir, base }), compactPath(path, maxChars?) (/…/agent/zidane: the start collapses, the last segments stay), formatPathForCwd(path, projectRoot, cwd) (relative below cwd, absolute above it, never ../), tildePath(path, home) (/Users/ada/app → ~/app) and tildeText(text, home) (the same for each path in a line, such as in /Users/ada/app).

The kit's components show paths with their machine's home folder as ~ when you give them the home folders. Wrap the app in PathDisplayProvider homes={{ local: '/Users/ada', [serverId]: '/home/ada' }}. Keys are host ids (HostView.id, 'local' for this computer). A component asks useDisplayPath().path(path, hostId), and PathDisplayScope hostId names the host for everything below it (one session's transcript). This is display only: tooltips, copies and what goes to the agent keep the real path. Without a provider, paths show in full. A zidane host reports its home folder in its ipc.hello (homeDir).

Reference#

components/button, components/IconButton, components/Menu, components/Surface, components/Segmented, components/TabPill, components/Form, components/floating/Popover, components/ConfirmDialog, components/CodeFrame.