alif-ui 2.0.0-alpha.2 → 2.0.0-alpha.21

package/skills/alif-ui/references/components.md

@@ -0,0 +1,540 @@
+# alif-ui component reference
+
+Props below are taken from the library's exported types. `?` = optional. Every component also accepts `className` and `style`, and most forward `ref` and the native attributes of the element they render.
+
+---
+
+## Actions
+
+### `Button`
+
+```tsx
+<Button variant="main" color="primary" size="m" onClick={handleSave}>Save</Button>
+<Button variant="outline" color="danger" loading={isSubmitting} fullWidth>Delete</Button>
+<Button variant="fab" size="s"><SolidSystemSettings /></Button>
+```
+
+`variant?: 'main' | 'fab' | 'function' | 'outline' | 'ghost'` (`'main'`) · `color?: 'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'danger' | 'highlight'` (`'primary'`) · `size?: 'xs' | 's' | 'm' | 'l'` (`'m'`) · `loading?` · `fullWidth?` · plus all `<button>` attributes.
+
+Icon-only button: pass a single icon as children. Left/right icon: put the icon next to the text as children — there are no `leftIcon`/`rightIcon` props on `Button`.
+
+### `UnstyledButton`
+
+A `<button>` with all browser styling removed. Use for custom clickable areas instead of `<div onClick>`. Accepts all `<button>` attributes.
+
+---
+
+## Text & media
+
+### `Typography`
+
+```tsx
+<Typography element="h1" variant="heading" size="h1" weight="bold">Title</Typography>
+<Typography variant="body" size="m" color="var(--mode-text-secondary)">Body copy</Typography>
+```
+
+`variant?: 'display' | 'heading' | 'body' | 'description'` (`'body'`) · `size?` — tied to the variant: `display` → `s|m|l`, `heading` → `h1…h6`, `body` → `xs|s|m|l`, `description` → `s|m|l` (default `'m'`) · `weight?: 'thin' | 'extra-light' | 'light' | 'regular' | 'medium' | 'semi-bold' | 'bold' | 'extra-bold' | 'black' | number` · `color?: string` (a token: `var(--…)`) · `element?: ElementType` (default `'p'`) + that element's props.
+
+With `variant="heading"` the tag is derived from `size` automatically (`size="h2"` renders `<h2>`), so `element` is only needed to override it — e.g. a visually-large label that must stay a `<span>`.
+
+### `Avatar`, `Avatar.Group`
+
+```tsx
+<Avatar size="m" src={user.photo} alt={user.name} name="Jane Cooper" />
+<Avatar.Group spacing="s">{avatars}</Avatar.Group>
+```
+
+`size?: 'xxs' | 'xs' | 's' | 'm' | 'l' | 'xl' | 'xxl'` · `src?` · `alt?` · `name?` (initials fallback) · `imageProps?` · `children?`. `Avatar.Group` takes `spacing?` on the same scale.
+
+### `Badge`
+
+`size?: 'xs' | 's' | 'm'` · `variant?: 'filled' | 'light'` · `color?: 'info' | 'success' | 'neutral' | 'warning' | 'danger' | \`#${string}\`` · `clickable?`. A custom hex is allowed here.
+
+### `Indicator`
+
+Dot/counter attached to a corner of its children.
+
+`size?: 's' | 'm' | 'l' | 'xl' | 'xxl'` · `color?: 'danger' | 'success' | string` · `label?: ReactNode` · `position?: 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end'` · `offset?: number` · `disabled?`.
+
+```tsx
+<Indicator label={unreadCount} color="danger" position="top-end">
+	<Avatar name="Jane" />
+</Indicator>
+```
+
+### `Divider`
+
+`orientation?: 'horizontal' | 'vertical'` · `color?: 'primary' | 'secondary' | 'accent' | 'contrast'` · `size?: 's' | 'm' | 'l'`.
+
+### `Paper`
+
+The surface primitive — use it instead of a styled `<div>` for cards, panels and sheets.
+
+`variant?: 'elevated' | 'surface-1' | 'surface-2' | 'surface-3'` · `shadow?: 'xs' | 's' | 'm' | 'l' | 'xl'` · `radius?: 'none' | 'cherry' | 'strawberry' | 'strawberry-alt' | 'apricot' | 'dulona' | 'peach' | 'apple' | 'coconut' | 'grapefruit' | 'pomelo' | 'blackberry' | 'full' | string` · `bgColor?: 'accent' | 'page-primary' | 'page-secondary' | 'page-tertiary' | 'footer-bg' | 'danger' | 'success' | 'warning' (+ `-tint-10|20|40`) | string`.
+
+### `Skeleton`, `Loader`, `ProgressBar`
+
+```tsx
+<Skeleton width="100%" height={20} radius={8} />
+<Loader size="m" color="primary" />
+<ProgressBar value={65} size="m" trackColor="default" />
+```
+
+- `Skeleton`: `width?`, `height?`, `radius?` (number → px, or string).
+- `Loader`: `size?: 'xs' | 's' | 'm' | 'l' | 'xl'`, `color?: 'primary' | 'secondary' | 'contrast' | string`.
+- `ProgressBar`: `value: number` (0–100, clamped), `size?: 's' | 'm' | 'l'`, `trackColor?: 'default' | 'contrast'`, `color?: string`.
+
+---
+
+## Inputs
+
+### `Input` (and `Field`)
+
+`Input` is the standard text field; `Field` is the same control without the outer wrapper (`Input` = `Field` minus `keepLabel`, `keepLabelFixed`, `bordered`, `leftSection`). Prefer `Input`.
+
+```tsx
+<Input
+	label="Email"
+	name="email"
+	type="email"
+	value={email}
+	onChange={(e) => setEmail(e.target.value)}
+	hasError={!!error}
+	hintLeftSection={error}
+	leftIcon={<OutlineSystemMail />}
+	onClear={() => setEmail('')}
+/>
+```
+
+`label?: ReactNode` · `size?: 's' | 'm' | 'l'` (`'m'`) · `fullWidth?` (**default `true`**) · `hasError?` · `onClear?: () => void` (renders a clear button) · `leftIcon?` / `rightIcon?: ReactNode` · `hintLeftSection?` / `hintRightSection?: ReactNode` (help/error row) · `disabled?` · `inputRegExp?: RegExp | string` (filters typed characters) · `type?: 'text' | 'password' | 'email' | 'number' | 'tel' | 'url' | 'search'` · `onFieldClick?: () => void` · plus native `<input>` attributes and `ref`.
+
+`Field` additionally has `bordered?`, `keepLabel?`, `keepLabelFixed?`, `leftSection?`.
+
+### `Textarea`
+
+`label?` · `size?: 's' | 'm' | 'l'` · `fullWidth?` · `hasError?` · `onClear?` · `hintLeftSection?` / `hintRightSection?` · native `<textarea>` attributes.
+
+### `Search`
+
+`Input` preconfigured with a search icon: `variant?: 'main' | 'filled' | 'accent'`, `size?`, `label?`, `value`, `onChange`, `onClear?`, `fullWidth?`. No `leftIcon`/`rightIcon`/`hasError`.
+
+### `InputOtp`
+
+```tsx
+<InputOtp value={code} onChange={setCode} length={6} onComplete={verify} integerOnly />
+```
+
+`value: string` · `onChange: (code: string) => void` · `length?: number` · `onComplete?: (code: string) => void` · `variant?: 'main' | 'filled'` · `size?: 's' | 'm' | 'l'` · `hasError?` · `mask?` · `integerOnly?` · `autoFocus?` · `placeholder?` · `disabled?` · `inputClassName?` / `inputStyle?`.
+
+### `Checkbox`, `Checkbox.Group`
+
+```tsx
+<Checkbox label="I agree" description="Terms and conditions" checked={agreed}
+	onChange={(e) => setAgreed(e.target.checked)} />
+
+<Checkbox.Group value={tags} onChange={setTags} orientation="vertical">
+	<Checkbox value="news" label="News" />
+	<Checkbox value="offers" label="Offers" />
+</Checkbox.Group>
+```
+
+`Checkbox`: `label?: ReactNode` · `description?: ReactNode` · `labelPosition?: 'left' | 'right'` · `size?: 's' | 'm'` · `isAllChecked?` (indeterminate "select all") · native `<input type=checkbox>` attributes + `ref`.
+
+`Checkbox.Group`: `value?: string[]` / `defaultValue?: string[]` · `onChange?: (value: string[]) => void` · `name?` · `orientation?: 'vertical' | 'horizontal'` · `size?` · `labelPosition?` · `disabled?` · `readOnly?`.
+
+### `Radio`, `Radio.Group`
+
+Same shape as `Checkbox`: `Radio` takes `label`, `description`, `labelPosition`, `size`, native attributes. `Radio.Group` takes `value?: string | null`, `defaultValue?`, `onChange?: (value: string) => void`, `name?`, `orientation?`, `disabled?`, `readOnly?`.
+
+### `Switch`
+
+`label?` · `description?` · `labelPosition?` · `size?: 's' | 'm'` · native checkbox attributes (`checked`, `onChange`, `disabled`).
+
+### `Rating`
+
+`value: number` · `onChange: (value: number) => void` · `max?: number` · `fraction?: number` (e.g. `2` for half-stars) · `size?: 'xs' | 's' | 'm' | 'l'` · `variant?: 'outline' | 'solid'` · `filledIcon?` / `emptyIcon?: ReactNode | ((value: number) => ReactNode)` · `name?`.
+
+### `Slider`, `RangeSlider`
+
+```tsx
+<Slider value={amount} onChange={setAmount} min={0} max={1000} step={50} withTooltip
+	marks={[{ value: 0, label: '0' }, { value: 1000, label: '1000' }]} />
+```
+
+`Slider`: `value: number`, `onChange: (value: number) => void`, `min?`, `max?`, `step?`, `marks?: { label: string; value: number }[]`, `withTooltip?`, `disabled?`.
+`RangeSlider`: the same, with a two-value tuple.
+
+### `FileUploader`, `FileView`
+
+```tsx
+<FileUploader
+	value={files}
+	onChange={setFiles}
+	title="Выберите файл или перетащите сюда"
+	description="PDF, JPG до 5 МБ"
+	allowedExtensions={['pdf', 'jpg']}
+	maxFileSize={5 * 1024 * 1024}
+	maxCount={3}
+	multiple
+/>
+```
+
+`FileUploader`: `value: File[]` · `onChange: (files: File[]) => void` · `title: string` (**required**) · `description?` · `buttonText?` · `multiple?` · `allowedExtensions?: string[]` · `allowedMimeTypes?: string[]` · `maxFileSize?: number` (bytes) · `maxCount?: number` · `hasError?` · `errorText?` · `loading?` · `disabled?`.
+
+`FileView` renders one uploaded file row: `leftIcon?` / `leftSection?` / `rightSection?: ReactNode` · `children?` · `onClick?`.
+
+### `SelectorInput`
+
+An input with an attached dropdown selector (e.g. amount + currency, phone + country).
+
+`inputProps?: Omit<InputProps, 'size' | 'disabled'>` · `selectorProps?: { options: ListItemOption<T>[]; value: T; onChange?: (value, option) => void; renderSelectedOption?: (option) => ReactNode; disabled?; … }` · `color?: 'primary' | 'secondary'` · `size?: 's' | 'm' | 'l'` · `disabled?`.
+
+### `Hinter`
+
+The hint/error line used under inputs: `hasError?`, `children`.
+
+---
+
+## Selection
+
+### `Select`
+
+```tsx
+const options: SelectOption<string>[] = [
+	{ value: 'frontend', label: 'Frontend Developer' },
+	{ value: 'backend', label: 'Backend Developer', secondaryText: 'Node.js' },
+];
+
+<Select
+	label="Role"
+	placeholder="Choose…"
+	value={role}
+	onChange={(value, option) => setRole(value)}
+	options={options}
+	filterable
+	showClearIcon
+/>
+```
+
+`value: T | SelectOption<T> | null` (**required**) · `onChange: (value: T | null, option: SelectOption<T> | null) => void` (**required**, two arguments) · `options: SelectOption<T>[] | SelectGroupOption<T>[]` · `filterable?` (search inside the dropdown) · `onSearch?: (value, event?) => void` · `disableClientFilter?` (for server-side search) · `showClearIcon?` · `alignItemsCenter?` · `itemClassName?` · `onBlur?`, plus from `Input`: `size`, `label`, `placeholder`, `fullWidth`, `name`, `id`, `hasError`, `disabled`, `hintLeftSection`, `hintRightSection`, and from `List`: `loading`, `skeletonCount`, `customEmptyText`, `maxHeight`, `onLoadMore`, `hasMore`, `loadingMore`, `loadMoreOffset`.
+
+Option shape (`SelectOption<T>` = `ListItemOption<T>`): `{ value: T; label?: string; secondaryText?: string; leftSection?: ReactNode; rightSection?: ReactNode; disabled?: boolean }`.
+Grouped options: `{ title: ReactNode; options: SelectOption<T>[]; collapsible?: boolean; defaultOpen?: boolean }`.
+
+### `SelectMultiple`
+
+Same props as `Select` except: `values: string[] | number[] | SelectOption[]` (**not** `value`) · `onChange: (values, options?) => void` · `closeOnSelect?` · `clearInputOnSelect?`.
+
+### `List`, `List.Item`, `List.Group`
+
+```tsx
+<List size="m" maxHeight={320} loading={isLoading} skeletonCount={5}
+	onLoadMore={fetchNext} hasMore={hasNextPage} loadingMore={isFetchingNext}>
+	<List.Group title="Recent" collapsible>
+		{items.map((item) => (
+			<List.Item key={item.id} value={item.id} label={item.name}
+				secondaryText={item.email} leftSection={<Avatar name={item.name} />}
+				onClick={(value, option) => open(value)} />
+		))}
+	</List.Group>
+</List>
+```
+
+`List`: `size?: 'm' | 'l'` · `fullWidth?` · `width?` · `maxHeight?` · `loading?` · `skeletonCount?` · `customEmptyText?` · `onLoadMore?` · `hasMore?` · `loadingMore?` · `loadMoreOffset?`.
+`List.Item`: `value: T` · `label?` · `secondaryText?` · `leftSection?` / `rightSection?` · `selected?` · `disabled?` · `alignItemCenter?` · `onClick?: (value: T, option: ListItemOption<T>) => void`.
+`List.Group`: `title: ReactNode` · `collapsible?` · `defaultOpen?`.
+
+### `Tab`, `Tab.Group`
+
+Chip-style selector built on native inputs (radio/checkbox).
+
+```tsx
+<Tab.Group value={period} onChange={setPeriod} variant="main" size="m" rounded fullWidth>
+	<Tab value="day">Day</Tab>
+	<Tab value="week">Week</Tab>
+</Tab.Group>
+```
+
+`Tab`: `children?` · `leftIcon?` / `rightIcon?` · `variant?: 'main' | 'ghost' | 'accent' | 'outline' | 'text'` · `size?: 's' | 'm' | 'l'` · `rounded?` · `type?: 'radio' | 'checkbox'` · native input attributes.
+`Tab.Group`: `value?` / `defaultValue?` / `onChange?` (arrays when `multiple`) · `multiple?` · `size?` · `variant?` (no `'text'`) · `fullWidth?` · `rounded?` · `justify?: 'flex-start' | 'center' | 'flex-end' | 'space-between'` · `disabled?`.
+
+### `SegmentedControl`
+
+Data-driven segmented switch — no children.
+
+```tsx
+<SegmentedControl
+	value={view}
+	onChange={setView}
+	data={[{ value: 'list', label: 'List' }, { value: 'grid', label: 'Grid', leftIcon: <OutlineSystemGridView /> }]}
+	fullWidth
+/>
+```
+
+`data: { value: string; label: ReactNode; leftIcon?; rightIcon?; disabled? }[]` · `value?` / `defaultValue?` · `onChange: (value: string) => void` (**required**) · `size?` · `variant?` (`Tab` variants except `'text' | 'outline'`) · `fullWidth?` · `rounded?` · `disabled?`.
+
+---
+
+## Dates
+
+Each picker comes in two flavours: `Input*` (field + dropdown, use this in forms) and the bare picker (calendar only, for inline/custom placement).
+
+```tsx
+<InputDatePicker label="Date" value={date} onChange={setDate} minDate={new Date()} />
+<InputDatePicker label="Period" isRange value={range} onChange={setRange} />
+<InputTimePicker label="Time" value={time} onChange={setTime} minutesStep={15} />
+<InputMonthYearPicker label="Month" value={month} onChange={setMonth} />
+```
+
+- `InputDatePicker` / `DatePicker`: `value: Date | [Date, Date] | null` · `onChange: (val) => void` · `isRange?` (with `isRange` you cannot use `withTime`) · `withTime?` · `minDate?` / `maxDate?` · `disabledDates?: Date[]` · `options?: PickerOption<Date | [Date, Date]>[]` (preset shortcuts) · `pickerWidth?` · time props (`hoursStep`, `minutesStep`, `minTime`, `maxTime`) + `Input` props.
+- `InputTimePicker` / `TimePicker`: `value: string` (`'HH:mm'`) · `onChange?` · `minTime?` / `maxTime?` · `hoursStep?` / `minutesStep?` · `withHeader?` · `withConfirmationButton?`.
+- `InputMonthPicker` / `MonthPicker`: `value: number | [number, number] | null` (month index) · `isRange?` · `disabledMonths?: number[]`.
+- `InputYearPicker` / `YearPicker`: `value: number | [number, number] | null` · `minYear?` / `maxYear?` · `disabledYears?: number[]`.
+- `InputMonthYearPicker` / `MonthYearPicker`: `value: string | [string, string] | null` · `minDate?` / `maxDate?` (strings) · `disabledDates?: string[]`.
+
+All bare pickers also accept `onPickerChange?` (fires while navigating, before commit) and `pickerWidth?`.
+
+---
+
+## Navigation
+
+### `Tabs`
+
+Controlled only — `value` and `onChange` are required.
+
+```tsx
+<Tabs value={tab} onChange={setTab} size="m" keepMounted={false}>
+	<Tabs.Menu grow divider>
+		<Tabs.Tab value="profile">Profile</Tabs.Tab>
+		<Tabs.Tab value="settings" leftIcon={<OutlineSystemSettings />}>Settings</Tabs.Tab>
+	</Tabs.Menu>
+
+	<Tabs.Panel value="profile">…</Tabs.Panel>
+	<Tabs.Panel value="settings">…</Tabs.Panel>
+</Tabs>
+```
+
+`Tabs`: `value: string` · `onChange: (value: string) => void` · `size?: 's' | 'm' | 'l'` · `keepMounted?` (default `true`).
+`Tabs.Menu`: `justify?` · `grow?` · `divider?`.
+`Tabs.Tab`: `value: string` + `Tab`-style `children`, `leftIcon`, `rightIcon`.
+`Tabs.Panel`: `value: string` · `keepMounted?`.
+
+### `Breadcrumbs`
+
+Router-agnostic — you supply the link component.
+
+```tsx
+<Breadcrumbs
+	links={[{ label: 'Home', path: '/' }, { label: 'Users', path: '/users' }]}
+	linkComponent={Link}
+	linkProps={(path) => ({ to: path })}
+	maxItems={3}
+/>
+```
+
+`links: { label: ReactNode; path: string }[]` · `linkComponent: ComponentType<T>` (**required**) · `linkProps?: (path: string) => T` · `color?: 'primary' | 'secondary' | 'highlight'` · `maxItems?` (collapses the middle into a menu) · `menuProps?`.
+
+### `Pagination`
+
+`page: number` · `totalPages: number` · `onPageChange: (page: number) => void` · `itemsPerPage?` · `itemsPerPageOptions?: SelectOption<number>[]` · `onItemsPerPageChange?: (value, option?) => void` · `size?: 's' | 'm'` · `siblingCount?` · `showPageNumbers?` · `showFirstLastButtons?` · `disableFirstButton?` / `disableLastButton?` / `disablePreviousButton?` / `disableNextButton?`.
+
+### `AppLayout`, `Navbar`, `Sidebar`
+
+```tsx
+<AppLayout navbar={<Navbar variant="with-border">…</Navbar>} sidebar={<AppSidebar />}>
+	{children}
+</AppLayout>
+```
+
+`AppLayout`: `navbar?: ReactNode` · `sidebar?: ReactNode` · children = page content.
+`Navbar`: `variant?: 'default' | 'with-border' | 'transparent'`.
+
+`Sidebar`: `size?: 'large' | 'compact'` · `variant?: 'default' | 'floating'` · `color?: 'default' | 'contrast' | 'velora' | 'everdeep' | 'abyss' | 'phantor' | string` · `withControlButton?` · `hideScrollbar?`.
+Parts: `Sidebar.Header` (`logo?: { default: ReactNode; compact: ReactNode }`), `Sidebar.Items`, `Sidebar.Item` (`children: string`, `icon?`, `counter?`, `path?`, `onClick?: (path) => void`, `active?`, `rightSection?`, `linkComponent?`, `linkProps?`), `Sidebar.Collapse` (`label`, `icon?`, `counter?`), `Sidebar.Group` (`label`), `Sidebar.Element` (free slot, `icon?`), `Sidebar.Profile` (`name`, `subtitle?`, `avatar?`, `rightSection?`), `Sidebar.Footer` (`withDivider?`).
+
+---
+
+## Overlays
+
+### `Modal`
+
+```tsx
+const [isOpen, setIsOpen] = useState(false);
+
+<Modal isOpen={isOpen} onClose={() => setIsOpen(false)} centered scrollable withCloseButton>
+	<Modal.Header title="Heading" description="Optional description" />
+	<Modal.Content>…</Modal.Content>
+	<Modal.Actions>
+		<Button variant="outline" onClick={() => setIsOpen(false)}>Cancel</Button>
+		<Button onClick={submit}>Confirm</Button>
+	</Modal.Actions>
+</Modal>
+```
+
+`isOpen: boolean` (**required**) · `onClose: () => void` (**required**) · `centered?` · `scrollable?` · `withCloseButton?` · `device?: 'desktop' | 'mobile'` · `closeOnClickOutside?` (default `true`) · `zIndex?` · `transitionProps?` (see `Transition`).
+Escape, click-outside, scroll lock and focus trap are handled by the component.
+
+### `Drawer`
+
+Same base as `Modal` (`isOpen`, `onClose`, `closeOnClickOutside`, `zIndex`) plus `position?: 'right' | 'left' | 'top' | 'bottom'` · `variant?: 'default' | 'floating'` · `width?` / `height?` / `maxWidth?` / `maxHeight?` · `withCloseButton?` · `scrollable?`. Parts: `Drawer.Header`, `Drawer.Content`, `Drawer.Actions`.
+
+### `Popover`
+
+```tsx
+<Popover position="bottom-start" width="trigger" triggerType="click" withArrow>
+	<Popover.Trigger><Button>Open</Button></Popover.Trigger>
+	<Popover.Dropdown>…</Popover.Dropdown>
+</Popover>
+```
+
+`children` must be `Popover.Trigger` + `Popover.Dropdown`. `position?: 'top' | 'bottom' | 'left' | 'right'` each with `-start` / `-end` variants (`'bottom'`) · `offset?: number` (`4`) · `isOpen?` + `onChange?: (isOpen: boolean) => void` (controlled; omit both for uncontrolled) · `onClose?` · `withArrow?` · `width?: number | string` — the special value `'trigger'` matches the trigger's width · `zIndex?` · `isFixed?` (for `position: fixed` contexts) · `triggerType?: 'click' | 'hover' | 'click-hover'` · `disabled?` · `transitionProps?`. Nesting popovers is supported.
+
+### `Menu`
+
+Popover preconfigured as an action menu; the trigger is a **prop**, not a child.
+
+```tsx
+<Menu trigger={<Button size="s">Actions</Button>} position="bottom-end" maxHeight={280}>
+	<Menu.Item leftIcon={<OutlineSystemMail />} onClick={openMail}>Messages</Menu.Item>
+	<Menu.Item disabled>Archive</Menu.Item>
+	<Menu.Sub label="More">
+		<Menu.Item onClick={exportCsv}>Export CSV</Menu.Item>
+	</Menu.Sub>
+</Menu>
+```
+
+`Menu`: `trigger: ReactNode` (**required**) · `maxHeight?` · `triggerClassName?` / `triggerStyle?` + all `Popover` props.
+`Menu.Item`: `children` · `leftIcon?` / `rightIcon?` · `onClick?` · `disabled?` · `closeOnClick?` (default closes).
+`Menu.Sub`: `label` + `Menu.Item` props + `Popover` props.
+
+### `Tooltip`
+
+```tsx
+<Tooltip label="Copy to clipboard" position="top">
+	<Button variant="ghost"><SolidSystemCopy /></Button>
+</Tooltip>
+```
+
+`label: ReactNode` (**required**) · children = the trigger · `position?` (`'top'`) · `withArrow?` (default `true`) · `triggerType?` (default `'hover'`) + `Popover` props.
+
+### `Backdrop`, `Portal`
+
+Low-level pieces behind `Modal`/`Drawer`. `Backdrop`: `isOpen`, `onClose`, `closeOnClickOutside?`, `zIndex?`, `transitionProps?`. `Portal`: `children`, `placement?: { top, left, zIndex? }`, `isFixed?`. Use them only for genuinely custom overlays.
+
+---
+
+## Feedback
+
+### `Snackbar` + `snackbar`
+
+Mount the host once near the app root, then call the imperative API from anywhere (including outside React).
+
+```tsx
+// once
+<Snackbar position="top-right" duration={4000} />
+
+// anywhere
+snackbar.success('Saved');
+snackbar.error('Something went wrong', { description: err.message, withCloseButton: true });
+snackbar('Plain message', { position: 'bottom-center' });
+const id = snackbar.loading('Uploading…');
+snackbar.promise(uploadFile(file), { loading: 'Uploading…', success: 'Uploaded', error: 'Failed' });
+snackbar.custom((id) => <MyCard onClose={() => snackbar.dismiss(id)} />);
+snackbar.dismiss(id); // or snackbar.dismiss() for all
+```
+
+`Snackbar` props: `position?: 'top-right' | 'top-left' | 'top-center' | 'bottom-right' | 'bottom-left' | 'bottom-center'` · `duration?: number` (ms, defaults `4000`).
+Per-call `SnackbarOptions`: `id?`, `duration?` (`0` = sticky), `position?`, `description?`, `leftSlot?`, `rightSlot?`, `actionSlot?`, `withCloseButton?`, `withTimer?`, `style?`.
+
+### `Alert`
+
+Inline message block. `title?: string` · `description?: string` · `variant?: 'light' | 'outline' | 'filled'` · `color?: 'info' | 'success' | 'warning' | 'error'` · `icon?: ReactNode` · `onClose?: () => void` (renders the close button).
+
+---
+
+## Disclosure
+
+### `Accordion`
+
+```tsx
+<Accordion type="single" defaultValue="a" withDivider size="m">
+	<Accordion.Item value="a">
+		<Accordion.Trigger>Question A</Accordion.Trigger>
+		<Accordion.Content>Answer A</Accordion.Content>
+	</Accordion.Item>
+</Accordion>
+```
+
+`type?: 'single' | 'multiple'` (`'single'`) — with `'multiple'`, `value`/`defaultValue`/`onChange` work with `string[]` instead of `string` · `value?` / `defaultValue?` / `onChange?` · `size?: 'xs' | 's' | 'm' | 'l'` · `withDivider?` · `duration?: number`.
+`Accordion.Item`: `value: string` · `disabled?`. `Accordion.Trigger`: `chevron?: ReactNode | ((isOpen: boolean) => ReactNode)`.
+
+### `Collapse`
+
+`isOpen: boolean` · `children` · `duration?: number`. Animates height only — no trigger of its own.
+
+### `Timeline`
+
+`horizontal?` · `active?: number` (index up to which items are completed) · `contentRatio?: { main?: number; opposite?: number }`. Parts: `Timeline.Item` (`bullet?: ReactNode | ((status) => ReactNode)`), `Timeline.Content`, `Timeline.OppositeContent`.
+
+---
+
+## Data
+
+### `Table`
+
+```tsx
+<Table verticalSpacing="m" highlightOnHover stickyHeader withRowBorders>
+	<Table.Thead>
+		<Table.Tr><Table.Th>Name</Table.Th><Table.Th>Role</Table.Th></Table.Tr>
+	</Table.Thead>
+	<Table.Tbody>
+		{rows.map((row) => (
+			<Table.Tr key={row.id}><Table.Td>{row.name}</Table.Td><Table.Td>{row.role}</Table.Td></Table.Tr>
+		))}
+	</Table.Tbody>
+</Table>
+```
+
+`verticalSpacing?: 's' | 'm' | 'l' | 'xl'` · `rowGap?: number | string` · `variant?: 'default' | 'filled'` · `headerColor?: 'primary' | 'secondary'` · `withRowBorders?` · `withColumnBorders?` · `highlightOnHover?` · `stickyHeader?` · `stickyFooter?`.
+Parts: `Table.Thead`, `Table.Tbody`, `Table.Tfoot`, `Table.Tr`, `Table.Th`, `Table.Td`, `Table.CollapseRow` (`isOpen: boolean`, `colSpan: number` — expandable row content). Each accepts the native attributes of its element.
+
+---
+
+## Motion
+
+### `Transition`
+
+Render-prop animation wrapper.
+
+```tsx
+<Transition mounted={isVisible} transition="fade-up" duration={200}>
+	{(styles) => <Paper style={styles}>…</Paper>}
+</Transition>
+```
+
+`mounted: boolean` · `children: (styles: CSSProperties) => ReactNode` · `transition?` — `'fade' | 'fade-up' | 'fade-down' | 'fade-left' | 'fade-right' | 'slide-up' | 'slide-down' | 'slide-left' | 'slide-right' | 'scale' | 'scale-x' | 'scale-y' | 'skew-up' | 'skew-down' | 'rotate-left' | 'rotate-right' | 'pop' | 'pop-top-left' | 'pop-top-right' | 'pop-bottom-left' | 'pop-bottom-right' | 'collapser'` or a custom styles object · `duration?` / `exitDuration?` · `enterDelay?` / `exitDelay?` · `timingFunction?` · `onEnter?` / `onEntered?` / `onExit?` / `onExited?`.
+
+Overlay components accept the same options as `transitionProps` (without `mounted`/`children`).
+
+---
+
+## Hooks
+
+- `useMode()` → `{ mode, toggleMode }` — current `'light' | 'dark' | 'system'` and a toggle.
+- `useLocale()` → `{ locale, setLocale }` — `'ru' | 'en' | 'tj'`.
+- `useTranslation()` → `{ t, language, changeLanguage }` — `t('key', { name: 'Alif' })` interpolates `{{name}}`; `changeLanguage` is async.
+- `localization` — the same translator outside React: `localization.init(loader)`, `localization.t(key, params?)`.
+- `useMediaQuery(query, { defaultValue?, initializeWithValue? })` → `boolean`, SSR-safe.
+- `useOutsideClick(refs, callback, shouldIgnore?)` — one ref or an array.
+- `useInfiniteScroll({ onLoadMore, hasMore, disabled, offset, root })` → refs for the scroll container and the sentinel.
+- `useFloatingPosition(...)` — low-level anchored positioning used by `Popover`.
+
+## Icons
+
+260+ icons plus country flags, all named exports of `alif-ui`:
+
+- `Outline*` / `Solid*` prefix, then the category: `System` (~190, both styles), `Navigation` (~34, both styles), `Finance` (~36, outline only) — e.g. `OutlineSystemSearch`, `SolidSystemSettings`, `OutlineNavigationChevronDown`, `OutlineFinanceAccounts`.
+- Brand marks: `AlifLogo`, `AlifIcon`, `AlifBusinessLogo`.
+- Flags: `TjFlag`, `AeFlag`, `CnFlag`, … (`<Cc>Flag`).
+
+They accept `SVGProps<SVGSVGElement>` (`width`, `height`, `fill`, `className`) and inherit `currentColor` by default, so they take the color of the surrounding component. To discover an exact name, grep the installed package: `node_modules/alif-ui/dist/main.d.ts`.