4AF Components

component-catalog.md

The 4AF component catalog and composition reference for coding agents.

View as Markdown

4AF Component Catalog for Agents

Use this chooser to select an installable component. registry.json holds the current install names, and https://4af.selfsimilar.dev/docs/<component>.md has each component's complete API, notes, and install/usage examples. The links below open the same owning documentation pages.

Sources of truth

  • https://4af.selfsimilar.dev/r/registry.json lists every install name, its files, and its dependencies; npx shadcn@latest search reads it.
  • https://4af.selfsimilar.dev/docs/<name>.md is each component's full reference: API, notes, install command, and usage example.
  • A bundled export such as SelectSortTrigger installs with select, not as a separate item.
  • https://4af.selfsimilar.dev/docs/reference/design.md covers shared geometry and tokens; https://4af.selfsimilar.dev/docs/reference/engineering.md covers the component contract, shared utilities, and loading indicators.

Installable catalog

The catalog contains 47 installable UI items.

Actions

Install name and docsChoose it for
buttonImmediate actions, links styled as buttons, and icon controls.
button-groupRelated buttons joined into one visual group; each keeps its own tab stop.
toggleA pressed state that changes immediately.
action-buttonAn async action with temporary success or error feedback.
action-toggleA pressed state that changes only after an async action succeeds.
copy-buttonClipboard actions with confirmation.
delete-buttonA destructive action confirmed by a second press.
morphAnimated replacement of text or icons with reserved space.

Fields and selection

Install name and docsChoose it for
inputText or number entry, with optional leading icons.
textareaMultiline text entry.
switchAn on/off setting.
checkboxBoolean or indeterminate selection.
radioOne choice from a visible group.
sliderA numeric value or range selected along a rail.
selectSingle or multiple selection from a button trigger; optional panel search and nested options.
select-searchSingle or multiple selection with an editable search field as the trigger.
select-alignedSingle selection aligned over its button trigger when space and input method allow.
date-pickerDate or date-range entry; also bundles the standalone Calendar.

Feedback and status

Install name and docsChoose it for
progressDeterminate progress.
alertAn inline status message or an associated field error.
badgeA compact status, category, or count.
skeletonA placeholder shaped like loading content.
emptyAn empty state with optional action.
text-shimmerA looping highlight for a work-in-progress label.
scramble-textA brief random-character text reveal.
ascii-loaderA compact text spinner.
matrix-loaderA grid of animated dots.
classic-loaderA radial spinner made of fading bars.
Install name and docsChoose it for
breadcrumbA navigation trail with optional expandable middle items.
tabsSwitching between content panels.
collapsibleShowing or hiding a section.
tablePresenting rows without selection, sort controls, or row menus.
data-tableTables with selection, sort controls, or row menus; the caller orders the data.
table-of-contentsHeading navigation with a rail and spanning or single-heading marker.
table-of-contents-linesCompact heading navigation drawn as depth-aware lines.
separatorA horizontal or vertical divider.
command-paletteCommand search, nested lists, or custom panels, including async search.
sidebarResponsive navigation, including split rail/panel layouts.
sidebar-layoutAn optional viewport and scrolling shell around Sidebar.

Overlays and menus

Install name and docsChoose it for
tooltipA short hover or focus description.
sheetA dialog entering from an edge.
dialogA centered dialog, including bundled multi-step flows.
alert-dialogA confirmation dialog that blocks backdrop dismissal.
popoverAn interactive panel anchored to a trigger.
selection-toolbarActions on selected text, with the captured text and range passed to handlers.
hover-cardA rich preview opened by hover or focus.
dropdown-menuAction menus, checkable rows, submenus, or nested searchable selection panels.

Bundled composition choices

Use the host component's parts instead of rebuilding their state handling:

NeedBundled API and owning docs
A compact sort/filter select triggerSelectSortTrigger in Select
Temporary async feedback in a menuDropdownMenuActionItem in Dropdown Menu
Persistent checked state after an async menu actionDropdownMenuCheckboxItem with action in Dropdown Menu
Tabs within a command panelCommandPanelTabs in Command Palette
Actions and toggles over selected textThe matching item parts in Selection Toolbar
An expandable sidebar rowSidebarMenuCollapsible in Sidebar
A validated multi-step dialogDialogSteps and DialogStep in Dialog

Component modules

An installable component can span several files. Consumers still import its public API from @/components/ui/<name>; follow that entry point's re-exports when locating implementation or prop types. Internal modules import their dependencies directly, without importing back through the public entry point.

The following files install together into the project's UI directory. Sibling suffixes below include the component name: for example, .context.ts means select.context.ts.

ComponentPublic entry pointInternal siblings
command-palettecommand-palette.tsx: root state and navigation.types.ts, .context.ts, .search.ts, .keybinds.ts, .panels.tsx, .actions.tsx, .chrome.tsx, .tabs.tsx, .variants.ts
selectselect.tsx: root state and option registration.context.ts, .shared.tsx, .utils.ts, .trigger.tsx, .content.tsx, .sub.tsx, .item.tsx, .variants.ts
dropdown-menudropdown-menu.tsx: public re-exports.menu.tsx, .select.tsx, .actions.tsx, .shared.tsx
sidebarsidebar.tsx: responsive shell.context.ts, .provider.tsx, .controls.tsx, .structure.tsx, .menu.tsx, .variants.ts
selection-toolbarselection-toolbar.tsx: selection tracking and positioning.context.ts, .controls.tsx, .variants.ts
date-pickerdate-picker.tsx: DatePicker, DateRangePicker, re-exported Calendarcalendar.tsx, .variants.ts

These siblings are part of the same registry item, not separate install names; installing the component writes all of them. select-aligned and select-search are separate installable items.

On this page