# LLM.md — @42-components > Documentation for AI agents. Understand the library, then jump to the per-category reference for exact markup, options and events. ## What is this `@42-components` is a headless UI component library in vanilla TypeScript. Components provide behaviour, state, accessibility (ARIA), and keyboard support with **no opinionated styling**. An optional theme (`@42/styles`) uses CSS custom properties for easy rebranding. ## Installation ```bash pnpm add @42/core # headless controllers pnpm add @42/styles # optional theme (CSS custom properties) ``` ## Universal pattern Every component follows the same contract: ```ts import { ComponentName } from '@42/core/'; const instance = new ComponentName(rootElement, options?); instance.on(':', (e) => { /* e.detail */ }); instance.destroy(); // cleanup ``` The controller attaches to **existing DOM** (progressive enhancement). It finds parts via `data-*` selectors, manages ARIA, keyboard, and reflects state on `data-state="open|closed"`. ## Theming Import `@42/styles/index.css` for the full theme, or individual files per component. ### Customizing colors Override the primitive palette — all components update automatically: ```css :root { --c42-primary-500: #0ea5e9; /* your brand color */ --c42-primary-600: #0284c7; /* darker shade for hover */ } ``` ### Dark mode Already included. Activates automatically via `prefers-color-scheme: dark` or explicitly: ```html ``` Force light: ``. ### Global scrollbar Importing the full theme (`@42/styles/index.css`) also applies a thin, subtle, theme-aware scrollbar globally (Firefox + WebKit). Tune it with tokens, or import just `@42/styles/scrollbar.css` on its own: ```css :root { --c42-scrollbar-size: 10px; /* thickness */ --c42-scrollbar-thumb: color-mix(in srgb, var(--c42-color-fg) 22%, transparent); --c42-scrollbar-thumb-hover: color-mix(in srgb, var(--c42-color-fg) 38%, transparent); } ``` ### Token layers | Layer | Purpose | Example | |-------|---------|---------| | Primitives | Raw palette (what users override) | `--c42-primary-500`, `--c42-gray-900` | | Semantic | What components consume | `--c42-color-accent`, `--c42-color-fg`, `--c42-color-bg` | ## Choosing a component Pick by what you are trying to do. The full per-component reference (markup, options, events) lives in the category files under [`docs/llm/reference/`](docs/llm/reference/); complex components also have a deep dive in [`docs/llm/`](docs/llm/). > This index is generated from the frontmatter in > `docs/llm/reference/_fragments/*.md`. Do not edit it by hand — run > `pnpm docs:generate`. ### Inputs & Forms Use when you capture data from the user. | Component | Use it when | Reference | | --- | --- | --- | | `choice` | Checkbox, switch and radio-group form toggles | [↗](docs/llm/reference/inputs.md#choice) | | `color-picker` | Color selection with hex input and native panel | [↗](docs/llm/reference/inputs.md#color-picker) | | `combobox` | Autocomplete/multiselect input with filtering | [↗](docs/llm/reference/inputs.md#combobox) | | `date-picker` | Calendar date selection with single/range modes | [↗](docs/llm/reference/inputs.md#date-picker) | | `file-dropzone` | File upload with drag & drop and type/size validation | [↗](docs/llm/reference/inputs.md#file-dropzone) | | `form` | Form/field orchestrator with validation and ARIA wiring | [↗](docs/llm/reference/inputs.md#form) | | `nested-select` | Hierarchical multi-select with tri-state checkboxes | [↗](docs/llm/reference/inputs.md#nested-select) | | `rich-text-editor` | Contenteditable region with a formatting toolbar | [↗](docs/llm/reference/inputs.md#rich-text-editor) | | `select` | Single-select dropdown (no search) with listbox ARIA | [↗](docs/llm/reference/inputs.md#select) | | `slider` | Single or range slider with keyboard and pointer drag | [↗](docs/llm/reference/inputs.md#slider) | | `sms-editor` | Textarea with live SMS encoding + segment counting | [↗](docs/llm/reference/inputs.md#sms-editor) | | `tags-input` | Token/tag entry with validation and dedupe | [↗](docs/llm/reference/inputs.md#tags-input) | | `textarea-emoji` | Textarea with character counter and emoji picker | [↗](docs/llm/reference/inputs.md#textarea-emoji) | | `time-picker` | Time selection with 12h/24h and minute stepping | [↗](docs/llm/reference/inputs.md#time-picker) | | `whatsapp-editor` | Textarea + formatting toolbar + live preview for WhatsApp messages | [↗](docs/llm/reference/inputs.md#whatsapp-editor) | ### Overlays Use when you need a transient layer above content. | Component | Use it when | Reference | | --- | --- | --- | | `command-palette` | Cmd/Ctrl+K searchable, grouped command panel | [↗](docs/llm/reference/overlays.md#command-palette) | | `drawer` | Edge-anchored slide-in panel with focus trap | [↗](docs/llm/reference/overlays.md#drawer) | | `dropdown` | Button-triggered floating menu with keyboard navigation | [↗](docs/llm/reference/overlays.md#dropdown) | | `modal` | Dialog with overlay, focus trap and scroll lock | [↗](docs/llm/reference/overlays.md#modal) | | `popover` | Interactive floating panel — like an interactive tooltip | [↗](docs/llm/reference/overlays.md#popover) | | `tooltip` | Hover/focus floating label, auto-positioned | [↗](docs/llm/reference/overlays.md#tooltip) | ### Navigation Use when you move around or structure a flow. | Component | Use it when | Reference | | --- | --- | --- | | `mega-menu` | Horizontal nav with large multi-column panels | [↗](docs/llm/reference/navigation.md#mega-menu) | | `nav` | Collapsible sidebar navigation with submenus and mini mode | [↗](docs/llm/reference/navigation.md#nav) | | `pagination` | Page navigation with ellipsis and prev/next | [↗](docs/llm/reference/navigation.md#pagination) | | `stepper` | Multi-step wizard with linear/non-linear navigation | [↗](docs/llm/reference/navigation.md#stepper) | | `tabs` | Tabbed navigation with roving tabindex and arrow keys | [↗](docs/llm/reference/navigation.md#tabs) | ### Data & Collections Use when you display or manipulate sets of data. | Component | Use it when | Reference | | --- | --- | --- | | `calendar` | Month/week/day calendar with events and drag-to-move | [↗](docs/llm/reference/data.md#calendar) | | `data-view` | Data table with search, sort, pagination and row actions | [↗](docs/llm/reference/data.md#data-view) | | `kanban` | Drag & keyboard board moving cards across columns | [↗](docs/llm/reference/data.md#kanban) | | `sortable-table` | Drag/keyboard row & column reordering plus resizing | [↗](docs/llm/reference/data.md#sortable-table) | | `tree` | Nested list with expand/collapse and tri-state checkboxes | [↗](docs/llm/reference/data.md#tree) | ### Media Use when you show images or people. | Component | Use it when | Reference | | --- | --- | --- | | `avatar` | Image with initials fallback and optional status dot | [↗](docs/llm/reference/media.md#avatar) | | `avatar-group` | Overlapping avatar stack with +N overflow | [↗](docs/llm/reference/media.md#avatar-group) | | `gallery` | Image lightbox with navigation and keyboard control | [↗](docs/llm/reference/media.md#gallery) | | `image-viewer` | Zoomable, pannable image with zoom controls | [↗](docs/llm/reference/media.md#image-viewer) | ### Feedback & Status Use when you communicate state, progress or an action. | Component | Use it when | Reference | | --- | --- | --- | | `alert` | Inline callout with variants and optional dismiss | [↗](docs/llm/reference/feedback.md#alert) | | `clipboard` | Copy-to-clipboard button with copied feedback | [↗](docs/llm/reference/feedback.md#clipboard) | | `progress` | Determinate / indeterminate progress bar | [↗](docs/llm/reference/feedback.md#progress) | | `skeleton` | Loading placeholder with loading→content swap | [↗](docs/llm/reference/feedback.md#skeleton) | | `toast` | Floating notification manager with auto-dismiss | [↗](docs/llm/reference/feedback.md#toast) | ### Disclosure & Layout Use when you show or hide regions of content. | Component | Use it when | Reference | | --- | --- | --- | | `accordion` | Collapsible panels, one or multiple open at a time | [↗](docs/llm/reference/disclosure.md#accordion) | | `carousel` | Content slider with dots, autoplay, loop and drag (Embla engine) | [↗](docs/llm/reference/disclosure.md#carousel) | ### Presentational (CSS-only) Use when you just need styles, no controller. | Component | Use it when | Reference | | --- | --- | --- | | `badge` | Small status/label badge with variants | [↗](docs/llm/reference/presentational.md#badge) | | `breadcrumb` | Breadcrumb navigation trail (conceptually Navigation) | [↗](docs/llm/reference/presentational.md#breadcrumb) | | `button` | Button styles with variants and sizes | [↗](docs/llm/reference/presentational.md#button) | | `card` | Container with header, body and footer slots | [↗](docs/llm/reference/presentational.md#card) | | `divider` | Horizontal rule, optionally with a centered label | [↗](docs/llm/reference/presentational.md#divider) | | `input-label` | Styled form label and text input | [↗](docs/llm/reference/presentational.md#input-label) |