# forty-cdk

> Headless / styleless UI primitives for Angular with WAI-ARIA accessibility built in. Every primitive exposes state, behavior, focus management and keyboard interaction, and applies no styles of its own.

Version 0.31.0, documented in 74 pages listed below: 49 primitives, 8 utilities, 11 guides, 3 orientation pages and 3 further entry points. Required peers: `@angular/common` `^22.0.1`, `@angular/core` `^22.0.1`. Optional peers, each unlocking one part of the library: `@angular/forms` `^22.0.1`, `@internationalized/date` `^3.0.0`.

```bash
npm install forty-cdk
```

**The package root exports nothing.** `import { ForDialog } from 'forty-cdk'` resolves to an empty barrel and does not compile. Every primitive ships as its own secondary entry point, named after its folder, and the entry point specifier is published before each description below.

Each page of the documentation site is published as markdown at that page's own URL plus `.md` — the page at https://tutkli.github.io/forty-cdk/select is https://tutkli.github.io/forty-cdk/select.md. The error roster is the one departure: https://tutkli.github.io/forty-cdk/errors.md carries every `FORCDK-*` code in a single file, and the per-code pages under https://tutkli.github.io/forty-cdk/errors have no markdown sibling of their own. Load the one page you need; `llms-full.txt` is every document at once and is listed under Optional for indexers.

## Getting started

- [Installation](https://tutkli.github.io/forty-cdk/installation.md): forty-cdk is a single unscoped npm package that ships one **secondary entry point per primitive**. Installing it adds no styles, no global CSS and no `NgModule` to your application, only the directives you import.
- [Getting started](https://tutkli.github.io/forty-cdk/getting-started.md): This page builds one primitive end to end (installed, composed, styled, and bound to a form) so that by the end you have written every kind of code forty-cdk asks for. The primitive is **Switch**, chosen because it is small enough to show whole and is a form control, so it exercises the one API that has an extra step.
- [Concepts](https://tutkli.github.io/forty-cdk/concepts.md): forty-cdk is one idea applied consistently: **the library owns behaviour, and you own everything else**. Six conventions fall out of that, and they hold across every entry point. Learn them once on a Switch, and a Table page reads the same way.

## Primitives

- [Accordion](https://tutkli.github.io/forty-cdk/accordion.md): `forty-cdk/accordion` — A stack of collapsible sections, optionally allowing multiple panels open at once.
- [Aspect Ratio](https://tutkli.github.io/forty-cdk/aspect-ratio.md): `forty-cdk/aspect-ratio` — A container that keeps its content at a fixed width-to-height ratio.
- [Avatar](https://tutkli.github.io/forty-cdk/avatar.md): `forty-cdk/avatar` — A user image with a graceful fallback across its loading lifecycle.
- [Breadcrumbs](https://tutkli.github.io/forty-cdk/breadcrumbs.md): `forty-cdk/breadcrumbs` — A labelled navigation landmark for a breadcrumb trail: links with aria-current='page' on the current page and decorative separators hidden from assistive technology.
- [Button](https://tutkli.github.io/forty-cdk/button.md): `forty-cdk/button` — Turns any element (a native `<button>` or a custom host like `<div>` / `<span>`) into an accessible button with keyboard activation. Disabled stays focusable (aria-disabled, never the native attribute) and pressed / hovered / focus-visible are reflected as data-\* hooks.
- [Calendar](https://tutkli.github.io/forty-cdk/calendar.md): `forty-cdk/calendar` — A single-date calendar grid implementing the APG Grid pattern over a pluggable date adapter: roving-tabindex day navigation, month / year paging, and min / max / per-date availability.
- [Carousel](https://tutkli.github.io/forty-cdk/carousel.md): `forty-cdk/carousel` — A slideshow of content panels with previous / next controls, an indicator group, optional looping and multi-slide views, and an accessible autoplay mode with a pause control.
- [Checkbox](https://tutkli.github.io/forty-cdk/checkbox.md): `forty-cdk/checkbox` — A checkbox supporting the three states checked, unchecked and indeterminate.
- [Combobox](https://tutkli.github.io/forty-cdk/combobox.md): `forty-cdk/combobox` — An editable input paired with a filterable listbox popup, supporting single or multi selection with chips.
- [Context Menu](https://tutkli.github.io/forty-cdk/context-menu.md): `forty-cdk/context-menu` — A menu opened by right-click or long-press, anchored to the pointer position.
- [Date Field](https://tutkli.github.io/forty-cdk/date-field.md): `forty-cdk/date-field` — A segmented date (and optional time) input over a pluggable date adapter, with one spinbutton per part, keyboard stepping, locale-driven segment order and min / max clamping.
- [Date Picker](https://tutkli.github.io/forty-cdk/date-picker.md): `forty-cdk/date-picker` — A trigger that opens a floating calendar to pick a date, composing ForCalendar inside a dismissible popover with min / max bounds and per-date availability.
- [Dialog](https://tutkli.github.io/forty-cdk/dialog.md): `forty-cdk/dialog` — A modal window overlaid on the page, with a focus trap, scroll lock and Escape / dismiss handling. Also openable imperatively through ForDialogManager.
- [Disclosure](https://tutkli.github.io/forty-cdk/disclosure.md): `forty-cdk/disclosure` — A single trigger that shows or hides a related region of content.
- [Drawer](https://tutkli.github.io/forty-cdk/drawer.md): `forty-cdk/drawer` — A side or bottom sheet built on the modal dialog pattern, adding pointer-driven swipe-to-dismiss and snap points.
- [Dropdown Menu](https://tutkli.github.io/forty-cdk/dropdown-menu.md): `forty-cdk/dropdown-menu` — A button that opens a menu of actions, with full keyboard navigation, typeahead and submenus.
- [Field](https://tutkli.github.io/forty-cdk/field.md): `forty-cdk/field` — Headless wiring that ties a label, description and error region to a control, and reflects validation state as data-\* for styling. Any forty-cdk form control auto-associates; native inputs opt in with forFieldControl.
- [Fieldset](https://tutkli.github.io/forty-cdk/fieldset.md): `forty-cdk/fieldset` — Headless grouping that gives a set of related fields a shared accessible name (a native `<fieldset>` / `<legend>`, or `role="group"` + `aria-labelledby` on any element) plus an optional shared disabled state that reaches custom-role controls.
- [File Upload](https://tutkli.github.io/forty-cdk/file-upload.md): `forty-cdk/file-upload` — A headless drag-and-drop / dialog file-selection zone: a visually-hidden native `<input type="file">` stays the accessible control while a trigger button opens the picker, and dropping files emits the same change. Supports multiple, accept filters and whole-folder (directory) selection.
- [Hover Card](https://tutkli.github.io/forty-cdk/hover-card.md): `forty-cdk/hover-card` — A floating card that opens on hover to preview the content behind a link, with a pointer bridge keeping it open.
- [Input](https://tutkli.github.io/forty-cdk/input.md): `forty-cdk/input` — Attribute directives for single- and multi-line text: a string value() that auto-wires with Signal Forms and reflects every form state (empty, disabled, readonly, invalid …) as `data-*` / `aria-*` hooks.
- [Listbox](https://tutkli.github.io/forty-cdk/listbox.md): `forty-cdk/listbox` — A scrollable list of selectable options with roving-tabindex navigation, single or multi selection.
- [Menu](https://tutkli.github.io/forty-cdk/menu.md): `forty-cdk/menu` — The shared menu surface composed by every menu-family primitive: items, checkbox / radio items, groups, separators and submenus.
- [Menubar](https://tutkli.github.io/forty-cdk/menubar.md): `forty-cdk/menubar` — A horizontal bar of menus, as in a desktop application, with roving tabindex across the triggers.
- [Meter](https://tutkli.github.io/forty-cdk/meter.md): `forty-cdk/meter` — A gauge that shows a scalar value within a known range, bucketed into quality bands.
- [Navigation Menu](https://tutkli.github.io/forty-cdk/navigation-menu.md): `forty-cdk/navigation-menu` — A site-navigation header built on the disclosure pattern: buttons that expand panels of links into a shared viewport.
- [Number Input](https://tutkli.github.io/forty-cdk/number-input.md): `forty-cdk/number-input` — A numeric spinbutton with keyboard stepping, optional +/− buttons, min / max / step clamping and Intl number formatting for the displayed text and aria-valuetext.
- [OTP Input](https://tutkli.github.io/forty-cdk/otp-input.md): `forty-cdk/otp-input` — A one-time-code / PIN field on the single-input model: typed and pasted characters fill styled slots, with masking, character filtering and a complete event.
- [Pagination](https://tutkli.github.io/forty-cdk/pagination.md): `forty-cdk/pagination` — A navigation landmark that derives a visible page list with ellipsis gaps from page, count, siblingCount and boundaryCount, with previous / next buttons and aria-current='page' on the active page.
- [Pane Resizer](https://tutkli.github.io/forty-cdk/pane-resizer.md): `forty-cdk/pane-resizer` — A focusable, draggable, and keyboard-operable divider that resizes the panes on either side, with an optional collapse behaviour.
- [Popover](https://tutkli.github.io/forty-cdk/popover.md): `forty-cdk/popover` — A non-modal floating panel anchored to its trigger by floating-ui, dismissed on Escape, pointer-down outside or focus outside.
- [Progress](https://tutkli.github.io/forty-cdk/progress.md): `forty-cdk/progress` — A bar that reflects the completion progress of a task.
- [Radio Group](https://tutkli.github.io/forty-cdk/radio-group.md): `forty-cdk/radio-group` — A set of radio buttons where only one option can be selected, with arrow-key navigation.
- [Scroll Area](https://tutkli.github.io/forty-cdk/scroll-area.md): `forty-cdk/scroll-area` — A scrollable region with cross-browser, stylable synthetic scrollbars.
- [Search](https://tutkli.github.io/forty-cdk/search.md): `forty-cdk/search` — A role='searchbox' text input that mirrors its value to a signal and reflects validation state, paired with a clear button that self-hides while the field is empty. Reuses forInput's form-value wiring, so it auto-wires with Signal Forms and Field.
- [Select](https://tutkli.github.io/forty-cdk/select.md): `forty-cdk/select` — A custom select: a trigger that opens a portaled listbox popup to pick one or many options, with groups and separators.
- [Separator](https://tutkli.github.io/forty-cdk/separator.md): `forty-cdk/separator` — A static, optionally semantic divider between groups of content or controls, horizontal or vertical.
- [Slider](https://tutkli.github.io/forty-cdk/slider.md): `forty-cdk/slider` — A draggable thumb that picks a numeric value along a track.
- [Stepper](https://tutkli.github.io/forty-cdk/stepper.md): `forty-cdk/stepper` — A multi-step wizard built on the Tabs pattern: a step list with indicators and separators, a content panel per step, Next / Previous navigation, linear gating with optional Signal Forms completion, a display-only progress mode and an optional progress bar.
- [Switch](https://tutkli.github.io/forty-cdk/switch.md): `forty-cdk/switch` — A binary on / off control toggled by click, Enter or Space.
- [Table](https://tutkli.github.io/forty-cdk/table.md): `forty-cdk/table` — A headless data table that decorates a native &lt;table&gt; or a &lt;div&gt; CSS grid with WAI-ARIA table / grid semantics: sticky headers, 2D keyboard navigation, row selection, sortable headers, column resizing and column / row reordering.
- [Tabs](https://tutkli.github.io/forty-cdk/tabs.md): `forty-cdk/tabs` — A tablist that switches between panels of content.
- [Time Field](https://tutkli.github.io/forty-cdk/time-field.md): `forty-cdk/time-field` — A segmented time-of-day input over a pluggable date adapter, with 12 / 24-hour cycles, optional seconds, and min / max time clamping.
- [Time Picker](https://tutkli.github.io/forty-cdk/time-picker.md): `forty-cdk/time-picker` — A trigger that opens a floating listbox of generated time slots over a pluggable date adapter, with a configurable step, 12 / 24-hour labels and min / max bounds. Picking a slot preserves the date, so it composes inside a date-time picker.
- [Toast](https://tutkli.github.io/forty-cdk/toast.md): `forty-cdk/toast` — Brief, auto-dismissing notifications stacked in a corner, opened programmatically through ForToastManager.
- [Toggle](https://tutkli.github.io/forty-cdk/toggle.md): `forty-cdk/toggle` — A two-state button that stays pressed or unpressed.
- [Toolbar](https://tutkli.github.io/forty-cdk/toolbar.md): `forty-cdk/toolbar` — A container that groups a set of controls under roving-tabindex navigation.
- [Tooltip](https://tutkli.github.io/forty-cdk/tooltip.md): `forty-cdk/tooltip` — A small floating label that describes its trigger on hover or focus, without ever taking focus itself.
- [Tree](https://tutkli.github.io/forty-cdk/tree.md): `forty-cdk/tree` — A nested tree view for hierarchical data: expandable nodes with roving-tabindex navigation, single or multi selection, and typeahead.

## Utilities

- [Breakpoints](https://tutkli.github.io/forty-cdk/breakpoints.md): `forty-cdk/breakpoints` — A signal-first, zoneless, SSR-safe viewport breakpoint observer (injectBreakpoints). Configure the breakpoint map once via provideForBreakpointsDefaults (or use the Tailwind scale by default), then read up / down / between / only / active or any arbitrary media query, each as a live Signal&lt;boolean&gt;.
- [Date adapter](https://tutkli.github.io/forty-cdk/date-adapter.md): `forty-cdk/date-adapter` — The `DateAdapter` contract, the `FOR_DATE_ADAPTER` token that provides one, and the zero-dependency `NativeDateAdapter`, imported from `forty-cdk/date-adapter` so that providing an adapter at the application root does not load the date and time primitives, or the code they share, before bootstrap.
- [Defaults](https://tutkli.github.io/forty-cdk/defaults.md): `forty-cdk/defaults` — Every `provideFor<Primitive>Defaults` provider, its `FOR_<PRIMITIVE>_DEFAULTS` token and its `For<Primitive>Defaults` interface, imported from `forty-cdk/defaults` so that configuring a primitive at the application root does not load the primitive itself.
- [Drag & Drop](https://tutkli.github.io/forty-cdk/drag-drop.md): `forty-cdk/drag-drop` — Headless, accessible drag-and-drop for sortable lists and cross-list transfers, driven by both keyboard and pointer. Ships drag handles, custom preview / placeholder templates, live-sort, FLIP reorder animations, auto-scroll, and boundary / axis-lock constraints.
- [Shared](https://tutkli.github.io/forty-cdk/shared.md): `forty-cdk/shared` — The contract surface the primitives share, imported from `forty-cdk/shared`.
- [Testing](https://tutkli.github.io/forty-cdk/testing.md): `forty-cdk/testing` — Spec helpers for code built on forty-cdk, imported from `forty-cdk/testing`: events dispatched the way a browser dispatches them, stubs for the browser APIs jsdom lacks, and real dialog and drawer refs for a component mounted outside its manager.
- [Virtualization](https://tutkli.github.io/forty-cdk/virtualization.md): `forty-cdk/virtualization` — A headless windowing core (injectVirtualizer) plus an ergonomic [forVirtualViewport] + \*forVirtualFor layer that render only the visible slice of huge lists. Fixed or measured item sizes, horizontal lists, scroll-to-index, and an infinite-scroll detector. List primitives (Select, Combobox, Listbox, Tree, Table) compose it directly.
- [Visually Hidden](https://tutkli.github.io/forty-cdk/visually-hidden.md): `forty-cdk/visually-hidden` — Hides its host visually while keeping it in the accessibility tree.

## Guides

- [Styling forty-cdk](https://tutkli.github.io/forty-cdk/guides/styling.md): forty-cdk ships **no styles**. Every primitive exposes state, ARIA, focus management, and keyboard behavior; the visual design is entirely yours. This guide explains the three hooks you style against, so the appearance is yours while the behavior stays the library's.
- [Styling floating content](https://tutkli.github.io/forty-cdk/guides/styling-floating-content.md): Every primitive that portals positioned content to `document.body` (**Popover**, **Tooltip**, **HoverCard**, **DropdownMenu**, **ContextMenu**, and nested **Menu sub-menus**) styles under the same four rules, because the positioner owns the content's `translate` and leaves the rest of the box to you. Follow them and enter / exit animations, arrow offsets and stacking all work without fighting the positioner.
- [Selected-indicator alignment pattern](https://tutkli.github.io/forty-cdk/guides/selected-indicator-pattern.md): Menu checkbox and radio items line their labels up only when every row reserves the checkmark's width, checked or not. `[forMenuItemIndicator]` is the one selection indicator that still keeps a `[forceMount]` opt-in for exactly that, and hiding the glyph with `opacity` rather than `display: none` keeps the slot it reserves.
- [Your first overlay](https://tutkli.github.io/forty-cdk/guides/your-first-overlay.md): This guide walks one overlay from an empty template to a styled, animated popover. It covers the two essential concepts every overlay in forty-cdk shares (the `@if` / open-state model and the portal → global CSS requirement) and points to the per-primitive references when you're ready to go deeper.
- [Wrapping non-form roots](https://tutkli.github.io/forty-cdk/guides/wrapping-non-form-roots.md): Design systems built on forty-cdk rarely expose the raw primitives. They wrap each one in a styled component carrying the system's selector and classes. For **form-value** controls that story lives in [Wrapping form primitives](https://tutkli.github.io/forty-cdk/guides/wrapping-form-primitives.md), which owns the Signal Forms contract, the `FOR_*_HOST_DIRECTIVE_INPUTS` name tuples, and the `[formField]` discovery rules.
- [Wrapping form primitives](https://tutkli.github.io/forty-cdk/guides/wrapping-form-primitives.md): Design systems built on forty-cdk usually don't expose the raw primitives. They wrap each form control in a styled component with the system's selector and classes. The wrapper must re-expose the primitive's full API by exact public name: the value model (`value` / `checked`), the `touched` model, the `touch` output, and the shared form-state inputs (`disabled`, `readonly`, `required`, `invalid`, `pending`, `dirty`, `name`, `errors`), plus every control-specific member. Any omission fails silently: an unbound name falls back to a native DOM property and `[formField]` discovery degrades.
- [Selection value-type contract](https://tutkli.github.io/forty-cdk/guides/selection-value-type-contract.md): Every selection primitive in forty-cdk models its value the same way, so you learn one shape across the whole library and it flows through `[formField]` unchanged whether the control is single- or multi-select.
- [Date adapters](https://tutkli.github.io/forty-cdk/guides/date-adapters.md): Every date and time primitive in forty-cdk (`ForCalendar`, `ForDateField`, `ForDatePicker`, `ForTimeField`, `ForTimePicker` and the range variants) does its arithmetic through a `DateAdapter<D>`. The library depends on no date package of its own: you pick the date type, provide one adapter, and every primitive in the family speaks it.
- [Table: declarative columns](https://tutkli.github.io/forty-cdk/guides/table-declarative-columns.md): Author one `[forTableColumnDef]` per column and `<for-table-body>` stamps the header row and one data row per item out of the same cell primitives, so a column is declared in one place instead of being kept in sync by hand across a header row and a data row.
- [Table: column & row reordering](https://tutkli.github.io/forty-cdk/guides/table-reordering.md): `[forTableColumnReorder]` and `[forTableRowReorder]` are opt-in companion directives that make header columns and data rows reorderable by pointer and by keyboard, each wrapping `[forDropList]` through `hostDirectives` so a table drags exactly as a standalone drop list does. The table never mutates your data: every committed drop reports `{ from, to }` for you to apply yourself.
- [Table: virtualized rows](https://tutkli.github.io/forty-cdk/guides/table-virtualized-rows.md): `[forTableVirtualized]` renders a window of rows instead of the whole dataset, while `aria-rowcount` and each row's `aria-rowindex` go on reporting the true totals, so a grid of tens of thousands of rows scrolls at a fixed cost and still tells a screen reader where the user is.

## Additional entry points

- [Internationalized Date](https://tutkli.github.io/forty-cdk/internationalized-date.md): `forty-cdk/internationalized-date` — Secondary entry point holding the [`@internationalized/date`](https://react-spectrum.adobe.com/internationalized/date/) implementations of the `DateAdapter` contract:
- [Table Virtualization](https://tutkli.github.io/forty-cdk/table-virtualization.md): `forty-cdk/table-virtualization` — The opt-in row-virtualization companion for `[forTable]`: it builds a windowing core from the table's `[rowCount]` and exposes the visible slice for the consumer to render, plus cross-window roving keyboard navigation.
- [Virtual Reorder](https://tutkli.github.io/forty-cdk/virtual-reorder.md): `forty-cdk/virtual-reorder` — Drag-reorder for a windowed `*forVirtualFor` list: it wraps `[forDropList]` and translates the window-relative drop into dataset-**absolute** indices, so a reorder is correct even when the lifted row scrolls out of the rendered window.

## Reference

- [Error codes](https://tutkli.github.io/forty-cdk/errors.md): Every `FORCDK-*` message the library can report — 132 codes across 48 entry points, each with the console line it prints, its cause, its fix and the source it is emitted from.

## Optional

- [llms-full.txt](https://tutkli.github.io/forty-cdk/llms-full.txt): Every document above concatenated, error roster included, 1266 kB. Published for indexers — load the individual pages instead.