# svar-react - full bundle

_Generated 2026-05-08T11:33:57.410Z_

## Contents

- [`SKILL.md`](#file-skill-md)
- [`locales.md`](#file-locales-md)
- [`themes.md`](#file-themes-md)
- [`core/index.md`](#file-core-index-md)
- [`core/avatar.md`](#file-core-avatar-md)
- [`core/button.md`](#file-core-button-md)
- [`core/calendar.md`](#file-core-calendar-md)
- [`core/checkbox.md`](#file-core-checkbox-md)
- [`core/colorboard.md`](#file-core-colorboard-md)
- [`core/colorpicker.md`](#file-core-colorpicker-md)
- [`core/colorselect.md`](#file-core-colorselect-md)
- [`core/combo.md`](#file-core-combo-md)
- [`core/counter.md`](#file-core-counter-md)
- [`core/datepicker.md`](#file-core-datepicker-md)
- [`core/daterangepicker.md`](#file-core-daterangepicker-md)
- [`core/dropdown.md`](#file-core-dropdown-md)
- [`core/field.md`](#file-core-field-md)
- [`core/fullscreen.md`](#file-core-fullscreen-md)
- [`core/globals.md`](#file-core-globals-md)
- [`core/icon.md`](#file-core-icon-md)
- [`core/locale.md`](#file-core-locale-md)
- [`core/modal.md`](#file-core-modal-md)
- [`core/modalarea.md`](#file-core-modalarea-md)
- [`core/month.md`](#file-core-month-md)
- [`core/multicombo.md`](#file-core-multicombo-md)
- [`core/pager.md`](#file-core-pager-md)
- [`core/popup.md`](#file-core-popup-md)
- [`core/portal.md`](#file-core-portal-md)
- [`core/radio.md`](#file-core-radio-md)
- [`core/rangecalendar.md`](#file-core-rangecalendar-md)
- [`core/richselect.md`](#file-core-richselect-md)
- [`core/segmented.md`](#file-core-segmented-md)
- [`core/select.md`](#file-core-select-md)
- [`core/sidearea.md`](#file-core-sidearea-md)
- [`core/slider.md`](#file-core-slider-md)
- [`core/suggest-dropdown.md`](#file-core-suggest-dropdown-md)
- [`core/switch.md`](#file-core-switch-md)
- [`core/tabs.md`](#file-core-tabs-md)
- [`core/text.md`](#file-core-text-md)
- [`core/textarea.md`](#file-core-textarea-md)
- [`core/themes.md`](#file-core-themes-md)
- [`core/timepicker.md`](#file-core-timepicker-md)
- [`core/twostate.md`](#file-core-twostate-md)
- [`menu/index.md`](#file-menu-index-md)
- [`toolbar/index.md`](#file-toolbar-index-md)
- [`layout/index.md`](#file-layout-index-md)
- [`grid/index.md`](#file-grid-index-md)
- [`editor/index.md`](#file-editor-index-md)
- [`filter/index.md`](#file-filter-index-md)
- [`filter/FilterBar.md`](#file-filter-filterbar-md)
- [`filter/FilterBuilder.md`](#file-filter-filterbuilder-md)
- [`filter/FilterEditor.md`](#file-filter-filtereditor-md)
- [`filter/FilterQuery.md`](#file-filter-filterquery-md)
- [`gantt/index.md`](#file-gantt-index-md)
- [`tasklist/index.md`](#file-tasklist-index-md)
- [`comments/index.md`](#file-comments-index-md)
- [`filemanager/index.md`](#file-filemanager-index-md)


## File: SKILL.md

> Source: `SKILL.md`

SVAR React ships as a family of `@svar-ui/react-*` packages. This file routes to the per-package entry; each child file is standalone and contains the imports, public types, styling hooks, and recipes for its components.

Open the matching file for the package you are using. If the component you need is not listed in the routing table below, default to `core/index.md`

#### Component Routing

| File | Package | Components |
| ---------------------- | ------------------------ | ------------------------------------------------------------------------------------------- |
| `core/index.md` | `@svar-ui/react-core` | buttons, inputs, selectors, calendars, dropdowns, popups, modals, themes, locale (40+ widgets) |
| `menu/index.md` | `@svar-ui/react-menu` | `Menu`, `MenuBar`, `DropDownMenu`, `ContextMenu`, `ActionMenu` |
| `toolbar/index.md` | `@svar-ui/react-toolbar` | `Toolbar` |
| `layout/index.md` | `@svar-ui/react-layout` | `Layout`, `Cell`, `Panel` |
| `grid/index.md` | `@svar-ui/react-grid` | `Grid`, `HeaderMenu`, `Tooltip`, `ContextMenu`, `Toolbar` |
| `editor/index.md` | `@svar-ui/react-editor` | `Editor` |
| `filter/index.md` | `@svar-ui/react-filter` | `FilterBuilder`, `FilterEditor`, `FilterBar`, `FilterQuery` |
| `gantt/index.md` | `@svar-ui/react-gantt` | `Gantt`, `Toolbar`, `ContextMenu`, `Editor`, `Tooltip`, `HeaderMenu` |
| `tasklist/index.md` | `@svar-ui/react-tasklist` | `Tasklist` |
| `comments/index.md` | `@svar-ui/react-comments` | `Comments` |
| `filemanager/index.md` | `@svar-ui/react-filemanager` | `Filemanager` |

#### Common Techniques

These apply to every `@svar-ui/react-*` package:

- `themes.md` - theme wrappers, CSS variables, the `css` prop convention, class hooks
- `locales.md` - locale context, bundled language packs, extending words and formats

The widget hierarchy need to be wrapped in a theme component to ensure proper styling
Some widgets (grid,gantt,filemanager, etc) exports their own theme components that delegate to core theme and add their own variables


## File: locales.md

> Source: `locales.md`

i18n patterns common to all SVAR React components - Locale wrapper, bundled language packs, extending words and formats

### Localizing SVAR React Components

All `@svar-ui/react-*` widgets read locale data from a single React context (`wx-i18n`). The mechanics live in `@svar-ui/react-core`; every other package consumes them.

#### Locale Wrapper

Wrap the subtree you want to localize. With no wrapper, widgets fall back to English.

```jsx
import { Calendar, Locale } from "@svar-ui/react-core";
import { de } from "@svar-ui/core-locales";

function App() {
    return (
        <Locale words={de}>
            <Calendar value={new Date(2025, 4, 1)} />
        </Locale>
    );
}
```

Wrap the smallest subtree that needs the alternative locale - nested `Locale` blocks let different parts of the app render in different languages.

`Locale` does not render any DOM wrapper; it only mutates context, so it never affects layout.

#### Bundled Language Packs

Core packs ship in `@svar-ui/core-locales`:

```js
import { en, cn, de, es, fr, it, ja, pt, ru } from "@svar-ui/core-locales";
```

Standalone widget packages ship their own dictionaries alongside the core pack - each exports locale objects keyed by language code (`cn`, `de`, `fr`, ...):

- `@svar-ui/core-locales` - core widgets (always include)
- `@svar-ui/editor-locales` - Editor
- `@svar-ui/filter-locales` - Filter
- `@svar-ui/gantt-locales` - Gantt
- `@svar-ui/filemanager-locales` - File Manager
- `@svar-ui/grid-locales` - Grid

If you see English fallbacks in a localized UI, the missing terms come from the package's own locale module - merge them in via `Locale words={...}`.

To localize a standalone widget, merge the matching package locale with the core locale:

```jsx
import { Gantt } from "@svar-ui/react-gantt";
import { Locale } from "@svar-ui/react-core";
import { cn } from "@svar-ui/gantt-locales";
import { cn as cnCore } from "@svar-ui/core-locales";

function App() {
    return (
        <Locale words={{ ...cn, ...cnCore }}>
            <Gantt {...settings} />
        </Locale>
    );
}
```

#### Extending Or Overriding Words

`Locale words` accepts a partial pack and extends the current context. Spread an existing pack to keep its formats and override only what you need:

```jsx
import { Calendar, Locale } from "@svar-ui/react-core";
import { cn } from "@svar-ui/core-locales";

function App() {
    const words = {
        ...cn,
        formats: {
            ...cn.formats,
            monthYearFormat: "%Y年%F",
            yearFormat: "%Y年",
        },
    };

    return (
        <Locale words={words}>
            <Calendar value={new Date(2025, 4, 1)} />
        </Locale>
    );
}
```

Pass `optional={true}` to make merged terms additive fallbacks rather than overrides - useful for layering app-specific strings on top of a full pack.

#### Affected Surfaces

Locale changes calendar labels, date/time formats, modal buttons, pager strings, empty-list text, notice/modal helpers, color-board select text - any widget that displays static strings or formats values reads them through this context.

#### Direct Helper

For non-component code, use the `locale` helper to build a translator:

```js
import { en, locale } from "@svar-ui/react-core";

const i18n = locale(en).extend(
    { core: { "Rows per page": "Rows" } },
    true
);
const _ = i18n.getGroup("core");
_("Rows per page"); // "Rows"
```


## File: themes.md

> Source: `themes.md`

### Styling SVAR React Components

All `@svar-ui/react-*` widgets share the same theming pipeline. The mechanics live in `@svar-ui/react-core`; every other package consumes them.

#### Per widget css files

Each package ships `style.css` (this component only) and `all.css` (this component plus all dependencies).

```css
@import "@svar-ui/react-gantt/style.css";
```

#### Theme Wrapper

Wrap the part of the app that uses SVAR widgets in a theme component from `@svar-ui/react-core`:

```jsx
import { Willow } from "@svar-ui/react-core";

function Root() {
    return (
        <Willow>
            <App />
        </Willow>
    );
}
```

Available themes: `Willow`, `WillowDark`. The wrapper:

- sets the React context `wx-theme`
- renders `.wx-theme.wx-{name}-theme` with `height:100%`
- loads Open Sans + the `wxi` icon CSS by default; pass `fonts={false}` to skip when the host app manages fonts itself

Without a theme wrapper widgets still render but lose theme variables and font/icon CSS.

#### Per-widget Willow / WillowDark themes

Several widgets ship their **own** `Willow` / `WillowDark` components on top of the core base. The widget version wraps the core theme and layers in widget-specific CSS variables (bar colors, grid borders, timescale fonts, etc.). When using such a widget, import the theme from the widget package - not from core - so both layers apply.

Widgets that expose custom `Willow` / `WillowDark` themes:

- `@svar-ui/react-core` - base
- `@svar-ui/react-gantt`
- `@svar-ui/react-grid`
- `@svar-ui/react-editor`
- `@svar-ui/react-filter`
- `@svar-ui/react-filemanager`
- `@svar-ui/react-comments`
- `@svar-ui/react-kanban`

The widget theme delegates to core and adds extra rules scoped to `.wx-willow-theme` (or `.wx-willow-dark-theme`):

```jsx
import "./WidgetTheme.css";
import { Willow } from "@svar-ui/react-core";

function WidgetTheme({ fonts = true, children }) {
    return children
        ? <Willow fonts={fonts}>{children}</Willow>
        : <Willow fonts={fonts} />;
}

/* WidgetTheme.css
.wx-willow-theme {
    --wx-gantt-border-color: #e6e6e6;
    --wx-gantt-task-color: #3983eb;
    /* ...widget-specific overrides... *\/
}
*/
```

Mount the widget's own theme once at the app root. The wrapper internally renders the core `Willow`, so a separate core import is not needed:

```jsx
import { Willow, Gantt } from "@svar-ui/react-gantt";

function App() {
    return (
        <>
            <Willow />
            <Gantt {...settings} />
        </>
    );
}
```

#### CSS Variables

Theme styling is variable-driven. Override variables on the theme wrapper or on any ancestor of the widgets you want to restyle - overrides cascade to every SVAR widget in the subtree.

```jsx
import "./Brand.css";

<Willow>
    <div className="brand">
        <App />
    </div>
</Willow>

/* Brand.css
.brand {
    --wx-color-primary: #0f766e;
    --wx-input-width: 280px;
    --wx-button-border-radius: 4px;
    --wx-calendar-cell-size: 30px;
}
*/
```

Nest different wrapper blocks for per-section restyling without forking the theme.

#### `css` Prop Convention

Most widgets accept a `css` prop. The string is appended to the widget's root class, so it works as a parent styling hook:

```jsx
<Toolbar css="my-toolbar" items={items} />

/* CSS
.my-toolbar {
    padding: 8px 12px;
}
*/
```

Composite widgets often expose secondary css props for nested popups (`menuCss` on `Toolbar`/`MenuBar`, etc.). Check the per-component file for the exact set.

#### Class Hooks

The per-component file lists the exact selectors that widget exposes.

#### Custom CSS class overrides

When writing custom rules to override widget styles, always use **at least two selectors** (e.g. `.a .b {}`). Component styles in the bundled SVAR widgets carry higher specificity than a plain `.b`. A two-selector rule (`.a .b`) matches or beats that specificity and wins.

Convention: the first selector is a container/wrapper of the widget instance, the second is the inner class you want to alter:

```css
.my-gantt-host .wx-bar-task {
    background: #ff8800;
}
```

#### Override Order

Prefer in this order:

1. **CSS variables on a wrapper** - propagates consistently to every widget in the subtree.
2. **`css` prop class** - a stable parent hook that survives internal markup changes.
3. **Direct `.wx-*` selectors** - targeted overrides; tightest coupling to widget internals, use sparingly.

#### Core Vars

##### Base Colors

| Variable | Default | Use for |
|---|---|---|
| `--wx-color-primary` | `#37a9ef` | Primary accent - active states, selected items, links |
| `--wx-color-primary-selected` | `#d5eaf7` | Selected/highlighted row or item background |
| `--wx-color-primary-font` | `#fff` | Text on primary-colored backgrounds |
| `--wx-color-secondary` | `transparent` | Secondary/ghost element background |
| `--wx-color-secondary-hover` | `rgba(55, 169, 239, 0.12)` | Secondary hover background |
| `--wx-color-secondary-font` | `#37a9ef` | Secondary element text |
| `--wx-color-secondary-border` | `#37a9ef` | Secondary element border |
| `--wx-color-success` | `#77d257` | Success indicator |
| `--wx-color-warning` | `#fcba2e` | Warning indicator |
| `--wx-color-info` | `#37a9ef` | Info indicator |
| `--wx-color-danger` | `#fe6158` | Error/destructive state, error borders |
| `--wx-color-disabled` | `#f2f3f7` | Disabled element background |
| `--wx-color-disabled-alt` | `#e9e9e9` | Alternate disabled background |
| `--wx-color-font` | `#2c2f3c` | Primary text |
| `--wx-color-font-alt` | `#9fa1ae` | Secondary/muted text, placeholders |
| `--wx-color-font-disabled` | `#c0c3ce` | Disabled text |
| `--wx-color-link` | `#37a9ef` | Link text |
| `--wx-background` | `#ffffff` | Main surface |
| `--wx-background-alt` | `#f2f3f7` | Alternate surface (cards, tags, odd/even areas) |
| `--wx-background-hover` | `#eaedf5` | Hover state background |

##### Typography

| Variable | Default | Use for |
|---|---|---|
| `--wx-font-family` | `"Open Sans", Arial, Helvetica, sans-serif` | All text |
| `--wx-font-size` | `14px` | Body text |
| `--wx-line-height` | `20px` | Body line height |
| `--wx-font-size-md` | `14px` | Medium text |
| `--wx-line-height-md` | `24px` | Medium line height |
| `--wx-font-size-hd` | `16px` | Headings |
| `--wx-line-height-hd` | `30px` | Heading line height |
| `--wx-font-size-sm` | `12px` | Captions, small text |
| `--wx-line-height-sm` | `16px` | Small line height |
| `--wx-font-weight` | `400` | Normal weight |
| `--wx-font-weight-md` | `600` | Semi-bold (labels, buttons) |
| `--wx-font-weight-b` | `700` | Bold (modal headers) |

##### Icons

| Variable | Default | Use for |
|---|---|---|
| `--wx-icon-color` | `#9fa1ae` | Default icon tint |
| `--wx-icon-size` | `20px` | Icon dimensions |
| `--wx-icon-border-radius` | `2px` | Icon hover-state rounding |

##### Borders, Shadows, Spacing

| Variable | Default | Use for |
|---|---|---|
| `--wx-border` | `1px solid #e6e6e6` | Standard border |
| `--wx-border-radius` | `3px` | Default corner radius |
| `--wx-radius-major` | `6px` | Larger radius (cards, panels) |
| `--wx-border-light` | `none` | Subtle divider |
| `--wx-border-medium` | `1px solid #eaedf5` | Medium divider |
| `--wx-shadow-light` | `0px 3px 10px ...` | Elevated panels (popups, dropdowns) |
| `--wx-shadow-medium` | `0px 4px 20px ...` | High-elevation surfaces (modals) |
| `--wx-padding` | `8px` | Base spacing unit |

##### Layout

| Variable | Default | Use for |
|---|---|---|
| `--wx-field-gutter` | `16px` | Vertical gap between form rows |
| `--wx-field-width` | `400px` | Max width of a form field row |

##### Z-index Scale

| Layer | Value |
|---|---|
| Popups / dropdowns | `100` |
| Modals | `1000` |
| Notices / toasts | `1010` |


## File: core/index.md

> Source: `core/index.md`

Use when building, configuring, styling, or modifying SVAR React Core / @svar-ui/react-core widgets, themes, locale, forms, popups, selectors, calendars, buttons, and display components

This is an index file. Open the focused widget file that matches the component you are using. Each child file is standalone and contain all critical info needed for that widget.

#### Package

```js
import {
	TextArea,
	Button,
	Checkbox,
	CheckboxGroup,
	ColorSelect,
	ColorBoard,
	ColorPicker,
	Combo,
	DatePicker,
	DateRangePicker,
	Fullscreen,
	Avatar,
	Icon,
	MultiCombo,
	Popup,
	Dropdown,
	Pager,
	RadioButton,
	RadioButtonGroup,
	RichSelect,
	Segmented,
	Select,
	Slider,
	Switch,
	Tabs,
	Text,
	Counter,
	Globals,
	Field,
	Calendar,
	Month,
	RangeCalendar,
	TimePicker,
	TwoState,
	Modal,
	ModalArea,
	SideArea,
	Portal,
	Willow,
	WillowDark,
	Locale,
	locale,
	popupContainer,
	SuggestDropdown,
	en,
} from "@svar-ui/react-core";
import "@svar-ui/react-menu/all.css";
```

#### Widget Index

- `button.md` - `Button`
- `twostate.md` - `TwoState`
- `icon.md` - `Icon`
- `checkbox.md` - `Checkbox`, `CheckboxGroup`
- `radio.md` - `RadioButton`, `RadioButtonGroup`
- `switch.md` - `Switch`
- `segmented.md` - `Segmented`
- `tabs.md` - `Tabs`
- `field.md` - `Field`
- `text.md` - `Text`
- `textarea.md` - `TextArea`
- `counter.md` - `Counter`
- `slider.md` - `Slider`
- `select.md` - `Select`
- `combo.md` - `Combo`
- `multicombo.md` - `MultiCombo`
- `richselect.md` - `RichSelect`
- `suggest-dropdown.md` - `SuggestDropdown`
- `dropdown.md` - `Dropdown`
- `popup.md` - `Popup`
- `portal.md` - `Portal`, `popupContainer`
- `colorselect.md` - `ColorSelect`
- `colorboard.md` - `ColorBoard`
- `colorpicker.md` - `ColorPicker`
- `calendar.md` - `Calendar`
- `month.md` - `Month`
- `rangecalendar.md` - `RangeCalendar`
- `datepicker.md` - `DatePicker`
- `daterangepicker.md` - `DateRangePicker`
- `timepicker.md` - `TimePicker`
- `avatar.md` - `Avatar`
- `pager.md` - `Pager`
- `fullscreen.md` - `Fullscreen`
- `modal.md` - `Modal`
- `modalarea.md` - `ModalArea`
- `sidearea.md` - `SideArea`
- `globals.md` - `Globals`, `showNotice`, `showModal`
- `themes.md` - `Willow`, `WillowDark`, theme CSS variables
- `locale.md` - `Locale`, `locale`, `en`, bundled locale imports

#### Shared Contracts

- Most controls expose a controlled `value` prop and an `onChange` callback. Event payloads differ by widget and are documented in each file.
- Option-based widgets generally use `{ id, label }` options and emit selected ids as values.
- Dropdown-backed widgets share `DropdownOptions` for position, align, width, inline mode, scroll tracking, and virtualization.


## File: core/avatar.md

> Source: `core/avatar.md`

### SVAR React Core Avatar

Package: `@svar-ui/react-core`

#### Package

```js
import { Avatar } from "@svar-ui/react-core";
```

#### Supported Functionality

- Displays one user or a stack of users.
- User object fields are `id`, `name`, `avatar`, and `color`.
- `size` controls circle size and computed font size; default is `32`.
- `limit` caps visible users before responsive fitting is applied.
- When users are hidden, the last visible avatar shows a `+N` overlay.
- If `avatar` is present, it renders an image; otherwise initials are derived from `name`.

#### Public Types

```ts
import type { ComponentType } from "react";

export interface IUser {
	id: string | number;
	name?: string;
	avatar?: string;
	color?: string;
}

export declare const Avatar: ComponentType<{
	value: IUser | IUser[];
	size?: number;
	limit?: number;
}>;
```

#### Styling

- Root: `.wx-avatar-root`
- Stack: `.wx-avatar-stack`
- Avatar item: `.wx-avatar`, `.wx-avatar-item`
- Overflow state and badge: `.wx-avatar-overflow`, `.wx-avatar-overflow-badge`
- Image selector: `.wx-avatar img`
- Initial text selector: `.wx-avatar span`

```jsx
<div className="people">
	<Avatar value={users} size={36} limit={5} />
</div>
```

```css
.people {
	width: 180px;
}

.people .wx-avatar {
	border: 2px solid var(--wx-background);
}
```

#### Recipes

##### User Stack With Responsive Overflow

```jsx
import { Avatar } from "@svar-ui/react-core";

const users = [
	{ id: 1, name: "Jane Smith", avatar: "/avatars/jane.png" },
	{ id: 2, name: "Lee Park", color: "#2ecc71" },
	{ id: 3, name: "Ana Stone", color: "#e74c3c" },
	{ id: 4, name: "Kai Wong", color: "#37a9ef" },
];

function Demo() {
	return (
		<div style={{ width: 160 }}>
			<Avatar value={users} size={32} limit={4} />
		</div>
	);
}
```

##### Single Initial Avatar

```jsx
import { Avatar } from "@svar-ui/react-core";

function Demo() {
	return (
		<Avatar value={{ id: 1, name: "Jane Smith", color: "#2f77e3" }} size={40} />
	);
}
```


## File: core/button.md

> Source: `core/button.md`

### SVAR React Core Button

Package: `@svar-ui/react-core`

#### Package

```js
import { Button } from "@svar-ui/react-core";
```

#### Supported Functionality

- Renders a native `<button class="wx-button">`.
- `type` is split on spaces and each part becomes a `wx-*` class.
- Typed values are `primary`, `secondary`, `danger`, `link`, and each with `block`.
- `css` is appended to the button class list.
- `icon` renders an `<i class={icon}>` before content.
- When `icon` is set and no `children` are supplied, the button also gets `.wx-icon` icon-only styling.
- Renders `children` when provided; otherwise renders `text`.
- `onClick` receives the native `MouseEvent`.

#### Public Types

```ts
import type { ComponentType, ReactNode, MouseEvent } from "react";

export declare const Button: ComponentType<{
	type?:
		| "primary"
		| "secondary"
		| "danger"
		| "link"
		| "primary block"
		| "secondary block"
		| "danger block"
		| "link block";
	css?: string;
	icon?: string;
	disabled?: boolean;
	title?: string;
	text?: string;
	children?: ReactNode;
	onClick?: (ev: MouseEvent) => void;
}>;
```

#### Styling

- Button class: `.wx-button`
- Type/state classes: `.wx-primary`, `.wx-secondary`, `.wx-danger`, `.wx-link`, `.wx-block`, `.wx-pressed`, `.wx-icon`
- Disabled styling uses the native `[disabled]` attribute.
- Icon child selector is `i`.

```jsx
<Button css="save-button" type="primary" icon="wxi-check">Save</Button>
```

```css
:.wx-button.save-button {
	min-width: 120px;
}
```

#### Recipes

##### Variants And Click Handler

```jsx
import { Button } from "@svar-ui/react-core";

function Demo() {
	function save(ev) {
		console.log(ev.currentTarget);
	}

	return (
		<>
			<Button type="primary" icon="wxi-check" onClick={save}>Save</Button>
			<Button type="secondary block">Full Width</Button>
			<Button type="danger" disabled>Delete</Button>
			<Button type="link">Details</Button>
		</>
	);
}
```

##### Icon-Only Button

```jsx
import { Button } from "@svar-ui/react-core";

function Demo() {
	return (
		<Button
			icon="wxi-search"
			title="Search"
			onClick={() => console.log("search")}
		/>
	);
}
```

#### Implementation Notes

- Source has `.wx-square` styles, but `square` is not in the public `type` union.
- `Button` does not call `preventDefault` or stop propagation; handler receives the raw event.


## File: core/calendar.md

> Source: `core/calendar.md`

### SVAR React Core Calendar

Package: `@svar-ui/react-core`

#### Package

```js
import { Calendar } from "@svar-ui/react-core";
```

#### Supported Functionality

- Full single-date calendar with header navigation and optional action buttons.
- `value` is controlled and is a `Date` or `null`.
- `current` is controlled and controls the visible month; source normalizes it to the first day of that month.
- `buttons` defaults to `["clear", "today"]`; pass `false` to hide buttons or `true` for the default set.
- `markers(date)` can return a CSS class string appended to the matching `.wx-day`.
- `onChange` receives `{ value: Date | null }`.
- Internally wraps the calendar panel in `Locale`, so it can work without an outer locale provider.

#### Public Types

```ts
import type { ComponentType } from "react";

export declare const Calendar: ComponentType<{
	value?: Date;
	current?: Date;
	markers?: (date: Date) => string;
	buttons?: boolean | ("clear" | "today")[];
	onChange?: (ev: { value: Date | null }) => void;
}>;
```

#### Styling

- Calendar wrapper: `.wx-calendar`
- Layout: `.wx-wrap`, `.wx-buttons`, `.wx-button-item`
- Header: `.wx-header`, `.wx-pager`, `.wx-spacer`, `.wx-label`
- Month grid comes from `Month`: `.wx-weekdays`, `.wx-weekday`, `.wx-days`, `.wx-day`, `.wx-out`, `.wx-selected`, `.wx-weekend`, `.wx-inactive`
- Year/month pickers: `.wx-months`, `.wx-month`, `.wx-years`, `.wx-year`, `.wx-current`, `.wx-prev-decade`, `.wx-next-decade`

```jsx
<div className="compact-calendar">
	<Calendar value={new Date(2025, 4, 1)} />
</div>
```

```css
.compact-calendar {
	--wx-calendar-cell-size: 28px;
	--wx-calendar-padding: 8px;
}

.compact-calendar .holiday {
	outline: 1px solid var(--wx-color-warning);
}
```

#### Recipes

##### Mark Dates And Keep Visible Month Bound

```jsx
import { useState } from "react";
import { Calendar } from "@svar-ui/react-core";

function Demo() {
	const [value, setValue] = useState(new Date(2025, 4, 1));
	const [current, setCurrent] = useState(new Date(2025, 4, 1));

	function markers(date) {
		return date.getDay() === 0 ? "holiday" : "";
	}

	return (
		<Calendar
			value={value}
			current={current}
			markers={markers}
			buttons={["today"]}
			onChange={ev => {
				setValue(ev.value);
				console.log(ev.value);
			}}
		/>
	);
}
```

##### Hide Action Buttons

```jsx
import { Calendar } from "@svar-ui/react-core";

function Demo() {
	return (
		<Calendar buttons={false} onChange={ev => console.log(ev.value)} />
	);
}
```

#### Implementation Notes

- Selecting a date clones it with `new Date(...)` before assigning `value`.
- Clearing sets `value` to `null`.
- Source calls `onChange` after updating the value.


## File: core/checkbox.md

> Source: `core/checkbox.md`

### SVAR React Core Checkbox

Package: `@svar-ui/react-core`

Use this file standalone for `Checkbox` and `CheckboxGroup`.

#### Package

```js
import { Checkbox, CheckboxGroup } from "@svar-ui/react-core";
```

#### Supported Functionality

- `Checkbox.value` is a controlled boolean.
- `Checkbox.inputValue` is emitted alongside the checked state; default is an empty string.
- `Checkbox.onChange` emits `{ value, inputValue }`.
- `CheckboxGroup.options` are `{ id, label }`.
- `CheckboxGroup.value` is a controlled array of selected option ids.
- Group `onChange` emits `{ value }`.
- Group `type` supports `inline` and `grid`; default layout is one item per row.

#### Public Types

```ts
import type { ComponentType } from "react";

export declare const Checkbox: ComponentType<{
	id?: string | number;
	label?: string;
	inputValue?: string | number;
	value?: boolean;
	style?: string;
	disabled?: boolean;
	onChange?: (ev: { value: boolean; inputValue: string | number }) => void;
}>;

export declare const CheckboxGroup: ComponentType<{
	options?: { id: string | number; label: string }[];
	value?: (string | number)[];
	type?: "inline" | "grid";
	onChange?: (ev: { value: (string | number)[] }) => void;
}>;
```

#### Styling

- Checkbox wrapper: `.wx-checkbox`
- `style` prop is applied to the checkbox wrapper.
- Group wrapper: `.wx-checkboxgroup`, `.wx-checkboxgroup.wx-inline`, `.wx-checkboxgroup.wx-grid`
- Group item wrapper: `.wx-item`

```jsx
<div className="todo-checks">
	<CheckboxGroup options={options} value={value} onChange={ev => setValue(ev.value)} />
</div>
```

```css
.todo-checks .wx-checkboxgroup .wx-item {
	margin-top: 8px;
}
```

#### Recipes

##### Single Checkbox

```jsx
import { useState } from "react";
import { Checkbox } from "@svar-ui/react-core";

function Demo() {
	const [done, setDone] = useState(false);

	return (
		<Checkbox
			label="Done"
			inputValue="done"
			value={done}
			onChange={ev => {
				setDone(ev.value);
				console.log(ev.value, ev.inputValue);
			}}
		/>
	);
}
```

##### Checkbox Group

```jsx
import { useState } from "react";
import { CheckboxGroup } from "@svar-ui/react-core";

const options = [
	{ id: "new", label: "New" },
	{ id: "open", label: "Open" },
	{ id: "done", label: "Done" },
];

function Demo() {
	const [selected, setSelected] = useState(["new"]);

	return (
		<CheckboxGroup
			options={options}
			value={selected}
			onChange={ev => setSelected(ev.value)}
			type="inline"
		/>
	);
}
```

#### Implementation Notes

- `CheckboxGroup` does not pass disabled state through option objects.


## File: core/colorboard.md

> Source: `core/colorboard.md`

### SVAR React Core ColorBoard

Package: `@svar-ui/react-core`

#### Package

```js
import { ColorBoard } from "@svar-ui/react-core";
```

#### Supported Functionality

- HSV color board with hue line, saturation/value block, text input, preview, and optional select button.
- `value` is controlled and defaults to `"#65D3B3"`.
- Valid typed hex is normalized to uppercase `#RRGGBB`; 3-digit hex is expanded.
- Moving sliders or typing a valid color emits `{ value, input: true }`.
- With `button={true}`, clicking the select button emits a final `{ value }`.
- Keyboard arrow keys move the focused block/line slider.

#### Public Types

```ts
import type { ComponentType } from "react";

export declare const ColorBoard: ComponentType<{
	value?: string;
	button?: boolean;
	onChange?: (ev: { value: string; input?: boolean }) => void;
}>;
```

#### Styling

- Wrapper: `.wx-colorboard`
- Saturation/value block: `.wx-color-block`
- Block slider: `.wx-color-block-slider.wx-slider`
- Hue line: `.wx-color-line`
- Hue slider: `.wx-color-line-slider.wx-slider`
- Controls row: `.wx-color-controls`
- Preview: `.wx-color`
- Text input: `.wx-text`

```jsx
<div className="picker-board">
	<ColorBoard value={value} onChange={ev => setValue(ev.value)} />
</div>
```

```css
.picker-board .wx-color-block {
	height: 180px;
}
```

#### Recipes

##### Inline Color Board

```jsx
import { useState } from "react";
import { ColorBoard } from "@svar-ui/react-core";

function Demo() {
	const [value, setValue] = useState("#48C8E2");

	return (
		<div style={{ width: 300 }}>
			<ColorBoard
				value={value}
				onChange={ev => {
					setValue(ev.value);
					if (!ev.input) console.log(ev.value);
				}}
			/>
		</div>
	);
}
```


## File: core/colorpicker.md

> Source: `core/colorpicker.md`

### SVAR React Core ColorPicker

Package: `@svar-ui/react-core`

#### Package

```js
import { ColorPicker } from "@svar-ui/react-core";
```

#### Supported Functionality

- Input-like color picker that opens `ColorBoard` in a `Dropdown`.
- `value` is a controlled color string.
- The inner `ColorBoard` is rendered with `button="true"`.
- `ColorPicker` ignores `ColorBoard` input events and updates only on the final select event.
- Final selection closes the popup and emits `{ value }`.
- `clear` shows a close icon when value is set and not disabled.
- `dropdown` is forwarded to `Dropdown`.

#### Public Types

```ts
import type { ComponentType } from "react";

export interface DropdownOptions {
	inline?: boolean;
	position?: "top" | "right" | "bottom" | "left";
	align?: "start" | "center" | "end";
	css?: string;
	width?: string | "unset" | "auto";
	trackScroll?: boolean;
	virtualized?: boolean;
}

export declare const ColorPicker: ComponentType<{
	value?: string;
	id?: string | number;
	placeholder?: string;
	title?: string;
	disabled?: boolean;
	error?: boolean;
	clear?: boolean;
	dropdown?: DropdownOptions;
	onChange?: (ev: { value: string }) => void;
}>;
```

#### Styling

- Wrapper: `.wx-colorpicker`
- Selected swatch: `.wx-color`
- Clear icon: `.wxi-close`
- Input state classes: `.wx-focus`, `.wx-error`
- Dropdown content uses `ColorBoard` hooks such as `.wx-colorboard`, `.wx-color-block`, `.wx-color-line`.


```jsx
<ColorPicker dropdown={{ css: "color-popup", width: "300px" }} />
```

```css
.wx-popup.color-popup {
	width: 300px;
}
```

#### Recipes

##### Color Picker In A Field

```jsx
import { useState } from "react";
import { ColorPicker, Field } from "@svar-ui/react-core";

function Demo() {
	const [color, setColor] = useState("#65D3B3");

	return (
		<Field label="Color" position="left">
			<ColorPicker
				value={color}
				placeholder="Select a color"
				clear
				onChange={ev => {
					setColor(ev.value);
					console.log(ev.value);
				}}
			/>
		</Field>
	);
}
```

#### Implementation Notes

- `ColorPicker` displays the current `value` as swatch background without validating it.


## File: core/colorselect.md

> Source: `core/colorselect.md`

### SVAR React Core ColorSelect

Package: `@svar-ui/react-core`

#### Package

```js
import { ColorSelect } from "@svar-ui/react-core";
```

#### Supported Functionality

- Input-like color palette selector.
- `value` is a controlled hex color string or empty string.
- Default colors are `#00a037`, `#37a9ef`, `#f5a623`, `#ff4c3b`, `#a0a0a0`, `#000000`, `#ffffff`.
- Clicking the input opens a `Dropdown` unless disabled.
- Palette includes an empty color item that selects `""`.
- `clear` shows a close icon when value is set and not disabled.
- `onChange` emits `{ value }`.

#### Public Types

```ts
import type { ComponentType } from "react";

export declare const ColorSelect: ComponentType<{
	colors?: string[];
	value?: string;
	id?: string | number;
	clear?: boolean;
	placeholder?: string;
	title?: string;
	disabled?: boolean;
	error?: boolean;
	onChange?: (ev: { value: string }) => void;
}>;
```

#### Styling

- Wrapper: `.wx-colorselect`
- Selected swatch: `.wx-selected`
- Dropdown palette: `.wx-colors`
- Swatch: `.wx-color`
- Empty swatch: `.wx-empty`
- Clear icon: `.wx-clear.wxi-close`


```jsx
<ColorSelect colors={colors} value={value} onChange={ev => setValue(ev.value)} clear />
```

```css
.wx-colorselect .wx-color {
	border-radius: 50%;
}
```

#### Recipes

##### Custom Palette

```jsx
import { useState } from "react";
import { ColorSelect, Field } from "@svar-ui/react-core";

function Demo() {
	const [color, setColor] = useState("");

	return (
		<Field label="Color" position="left">
			<ColorSelect
				colors={["#65D3B3", "#FFC975", "#58C3FE"]}
				value={color}
				onChange={ev => setColor(ev.value)}
				placeholder="Select a color"
				clear
			/>
		</Field>
	);
}
```


## File: core/combo.md

> Source: `core/combo.md`

### SVAR React Core Combo

Package: `@svar-ui/react-core`

#### Package

```js
import { Combo } from "@svar-ui/react-core";
```

#### Supported Functionality

- Searchable single-select input backed by `SuggestDropdown`.
- `options` are `{ id, label }` by default.
- `textField` controls display/filter field; default is `"label"`.
- `textOptions` can provide selected display objects when visible `options` are filtered or partial.
- Typing filters `options` case-insensitively by `textField`.
- Blur selects exact text match first, then first containing match, then previous value or first option.
- Dropdown selection updates the controlled `value` and emits `{ value }`.
- `children` render function receives `{ option }` for custom list row content.
- `dropdown` is forwarded to `SuggestDropdown`/`Dropdown`.

#### Public Types

```ts
import type { ComponentType, ReactNode } from "react";

export interface DropdownOptions {
	inline?: boolean;
	position?: "top" | "right" | "bottom" | "left";
	align?: "start" | "center" | "end";
	css?: string;
	width?: string | "unset" | "auto";
	trackScroll?: boolean;
	virtualized?: boolean;
}

export declare const Combo: ComponentType<{
	value?: string | number;
	id?: string | number;
	options?: { id: string | number; label: string }[];
	textOptions?: { id: string | number; label: string }[];
	textField?: string;
	placeholder?: string;
	title?: string;
	disabled?: boolean;
	error?: boolean;
	clear?: boolean;
	dropdown?: DropdownOptions & {
		virtualized?: boolean;
	};
	children?: (params: { option: any }) => ReactNode;
	onChange?: (ev: { value: string | number }) => void;
}>;
```

#### Styling

- Wrapper: `.wx-combo`
- Icon: `.wx-icon`, close icon `.wxi-close`
- Error class is applied to the input as `.wx-error`.
- Dropdown list hooks from `SuggestDropdown`: `.wx-list`, `.wx-item`, `.wx-focus`, `.wx-no-data`.
- Non-inline dropdown `css` is appended to `.wx-popup`.


```jsx
<Combo options={users} dropdown={{ css: "users-popup", width: "320px" }} />
```

```css
.wx-popup.users-popup .wx-list {
	max-height: 360px;
}
```

#### Recipes

##### Custom Option Template And Virtualized List

```jsx
import { useState } from "react";
import { Combo } from "@svar-ui/react-core";

const users = Array.from({ length: 10000 }, (_, id) => ({
	id,
	label: `User ${id}`,
	email: `user${id}@example.com`,
}));

function Demo() {
	const [value, setValue] = useState(9000);

	return (
		<Combo
			options={users}
			value={value}
			onChange={ev => setValue(ev.value)}
			dropdown={{ virtualized: true, width: "320px" }}
		>
			{({ option }) => (
				<div className="user-option">
					<strong>{option.label}</strong>
					<span>{option.email}</span>
				</div>
			)}
		</Combo>
	);
}
```

##### Hidden Selected Option

```jsx
import { Combo } from "@svar-ui/react-core";

const allUsers = [
	{ id: 87, label: "Berni Mayou" },
	{ id: 103, label: "Ned Stark" },
];

const visibleUsers = [{ id: 103, label: "Ned Stark" }];

function Demo() {
	return (
		<Combo textOptions={allUsers} options={visibleUsers} value={87} clear />
	);
}
```

#### Implementation Notes

- Filtering assumes `option[textField]` is a string


## File: core/counter.md

> Source: `core/counter.md`

### SVAR React Core Counter

Package: `@svar-ui/react-core`

#### Package

```js
import { Counter } from "@svar-ui/react-core";
```

#### Supported Functionality

- Numeric input with decrement and increment buttons.
- Controlled `value`, default `0`.
- `step` defaults to `1`, `min` defaults to `0`, `max` defaults to `Infinity`.
- Button clicks update `value` and emit `{ value }`.
- Typing emits `{ value, input: true }` without immediately mutating the bound value in the handler payload path.
- Blur normalizes the bound value to min/max and step, then emits `{ value }`.
- `readonly` blocks button changes and blur normalization.
- `disabled` disables the input and both buttons.

#### Public Types

```ts
import type { ComponentType } from "react";

export declare const Counter: ComponentType<{
	id?: string | number;
	value?: number;
	step?: number;
	min?: number;
	max?: number;
	error?: boolean;
	disabled?: boolean;
	readonly?: boolean;
	onChange?: (ev: { value: number; input?: boolean }) => void;
}>;
```

#### Styling

- Wrapper: `.wx-counter`
- State classes: `.wx-disabled`, `.wx-readonly`, `.wx-error`
- Input: `.wx-input`
- Buttons: `.wx-btn`, `.wx-btn-dec`, `.wx-btn-inc`
- SVG icons: `.wx-dec`, `.wx-inc`

```jsx
<Counter value={value} onChange={ev => setValue(ev.value)} min={0} max={30} />
```

```css
.wx-counter .wx-input {
	width: 64px;
}
```

#### Recipes

##### Counter With Final Change Handling

```jsx
import { useState } from "react";
import { Counter, Field } from "@svar-ui/react-core";

function Demo() {
	const [count, setCount] = useState(5);

	return (
		<Field label="Quantity">
			<Counter
				value={count}
				min={0}
				max={30}
				step={3}
				onChange={ev => {
					setCount(ev.value);
					if (!ev.input) console.log(ev.value);
				}}
			/>
		</Field>
	);
}
```


## File: core/datepicker.md

> Source: `core/datepicker.md`

### SVAR React Core DatePicker

Package: `@svar-ui/react-core`

#### Package

```js
import { DatePicker } from "@svar-ui/react-core";
```

#### Supported Functionality

- Input-like single-date picker backed by `Text`, `Dropdown`, and `Calendar`.
- `value` is a controlled prop and is a `Date` or `null`.
- `format` can be a date format string or `(value: Date) => string`; locale date format is used by default.
- `editable={true}` parses committed text with `new Date(text)`.
- `editable={fn}` uses the custom parser and expects `Date | null`.
- `clear` passes through to the inner `Text` clear icon.
- `buttons` is forwarded to `Calendar`; default is `["clear", "today"]`.
- `dropdown` is forwarded to `Dropdown`; date dropdowns default width to `"unset"` when no width is provided.
- Popup closes on window scroll.
- `onChange` receives `{ value: Date | null }` after the value is updated.

#### Public Types

```ts
import type { ComponentType } from "react";

export interface DropdownOptions {
	inline?: boolean;
	position?: "top" | "right" | "bottom" | "left";
	align?: "start" | "center" | "end";
	css?: string;
	width?: string | "unset" | "auto";
	trackScroll?: boolean;
	virtualized?: boolean;
}

export declare const DatePicker: ComponentType<{
	value?: Date;
	id?: string | number;
	disabled?: boolean;
	error?: boolean;
	width?: string;
	align?: "start" | "center" | "end";
	placeholder?: string;
	format?: string | ((value: Date) => string);
	buttons?: boolean | ("clear" | "today")[];
	css?: string;
	title?: string;
	editable?: boolean | ((value: string) => Date | null);
	clear?: boolean;
	dropdown?: DropdownOptions;
	onChange?: (ev: { value: Date | null }) => void;
}>;
```

#### Styling

- Wrapper: `.wx-datepicker`
- `css` is passed to the inner `Text`; use `css="wx-icon-left"` for the left-icon input variant.
- Inner input classes come from `Text`: `.wx-text`, `.wx-input`, `.wx-icon`, `.wx-error`, `.wx-disabled`, `.wx-focus`.
- Popup surface uses `Dropdown`/`Popup` hooks such as `.wx-popup`.
- Calendar hooks come from `Calendar` and `Month`.


```jsx
<DatePicker css="wx-icon-left date-input" dropdown={{ css: "date-popup" }} />
```

```css
.wx-text.date-input {
	--wx-input-width: 220px;
}

.wx-popup.date-popup {
	padding: 4px;
}
```

#### Recipes

##### Bound Date In A Field

```jsx
import { useState } from "react";
import { DatePicker, Field } from "@svar-ui/react-core";

function Example() {
	const [value, setValue] = useState(new Date(2025, 4, 1));

	return (
		<Field label="Date" position="left">
			<DatePicker
				value={value}
				clear
				onChange={ev => {
					setValue(ev.value);
					console.log(ev.value);
				}}
			/>
		</Field>
	);
}
```

##### Editable Date With Custom Parser

```jsx
import { useState } from "react";
import { DatePicker } from "@svar-ui/react-core";

function parseDate(text) {
	const p = text.match(/(..)(..)(.+)/);
	return p ? new Date(p.slice(1, 4).join("/")) : null;
}

function Example() {
	const [value, setValue] = useState(new Date(2025, 4, 1));

	return (
		<DatePicker
			value={value}
			editable={parseDate}
			format="%m%d%Y"
			clear
			dropdown={{ width: "280px", align: "start" }}
			onChange={ev => setValue(ev.value)}
		/>
	);
}
```

#### Implementation Notes

- Public types include `width` and `align`, but source does not use those props directly; use `dropdown={{ width, align }}`.
- Selecting the same date value does not emit `onChange`.


## File: core/daterangepicker.md

> Source: `core/daterangepicker.md`

### SVAR React Core DateRangePicker

Package: `@svar-ui/react-core`

#### Package

```js
import { DateRangePicker } from "@svar-ui/react-core";
```

#### Supported Functionality

- Input-like date range picker backed by `Text`, `Dropdown`, and `RangeCalendar`.
- `value` is a controlled prop and is `{ start: Date; end?: Date }` or `null`.
- `format` can be a date format string or `(date: Date) => string`; locale date format is used by default.
- Display text is `start - end`; missing `end` displays only the start.
- `months` is forwarded to `RangeCalendar` and is `1` or `2`.
- `buttons` is forwarded to `RangeCalendar`; arrays can include `"done"`.
- `editable={true}` parses committed text with `new Date(text)`.
- `editable={fn}` uses the custom parser and expects `Date | null`.
- Editable parsing splits text on `" -"`.
- `clear` passes through to the inner `Text` clear icon.
- `dropdown` is forwarded to `Dropdown`; date dropdowns default width to `"unset"` when no width is provided.
- Popup closes on window scroll.
- `onChange` receives `{ value: { start: Date; end: Date | null } | null }`.

#### Public Types

```ts
import type { ComponentType } from "react";

export interface DropdownOptions {
	inline?: boolean;
	position?: "top" | "right" | "bottom" | "left";
	align?: "start" | "center" | "end";
	css?: string;
	width?: string | "unset" | "auto";
	trackScroll?: boolean;
	virtualized?: boolean;
}

export declare const DateRangePicker: ComponentType<{
	value?: { start: Date; end?: Date };
	id?: string | number;
	disabled?: boolean;
	error?: boolean;
	width?: string;
	align?: "start" | "center" | "end";
	placeholder?: string;
	css?: string;
	title?: string;
	format?: string | ((date: Date) => string);
	months?: 1 | 2;
	buttons?: boolean | ("clear" | "today" | "done")[];
	editable?: boolean | ((value: string) => Date | null);
	clear?: boolean;
	dropdown?: DropdownOptions;
	onChange?: (ev: {
		value: { start: Date; end: Date | null } | null;
	}) => void;
}>;
```

#### Styling

- Wrapper: `.wx-daterangepicker`
- State classes: `.wx-disabled`, `.wx-error`
- `css` is passed to the inner `Text`.
- Inner input classes come from `Text`: `.wx-text`, `.wx-input`, `.wx-icon`.
- Popup surface uses `Dropdown`/`Popup` hooks such as `.wx-popup`.
- Calendar hooks come from `RangeCalendar`, `Calendar`, and `Month`.

```jsx
<DateRangePicker css="range-input" dropdown={{ css: "range-popup" }} />
```

```css
.wx-text.range-input {
	--wx-input-width: 280px;
}
```

#### Recipes

##### Two-Month Range Picker

```jsx
import { useState } from "react";
import { DateRangePicker, Field } from "@svar-ui/react-core";

function Example() {
	const [value, setValue] = useState({
		start: new Date(2025, 4, 1),
		end: new Date(2025, 4, 7),
	});

	return (
		<Field label="Range" position="left">
			<DateRangePicker
				value={value}
				months={2}
				buttons={["done", "clear", "today"]}
				clear
				onChange={ev => {
					setValue(ev.value);
					console.log(ev.value);
				}}
			/>
		</Field>
	);
}
```

##### Editable Range

```jsx
import { useState } from "react";
import { DateRangePicker } from "@svar-ui/react-core";

function Example() {
	const [value, setValue] = useState();

	return (
		<DateRangePicker
			value={value}
			editable
			placeholder="Start - end"
			dropdown={{ width: "unset", align: "start" }}
			onChange={ev => setValue(ev.value)}
		/>
	);
}
```

#### Implementation Notes

- Public types include `width` and `align`, but source does not use those props directly; use `dropdown={{ width, align }}`.
- If the popup closes while only `start` is selected, source emits the pending single-start range.
- With a `"done"` button, `RangeCalendar` holds intermediate selection changes until done is pressed.


## File: core/dropdown.md

> Source: `core/dropdown.md`

### SVAR React Core Dropdown

Package: `@svar-ui/react-core`

#### Package

```js
import { Dropdown } from "@svar-ui/react-core";
```

#### Supported Functionality

- Anchored dropdown surface for arbitrary child content.
- `position` is `top`, `right`, `bottom`, or `left`; default is `bottom`.
- `align` is `start`, `center`, or `end`; default is `start`.
- `width` defaults to `"100%"`.
- Non-inline mode renders a `Portal` containing `Popup` anchored to the trigger's parent node.
- `inline={true}` renders `.wx-dropdown` in place without `Portal`.
- `trackScroll` is passed to `Popup` in non-inline mode.
- `onCancel` is called by click-outside behavior and scroll tracking where enabled.

#### Public Types

```ts
import type { ComponentType, ReactNode } from "react";

export interface DropdownOptions {
	inline?: boolean;
	position?: "top" | "right" | "bottom" | "left";
	align?: "start" | "center" | "end";
	css?: string;
	width?: string | "unset" | "auto";
	trackScroll?: boolean;
	virtualized?: boolean;
}

export declare const Dropdown: ComponentType<
	DropdownOptions & {
		children?: ReactNode;
		onCancel?: (ev: MouseEvent) => void;
	}
>;
```

#### Styling

- Inline dropdown container: `.wx-dropdown`
- Inline position classes: `.wx-top-start`, `.wx-top-center`, `.wx-top-end`, `.wx-bottom-start`, `.wx-bottom-center`, `.wx-bottom-end`, `.wx-left-start`, `.wx-left-center`, `.wx-left-end`, `.wx-right-start`, `.wx-right-center`, `.wx-right-end`
- Non-inline dropdown uses `Popup`; `css` is appended to `.wx-popup`.
- Hidden anchor marker: `.wx-portal-node`


```jsx
<Dropdown css="calendar-popup" width="300px">
	<div>Content</div>
</Dropdown>
```

```css
.wx-popup.calendar-popup {
	padding: 8px;
}
```

#### Recipes

##### Anchored Dropdown

```jsx
import { useState } from "react";
import { Button, Calendar, Dropdown } from "@svar-ui/react-core";

function Example() {
	const [open, setOpen] = useState(false);

	return (
		<>
			<Button onClick={() => setOpen(true)}>Open</Button>
			{open && (
				<Dropdown
					width="300px"
					position="bottom"
					align="start"
					css="calendar-popup"
					onCancel={() => setOpen(false)}
				>
					<Calendar />
				</Dropdown>
			)}
		</>
	);
}
```

##### Inline Dropdown

```jsx
import { Dropdown } from "@svar-ui/react-core";

function Example() {
	return (
		<div style={{ position: "relative" }}>
			<Dropdown inline width="200px" position="bottom" align="end">
				<div style={{ padding: 8 }}>Inline content</div>
			</Dropdown>
		</div>
	);
}
```

#### Implementation Notes

- Source supports `autoFit = true` for inline dropdowns; `DropdownOptions` does not declare `autoFit`.
- `virtualized` is part of `DropdownOptions` for list helpers; `Dropdown` itself does not implement list virtualization.


## File: core/field.md

> Source: `core/field.md`

### SVAR React Core Field

Package: `@svar-ui/react-core`

#### Package

```js
import { Field } from "@svar-ui/react-core";
```

#### Supported Functionality

- Wraps controls with label and control layout.
- Default label position is top; `position="left"` creates a side label layout.
- `width` sets inline width on the `.wx-field` wrapper.
- `error` adds `.wx-error` and colors the label.
- `required` adds `.wx-required` and appends a red `*` to the label.
- `type="checkbox" | "slider" | "switch"` adjusts vertical padding for those controls in left-label layout.
- Sets React context `wx-input-id`; child controls that call `getInputId` share the generated id with the label.

#### Public Types

```ts
import type { ComponentType, ReactNode } from "react";

export declare const Field: ComponentType<{
	label?: string;
	position?: "left";
	width?: string;
	error?: boolean;
	type?: "checkbox" | "slider" | "switch";
	required?: boolean;
	children?: ReactNode;
}>;
```

#### Styling

- Wrapper: `.wx-field`
- Side label modifier: `.wx-left`
- State classes: `.wx-error`, `.wx-required`
- Label: `.wx-label`
- Control wrapper: `.wx-field-control`
- Control type modifiers: `.wx-field-control.wx-checkbox`, `.wx-field-control.wx-slider`, `.wx-field-control.wx-switch`


```jsx
<Field label="Owner" position="left" width="480px">
	{children}
</Field>
```

```css
.wx-field.wx-left > .wx-label {
	width: 140px;
}
```

#### Recipes

##### Labeled Control

```jsx
import { useState } from "react";
import { Field, Text } from "@svar-ui/react-core";

function Example() {
	const [name, setName] = useState("");

	return (
		<Field label="Name" required>
			<Text value={name} onChange={ev => setName(ev.value)} />
		</Field>
	);
}
```

##### Nested Fields

```jsx
import { Field, Text } from "@svar-ui/react-core";

function Example() {
	return (
		<Field label="Name">
			<Field label="First" position="left">
				<Text />
			</Field>
			<Field label="Last" position="left">
				<Text />
			</Field>
		</Field>
	);
}
```


## File: core/fullscreen.md

> Source: `core/fullscreen.md`

### SVAR React Core Fullscreen

Package: `@svar-ui/react-core`

#### Package

```js
import { Fullscreen } from "@svar-ui/react-core";
```

#### Supported Functionality

- Wraps content in a fullscreen-capable container.
- Default toggle button uses `Button` with `css="wx-fullscreen-button"`.
- Default icon switches between `wxi-expand` and `wxi-collapse`.
- Custom `toggleButton` render function receives `(toggleFullscreen, inFullscreen)`.
- `hotkey` configures a scoped hotkey on the fullscreen wrapper through `@svar-ui/lib-dom` hotkeys.
- Tracks native `fullscreenchange` to keep `inFullscreen` in sync.

#### Public Types

```ts
import type { ComponentType, ReactNode } from "react";

export declare const Fullscreen: ComponentType<{
	toggleButton?: (
		toggle: (ev: MouseEvent) => void,
		inFullscreen: boolean
	) => ReactNode;
	children?: ReactNode;
	hotkey?: string;
}>;
```

#### Styling

- Wrapper: `.wx-fullscreen`
- Default button: `.wx-fullscreen-button`
- Default icon: `.wx-fullscreen-icon`
- Fullscreen backdrop selector: `.wx-fullscreen::backdrop`
- Wrapper is `position: relative`, `height: 100%`, `width: 100%`, `tabindex="-1"`.
- Default button is absolutely positioned at bottom right.

```jsx
<Fullscreen>
	<div className="report">Report content</div>
</Fullscreen>
```

```css
.wx-fullscreen .wx-fullscreen-button {
	right: 12px;
	bottom: 12px;
}
```

#### Recipes

##### Custom Toggle Button

```jsx
import { Button, Fullscreen } from "@svar-ui/react-core";

function Example() {
	return (
		<Fullscreen
			hotkey="ctrl+shift+f"
			toggleButton={(toggle, inFullscreen) => (
				<Button onClick={toggle}>
					{inFullscreen ? "Exit fullscreen" : "Enter fullscreen"}
				</Button>
			)}
		>
			<div className="panel">Report content</div>
		</Fullscreen>
	);
}
```

#### Implementation Notes

- `toggleFullscreen` calls `node.requestFullscreen()` and `document.exitFullscreen()`.


## File: core/globals.md

> Source: `core/globals.md`

### SVAR React Core Globals

Package: `@svar-ui/react-core`

#### Package

```js
import { Globals } from "@svar-ui/react-core";
```

#### Supported Functionality

- Renders children and installs React context `context.helpers`.
- `helpers.showNotice(msg)` appends a notice.
- `helpers.showModal(msg)` renders a `Modal` and returns a Promise.
- `showNotice` payload fields used by source include `text`, `type`, `expire`, and optional `id`.
- Notice `type` can be empty or classes such as `info`, `warning`, `success`, and `danger`.
- `showNotice` default expiry is `5100ms`; `expire: -1` keeps the notice until the close icon is clicked.
- `showModal` payload fields used by source include `title`, `message`, and `buttons`.
- Confirm resolves the modal Promise; cancel rejects it.
- `Notice` and `Notices` are source components but are not top-level exports.

#### Public Types

```ts
import type { ComponentType, ReactNode } from "react";

export declare const Globals: ComponentType<{
	children?: ReactNode;
}>;
```

#### Source Helper Shapes

These helper payloads are source behavior, not exported public TypeScript declarations.

```ts
type NoticeMessage = {
	id?: string | number;
	text?: string;
	type?: "" | "info" | "warning" | "success" | "danger" | string;
	expire?: number;
};

type ModalMessage = {
	title?: string;
	message?: any;
	buttons?: boolean | string[];
};
```

#### Styling

- Notice list: `.wx-notices`
- Notice item: `.wx-notice`
- Notice content: `.wx-text`
- Notice close button: `.wx-button`
- Notice type classes: `.wx-info`, `.wx-warning`, `.wx-success`, `.wx-danger`
- Modals rendered by `showModal` use `Modal` classes: `.wx-modal`, `.wx-window`, `.wx-header`, `.wx-buttons`, `.wx-button`

```jsx
<Globals>
	<App />
</Globals>
```

```css
.wx-notices {
	top: 12px;
	right: 12px;
}
```

#### Recipes

##### Install Globals At App Root

```jsx
import { Globals } from "@svar-ui/react-core";
import Actions from "./Actions.jsx";

function App() {
	return (
		<Globals>
			<Actions />
		</Globals>
	);
}
```

##### Use Notice And Modal Helpers In A Child

```jsx
import { useContext } from "react";
import { Button, context } from "@svar-ui/react-core";

function Actions() {
	const { showNotice, showModal } = useContext(context.helpers);

	async function confirmDelete() {
		try {
			await showModal({ title: "Confirm", message: "Delete item?" });
			showNotice({ type: "success", text: "Deleted" });
		} catch {
			showNotice({ type: "info", text: "Canceled" });
		}
	}

	return (
		<>
			<Button type="danger" onClick={confirmDelete}>Delete</Button>
			<Button onClick={() => showNotice({ type: "info", text: "Saved" })}>
				Notice
			</Button>
		</>
	);
}
```

#### Implementation Notes

- `showModal` stores one active modal at a time.


## File: core/icon.md

> Source: `core/icon.md`

### SVAR React Core Icon

Package: `@svar-ui/react-core`

#### Package

```js
import { Icon } from "@svar-ui/react-core";
```

#### Supported Functionality

- Renders `<i className="wx-icon {css}">`.
- Use `css` for icon font classes such as `wxi-search`.
- `title` is forwarded to the `<i>`.
- `onClick` is forwarded to the `<i>`.
- If `children` is provided, it is rendered inside the `<i>` and `role="img"` is added.

#### Public Types

```ts
import type { ComponentType, ReactNode } from "react";

export declare const Icon: ComponentType<{
	css?: string;
	title?: string;
	children?: ReactNode;
	onClick?: (ev: MouseEvent) => void;
}>;
```

#### Styling

- Icon class: `.wx-icon`
- `css` is appended to `.wx-icon`.

```jsx
<Icon css="wxi-search app-icon" title="Search" />
```

```css
.wx-icon.app-icon {
	color: var(--wx-color-primary);
}
```

#### Recipes

##### Clickable Icon

```jsx
import { Icon } from "@svar-ui/react-core";

function Example() {
	return (
		<Icon
			css="wxi-information-outline"
			title="Info"
			onClick={() => console.log("info")}
		/>
	);
}
```

#### Implementation Notes

- The component intentionally uses an `<i>` rather than a button


## File: core/locale.md

> Source: `core/locale.md`

### SVAR React Core Locale

Package: `@svar-ui/react-core`

#### Package

```js
import { Locale, locale, en } from "@svar-ui/react-core";
```

For all bundled language packs, import from `@svar-ui/core-locales`:

```js
import { en, cn, de, es, fr, it, ja, pt, ru } from "@svar-ui/core-locales";
```

#### Supported Functionality

- `Locale` reads React context `context.i18n` (use `useContext(context.i18n)` from `@svar-ui/react-core`).
- If no locale context exists, it creates one from English words.
- If `words` is not `null`, it extends the current locale with `words`.
- `optional` is passed to the locale `extend` call.
- Use `Locale` around the smallest subtree that needs different words or formats.
- Locale affects calendar labels, date/time formats, modal buttons, pager labels, empty-list text, notices/modal helper strings, and color board select text.
- `locale` is re-exported in JS from `@svar-ui/lib-dom`.
- `en` is re-exported in JS from `@svar-ui/core-locales`.

#### Public Types

```ts
import type { FC, ReactNode } from "react";

export declare const Locale: FC<{
	words?: any;
	optional?: boolean;
	children?: ReactNode;
}>;

export type { ILocale, Terms, TPosition } from "@svar-ui/lib-dom";
```

#### Styling

- `Locale` does not render a wrapper element or public classes.
- It only changes locale context for children.
- Styling changes that depend on locale direction or content length must be handled by app CSS or theme variables.

#### Recipes

##### Localize A Calendar Subtree

```jsx
import { Calendar, Locale } from "@svar-ui/react-core";
import { de } from "@svar-ui/core-locales";

function Example() {
	return (
		<Locale words={de}>
			<Calendar value={new Date(2025, 4, 1)} />
		</Locale>
	);
}
```

##### Override Date Formats

```jsx
import { Calendar, Locale } from "@svar-ui/react-core";
import { cn } from "@svar-ui/core-locales";

const words = {
	...cn,
	formats: {
		...cn.formats,
		monthYearFormat: "%Y年%F",
		yearFormat: "%Y年",
	},
};

function Example() {
	return (
		<Locale words={words}>
			<Calendar value={new Date(2025, 4, 1)} />
		</Locale>
	);
}
```

##### Use The Locale Helper Directly

```jsx
import { en, locale } from "@svar-ui/react-core";

function Example() {
	const i18n = locale(en).extend(
		{
			core: {
				"Rows per page": "Rows",
			},
		},
		true
	);
	const _ = i18n.getGroup("core");

	return <span>{_("Rows per page")}</span>;
}
```

##### Read Locale From Context

```jsx
import { useContext } from "react";
import { context } from "@svar-ui/react-core";

function Example() {
	const locale = useContext(context.i18n);
	const _ = locale.getGroup("core");
	return <span>{_("Rows per page")}</span>;
}
```

#### Implementation Notes

- `Locale` renders only `children`; it has no DOM wrapper.

#### Other information

extra details about locales can be obtained from `../locales.md`


## File: core/modal.md

> Source: `core/modal.md`

### SVAR React Core Modal

Package: `@svar-ui/react-core`

#### Package

```js
import { Modal } from "@svar-ui/react-core";
```

#### Supported Functionality

- Fixed-position backdrop and centered window.
- `title` renders the default header unless a `header` render function is supplied.
- `children` renders the modal body.
- `footer` render function replaces the default button row.
- `buttons` defaults to `["cancel", "ok"]`; pass `false` to hide default buttons.
- Button id `"cancel"` calls `onCancel`; every other button id calls `onConfirm`.
- Button labels are localized through locale group `core`.
- Modal focuses itself on mount.
- Enter calls `onConfirm` unless focus is inside a `TEXTAREA` or `BUTTON`; Escape calls `onCancel`.

#### Public Types

```ts
import type { FC, ReactNode } from "react";

export declare const Modal: FC<{
	title?: string;
	buttons?: boolean | string[];
	header?: () => ReactNode;
	footer?: () => ReactNode;
	children?: ReactNode;
	onConfirm?: (ev: { button?: string; event: MouseEvent }) => void;
	onCancel?: (ev: { button?: string; event: MouseEvent }) => void;
}>;
```

#### Styling

- Backdrop: `.wx-modal`
- Window: `.wx-window`
- Header: `.wx-header`
- Button row: `.wx-buttons`
- Button cell: `.wx-button`

```jsx
<Modal title="Confirm">
	<div>Continue?</div>
</Modal>
```

```css
.wx-modal .wx-window {
	--wx-modal-width: 360px;
}
```

#### Recipes

##### Portal Modal With Default Buttons

```jsx
import { useState } from "react";
import { Button, Modal, Portal } from "@svar-ui/react-core";

function Example() {
	const [open, setOpen] = useState(false);

	return (
		<>
			<Button type="primary" onClick={() => setOpen(true)}>Show</Button>

			{open && (
				<Portal>
					<Modal
						title="Confirm"
						onConfirm={() => setOpen(false)}
						onCancel={() => setOpen(false)}
					>
						Continue?
					</Modal>
				</Portal>
			)}
		</>
	);
}
```

##### Custom Header And Footer

```jsx
import { Button, Modal } from "@svar-ui/react-core";

function Example() {
	return (
		<Modal
			buttons={false}
			header={() => <h2>Custom Title</h2>}
			footer={() => <Button type="primary">Apply</Button>}
		>
			<div>Body</div>
		</Modal>
	);
}
```

#### Implementation Notes

- Keyboard Enter/Escape handlers pass a keyboard event, while public types declare `MouseEvent`.
- Button click handlers pass `{ button, event }`.
- Default `"ok"` button is rendered as `type="block primary"`; other default buttons use `type="block secondary"`.


## File: core/modalarea.md

> Source: `core/modalarea.md`

### SVAR React Core ModalArea

Package: `@svar-ui/react-core`

#### Package

```js
import { ModalArea } from "@svar-ui/react-core";
```

#### Supported Functionality

- Local absolute-position modal backdrop and centered window.
- Intended for modal content inside the current layout rather than a viewport-level fixed modal.
- Renders only `children`; it has no built-in header, footer, buttons, or cancel handler.
- Uses a short fade transition.
- Parent layout should provide a positioned containing block when local placement matters.

#### Public Types

```ts
import type { FC, ReactNode } from "react";

export declare const ModalArea: FC<{
	children?: ReactNode;
}>;
```

#### Styling

- Backdrop: `.wx-modal`
- Window: `.wx-window`
- Backdrop is `position: absolute`, fills the containing block, and uses `--wx-modal-backdrop`.
- Window uses modal background, shadow, border, radius, and min width variables.

```jsx
<div className="local-area">
	<ModalArea>
		<div className="inner">Local modal content</div>
	</ModalArea>
</div>
```

```css
.local-area {
	position: relative;
	min-height: 300px;
}
```

#### Recipes

##### Local Modal Overlay

```jsx
import { useState } from "react";
import { Button, ModalArea } from "@svar-ui/react-core";

function Example() {
	const [open, setOpen] = useState(false);

	return (
		<div style={{ position: "relative", minHeight: 300 }}>
			<Button onClick={() => setOpen(true)}>Open local modal</Button>

			{open && (
				<ModalArea>
					<Button onClick={() => setOpen(false)}>Close</Button>
				</ModalArea>
			)}
		</div>
	);
}
```

#### Implementation Notes

- `ModalArea` does not trap focus or handle Escape.
- Use `Modal` when you need built-in title, buttons, confirmation, or cancellation behavior.


## File: core/month.md

> Source: `core/month.md`

### SVAR React Core Month

Package: `@svar-ui/react-core`

#### Package

```js
import { Month } from "@svar-ui/react-core";
```

#### Supported Functionality

- Low-level month grid used by `Calendar` and `RangeCalendar`.
- `current` is the visible month; pass a date inside the month to render.
- `part="normal"` is required for standalone single-date selection with `value={Date}`.
- Range rendering uses `value={{ start, end }}` and `part` values such as `"left"`, `"right"`, or `"both"`.
- `markers(date)` can return a CSS class string appended to `.wx-day`.
- `onChange` receives a `Date` directly, not an object.
- After selecting a date, source calls `onCancel()` if provided.
- Weekday labels and week start come from locale context, falling back to the default locale.

#### Public Types

```ts
import type { FC } from "react";

export declare const Month: FC<{
	value?: { start: Date; end: Date } | Date;
	current?: Date;
	part?: string;
	markers?: (date: Date) => string;
	onCancel?: () => void;
	onChange?: (ev: Date) => void;
}>;
```

#### Styling

- Weekday row: `.wx-weekdays`, `.wx-weekday`
- Day grid: `.wx-days`, `.wx-day`
- Date state classes: `.wx-out`, `.wx-selected`, `.wx-left`, `.wx-right`, `.wx-inrange`, `.wx-weekend`, `.wx-inactive`
- Marker classes from `markers(date)` are appended to `.wx-day`.

```jsx
<Month current={new Date(2025, 4, 1)} part="normal" markers={markers} />
```

```css
.wx-day.payday {
	font-weight: 700;
}
```

#### Recipes

##### Standalone Single-Month Picker

```jsx
import { useState } from "react";
import { Month } from "@svar-ui/react-core";

function Example() {
	const [value, setValue] = useState(new Date(2025, 4, 15));
	const [current, setCurrent] = useState(new Date(2025, 4, 1));

	return (
		<Month
			value={value}
			current={current}
			part="normal"
			onChange={date => setValue(date)}
		/>
	);
}
```

##### Range Markup Preview

```jsx
import { Month } from "@svar-ui/react-core";

const value = {
	start: new Date(2025, 4, 10),
	end: new Date(2025, 4, 18),
};

function Example() {
	return (
		<Month
			value={value}
			current={value.start}
			part="both"
			onChange={date => console.log(date)}
		/>
	);
}
```

#### Implementation Notes

- Source default `part` is `""`; that path treats `value` as a range object. Use `part="normal"` for a plain `Date`.
- Days outside the current month get `.wx-out` and `.wx-inactive`.
- `Month` does not render calendar header or action buttons; use `Calendar` or `RangeCalendar` for those.


## File: core/multicombo.md

> Source: `core/multicombo.md`

### SVAR React Core MultiCombo

Package: `@svar-ui/react-core`

#### Package

```js
import { MultiCombo } from "@svar-ui/react-core";
```

#### Supported Functionality

- Multi-select searchable input backed by `SuggestDropdown`.
- `value` is an array of selected ids; pair with `onChange` to keep state in sync.
- `options` are `{ id, label }` by default.
- `textField` controls display/filter field; default is `"label"`.
- `textOptions` can provide selected tag display objects when visible `options` are partial.
- Typing filters options case-insensitively by `textField`.
- Selected options render as tags with remove icons.
- `checkboxes` shows non-interactive checkboxes in dropdown rows.
- `children` render function receives `{ option }` for both tags and list rows.
- `onChange` emits `{ value }`.

#### Public Types

```ts
import type { FC, ReactNode } from "react";

export interface DropdownOptions {
	inline?: boolean;
	position?: "top" | "right" | "bottom" | "left";
	align?: "start" | "center" | "end";
	css?: string;
	width?: string | "unset" | "auto";
	trackScroll?: boolean;
	virtualized?: boolean;
}

export declare const MultiCombo: FC<{
	id?: string | number;
	value?: (string | number)[];
	options?: { id: string | number; label: string }[];
	textOptions?: { id: string | number; label: string }[];
	textField?: string;
	placeholder?: string;
	title?: string;
	disabled?: boolean;
	error?: boolean;
	checkboxes?: boolean;
	dropdown?: DropdownOptions & {
		virtualized?: boolean;
	};
	children?: (ctx: { option: any }) => ReactNode;
	onChange?: (ev: { value: (string | number)[] }) => void;
}>;
```

#### Styling

- Wrapper: `.wx-multicombo`
- State classes: `.wx-focus`, `.wx-disabled`, `.wx-error`, `.wx-not-empty`
- Border wrapper: `.wx-wrapper`
- Tags wrapper: `.wx-tags`, tag `.wx-tag`
- Input row: `.wx-select`
- Icons: `.wx-icon`, `.wxi-close`
- Dropdown list hooks: `.wx-list`, `.wx-item`, `.wx-focus`

```jsx
<MultiCombo
	options={options}
	value={value}
	onChange={ev => setValue(ev.value)}
	dropdown={{ css: "roles-popup" }}
/>
```

```css
.wx-multicombo .wx-tag {
	max-width: 180px;
}
```

#### Recipes

##### Multi Select With Checkboxes

```jsx
import { useState } from "react";
import { MultiCombo } from "@svar-ui/react-core";

const options = [
	{ id: "editor", label: "Editor" },
	{ id: "owner", label: "Owner" },
	{ id: "viewer", label: "Viewer" },
];

function Example() {
	const [roles, setRoles] = useState(["viewer"]);

	return (
		<MultiCombo
			options={options}
			value={roles}
			onChange={ev => setRoles(ev.value)}
			checkboxes
			placeholder="Select roles"
		/>
	);
}
```

##### Custom Tag And Row Content

```jsx
import { MultiCombo } from "@svar-ui/react-core";

const users = [
	{ id: 104, label: "Lord Varys", email: "little.birds@mail" },
];

function Example() {
	return (
		<MultiCombo options={users} value={[104]}>
			{({ option }) => <strong>{option.label}</strong>}
		</MultiCombo>
	);
}
```

#### Implementation Notes

- Filtering assumes `option[textField]` is a string
- The source `onselect` path ignores falsy ids; avoid empty-string ids for selected options.


## File: core/pager.md

> Source: `core/pager.md`

### SVAR React Core Pager

Package: `@svar-ui/react-core`

#### Package

```js
import { Pager } from "@svar-ui/react-core";
```

#### Supported Functionality

- Pagination control with rows-per-page input, page navigation icons, current page input, and total page count.
- `value` is the current page; default is `1`. Pair with `onChange` to keep state in sync.
- `pageSize` is controlled; default is `20`.
- `pageCount` is `Math.ceil(total / pageSize)`.
- `from` is the zero-based row offset: `(value - 1) * pageSize`.
- `to` is capped by `total`: `Math.min(value * pageSize, total)`.
- Page navigation emits `{ value, from, to }` after updating the bound page.
- Labels come from locale group `core`.

#### Public Types

```ts
import type { FC } from "react";

export declare const Pager: FC<{
	total?: number;
	pageSize?: number;
	value?: number;
	onChange?: (ev: { value: number; from: number; to: number }) => void;
}>;
```

#### Styling

- Wrapper: `.wx-pager`
- Sections: `.wx-left`, `.wx-center`, `.wx-right`
- Navigation icons: `.wx-icon`, icon font classes `wxi-angle-dbl-left`, `wxi-angle-left`, `wxi-angle-right`, `wxi-angle-dbl-right`
- Disabled icons: `.wx-disabled`
- Inputs use local `input` styles inside the component.

```jsx
<div className="grid-footer">
	<Pager total={100} />
</div>
```

```css
.grid-footer .wx-pager {
	justify-content: flex-end;
}
```

#### Recipes

##### Bound Page And Page Size

```jsx
import { useState } from "react";
import { Pager } from "@svar-ui/react-core";

function Example() {
	const [page, setPage] = useState(2);
	const [pageSize, setPageSize] = useState(10);

	return (
		<Pager
			total={100}
			value={page}
			pageSize={pageSize}
			onChange={ev => {
				setPage(ev.value);
				console.log(ev.value, ev.from, ev.to);
			}}
		/>
	);
}
```

#### Implementation Notes

- Page-size input calls `onChange` with `value` equal to the entered page size, not the active page.
- Page navigation calls `onChange` with `value` equal to the active page.
- Current-page input rejects values below `1`, above `pageCount`, or `NaN`.


## File: core/popup.md

> Source: `core/popup.md`

### SVAR React Core Popup

Package: `@svar-ui/react-core`

#### Package

```js
import { Popup } from "@svar-ui/react-core";
```

#### Supported Functionality

- Low-level absolutely positioned popup surface.
- Position is calculated with `calculatePosition` from `@svar-ui/lib-dom`.
- Use `parent` to anchor to an element, or use `left`/`top` with an `at` position.
- `at` defaults to `"bottom"` in source.
- `onCancel` is called by click-outside behavior.
- `width` can be number, "auto" or percentage like `100%` - calculated from `parent.offsetWidth`.
- `trackScroll`; when enabled hides on scroll outside of popup.

#### Public Types

```ts
import { TPosition } from "@svar-ui/lib-dom";
import type { FC, ReactNode } from "react";

export declare const Popup: FC<{
	left?: number;
	top?: number;
	at?: TPosition;
	css: string;
	width: number | string;
	trackScroll: boolean;
	parent?: HTMLElement;
	children?: ReactNode;
	onCancel?: (ev: MouseEvent) => void;
}>;
```

#### Styling

- Container: `.wx-popup`
- Source appends `css` to `.wx-popup`.
- Inline style sets `position:absolute`, calculated `top`, `left`, and `width`.

```jsx
<Popup parent={buttonNode} css="help-popup">
	<div className="body">Help</div>
</Popup>
```

```css
.wx-popup.help-popup {
	padding: 12px;
}
```

#### Recipes

##### Popup Anchored To A Button

```jsx
import { useRef, useState } from "react";
import { Button, Popup } from "@svar-ui/react-core";

function Example() {
	const parentRef = useRef(null);
	const [open, setOpen] = useState(false);

	return (
		<>
			<div ref={parentRef}>
				<Button onClick={() => setOpen(true)}>Anchor</Button>
			</div>

			{open && parentRef.current && (
				<Popup
					parent={parentRef.current}
					at="bottom"
					onCancel={() => setOpen(false)}
				>
					<div style={{ padding: 12 }}>Popup content</div>
				</Popup>
			)}
		</>
	);
}
```

#### Implementation Notes

- Use `Dropdown` for the common anchored dropdown case; it handles `Portal` and parent discovery.


## File: core/portal.md

> Source: `core/portal.md`

### SVAR React Core Portal

Package: `@svar-ui/react-core`

#### Package

```js
import { Portal, popupContainer } from "@svar-ui/react-core";
```

#### Supported Functionality

- `Portal` moves its themed child node to `target` or the nearest `data-wx-portal-root` ancestor.
- If no local portal root exists, source appends to the top node from `@svar-ui/lib-dom` environment.
- `theme` defaults from `context.skin` (read via `useContext(context.skin)` from `@svar-ui/react-core`) when not supplied.
- Children are rendered into the portal target as standard JSX children.
- `popupContainer(node)` marks a local portal root with a generated `data-wx-portal-root` attribute.

#### Public Types

```ts
import type { FC, ReactNode } from "react";

export declare const Portal: FC<{
	theme?: "willow" | "willow-dark";
	target?: HTMLElement;
	children?: ReactNode;
}>;

export declare function popupContainer(node: HTMLElement): void;
```

#### Styling

- Source wrapper `.wx-portal` is `display: none`.
- Moved node receives `.wx-{theme}-theme`, such as `.wx-willow-theme`.
- `popupContainer` has no class; it sets a data attribute.

```jsx
import { useEffect, useRef } from "react";
import { popupContainer } from "@svar-ui/react-core";

function LocalRoot({ children }) {
	const ref = useRef(null);
	useEffect(() => {
		if (ref.current) popupContainer(ref.current);
	}, []);
	return <div ref={ref} className="local-root">{children}</div>;
}
```

#### Recipes

##### Render A Modal Through Portal

```jsx
import { useState } from "react";
import { Button, Modal, Portal } from "@svar-ui/react-core";

function Example() {
	const [open, setOpen] = useState(false);

	return (
		<>
			<Button onClick={() => setOpen(true)}>Open</Button>

			{open && (
				<Portal>
					<Modal title="Portal Modal" onCancel={() => setOpen(false)}>
						Content
					</Modal>
				</Portal>
			)}
		</>
	);
}
```

##### Local Portal Root

```jsx
import { useEffect, useRef } from "react";
import { DatePicker, popupContainer } from "@svar-ui/react-core";

function Example() {
	const ref = useRef(null);
	useEffect(() => {
		if (ref.current) popupContainer(ref.current);
	}, []);

	return (
		<div ref={ref} className="local-root">
			<DatePicker />
		</div>
	);
}
```


## File: core/radio.md

> Source: `core/radio.md`

### SVAR React Core Radio

Package: `@svar-ui/react-core`

Use this file standalone for `RadioButton` and `RadioButtonGroup`.

#### Package

```js
import { RadioButton, RadioButtonGroup } from "@svar-ui/react-core";
```

#### Supported Functionality

- `RadioButton.value` is a controlled boolean checked state.
- `RadioButton.onChange` fires only when the radio becomes checked and emits `{ value: true, inputValue }`.
- Standalone radio buttons need a shared `name` to behave as one browser radio group.
- `RadioButtonGroup.options` are `{ id, label }`.
- `RadioButtonGroup.value` is the selected option id.
- Group `onChange` emits `{ value }`.
- Group `type` supports `inline` and `grid`; default layout is one item per row.

#### Public Types

```ts
import type { ComponentType } from "react";

export declare const RadioButton: ComponentType<{
	id?: string | number;
	label?: string;
	value?: boolean;
	name?: string;
	inputValue?: string | number;
	disabled?: boolean;
	onChange?: (ev: { value: boolean; inputValue: string | number }) => void;
}>;

export declare const RadioButtonGroup: ComponentType<{
	options?: { id: string | number; label: string }[];
	value?: string | number;
	type?: "inline" | "grid";
	onChange?: (ev: { value: string | number }) => void;
}>;
```

#### Styling

- Radio wrapper: `.wx-radio`
- Group wrapper: `.wx-radiogroup`, `.wx-radiogroup.wx-inline`, `.wx-radiogroup.wx-grid`
- Group item wrapper: `.wx-item`

```jsx
<RadioButtonGroup options={options} value={value} onChange={ev => setValue(ev.value)} type="grid" />
```

```css
.wx-radiogroup.wx-grid .wx-item {
	flex-basis: 33.333%;
	max-width: 33.333%;
}
```

#### Recipes

##### Standalone Radio Buttons

```jsx
import { RadioButton } from "@svar-ui/react-core";

function Demo() {
	return (
		<>
			<RadioButton label="One" name="mode" inputValue="one" value={true} />
			<RadioButton label="Two" name="mode" inputValue="two" />
		</>
	);
}
```

##### Radio Group

```jsx
import { useState } from "react";
import { RadioButtonGroup } from "@svar-ui/react-core";

function Demo() {
	const options = [
		{ id: 1, label: "Option 1" },
		{ id: 2, label: "Option 2" },
		{ id: 3, label: "Option 3" },
	];

	const [value, setValue] = useState(1);

	return (
		<RadioButtonGroup
			options={options}
			value={value}
			onChange={ev => setValue(ev.value)}
			type="inline"
		/>
	);
}
```

#### Implementation Notes

- `RadioButtonGroup` does not pass disabled state through option objects.


## File: core/rangecalendar.md

> Source: `core/rangecalendar.md`

### SVAR React Core RangeCalendar

Package: `@svar-ui/react-core`

#### Package

```js
import { RangeCalendar } from "@svar-ui/react-core";
```

#### Supported Functionality

- Date range calendar with controlled `start` and `end`.
- `months` is `1` or `2`; default is `2`.
- Two-month mode renders left and right panels with synchronized months.
- `buttons` defaults to `["clear", "today"]`; arrays can include `"done"`.
- When `buttons` includes `"done"`, selection changes are held until the done action emits the final value.
- Selection order is normalized: selecting an end before the start swaps `start` and `end`.
- `markers(date)` can return a class string appended to `.wx-day`.
- `onChange` receives `{ start: Date | null, end: Date | null }`.

#### Public Types

```ts
import type { ComponentType } from "react";

export declare const RangeCalendar: ComponentType<{
	start?: Date;
	end?: Date;
	current?: Date;
	months?: 1 | 2;
	markers?: (date: Date) => string;
	buttons?: boolean | ("clear" | "today" | "done")[];
	onChange?: (ev: { start: Date | null; end: Date | null }) => void;
}>;
```

#### Styling

- Two-month wrapper: `.wx-rangecalendar`
- Panel wrapper: `.wx-half`
- Calendar panels use `.wx-calendar`, `.wx-wrap`, `.wx-buttons`, `.wx-button-item`
- Month range states: `.wx-selected`, `.wx-left`, `.wx-right`, `.wx-inrange`

```jsx
<div className="range-shell">
	<RangeCalendar months={2} />
</div>
```

```css
.range-shell {
	--wx-calendar-cell-size: 30px;
}
```

#### Recipes

##### Two-Month Range With Done Button

```jsx
import { useState } from "react";
import { RangeCalendar } from "@svar-ui/react-core";

function Demo() {
	const [start, setStart] = useState(new Date(2025, 4, 1));
	const [end, setEnd] = useState(new Date(2025, 4, 7));

	return (
		<RangeCalendar
			start={start}
			end={end}
			months={2}
			buttons={["done", "clear", "today"]}
			onChange={ev => {
				setStart(ev.start);
				setEnd(ev.end);
				console.log(ev.start, ev.end);
			}}
		/>
	);
}
```

##### Single-Month Range

```jsx
import { useState } from "react";
import { RangeCalendar } from "@svar-ui/react-core";

function Demo() {
	const [start, setStart] = useState();
	const [end, setEnd] = useState();

	return (
		<RangeCalendar
			start={start}
			end={end}
			months={1}
			buttons={false}
			onChange={ev => {
				setStart(ev.start);
				setEnd(ev.end);
				console.log(ev.start, ev.end);
			}}
		/>
	);
}
```

#### Implementation Notes

- Source initializes the visible month from `start`, then `current`, then `new Date()`.
- Clearing emits `{ start: null, end: null }`.


## File: core/richselect.md

> Source: `core/richselect.md`

### SVAR React Core RichSelect

Package: `@svar-ui/react-core`

#### Package

```js
import { RichSelect } from "@svar-ui/react-core";
```

#### Supported Functionality

- Non-input single-select control backed by `SuggestDropdown`.
- `value` is the selected id and is controlled.
- `options` are `{ id, label }` by default.
- `textField` controls display field; default is `"label"`.
- `textOptions` can provide selected display objects when visible `options` are partial.
- `clear` shows a close icon when value is set and not disabled.
- `children` render function receives the option object directly for both selected content and list rows.
- `onChange` emits `{ value }`.

#### Public Types

```ts
import type { ComponentType, ReactNode } from "react";

export interface DropdownOptions {
	inline?: boolean;
	position?: "top" | "right" | "bottom" | "left";
	align?: "start" | "center" | "end";
	css?: string;
	width?: string | "unset" | "auto";
	trackScroll?: boolean;
	virtualized?: boolean;
}

export declare const RichSelect: ComponentType<{
	value?: string | number;
	options?: { id: string | number; label: string }[];
	textOptions?: { id: string | number; label: string }[];
	placeholder?: string;
	disabled?: boolean;
	error?: boolean;
	title?: string;
	textField?: string;
	clear?: boolean;
	dropdown?: DropdownOptions & {
		virtualized?: boolean;
	};
	children?: (option: any) => ReactNode;
	onChange?: (ev: { value: string | number }) => void;
}>;
```

#### Styling

- Wrapper: `.wx-richselect`
- State classes: `.wx-disabled`, `.wx-error`, `.wx-nowrap`
- Content label: `.wx-label`
- Placeholder: `.wx-placeholder`
- Icon: `.wx-icon`, close icon `.wxi-close`
- Dropdown list hooks: `.wx-list`, `.wx-item`, `.wx-focus`

```jsx
<RichSelect
	options={users}
	value={104}
	dropdown={{ css: "user-select-menu" }}
/>
```

```css
.wx-popup.user-select-menu .wx-item {
	min-height: 40px;
}
```

#### Recipes

##### Rich Select With Custom Template

```jsx
import { RichSelect } from "@svar-ui/react-core";

function Demo() {
	const users = [
		{ id: 104, label: "Lord Varys", email: "little.birds@mail" },
		{ id: 103, label: "Ned Stark", email: "winterhell@mail" },
	];

	return (
		<RichSelect options={users} value={104}>
			{option => (
				<div>
					<strong>{option.label}</strong>
					<span>{option.email}</span>
				</div>
			)}
		</RichSelect>
	);
}
```

##### Hidden Selected Option

```jsx
import { RichSelect } from "@svar-ui/react-core";

function Demo() {
	const allUsers = [
		{ id: 87, label: "Berni Mayou" },
		{ id: 103, label: "Ned Stark" },
	];

	const visibleUsers = [{ id: 103, label: "Ned Stark" }];

	return (
		<RichSelect textOptions={allUsers} options={visibleUsers} value={87} clear />
	);
}
```

#### Implementation Notes

- Without a custom render function, `.wx-nowrap` is added to ellipsize the selected label.


## File: core/segmented.md

> Source: `core/segmented.md`

### SVAR React Core Segmented

Package: `@svar-ui/react-core`

#### Package

```js
import { Segmented } from "@svar-ui/react-core";
```

#### Supported Functionality

- Renders an inline segmented button group.
- `options` are `{ id, label, icon?, title? }`.
- `value` is the selected id and is controlled.
- Clicking an option sets `value = option.id` and emits `onChange({ value })`.
- `css` is appended to `.wx-segmented`.
- Default content renders `option.icon` and `option.label`.
- `children` render function receives `{ option }` for custom option content.

#### Public Types

```ts
import type { ComponentType, ReactNode } from "react";

export declare const Segmented: ComponentType<{
	options?: {
		id: string | number;
		label: string;
		icon?: string;
		title?: string;
	}[];
	value?: string | number;
	css?: string;
	children?: (ctx: { option: any }) => ReactNode;
	onChange?: (ev: { value: string | number }) => void;
}>;
```

#### Styling

- Wrapper: `.wx-segmented`
- Selected button: `.wx-selected`
- Default icon: `.wx-icon`, icon-only modifier `.wx-only`
- Default label: `.wx-label`

```jsx
<Segmented css="view-mode" options={options} value={value} onChange={ev => setValue(ev.value)} />
```

```css
.wx-segmented.view-mode {
	--wx-segmented-padding: 3px;
}
```

#### Recipes

##### Basic Segmented Control

```jsx
import { useState } from "react";
import { Segmented } from "@svar-ui/react-core";

function Demo() {
	const options = [
		{ id: "list", label: "List", icon: "wxi-view-sequential" },
		{ id: "grid", label: "Grid", icon: "wxi-view-grid" },
	];

	const [value, setValue] = useState("list");

	return (
		<Segmented
			options={options}
			value={value}
			onChange={ev => {
				setValue(ev.value);
				console.log(ev.value);
			}}
		/>
	);
}
```

##### Custom Option Content

```jsx
import { Segmented } from "@svar-ui/react-core";

function Demo() {
	const options = [
		{ id: "left", label: "Left", icon: "wxi-align-left" },
		{ id: "right", label: "Right", icon: "wxi-align-right" },
	];

	return (
		<Segmented options={options} value="left">
			{({ option }) => (
				<>
					<i className={option.icon}></i>
					<span>{option.label}</span>
				</>
			)}
		</Segmented>
	);
}
```


## File: core/select.md

> Source: `core/select.md`

### SVAR React Core Select

Package: `@svar-ui/react-core`

#### Package

```js
import { Select } from "@svar-ui/react-core";
```

#### Supported Functionality

- Renders a native `<select>` inside `.wx-select`.
- `options` are `{ id, label }` by default.
- `textField` changes the displayed field; default is `"label"`.
- `value` is controlled and stores the selected option id.
- `placeholder` is shown as an overlay when value is empty and not `0`.
- `clear` shows a close icon when the component has a value and is not disabled.
- `onChange` emits `{ value }`.

#### Public Types

```ts
import type { ComponentType } from "react";

export declare const Select: ComponentType<{
	value?: string | number;
	options?: { id: string | number; label: string }[];
	placeholder?: string;
	title?: string;
	disabled?: boolean;
	error?: boolean;
	textField?: string;
	clear?: boolean;
	id?: string | number;
	onChange?: (ev: { value: string | number }) => void;
}>;
```

#### Styling

- Wrapper: `.wx-select`
- Placeholder overlay: `.wx-placeholder`
- Icon: `.wx-icon`, close icon `.wxi-close`
- Error class is applied to the native `select` as `.wx-error`.

```jsx
<div className="owner-select">
	<Select options={users} value={value} onChange={ev => setValue(ev.value)} clear />
</div>
```

```css
.owner-select .wx-select {
	--wx-input-width: 280px;
}
```

#### Recipes

##### Native Select With Clear

```jsx
import { useState } from "react";
import { Field, Select } from "@svar-ui/react-core";

function Demo() {
	const users = [
		{ id: 103, label: "Ned Stark" },
		{ id: 104, label: "Lord Varys" },
	];

	const [owner, setOwner] = useState("");

	return (
		<Field label="Owner" position="left">
			<Select
				options={users}
				value={owner}
				onChange={ev => setOwner(ev.value)}
				placeholder="Select owner"
				clear
			/>
		</Field>
	);
}
```

#### Implementation Notes

- `Select` has no `css` prop; use a parent/global selector for styling.


## File: core/sidearea.md

> Source: `core/sidearea.md`

### SVAR React Core SideArea

Package: `@svar-ui/react-core`

#### Package

```js
import { SideArea } from "@svar-ui/react-core";
```

#### Supported Functionality

- Absolute-position side panel for local layouts.
- `position` public type supports only `"right"`; source defaults to `"right"`.
- Clicking outside the panel calls `onCancel`.
- Uses a fly transition from the right.
- Renders arbitrary `children`.

#### Public Types

```ts
import type { ComponentType, ReactNode } from "react";

export declare const SideArea: ComponentType<{
	position?: "right";
	children?: ReactNode;
	onCancel?: () => void;
}>;
```

#### Styling

- Panel: `.wx-sidearea`
- Right position: `.wx-pos-right`

```jsx
<div className="side-host">
	<SideArea>
		<div className="side-content">Panel</div>
	</SideArea>
</div>
```

```css
.side-host {
	position: relative;
	min-height: 300px;
}

.side-content {
	width: 400px;
	padding: 20px;
}
```

#### Recipes

##### Right-Side Local Panel

```jsx
import { useState } from "react";
import { Button, SideArea } from "@svar-ui/react-core";

function Demo() {
	const [open, setOpen] = useState(false);

	return (
		<div style={{ position: "relative", minHeight: "300px" }}>
			<Button onClick={() => setOpen(true)}>Open side panel</Button>

			{open && (
				<SideArea onCancel={() => setOpen(false)}>
					<div style={{ width: "400px", padding: "20px" }}>Panel content</div>
				</SideArea>
			)}
		</div>
	);
}
```


## File: core/slider.md

> Source: `core/slider.md`

### SVAR React Core Slider

Package: `@svar-ui/react-core`

#### Package

```js
import { Slider } from "@svar-ui/react-core";
```

#### Supported Functionality

- Renders an input range with optional label.
- Controlled `value`, default `0`.
- `min` defaults to `0`, `max` to `100`, `step` to `1`.
- `width` sets inline width on `.wx-slider`.
- During drag, `onChange` emits `{ value, previous, input: true }`.
- On final change, `onChange` emits `{ value, previous }`.
- `previous` tracks the previous input/final value separately for drag and final changes.

#### Public Types

```ts
import type { ComponentType } from "react";

export declare const Slider: ComponentType<{
	id?: string | number;
	label?: string;
	width?: string;
	min?: number;
	max?: number;
	value?: number;
	step?: number;
	title?: string;
	disabled?: boolean;
	onChange?: (ev: {
		value: number;
		previous: number;
		input?: boolean;
	}) => void;
}>;
```

#### Styling

- Wrapper: `.wx-slider`
- Inner range input is styled through input pseudo-elements.
- Label is a native `label` inside `.wx-slider`.

```jsx
<Slider width="240px" value={value} onChange={ev => setValue(ev.value)} />
```

```css
.wx-slider {
	--wx-slider-thumb-size: 18px;
}
```

#### Recipes

##### Slider With Drag And Final Events

```jsx
import { useState } from "react";
import { Field, Slider } from "@svar-ui/react-core";

function Demo() {
	const [progress, setProgress] = useState(50);

	return (
		<Field label="Progress" position="left" type="slider">
			<Slider
				label={`Progress: ${progress}%`}
				value={progress}
				min={0}
				max={100}
				onChange={ev => {
					setProgress(ev.value);
					if (ev.input) console.log("drag", ev.previous, ev.value);
					else console.log("final", ev.previous, ev.value);
				}}
			/>
		</Field>
	);
}
```


## File: core/suggest-dropdown.md

> Source: `core/suggest-dropdown.md`

### SVAR React Core SuggestDropdown

Package: `@svar-ui/react-core`

#### Package

```js
import { SuggestDropdown } from "@svar-ui/react-core";
```

#### Supported Functionality

- Low-level dropdown list helper used by `Combo`, `MultiCombo`, and `RichSelect`.
- Renders only when navigation index is not `null`; callers open it through `onReady.navigate`.
- `items` are `{ id, label }`.
- `onReady` receives navigation helpers: `navigate`, `keydown`, and `move`.
- `onSelect` emits `{ id }`; in multiselect mode `id` is the next selected id array.
- `multiselect` toggles id arrays instead of a single id.
- `checkboxes` renders a non-interactive `Checkbox` in each row.
- `virtualized` renders only visible rows with fixed measured item height and overscan.
- `children` render function receives `{ option }`.

#### Public Types

```ts
import type { ComponentType, ReactNode } from "react";

export interface DropdownOptions {
	inline?: boolean;
	position?: "top" | "right" | "bottom" | "left";
	align?: "start" | "center" | "end";
	css?: string;
	width?: string | "unset" | "auto";
	trackScroll?: boolean;
	virtualized?: boolean;
}

export declare const SuggestDropdown: ComponentType<
	DropdownOptions & {
		items?: { id: string | number; label: string }[];
		children?: (ctx: { option: any }) => ReactNode;
		onSelect?: (ev: { id: string | number | (string | number)[] }) => void;
		onReady?: (ev: {
			navigate?: (dir: number | null, ev?: KeyboardEvent) => void;
			keydown?: (ev: KeyboardEvent, dir: number) => void;
			move?: (ev: KeyboardEvent) => void;
		}) => void;
		multiselect?: boolean;
		checkboxes?: boolean;
		value?: string | number | (string | number)[];
		virtualized?: boolean;
	}
>;
```

#### Styling

- List container: `.wx-list`
- Virtual wrapper/content: `.wx-list-wrapper`, `.wx-list-content`
- Row: `.wx-item`
- Focus row: `.wx-item.wx-focus`
- Empty state: `.wx-no-data`
- Non-inline dropdown `css` is appended to `.wx-popup`.

```jsx
<SuggestDropdown items={items} css="suggest-menu" />
```

```css
.wx-popup.suggest-menu .wx-list {
	max-height: 180px;
}
```

#### Recipes

##### Controlled Suggest Dropdown

```jsx
import { useRef } from "react";
import { SuggestDropdown } from "@svar-ui/react-core";

function Demo() {
	const items = [
		{ id: 1, label: "One" },
		{ id: 2, label: "Two" },
	];

	const apiRef = useRef(null);

	return (
		<>
			<button onClick={() => apiRef.current?.navigate(0)}>Open</button>

			<SuggestDropdown
				items={items}
				onReady={ev => (apiRef.current = ev)}
				onSelect={ev => console.log(ev.id)}
			/>
		</>
	);
}
```

#### Implementation Notes

- Keyboard handlers use `ev.code` values `Enter`, `Space`, `Escape`, `Tab`, `ArrowDown`, and `ArrowUp`.
- Virtual mode measures the first rendered item and assumes all rows have that height.


## File: core/switch.md

> Source: `core/switch.md`

### SVAR React Core Switch

Package: `@svar-ui/react-core`

#### Package

```js
import { Switch } from "@svar-ui/react-core";
```

#### Supported Functionality

- Renders a labeled checkbox styled as a switch.
- `value` is a controlled boolean.
- `disabled` is forwarded to the hidden checkbox input.
- `onChange` emits `{ value }` after the checked state changes.
- `id` is used through the shared input id helper, so it can connect with a surrounding `Field`.

#### Public Types

```ts
import type { ComponentType } from "react";

export declare const Switch: ComponentType<{
	id?: string | number;
	value?: boolean;
	disabled?: boolean;
	onChange?: (ev: { value: boolean }) => void;
}>;
```

#### Styling

- Wrapper: `.wx-switch`
- Internal elements are an invisible checkbox input and a visual `span`.

```jsx
<Switch value={value} onChange={ev => setValue(ev.value)} />
```

```css
.wx-switch {
	--wx-switch-width: 56px;
}
```

#### Recipes

##### Bound Switch In A Field

```jsx
import { useState } from "react";
import { Field, Switch } from "@svar-ui/react-core";

function Demo() {
	const [enabled, setEnabled] = useState(true);

	return (
		<Field label={`Enabled: ${enabled}`} position="left" type="switch">
			<Switch
				value={enabled}
				onChange={ev => {
					setEnabled(ev.value);
					console.log(ev.value);
				}}
			/>
		</Field>
	);
}
```

#### Implementation Notes

- The component does not expose `css`; style through parent/global selectors or theme variables.


## File: core/tabs.md

> Source: `core/tabs.md`

### SVAR React Core Tabs

Package: `@svar-ui/react-core`

#### Package

```js
import { Tabs } from "@svar-ui/react-core";
```

#### Supported Functionality

- Renders a tab strip only; render the tab panel yourself based on `value`.
- `options` are `{ id, label?, title?, icon? }`.
- `value` is the active tab id and is controlled.
- Clicking a tab sets `value = option.id` and emits `onChange({ value })`.
- `type` is `top` or `bottom`; default is `top`.
- Icons use the same icon class pattern as other core controls.

#### Public Types

```ts
import type { ComponentType } from "react";

export declare const Tabs: ComponentType<{
	options?: {
		id: string | number;
		label?: string;
		title?: string;
		icon?: string;
	}[];
	value?: string | number;
	type?: "top" | "bottom";
	onChange?: (ev: { value: string | number }) => void;
}>;
```

#### Styling

- Wrapper: `.wx-tabs`, plus `.wx-top` or `.wx-bottom`
- Active button: `.wx-active`
- Default icon: `.wx-icon`, icon-only modifier `.wx-only`
- Default label: `.wx-label`

```jsx
<Tabs options={tabs} value={active} onChange={ev => setActive(ev.value)} />
```

```css
.wx-tabs {
	--wx-tabs-cell-min-width: 80px;
}
```

#### Recipes

##### Tabs With Panels

```jsx
import { useState } from "react";
import { Tabs } from "@svar-ui/react-core";

function Demo() {
	const tabs = [
		{ id: "info", label: "Info", icon: "wxi-alert" },
		{ id: "audit", label: "Audit" },
		{ id: "done", icon: "wxi-check", title: "Done" },
	];

	const [active, setActive] = useState("info");

	return (
		<>
			<Tabs options={tabs} value={active} onChange={ev => setActive(ev.value)} />

			{active === "info" ? (
				<div>Info panel</div>
			) : active === "audit" ? (
				<div>Audit panel</div>
			) : (
				<div>Done panel</div>
			)}

			<Tabs options={tabs} value={active} onChange={ev => setActive(ev.value)} type="bottom" />
		</>
	);
}
```

#### Implementation Notes

- `Tabs` has no `css` prop; style with an enclosing parent/global selector or theme variables.


## File: core/text.md

> Source: `core/text.md`

### SVAR React Core Text

Package: `@svar-ui/react-core`

#### Package

```js
import { Text } from "@svar-ui/react-core";
```

#### Supported Functionality

- Controlled `value`, with `string | number` public type.
- `type` supports `text`, `number`, and `password`; default is `text`.
- `onChange` fires `{ value, input: true }` on input and `{ value }` on native change.
- `focus` and `select` focus/select the input after mount.
- `clear` shows a close icon when the input has a value; clicking it sets `value = ""` and emits `{ value }`.
- `icon` renders inside the input. It is right-aligned unless `css` includes `wx-icon-left`.
- `inputStyle` is applied to the inner `<input>`.
- `readonly`, `disabled`, `error`, `placeholder`, and `title` are forwarded to the input/wrapper.

#### Public Types

```ts
import type { ComponentType } from "react";

export declare const Text: ComponentType<{
	value?: string | number;
	id?: string | number;
	readonly?: boolean;
	focus?: boolean;
	select?: boolean;
	type?: "text" | "number" | "password";
	placeholder?: string;
	disabled?: boolean;
	error?: boolean;
	inputStyle?: string;
	title?: string;
	css?: string;
	icon?: string;
	clear?: boolean;
	onChange?: (ev: { value: string | number; input?: boolean }) => void;
}>;
```

#### Styling

- Wrapper: `.wx-text`
- State/classes: `.wx-error`, `.wx-disabled`, `.wx-clear`, `.wx-icon-left`, `.wx-icon-right`
- Icon: `.wx-icon`; clear icon: `.wx-icon.wxi-close`
- `css` is appended to `.wx-text`.

```jsx
<Text css="search-input wx-icon-left" icon="wxi-search" clear />
```

```css
.wx-text.search-input {
	--wx-input-width: 320px;
}
```

#### Recipes

##### Text With Clear And Left Icon

```jsx
import { useState } from "react";
import { Field, Text } from "@svar-ui/react-core";

function Demo() {
	const [query, setQuery] = useState("");

	return (
		<Field label="Search" position="left">
			<Text
				value={query}
				onChange={ev => {
					setQuery(ev.value);
					if (!ev.input) console.log("final", ev.value);
				}}
				placeholder="Type here"
				icon="wxi-search"
				css="wx-icon-left"
				clear
			/>
		</Field>
	);
}
```

##### Focus And Select On Mount

```jsx
import { Text } from "@svar-ui/react-core";

function Demo() {
	return <Text value="Some value" focus select />;
}
```

#### Implementation Notes

- `type="number"` still binds through the input value; account for string/number conversion in your app logic.


## File: core/textarea.md

> Source: `core/textarea.md`

### SVAR React Core TextArea

Package: `@svar-ui/react-core`

#### Package

```js
import { TextArea } from "@svar-ui/react-core";
```

#### Supported Functionality

- Renders a native `<textarea class="wx-textarea">`.
- `value` is controlled.
- `onChange` fires `{ value, input: true }` on input and `{ value }` on native change.
- Supports `id`, `placeholder`, `title`, `disabled`, `error`, and `readonly`.
- The textarea is vertically resizable unless disabled.

#### Public Types

```ts
import type { ComponentType } from "react";

export declare const TextArea: ComponentType<{
	value?: string;
	id?: string | number;
	placeholder?: string;
	title?: string;
	disabled?: boolean;
	error?: boolean;
	readonly?: boolean;
	onChange?: (ev: { value: string; input?: boolean }) => void;
}>;
```

#### Styling

- Textarea: `.wx-textarea`
- Error state: `.wx-textarea.wx-error`
- Disabled state uses `[disabled]`.

```jsx
<TextArea placeholder="Details" />
```

```css
.wx-textarea {
	min-height: 140px;
}
```

#### Recipes

##### TextArea In A Field

```jsx
import { useState } from "react";
import { Field, TextArea } from "@svar-ui/react-core";

function Demo() {
	const [details, setDetails] = useState("");

	return (
		<Field label="Details" error>
			<TextArea
				value={details}
				onChange={ev => setDetails(ev.value)}
				error
				title="Details are required"
				placeholder="Type here"
			/>
		</Field>
	);
}
```

#### Implementation Notes

- There is no `css` prop; style through a parent/global selector or theme variables.


## File: core/themes.md

> Source: `core/themes.md`

### SVAR React Core Themes

Package: `@svar-ui/react-core`

#### Package

```js
import { Willow, WillowDark } from "@svar-ui/react-core";
```

#### Supported Functionality

- Theme components provide React context `wx-theme`.
- `Willow` sets `wx-theme` to `"willow"`.
- `WillowDark` sets `wx-theme` to `"willow-dark"`.
- When `children` are supplied, each theme renders `.wx-theme.wx-*-theme` with `height:100%`.
- `fonts` defaults to `true`.
- `Willow` and `WillowDark` load Open Sans font files and the `wxi` icon CSS.
- Use `fonts={false}` when fonts/icons are already loaded or the app manages font loading.
- Theme styling is CSS-variable driven; override variables on the theme wrapper or an ancestor around specific controls.

#### Public Types

```ts
import type { ComponentType, ReactNode } from "react";

export declare const Willow: ComponentType<{
	fonts?: boolean;
	children?: ReactNode;
}>;

export declare const WillowDark: ComponentType<{
	fonts?: boolean;
	children?: ReactNode;
}>;
```

#### Styling


```jsx
<Willow fonts={false}>
	<div className="app-theme">
		<App />
	</div>
</Willow>
```

```css
.app-theme {
	--wx-color-primary: #0f766e;
	--wx-input-width: 280px;
	--wx-button-border-radius: 4px;
	--wx-calendar-cell-size: 30px;
}
```

#### Recipes

##### Wrap An App In A Theme

```jsx
import { Willow } from "@svar-ui/react-core";
import AppRoutes from "./AppRoutes.jsx";

function Demo() {
	return (
		<Willow>
			<AppRoutes />
		</Willow>
	);
}
```

##### Dark Theme Without CDN Font Injection

```jsx
import { WillowDark } from "@svar-ui/react-core";

function Demo() {
	return (
		<WillowDark fonts={false}>
			<div className="screen">Dark UI</div>
		</WillowDark>
	);
}
```

#### Other information

extra details about themes can be obtained from `../themes.md`


## File: core/timepicker.md

> Source: `core/timepicker.md`

### SVAR React Core TimePicker

Package: `@svar-ui/react-core`

#### Package

```js
import { TimePicker } from "@svar-ui/react-core";
```

#### Supported Functionality

- Input-like time picker backed by `Text`, `Dropdown`, `Slider`, and optional `TwoState`.
- `value` is controlled and is a `Date`; only hours and minutes are used.
- Default value is `new Date(0, 0, 0, 0, 0)` when `value` is nullish.
- `format` can be a time format string or `(value: Date) => string`; locale time format is used by default.
- Locale `calendar.clockFormat == 12` enables the AM/PM `TwoState`.
- Hour and minute text inputs update on blur.
- Hour and minute sliders update through `Slider.onChange`.
- `dropdown` is forwarded to `Dropdown`; date/time dropdowns default width to `"unset"` when no width is provided.
- `onChange` receives `{ value: Date }` after assigning the new value.

#### Public Types

```ts
import type { ComponentType } from "react";

export interface DropdownOptions {
	inline?: boolean;
	position?: "top" | "right" | "bottom" | "left";
	align?: "start" | "center" | "end";
	css?: string;
	width?: string | "unset" | "auto";
	trackScroll?: boolean;
	virtualized?: boolean;
}

export declare const TimePicker: ComponentType<{
	value?: Date;
	id?: string | number;
	title?: string;
	css?: string;
	disabled?: boolean;
	error?: boolean;
	format?: string | ((value: Date) => string);
	dropdown?: DropdownOptions;
	onChange?: (ev: { value: Date }) => void;
}>;
```

#### Styling

- Wrapper: `.wx-timepicker`
- State classes: `.wx-disabled`, `.wx-error`
- `css` is passed to the inner `Text`.
- Popup content: `.wx-wrapper`, `.wx-timer`, `.wx-digit`, `.wx-separator`
- Slider rows use `Field` and `Slider` classes.
- AM/PM toggle uses `TwoState`/`Button` classes.

```jsx
<TimePicker css="time-input" dropdown={{ css: "time-popup", width: "260px" }} />
```

```css
.wx-text.time-input {
	--wx-input-width: 180px;
}
```

#### Recipes

##### Bound Time

```jsx
import { useState } from "react";
import { Field, TimePicker } from "@svar-ui/react-core";

function Demo() {
	const [value, setValue] = useState(new Date(0, 0, 0, 14, 30));

	return (
		<Field label="Time" position="left">
			<TimePicker
				value={value}
				onChange={ev => {
					setValue(ev.value);
					console.log(ev.value);
				}}
			/>
		</Field>
	);
}
```

##### Twelve-Hour Locale

```jsx
import { useState } from "react";
import { Field, Locale, TimePicker } from "@svar-ui/react-core";

function Demo() {
	const [value, setValue] = useState(new Date(0, 0, 0, 14, 30));

	return (
		<Locale
			words={{
				formats: { timeFormat: "%g:%i %a" },
				calendar: { clockFormat: 12 },
			}}
		>
			<Field label="Time" position="left">
				<TimePicker
					value={value}
					onChange={ev => setValue(ev.value)}
					dropdown={{ width: "100%" }}
				/>
			</Field>
		</Locale>
	);
}
```

#### Implementation Notes

- The visible text is readonly; typed hour/minute edits happen only inside the popup.


## File: core/twostate.md

> Source: `core/twostate.md`

### SVAR React Core TwoState

Package: `@svar-ui/react-core`

#### Package

```js
import { TwoState } from "@svar-ui/react-core";
```

#### Supported Functionality

- Wraps `Button` and toggles controlled boolean `value`.
- When active, adds `pressed` to the forwarded `type`.
- `textActive` and `iconActive` replace `text` and `icon` while active.
- `children` renders inactive/default content; `active` render function prop renders active content when `value` is true.
- Click order: `onClick(ev)` first, then value toggle and `onChange({ value })`.
- Calling `ev.preventDefault()` inside `onClick` prevents the toggle and `onChange`.

#### Public Types

```ts
import type { ComponentType, ReactNode } from "react";

export declare const TwoState: ComponentType<{
	value?: boolean;
	type?:
		| "primary"
		| "secondary"
		| "danger"
		| "link"
		| "primary block"
		| "secondary block"
		| "danger block"
		| "link block";
	icon?: string;
	disabled?: boolean;
	iconActive?: string;
	title?: string;
	css?: string;
	text?: string;
	textActive?: string;
	active?: () => ReactNode;
	children?: ReactNode;
	onClick?: (ev: MouseEvent) => void;
	onChange?: (ev: { value: boolean }) => void;
}>;
```

#### Styling

- Uses `Button`, so styling hooks are `.wx-button` plus `.wx-pressed` when active.
- `css` is passed to the inner `Button`.
- Button type variables such as `--wx-button-pressed`, `--wx-button-primary-pressed`, and `--wx-button-box-shadow` control active state.

```jsx
<TwoState css="favorite-button" icon="wxi-star" iconActive="wxi-check" />
```

```css
.wx-button.favorite-button.wx-pressed {
	font-weight: 700;
}
```

#### Recipes

##### Toggle With Active Content

```jsx
import { useState } from "react";
import { TwoState } from "@svar-ui/react-core";

function Demo() {
	const [active, setActive] = useState(false);

	return (
		<TwoState
			value={active}
			onChange={ev => {
				setActive(ev.value);
				console.log(ev.value);
			}}
			type="primary"
			icon="wxi-star"
			iconActive="wxi-check"
			active={() => "Favorited"}
		>
			Favorite
		</TwoState>
	);
}
```

##### Prevent Toggle

```jsx
import { TwoState } from "@svar-ui/react-core";

function Demo() {
	function beforeToggle(ev) {
		if (!confirm("Toggle?")) ev.preventDefault();
	}

	return <TwoState onClick={beforeToggle}>Toggle</TwoState>;
}
```

#### Implementation Notes

- The active render function is invoked only when `value` is true.
- If `active` is not supplied, the component reuses `children` or `text` with active icon/text substitutions.


## File: menu/index.md

> Source: `menu/index.md`

Use when UI of app requires Menu, MenuBar, DropDownMenu, ContextMenu, or ActionMenu / @svar-ui/react-menu components

Styles must be imported separately:

#### Package

```js
import {
	Menu,
	MenuBar,
	DropDownMenu,
	ContextMenu,
	ActionMenu,
	registerMenuItem,
} from "@svar-ui/react-menu";
import "@svar-ui/react-menu/all.css";
```

#### Components

- `Menu` - low-level popup menu positioned from `parent` or `left`/`top`
- `DropDownMenu` - wraps trigger content, opens a menu on click
- `ContextMenu` - wraps content, opens an action menu on `contextmenu`
- `ActionMenu` - reusable menu controller; wraps clickable content or opened with `ref` and `show(ev, obj)`
- `MenuBar` - horizontal menu bar; top-level items with `data` open submenus through an internal `ActionMenu`

#### Supported functionality

##### Events

- option `handler`, component `onClick`
- leaf click order: `option.handler(pack)` first, then component `onClick(pack)`, where `pack` is `{ context, option, event }`
- submenu parent options do not fire `onClick`; hover/click opens the child menu
- clicking outside an open menu calls `onClick({ action: null, option: null })`

##### Positioning

`at` defaults to `"bottom"` and is passed to `calculatePosition` from `@svar-ui/lib-dom`

- options: `bottom`, `right`, `left`, `top`, `bottom-right`, `bottom-left`, `bottom-fit`, `point`
- submenus internally use `at="right-overlap"`

##### Context resolution (ContextMenu, ActionMenu)

- `ActionMenu.show(ev, obj)` opens from event target, sets cursor coordinates from `ev.clientX/Y`, uses `obj` as `context`
- without `obj`, locates context from a data attribute derived from `dataKey`; default `dataKey="contextId"` means `data-context-id`
- `resolver(item, event)` can replace or reject context; falsy return prevents menu opening
- `filter(option, item)` hides leaf options for a context; groups remain only when filtered children remain

##### Option's properties

- `comp` - component name; built-in is `separator`; can also be a registered string renderer or a React component
- `id` - stable key returned in callbacks and used by keyed rendering; missing ids generated during normalization
- `text`, `subtext` - default label and right-side helper text
- `icon` - appended to `wx-icon`, e.g. `"wxi wxi-content-copy"`
- `data` - creates nested submenu options
- `disabled` - adds `wx-disabled`, blocks pointer interaction
- `css` - appended to option wrapper `.wx-option`
- `handler` - per-option click handler
- deprecated `type` is copied to `comp`
- custom item components receive `option` object with all configured props

##### Common option configurations

```js
{ id: "edit", text: "Edit", icon: "wxi wxi-edit" }
{ id: "delete", text: "Delete", disabled: true }
{ id: "copy", text: "Copy", subtext: "Ctrl+C" }
{ id: "add", text: "Add", data: [/* submenu options */] }
{ comp: "separator" }
```

Custom renderers can be registered with `registerMenuItem("user", UserMenuItem)` and referenced as `comp: "user"`, or `comp` can be set to a React component directly.

#### Public Types

```ts
import type { ComponentType, ReactNode } from "react";

export interface IMenuOption {
	id?: string | number;
	text?: string;
	subtext?: string;
	handler?: (ev: IMenuOptionClick) => void;
	data?: IMenuOption[];
	css?: string;
	icon?: string;
	disabled?: boolean;
	comp?: string | ComponentType<any>;
}

export interface IMenuOptionClick {
	context?: any;
	option: IMenuOption;
	event?: MouseEvent;
}

export declare const Menu: ComponentType<{
	options?: IMenuOption[];
	left?: number;
	top?: number;
	at?: string;
	parent?: HTMLElement;
	mount?: (callback: () => void) => void;
	context?: any;
	css?: string;
	onClick?: (ev: IMenuOptionClick) => void;
}>;

export declare const MenuBar: ComponentType<{
	css?: string;
	menuCss?: string;
	options?: IMenuOption[];
	onClick?: (ev: IMenuOptionClick) => void;
}>;

export declare const DropDownMenu: ComponentType<{
	options?: IMenuOption[];
	at?: string;
	css?: string;
	children?: ReactNode;
	onClick?: (ev: IMenuOptionClick) => void;
}>;

export declare const ContextMenu: ComponentType<{
	options?: IMenuOption[];
	at?: string;
	resolver?: (item: any, event: MouseEvent) => any;
	dataKey?: string;
	filter?: (option: IMenuOption, item: any) => boolean;
	css?: string;
	children?: ReactNode;
	onClick?: (ev: IMenuOptionClick) => void;
}>;

export declare const ActionMenu: ComponentType<{
	options?: IMenuOption[];
	at?: string;
	resolver?: (item: any, event: MouseEvent) => any;
	dataKey?: string;
	filter?: (option: IMenuOption, item: any) => boolean;
	css?: string;
	children?: ReactNode;
	onClick?: (ev: IMenuOptionClick) => void;
}>;

export declare function registerMenuItem(
	type: string,
	handler: ComponentType<{ option?: any }>
): void;
```

#### Styling

Import the package CSS before using the component (`all.css` includes dependency styles, `style.css` is this component only)

- for `Menu`/`DropDownMenu`/`ContextMenu`/`ActionMenu` - `css` is appended to `.wx-menu`; use it as the parent styling hook for the popup
- for `MenuBar` - `css` is appended to `.wx-menubar`; `menuCss` is passed to its popup `.wx-menu`
- `option.css` is appended to the option wrapper `.wx-option`

- menu container: `.wx-menu`
- menubar container: `.wx-menubar`
- option wrapper: `.wx-option`
- separator: `.wx-separator` and `.wx-separator-menu` (full width, `--wx-border-medium`)
- icons inside options: `.wx-icon`, `.wx-sub-icon`
- text parts: `.wx-value`, `.wx-subtext`
- state hooks: `.wx-active`, `.wx-disabled`
- `DropDownMenu`/`ActionMenu`/`ContextMenu` render through `Portal`; `css` targets the menu, not the trigger wrapper - style trigger child markup directly


```css
/* widen popup */
.app-menu {
	min-width: 200px;
}
```

#### Recipes

##### Dropdown With Click Handler

```jsx
import { DropDownMenu } from "@svar-ui/react-menu";

function DropdownExample() {
	const options = [
		{
			id: "add",
			text: "Add",
			icon: "wxi wxi-plus",
			data: [
				{ id: "add-child", text: "Child task" },
				{ id: "add-below", text: "Task below" },
			],
		},
		{ comp: "separator" },
		{ id: "edit", text: "Edit", icon: "wxi wxi-edit" },
		{ id: "delete", text: "Delete", disabled: true },
	];

	function clicked(ev) {
		if (!ev.option) return;
		console.log(ev.option.id);
	}

	return (
		<DropDownMenu options={options} onClick={clicked} at="bottom-fit">
			<button>Open</button>
		</DropDownMenu>
	);
}
```

##### Low-Level Menu Anchored To An Element

```jsx
import { useState } from "react";
import { Menu } from "@svar-ui/react-menu";

function AnchoredMenu() {
	const options = [{ id: "copy", text: "Copy" }];
	const [parent, setParent] = useState(null);

	function clicked() {
		setParent(null);
	}

	return (
		<>
			<button onClick={ev => setParent(ev.currentTarget)}>Open</button>

			{parent && <Menu options={options} parent={parent} at="right" onClick={clicked} />}
		</>
	);
}
```

##### Menu Bar With Submenus

```jsx
import { MenuBar } from "@svar-ui/react-menu";

function AppMenuBar() {
	const options = [
		{
			id: "file",
			text: "File",
			data: [
				{ id: "new", text: "New document" },
				{ id: "print", text: "Print", icon: "wxi-empty" },
			],
		},
		{ id: "help", text: "Help", data: [{ id: "hotkeys", text: "Hotkeys" }] },
		{ id: "about", text: "About" },
	];

	return (
		<MenuBar
			options={options}
			css="app-menubar"
			menuCss="app-menu"
			onClick={ev => console.log(ev.option?.id)}
		/>
	);
}
```

##### Context Menu With Resolver And Filter

```jsx
import { ContextMenu } from "@svar-ui/react-menu";

function ContextMenuExample() {
	const rows = [
		{ id: 1, kind: "project", name: "Project A" },
		{ id: 2, kind: "task", name: "Task 1" },
	];

	const options = [
		{ id: "add", text: "Add task" },
		{ id: "edit", text: "Edit" },
		{ id: "delete", text: "Delete" },
	];

	function resolver(id) {
		return rows.find(row => row.id == id);
	}

	function filter(option, row) {
		return row.kind !== "project" || option.id === "add";
	}

	return (
		<ContextMenu
			options={options}
			at="point"
			resolver={resolver}
			filter={filter}
			onClick={ev => console.log(ev.context, ev.option?.id)}
		>
			{rows.map(row => (
				<div key={row.id} data-context-id={row.id}>{row.name}</div>
			))}
		</ContextMenu>
	);
}
```

##### Programmatic Action Menu

```jsx
import { useRef, useState } from "react";
import { ActionMenu } from "@svar-ui/react-menu";

function ProgrammaticMenu() {
	const options = [
		{ id: "a", text: "Project A" },
		{ id: "b", text: "Project B" },
	];

	const [selected, setSelected] = useState(["a", "b"]);
	const menuRef = useRef(null);

	function markSelected(option, index) {
		option.icon = option.id === selected[index] ? "wxi-check" : "wxi-empty";
		return true;
	}

	function clicked(ev) {
		if (ev.option) {
			setSelected(prev => {
				const next = [...prev];
				next[ev.context] = ev.option.id;
				return next;
			});
		}
	}

	return (
		<>
			<ActionMenu options={options} filter={markSelected} onClick={clicked} ref={menuRef} />

			{selected.map((value, index) => (
				<button key={index} onClick={ev => menuRef.current.show(ev, index)}>{value}</button>
			))}
		</>
	);
}
```

##### Custom Menu Item Renderer

```jsx
// UserMenuItem.jsx
function UserMenuItem({ option }) {
	return <div className="user-option">{option.name}</div>;
}

export default UserMenuItem;
```

```jsx
import { DropDownMenu, registerMenuItem } from "@svar-ui/react-menu";
import AddUserItem from "./AddUserItem.jsx";
import UserMenuItem from "./UserMenuItem.jsx";

registerMenuItem("user", UserMenuItem);

function UserMenu() {
	const options = [
		{ id: "u1", comp: "user", name: "Alex Wolensy" },
		{ id: "add", comp: AddUserItem, name: "Add New" },
	];

	return (
		<DropDownMenu options={options}>
			<button>Select user</button>
		</DropDownMenu>
	);
}
```

#### Implementation Notes

- `ActionMenu` and `ContextMenu` ignore events whose target has `data-menu-ignore`
- `dataKey` is converted from camelCase to kebab-case for DOM attribute lookup
- `ActionMenu.show(null)` closes the active menu
- `onClick` can receive `{ option: null }`
- runtime options can carry extra fields for custom renderers


## File: toolbar/index.md

> Source: `toolbar/index.md`

Use when UI of app requires Toolbar, configuring, or modifying SVAR React Toolbar / @svar-ui/react-toolbar components

#### Package

```js
import { Toolbar, registerToolbarItem } from "@svar-ui/react-toolbar";
import "@svar-ui/react-toolbar/all.css";
```

#### Supported functionality

##### Events

- item `handler`, toolbar `onClick`, toolbar `onChange`

##### Value binding

- `values` bag of properties bound to inputs in toolbar by `item.key`, changes tracked by `onChange`

##### Overflow modes

default is `overflow="menu"`

- `menu`: when items no longer fit, trailing top-level items move into a dots menu
    - `menuText` replaces `text` only inside the overflow menu
- `wrap`: wraps to new rows
- `collapse`: never creates a dots menu; it collapses the rightmost open top-level group first, only affects top-level items that have nested `items`; plain buttons do not collapse

##### Item's properties

- `comp` - component name, built in are `button`, `icon`, `label`, `item`, `separator`, `spacer`
- `key` - bind to values by this key
- `text`, `menuText` - content of button in normal and menu modes
- `collapsed`, `layout`, `items` - used to organise groups of buttons ( like ribbons )
- `handler` - per item click handler
- `css` - css class to the button's container
- `spacer` - adds `flex:1` to the button (it takes all space)
- all extra properties passthrough to the React components

##### Common elements

Button configurations:

```js
{ comp: "button", text: "Save" }
{ comp: "button", icon: "wxi-search" }
{ comp: "button", icon: "wxi-file", text: "Load" }
{ comp: "button", text: "Apply", type: "primary" }
{ comp: "button", icon: "wxi-delete-outline", disabled: true }
{ comp: "button", icon: "wxi-content-copy", text: "Ctrl+C", menuText: "Copy" }
```

Icon configurations:

```js
{ comp: "icon", icon: "wxi-search" }
{ comp: "icon", icon: "wxi-information-outline", text: "Info" }
{ comp: "icon", icon: "wxi-content-copy", text: "Ctrl+C", menuText: "Copy" }
{ comp: "icon", icon: "wxi-delete-outline", disabled: true }
```

Label, item, separator, spacer configurations:

```js
{ comp: "label", text: "Toolbar title" }
{ comp: "label", key: "name" }
{ comp: "label", key: "name", spacer: true }
{ comp: "item", id: "done", text: "Mark as finished task" }
{ comp: "item", id: "delete", icon: "wxi-delete-outline", text: "Delete item", css: "danger" }
{ comp: "separator" }
{ comp: "spacer" }
```

`item` is a simple clickable row, not a core button, use it for menu/list-style actions, especially inside collapsed groups/header menus.

Widgets from `@svar-ui/react-core` which can be used as components: Slider, Text, CheckboxGroup, RichSelect, DatePicker, ColorPicker, ColorSelect, Checkbox, Tabs, Pager, Segmented, Switch, TwoState, Combo, MultiCombo.

#### Public Types

```ts
import type { ComponentType } from "react";

export interface IToolbarItem {
	id?: string | number;
	comp?: string | ComponentType<any>;
	icon?: string;
	css?: string;
	text?: string;
	menuText?: string;
	key?: string;
	spacer?: boolean;
	collapsed?: boolean;
	handler?: (item: IToolbarItem, value?: any) => void;
	layout?: "column";
	items?: IToolbarItem[];
	[key: string]: any;
}

export declare const Toolbar: ComponentType<{
	items?: IToolbarItem[];
	menuCss?: string;
	css?: string;
	values?: { [key: string]: any };
	overflow?: "collapse" | "wrap" | "menu";
	onClick?: (ev: { item: IToolbarItem }) => void;
	onChange?: (ev: { value: any; item: IToolbarItem }) => void;
}>;

export declare function registerToolbarItem(
	type: string,
	handler: ComponentType<any>
): void;
```

#### Styling

Import the package CSS before using the component (`all.css` includes dependency styles, `style.css` is this component only)

- toolbar `css` is appended to `.wx-toolbar`; use it as the parent styling hook
- menu `menuCss` is appended to the overflow `.wx-menu`; item `css` is appended to `.wx-tb-element` or group `.wx-tb-group`

- toolbar container: `.wx-toolbar`
- top-level item wrapper: `.wx-tb-element`
- group wrapper: `.wx-tb-group`, group body: `.wx-tb-body`
- overflow menu container in the toolbar row `.wx-menu`
- content wrapper inside the opened dropdown `wx-drop-menu`
- separator `.wx-separator` and `.wx-separator-menu`
- `layout="column"` on Toolbar makes `.wx-toolbar.wx-column`
- `layout: "column"` on a group makes `.wx-column > .wx-tb-body`
- `comp: "spacer"` renders flex filler; `spacer: true` on normal item makes its wrapper `flex: 1`

```css
/*Gap between toolbar items*/
.my-toolbar .wx-tb-element {
	padding: 2px;
}

/*padding around the whole toolbar*/
.my-toolbar {
	padding: 8px 12px; /* default is 4px */
}

/*padding for groups*/
.my-toolbar .wx-tb-body {
	gap: 4px;
}
```

#### Recipes

##### Basic Toolbar

```jsx
import { useState } from "react";
import { Toolbar } from "@svar-ui/react-toolbar";

function BasicToolbar() {
	const [message, setMessage] = useState("");
	function onClick(item) {
		setMessage(`Button '${item.id}' clicked`);
	}

	const items = [
		{ id: "label", text: "Toolbar with icon buttons" },
		{ comp: "separator" },
		{ id: "search", comp: "button", icon: "wxi-search", handler: onClick },
		{ comp: "spacer" },
		{
			id: "copy",
			comp: "icon",
			icon: "wxi-content-copy",
			handler: onClick,
		},
	];

	return <Toolbar items={items} />;
}
```

##### Per-Item Handler

```js
function onClick(item) {
	console.log(item.id);
}

const items = [
	{ id: "edit", comp: "button", icon: "wxi-edit-outline", handler: onClick },
];
```

##### Toolbar Click Handler

```jsx
<Toolbar
	items={[
		{ id: "edit", comp: "button", icon: "wxi-edit-outline" },
		{ id: "delete", comp: "button", icon: "wxi-delete-outline" },
	]}
	onClick={ev => console.log(ev.item.id)}
/>
```

##### Keyed Values

```jsx
import { useState } from "react";
// component must support `value` prop and `onChange` callback to be bound, most react-core controls fit
import { Slider } from "@svar-ui/react-core";
import { Toolbar } from "@svar-ui/react-toolbar";

function KeyedValuesToolbar() {
	const [values, setValues] = useState({ size: 15 });

	return (
		<Toolbar
			items={[{ comp: Slider, min: 0, max: 100, key: "size" }]}
			values={values}
			onChange={ev => {
				setValues(prev => ({ ...prev, [ev.item.key]: ev.value }));
				console.log(ev.item.key, ev.value);
			}}
		/>
	);
}
```

##### Common core controls

```jsx
import { Slider, Segmented, Switch } from "@svar-ui/react-core";
import { Toolbar } from "@svar-ui/react-toolbar";

function CommonControlsToolbar() {
	const options = [
		{ id: 1, label: "One" },
		{ id: 2, label: "Two" },
	];

	return (
		<Toolbar
			css="demo-toolbar"
			values={{ size: 14, mode: 1, enabled: true }}
			items={[
				{ text: "Controls" },
				{ comp: "spacer" },
				{ comp: Slider, min: 0, max: 100, key: "size" },
				{ comp: Segmented, options, key: "mode" },
				{ comp: Switch, key: "enabled" },
			]}
		/>
	);
}
```

##### Custom Component Contract

```jsx
// CustomToolbarItem.jsx
function CustomToolbarItem({
	value,
	onChange,
	onClick,
	menu,
	text = "",
	disabled = false,
}) {
	return (
		<button
			className={menu ? "in-menu" : ""}
			disabled={disabled}
			onClick={() => {
				onClick?.();
				onChange?.({ value: !value });
			}}
		>
			{text}
		</button>
	);
}

export default CustomToolbarItem;
```

```js
import CustomToolbarItem from "./CustomToolbarItem.jsx";

const items = [{ comp: CustomToolbarItem, key: "flag", text: "Toggle" }];
const values = { flag: false };
```

##### Group

```js
const items = [
	{
		text: "Align",
		items: [
			{ id: "align-left", comp: "button", icon: "wxo-align-left" },
			{ id: "align-center", comp: "button", icon: "wxo-align-center" },
			{ id: "align-right", comp: "button", icon: "wxo-align-right" },
		],
	},
];
```

##### Column Group

```js
const items = [
	{
		layout: "column",
		text: "Font",
		items: [
			{
				items: [
					{
						key: "font-family",
						comp: "richselect",
						options: fontFamilyData,
					},
					{
						key: "font-size",
						comp: "richselect",
						options: fontSizeData,
					},
				],
			},
			{
				items: [
					{ id: "font-bold", comp: "button", icon: "wxo-bold" },
					{ id: "font-italic", comp: "button", icon: "wxo-italic" },
					{
						id: "font-underline",
						comp: "button",
						icon: "wxo-underline",
					},
				],
			},
		],
	},
];
```

##### Ribbon Layout

```js
const items = [
	{
		items: [
			{
				layout: "column",
				items: [
					{
						id: "load",
						css: "bigButton",
						comp: "button",
						icon: "wxi-file",
						text: "Load",
					},
				],
			},
			{
				layout: "column",
				items: [
					{ id: "undo", comp: "button", icon: "wxo-undo" },
					{ id: "redo", comp: "button", icon: "wxo-redo" },
				],
			},
		],
	},
	{ comp: "separator" },
	{
		layout: "column",
		items: [
			{
				items: [
					{
						key: "font-family",
						comp: "richselect",
						options: fontFamilyData,
					},
				],
			},
			{ items: [{ id: "font-bold", comp: "button", icon: "wxo-bold" }] },
		],
	},
];
```

##### Initially-Collapsed Group

```js
const items = [
	{
		text: "Data",
		icon: "wxi-dots-v",
		collapsed: true,
		layout: "column",
		items: [{ id: "load" }, { id: "delete" }],
	},
];
```

##### Header Menu

```jsx
<Toolbar
	values={{ name: "Item X12-A" }}
	items={[
		{ comp: "label", spacer: true, key: "name" },
		{ comp: "separator" },
		{
			icon: "wxi-dots-v",
			collapsed: true,
			layout: "column",
			items: [
				{ id: "done", comp: "item", text: "Mark as finished task" },
				{
					id: "delete",
					comp: "item",
					css: "danger",
					text: "Delete item",
				},
			],
		},
	]}
/>
```

##### Vertical Toolbar

```jsx
<Toolbar
	layout="column"
	items={[
		{ id: "new", comp: "button", icon: "wxi-plus" },
		{ id: "edit", comp: "button", icon: "wxi-edit-outline" },
		{ comp: "separator" },
		{ id: "delete", comp: "button", icon: "wxi-delete-outline" },
	]}
/>
```


## File: layout/index.md

> Source: `layout/index.md`

Use when building, configuring, styling, or modifying SVAR React Layout / @svar-ui/react-layout components

Styles must be imported separately:

```js
import "@svar-ui/react-layout/all.css";
```

The package ships `style.css` (this component only) and `all.css` (this component plus all dependencies).

#### Package

```js
import { Layout, Cell, Panel } from "@svar-ui/react-layout";
```

Top-level exports:

- `Layout` - flex container with direction, spacing presets, padding, and optional drag resizing
- `Cell` - direct layout child with fixed or grow-based sizing and optional header
- `Panel` - collapsible `Cell` variant with an expanded header and collapsed bar

#### Supported functionality

##### Components

- `Layout` renders a full-size flex container with `direction="column"` by default; use `direction="row"` for horizontal panes.
- `Cell` and `Panel` emit `.wx-cell`; only direct `.wx-cell` children of a resizable `Layout` participate in drag resizing

##### Sizing

- `width` or `height` on `Cell`/`Panel` sets a fixed pixel size and `flex:none`.
- Without `width` and `height`, `Cell`/`Panel` uses `flex:{grow}`; `grow` defaults to `1`.
- `minWidth` and `minHeight` set CSS minimums and are read by the resizer to clamp drag ranges.
- In row layouts, fixed `width` is the usual main-axis control; in column layouts, fixed `height` is the usual main-axis control.

##### Layout spacing

- Presets are `clean`, `line`, `wide`, and `space`.
- Preset values in source: `clean` = gap 0/padding 0, `line` = gap 1/padding 0, `wide` = gap 10/padding 0, `space` = gap 10/padding 10.
- `gap` and `padding` override preset values when provided.
- When `resizable` is true, CSS gap is not rendered; 6px `.wx-resizer` elements are injected between direct cells. `padding` still applies.

##### Events and state

- if at least one cell is not flexible, it will have new size set after resizing
- resize between two flexibles cell must be resolved by `onCellResize` handler ( setting new size / flex )
- `Panel` accepts `onCollapse?: (collapsed: boolean) => void`, called after the internal collapsed state toggles.

##### Panel collapse

- Expanded `Panel` always renders `.wx-cell-header` with a toggle button; custom `header` render prop replaces label text but not the toggle.
- Collapsed row panels become a vertical bar; collapsed column panels become a horizontal bar.
- Collapsed size is controlled by `--wx-panel-collapsed-size`, default `24px`.
- Collapsed panels can't be resized

#### Public Types

```ts
import { type ReactNode, type ComponentType } from "react";

interface ILayoutProps {
	direction?: "column" | "row";
	preset?: "clean" | "line" | "wide" | "space";
	gap?: number;
	padding?: number;
	resizable?: boolean;
	css?: string;
	children: ReactNode;
	onCellResize?: (sizes: number[]) => void;
}

interface ICellProps {
	label?: string;
	width?: number;
	height?: number;
	minWidth?: number;
	minHeight?: number;
	grow?: number;
	scroll?: boolean;
	css?: string;
	children: ReactNode;
	header?: ReactNode | (() => ReactNode);
}

interface IPanelProps {
	label?: string;
	collapsed?: boolean;
	width?: number;
	height?: number;
	minWidth?: number;
	minHeight?: number;
	grow?: number;
	scroll?: boolean;
	css?: string;
	children: ReactNode;
	header?: ReactNode | (() => ReactNode);
	onCollapse?: (collapsed: boolean) => void;
}

export declare const Layout: ComponentType<ILayoutProps>;
export declare const Cell: ComponentType<ICellProps>;
export declare const Panel: ComponentType<IPanelProps>;
```

#### Styling

Import the package CSS before using the component (`all.css` includes dependency styles, `style.css` is this component only)

- `css` is appended to the component root: `.wx-layout`, `.wx-cell`, or `.wx-cell.wx-panel`.
- Layout hooks: `.wx-layout`, `.wx-layout-{preset}`, `.wx-column`, `.wx-row`.
- Cell hooks: `.wx-cell`, `.wx-cell-header`, `.wx-cell-body`.
- Panel hooks: `.wx-panel`, `.wx-panel-collapsed`, `.wx-panel-animating`, `.wx-panel-row`, `.wx-panel-column`, `.wx-panel-collapsed-bar`, `.wx-panel-toggle`, `.wx-panel-icon`, `.wx-panel-label`.
- Resizer hooks: `.wx-resizer` is inserted between direct cells; `.wx-resize-overlay` is a temporary fixed overlay during drag.
- global `.wx-scroll` sets `overflow:auto` on the component root.
- global `.wx-border` adds border
- Built-in variables: `--wx-layout-gap-color`, `--wx-layout-line-color`, `--wx-layout-resizer-hover`, `--wx-layout-resizer-active`, `--wx-panel-collapsed-size`.

```jsx
import "./AppLayout.css";

<Layout direction="row" preset="line" css="app-layout">
	<Cell label="Files" width={220} css="app-pane">Files</Cell>
	<Cell label="Editor">Editor</Cell>
</Layout>

/* AppLayout.css
.app-layout {
	--wx-layout-line-color: #d7dee8;
	--wx-layout-resizer-hover: rgba(40, 95, 170, 0.18);
	--wx-panel-collapsed-size: 30px;
}

.app-pane .wx-cell-header {
	padding: 6px 10px;
}
*/
```

#### Recipes

##### Basic Fixed And Flexible Panes

```jsx
import "./Workspace.css";
import { Layout, Cell } from "@svar-ui/react-layout";

function Workspace() {
	return (
		<div className="workspace">
			<Layout direction="row" preset="line">
				<Cell label="Sidebar" width={240} minWidth={160}>
					<nav>Navigation</nav>
				</Cell>
				<Cell label="Main" grow={3}>
					<main>Content</main>
				</Cell>
			</Layout>
		</div>
	);
}

/* Workspace.css
.workspace {
	width: 100%;
	height: 100vh;
}
*/
```

##### Resizable IDE Layout

```jsx
import { useState } from "react";
import { Layout, Cell, Panel } from "@svar-ui/react-layout";

function IdeLayout() {
	const [sidebarWidth, setSidebarWidth] = useState(220);

	return (
		<Layout
			direction="row"
			padding={6}
			resizable
			onCellResize={sizes => setSidebarWidth(sizes[0])}
		>
			<Panel label="Files" width={sidebarWidth} minWidth={120}>
				<div>File tree</div>
			</Panel>

			<Cell>
				<Layout preset="line">
					<Cell grow={3} header={() => <span>Editor</span>}>
						<div>Editor area</div>
					</Cell>
					<Panel grow={1} label="Terminal">
						<div>Terminal</div>
					</Panel>
				</Layout>
			</Cell>
		</Layout>
	);
}
```

##### Controlled Panel Collapse

```jsx
import { useState } from "react";
import { Layout, Cell, Panel } from "@svar-ui/react-layout";

function CollapseLayout() {
	const [collapsed, setCollapsed] = useState(false);

	return (
		<Layout direction="row" preset="line">
			<Panel
				label="Sidebar"
				width={220}
				minWidth={140}
				collapsed={collapsed}
				onCollapse={value => setCollapsed(value)}
			>
				<div>Sidebar content</div>
			</Panel>
			<Cell>
				<div>Main content</div>
			</Cell>
		</Layout>
	);
}
```

##### Custom Header Render Function

```jsx
import { Layout, Cell } from "@svar-ui/react-layout";

function CustomHeaderLayout() {
	return (
		<Layout>
			<Cell
				height={48}
				header={() => (
					<div className="bar">
						<span>Toolbar</span>
						<button>Save</button>
					</div>
				)}
			>
				<div>Body</div>
			</Cell>
			<Cell scroll>
				<div>Long content</div>
			</Cell>
		</Layout>
	);
}
```

##### Presets And Explicit Spacing

```jsx
import { Layout, Cell } from "@svar-ui/react-layout";

function PresetLayout() {
	return (
		<Layout direction="row" preset="space" gap={12} padding={16}>
			<Cell css="wx-border">Left</Cell>
			<Cell css="wx-border">Right</Cell>
		</Layout>
	);
}
```

#### Implementation Notes

- `Cell` renders `.wx-cell-header` and `.wx-cell-body` only when `header` or `label` is provided.
- `Panel` detects row vs column from the parent DOM class `.wx-row`; outside a `Layout`, it behaves as column-oriented.
- Resizable layouts query only `:scope > .wx-cell`, so wrapping a `Cell` or `Panel` in another element prevents it from being resized.
- Drag resizing mutates inline styles on the adjacent cells during the pointer drag. Originally flexible cells are restored after pointer up; originally fixed cells keep their dragged pixel size.


## File: grid/index.md

> Source: `grid/index.md`

Use when building, configuring, styling, or modifying SVAR React Grid / @svar-ui/react-grid data tables, toolbars, context menus, themes, inline editors, filters, sorting, selection, tree data, responsive layouts, export, or print behavior.

#### Package

```js
import {
	Grid,
	HeaderMenu,
	Tooltip,
	ContextMenu,
	Toolbar,
	Willow,
	WillowDark,
	registerInlineEditor,
	getEditorConfig,
	defaultMenuOptions,
	defaultToolbarButtons,
} from "@svar-ui/react-grid";
import "@svar-ui/react-grid/all.css";
```

#### Supported functionality

##### Grid Data And Columns

- `data` is an array of row objects; stable `row.id` is expected.
- Missing row ids are mutated into `temp://...` ids by the store.
- In tree mode, rows use nested `row.data`; the store mutates rows with `$level`, `$parent`, and `$count`.
- `columns` configure `id`, `header`, `footer`, `width`, `flexgrow`, `hidden`, `resize`, `sort`, `template`, `cell`, `editor`, `options`, `getter`, `setter`, `treetoggle`, and `draggable`.
- Cell values are read with `column.getter(row)` or `row[column.id]`.
- Cell updates write with `column.setter(row, value)` or assign `row[column.id] = value`.
- `column.options` use `{ id, label }`; display text comes from `optionsMap` unless `template` is supplied.
- `autoConfig={true}` creates columns from first data row keys except `id` and keys starting with `$` only when `columns` is empty.
- `autoConfig={object}` merges that object into every generated column only when `columns` is empty.
- Default sizes from source: `rowHeight: 37`, `columnWidth: 160`, `headerHeight: 36`, `footerHeight: 36`.

##### Header, Footer, And Layout

- `header` defaults to `true`; `footer` defaults to `false`.
- `column.header` and `column.footer` can be a string, an object, or an array of strings/objects.
- Header/footer object fields include `text`, `cell`, `css`, `rowspan`, `colspan`, `collapsible`, `collapsed`, `vertical`, and header-only `filter`.
- `column.width` produces fixed pixel width; `column.flexgrow` produces flexible width.
- `split={{ left }}` fixes the first visible columns on the left.
- Source supports `split={{ right }}` for fixed right columns; the `Grid` prop type inherits `IConfig`, which only types `split.left`.
- The grid root is `height: 100%`; the parent must provide a height for useful vertical scrolling.
- Virtual rendering is built in for rows and columns.

##### Selection

- `select` defaults to `true`; `select={false}` disables row click selection.
- `multiselect` enables Ctrl/Cmd toggle and Shift range selection.
- `selectedRows` is an initial/sync prop passed into the store; read live selection with `api.getState().selectedRows`, `api.getReactiveState().selectedRows`, or `onSelectRow`.
- Custom checkbox cells should call `api.exec("select-row", { id: row.id, toggle: true, mode: value })` and wrap the control in `data-action="ignore-click"` when row click selection should not fire.

##### Events And API

- Use `ref={apiRef}` or `init={api => ...}` to access the grid API.
- API methods: `exec`, `on`, `intercept`, `detach`, `getState`, `getReactiveState`, `setNext`, `getStores`, `getRow`, `getColumn`.
- Action names are exposed as prop callbacks by removing hyphens and prefixing `on` (camelCase in React): `select-row` -> `onSelectRow`, `request-data` -> `onRequestData`.
- Prop event callbacks receive the same payload passed to `api.exec`.
- `api.intercept(action, fn)` can return `false` to block an action before the normal handling path.
- `api.on(action, fn)` observes actions.
- Common actions: `add-row`, `delete-row`, `update-row`, `update-cell`, `select-row`, `resize-column`, `hide-column`, `sort-rows`, `filter-rows`, `search-rows`, `open-editor`, `close-editor`, `collapse-column`, `move-item`, `copy-row`, `open-row`, `close-row`, `export-data`, `scroll`, `print`, `undo`, `redo`, `request-data`.

##### Sorting And Filtering

- `column.sort: true` enables header click sorting.
- `column.sort: (a, b) => 1 | -1 | 0` supplies custom sort logic.
- Ctrl/Cmd-click on sortable headers adds multi-sort marks.
- `sortMarks` shape is `{ [columnId]: { order: "asc" | "desc", index?: number } }`.
- Header filters are configured as `header: { filter: "text" }` or `header: { filter: { type, config } }`.
- Built-in filter types: `text`, `richselect`, `datepicker`.
- `filter.config` is forwarded to the underlying React Core control.
- `richselect` filter options come from `filter.config.options`, then `column.options`, then unique values in grid data.
- `api.exec("filter-rows", {})` clears all filters.
- `api.exec("filter-rows", { key, value })` updates `filterValues[key]` and applies the generated column filters.
- `api.exec("filter-rows", { filter })` applies a custom row predicate.

##### Inline Editors

- Double-clicking a cell runs `open-editor` for the row and column.
- Built-in editor names: `text`, `combo`, `datepicker`, `richselect`, `multiselect`.
- `column.editor` can be a string, `{ type, config }`, or `(row, column) => editor | null`.
- Returning `null` from an editor handler makes that cell non-editable.
- `combo`, `richselect`, and `multiselect` use `column.options` with `{ id, label }`.
- `multiselect` expects the cell value to be an array of option ids.
- Editor `config.template` renders option/value text; `config.cell` renders custom option/value components; `config.dropdown` is passed to dropdown-based editors.
- `datepicker` supports `config.buttons` with `["clear" | "today"]`.
- `registerInlineEditor(type, Component)` registers a custom editor component.

##### Custom Components

- `column.cell` receives `{ api, row, column, onAction }`.
- Header/footer `cell` receives `{ api, cell, column, row, onAction }`.
- Calling `onAction({ action, data })` inside a custom cell executes `api.exec(action, data)`.
- Custom action names are routed to prop callbacks, for example `onAction({ action: "custom-check", data })` -> `onCustomCheck={...}`.
- `overlay` can be text or a component; overlay components receive `onAction`.
- `Tooltip` can use default cell text, `column.tooltip(row)`, or `content={Component}`; tooltip content receives `{ data }`.

##### Toolbar And Menus

- `Toolbar` wraps `@svar-ui/react-toolbar` and defaults to `defaultToolbarButtons`.
- `Toolbar` auto-runs `handleAction(api, item.id)` before calling its own `onClick`.
- Default toolbar actions: `add-row`, `open-editor`, `delete-row`, `copy-row`, `cut-row`, `paste-row`, `move-item:up`, `move-item:down`, `undo`, `redo`.
- `Toolbar` filters move actions when `reorder` is off and undo/redo when `undo` is off.
- `ContextMenu` wraps `@svar-ui/react-menu` and defaults to `defaultMenuOptions`.
- `ContextMenu` defaults `at="point"` and uses row `data-context-id` through the base menu's default `dataKey`.
- The default resolver selects the right-clicked row if it is not already selected.
- `ContextMenu` auto-runs `handleAction(api, ev.action.id)` before calling its own `onClick`; base menu events also expose `ev.option`.
- Default context menu actions: `add-row:before`, `add-row:after`, `copy-row`, `cut-row`, `paste-row`, `move-item:up`, `move-item:down`, `delete-row`.
- `HeaderMenu` wraps grid content and opens on header right-click using `data-header-id`; clicking an item runs `hide-column`.
- `HeaderMenu columns={{ id: true }}` limits which columns appear in the hide/show menu.

##### Saving

- `RestDataProvider` from `@svar-ui/grid-data-provider` persists data changes to a REST backend.
- Wire it once with `api.setNext(provider)` in `init`; the provider then forwards every data action (`add-row`, `update-row`, `update-cell`, `delete-row`, `move-item`, `copy-row`, `sort-rows`, etc.) emitted on the event bus as the matching REST call. No per-action save handlers needed.
- Initial load uses `provider.getData()`; the optional second constructor arg is a per-row coercion callback (e.g. cast string fields to numbers).

```js
import { RestDataProvider } from "@svar-ui/grid-data-provider";

const provider = new RestDataProvider("/api/films");

function init(api) {
	api.setNext(provider); // forwards all row mutations to REST
}
```

##### Themes

- Theme components: `Willow`, `WillowDark`.
- Each theme accepts `fonts?: boolean` and optional children.
- Theme wrappers delegate to `@svar-ui/react-core` and add grid CSS variables to `.wx-material-theme`, `.wx-willow-theme`, or `.wx-willow-dark-theme`.
- If no `wx-theme` context exists, the store calls `suggestSkin()` and defaults to Willow.

#### Public Types

```ts
import type { ComponentType, ComponentProps, ReactNode } from "react";
import { ContextMenu as BaseContextMenu } from "@svar-ui/react-menu";
import { Toolbar as BaseToolbar } from "@svar-ui/react-toolbar";

import type {
	IColumn,
	IRow,
	IApi,
	ISizeConfig,
	TMethodsConfig,
	IConfig,
	TEditorType,
	TEditorConfig,
	IColumnEditor,
	IHeaderCell,
} from "@svar-ui/grid-store";

export * from "@svar-ui/grid-store";

export interface IColumnEditorConfig extends IColumnEditor {
	config?: IColumnEditor["config"] & {
		cell?: ComponentType<{
			data: any;
			onAction: (ev: {
				action?: any;
				data?: { [key: string]: any };
			}) => void;
		}>;
	};
}

export type TEditorHandlerConfig = (
	row?: IRow,
	column?: IColumn
) => TEditorType | IColumnEditorConfig | null;

export interface ICellProps {
	api: IApi;
	row: IRow;
	column: IColumn;
	onAction: (ev: { action?: any; data?: { [key: string]: any } }) => void;
}

export interface IHeaderCellConfig extends IHeaderCell {
	cell?: ComponentType<
		ICellProps & {
			cell: Omit<IHeaderCell, "cell">;
		}
	>;
}

export type TColumnHeaderConfig =
	| string
	| IHeaderCellConfig
	| (string | IHeaderCellConfig)[];

export interface IColumnConfig
	extends Omit<
		IColumn,
		"left" | "right" | "fixed" | "optionsMap" | "header" | "footer"
	> {
	cell?: ComponentType<ICellProps>;
	editor?: TEditorType | IColumnEditorConfig | TEditorHandlerConfig;
	header?: TColumnHeaderConfig;
	footer?: TColumnHeaderConfig;
}

export declare const Grid: ComponentType<
	{
		rowStyle?: (row: any) => string;
		columnStyle?: (column: IColumn) => string;
		cellStyle?: (row: any, column: IColumn) => string;
		multiselect?: boolean;
		autoConfig?: boolean | IColumnConfig;
		header?: boolean;
		footer?: boolean;
		reorder?: boolean;
		autoRowHeight?: boolean;
		responsive?: {
			[key: string]: {
				sizes?: ISizeConfig;
				columns?: IColumnConfig[];
			};
		};
		init?: (api: IApi) => void;

		overlay?: string | ComponentType;
		columns: IColumnConfig[];
		hotkeys?:
			| false
			| { [key: string]: ((e?: KeyboardEvent) => void) | boolean };
	} & IConfig &
		GridActions<TMethodsConfig>
>;

export declare const HeaderMenu: ComponentType<{
	columns?: { [key: string]: boolean };
	api?: IApi;
	children?: ReactNode;
}>;

export declare const ContextMenu: ComponentType<
	ComponentProps<typeof BaseContextMenu> & {
		api?: IApi;
	}
>;

export declare const Toolbar: ComponentType<
	ComponentProps<typeof BaseToolbar> & {
		api?: IApi;
	}
>;

export declare const Tooltip: ComponentType<{
	content?: ComponentType;
	api?: IApi;
	children?: ReactNode;
}>;

export declare const Willow: ComponentType<{
	fonts?: boolean;
	children?: ReactNode;
}>;

export declare const WillowDark: ComponentType<{
	fonts?: boolean;
	children?: ReactNode;
}>;

export declare function registerInlineEditor(
	type: string,
	component: ComponentType<{
		editor: TEditorConfig;
		onSave?: (ignoreFocus: boolean) => void;
		onCancel?: () => void;
		onApply?: (value: any) => void;
		onAction?: (ev: {
			action: string;
			data?: { [key: string]: any };
		}) => void;
	}>
): void;

/* get component events from store actions*/
type RemoveHyphen<S extends string> = S extends `${infer Head}-${infer Tail}`
	? `${Head}${Capitalize<RemoveHyphen<Tail>>}`
	: S;

type EventName<K extends string> = `on${Capitalize<RemoveHyphen<K>>}`;

export type GridActions<TMethodsConfig extends Record<string, any>> = {
	[K in keyof TMethodsConfig as EventName<K & string>]?: (
		ev: TMethodsConfig[K]
	) => void;
} & {
	[key: `on${string}`]: (ev?: any) => void;
};
```

Common public action payloads from `@svar-ui/grid-store`:

```ts
export type IDataMethodsConfig = CombineTypes<
	{
		["update-cell"]: {
			id: TID;
			column: TID;
			value: string | number | Date;
			eventSource?: string;
		};
		["add-row"]: {
			id?: TID;
			before?: TID;
			after?: TID;
			row: IRow;
			select?: boolean;
			eventSource?: string;
		};
		["delete-row"]: { id: TID; eventSource?: string };
		["update-row"]: {
			id: TID;
			row: Record<string, any>;
			eventSource?: string;
		};
		["select-row"]: {
			id: TID;
			toggle?: boolean;
			range?: boolean;
			mode?: boolean;
			show?: boolean;
			column?: TID;
		};
		["resize-column"]: {
			id: TID;
			width?: number;
			auto?: boolean | "data" | "header";
			maxRows?: number;
			inProgress?: boolean;
			eventSource?: string;
		};
		["hide-column"]: {
			id: TID;
			mode?: boolean;
			eventSource?: string;
		} & ISkipUndoAction;
		["sort-rows"]: {
			key: TID;
			order?: "asc" | "desc";
			add?: boolean | number;
			sort?: (a: IRow, b: IRow) => 1 | -1 | 0;
		};
		["search-rows"]: {
			search: string;
			columns?: Partial<Record<TID, boolean>>;
		};
		["open-editor"]: {
			id: TID;
			column?: TID;
		};
		["close-editor"]: {
			ignore?: boolean;
		};
		["editor"]: {
			value: any;
		};
		["filter-rows"]: {
			filter?: any;
			key?: TID;
			value?: any;
		};
		["collapse-column"]: {
			id: TID;
			row?: number;
			mode?: boolean;
			eventSource?: string;
		};
		["move-item"]: {
			id: TID;
			target?: TID;
			mode?: "before" | "after" | "up" | "down";
			inProgress?: boolean;
			eventSource?: string;
		};
		["copy-row"]: {
			id: TID;
			target?: TID;
			mode?: "before" | "after";
			eventSource?: string;
		};
		["open-row"]: {
			id: TID;
			nested?: boolean;
			eventSource?: string;
		};
		["close-row"]: {
			id: TID;
			nested?: boolean;
			eventSource?: string;
		};
		["export-data"]: IExportOptions;
		["scroll"]: {
			row?: TID;
			column?: TID;
		};
		["hotkey"]: {
			key: string;
			event: any;
			isInput?: boolean;
		};
		["focus-cell"]: {
			row?: TID;
			column?: TID;
			eventSource?: string;
		};
		["print"]: IPrintConfig;
		["undo"]: void;
		["redo"]: void;
		["request-data"]: {
			row: {
				start: number;
				end: number;
			};
		};
	},
	{
		[key: string]: any;
	}
>;
```

#### Styling

Import the package CSS before using the component (`all.css` includes dependency styles, `style.css` is this component only)

- `Grid` has no `css`, `class`, or `style` passthrough prop.
- Style through wrapper elements, `rowStyle`, `columnStyle`, `cellStyle`, header/footer cell `css`, and theme CSS variables.
- `rowStyle(row)` appends a class to `.wx-row`.
- `columnStyle(column)` appends a class to body, header, footer, and print cells.
- `cellStyle(row, column)` appends a class to body and print cells only.
- Header/footer cell `css` appends to the header/footer `.wx-cell`.
- `IColumn.css` exists in store types and is used in auto-width measurement helpers, but it is not appended to rendered body cells by `Cell`.

Stable class hooks visible in source:

- root and containers: `.wx-grid`, `.wx-responsive-{level}`, `.wx-table-box`, `.wx-scroll`, `.wx-header-wrapper`, `.wx-header`, `.wx-footer`, `.wx-h-row`, `.wx-f-row`, `.wx-body`, `.wx-data`, `.wx-row`
- cells: `.wx-cell`, `.wx-selected`, `.wx-inactive`, `.wx-autoheight`, `.wx-fixed`, `.wx-fixed-right`, `.wx-shadow`, `.wx-rowspan`, `.wx-colspan`, `.wx-vertical`, `.wx-collapsed`, `.wx-filter`
- header controls: `.wx-grip`, `.wx-sort`, `.wx-order`, `.wx-collapse`
- body controls: `.wx-draggable`, `.wx-draggable-stub`, `.wx-table-tree-toggle`, `.wx-search`
- wrappers: `.wx-overlay`, `.tooltip`, `.wx-table-menu`
- print: `.wx-print-container`, `.wx-print-grid`, `.wx-print-grid-wrapper`, `.wx-print-cell`, `.wx-print-cell-header`, `.wx-print-cell-footer`, `.wx-print-cell-filter`, `.wx-print-filter`, `.wx-print-draggable`, `.wx-print-grid-tree-toggle`

Layout defaults from source:

- `.wx-grid` height is `100%`.
- `.wx-table-box` is `display: flex`, `flex-direction: column`, `height: 100%`, `position: relative`, `overflow: hidden`, with `border: var(--wx-table-cell-border)`.
- `.wx-scroll` is `position: relative`, `flex: 1`, and owns scrollbars.
- `.wx-row` is `display: flex` and gets row height from `sizes.rowHeight` or `row.rowHeight`.
- `.wx-cell` default body padding is `8px`, with overflow hidden and nowrap text.
- Header/footer `.wx-cell` default padding is `8px`; filter header cells use `4px`.
- Column widths are inline styles from `width`, `min-width`, `flex-grow`, and sticky left/right offsets.

Grid CSS variables set by theme components:

```css
--wx-table-select-background
--wx-table-select-color
--wx-table-border
--wx-table-select-border
--wx-table-header-border
--wx-table-header-cell-border
--wx-table-footer-cell-border
--wx-table-cell-border
--wx-header-font-weight
--wx-table-header-background
--wx-table-fixed-column-border
--wx-table-editor-dropdown-border
--wx-table-editor-dropdown-shadow
--wx-table-drag-over-background
--wx-table-drag-zone-shadow
```

Scoped styling pattern:

```jsx
import "./OrdersGrid.css";

<div className="orders-grid">
	<Grid data={data} columns={columns} rowStyle={row => (row.priority ? "is-priority" : "")} />
</div>

/* OrdersGrid.css
.orders-grid {
	height: 420px;
}

.orders-grid .wx-row.is-priority:not(.wx-selected) .wx-cell {
	background: #fff7d6;
}

.orders-grid .wx-header .wx-cell {
	padding: 6px 8px;
}
*/
```

#### Recipes

##### Basic Grid

```jsx
import { Grid } from "@svar-ui/react-grid";

function BasicGrid() {
	const data = [
		{ id: 1, name: "Alex Brown", year: 1974 },
		{ id: 2, name: "Maria Ford", year: 1988 },
	];

	const columns = [
		{ id: "name", header: "Name", flexgrow: 1, sort: true },
		{ id: "year", header: "Year", width: 100, sort: true },
	];

	return (
		<div style={{ height: 360 }}>
			<Grid data={data} columns={columns} />
		</div>
	);
}
```

##### API, Events, And Selection

```jsx
import { useRef, useState } from "react";
import { Grid } from "@svar-ui/react-grid";

function ApiGrid() {
	const apiRef = useRef(null);
	const [selected, setSelected] = useState([]);

	const data = [
		{ id: 1, city: "London" },
		{ id: 2, city: "Paris" },
	];
	const columns = [{ id: "city", header: "City", flexgrow: 1 }];

	function init(grid) {
		grid.intercept("select-row", ev => {
			if (ev.id === 1) return false;
		});
	}

	function addRow() {
		apiRef.current.exec("add-row", { row: { city: "New city" } });
	}

	function updateSelected() {
		setSelected(apiRef.current.getState().selectedRows);
	}

	return (
		<>
			<button onClick={addRow}>Add</button>
			<Grid
				data={data}
				columns={columns}
				init={init}
				ref={apiRef}
				multiselect
				onSelectRow={updateSelected}
			/>
		</>
	);
}
```

##### Sort, Header Filters, And Inline Editors

```jsx
import { Grid } from "@svar-ui/react-grid";

function SortFilterGrid() {
	const countries = [
		{ id: "pl", label: "Poland" },
		{ id: "us", label: "United States" },
	];

	const data = [
		{ id: 1, name: "Alex", country: "pl", joined: new Date() },
		{ id: 2, name: "Sam", country: "us", joined: new Date() },
	];

	const columns = [
		{
			id: "name",
			header: [{ text: "Name" }, { filter: "text" }],
			editor: "text",
			sort: true,
			flexgrow: 1,
		},
		{
			id: "country",
			header: {
				filter: { type: "richselect", config: { options: countries } },
			},
			editor: "richselect",
			options: countries,
			width: 180,
		},
		{
			id: "joined",
			header: { text: "Joined" },
			editor: { type: "datepicker", config: { buttons: ["today", "clear"] } },
			template: value => (value ? value.toLocaleDateString() : ""),
			width: 140,
		},
	];

	return <Grid data={data} columns={columns} />;
}
```

##### Custom Body, Header, And Footer Cells

```jsx
// CheckCell.jsx
import { Checkbox } from "@svar-ui/react-core";

function CheckCell({ api, row, column, onAction }) {
	function change({ value }) {
		api.exec("update-cell", { id: row.id, column: column.id, value });
		onAction({
			action: "checked-change",
			data: { row: row.id, column: column.id, value },
		});
	}

	return (
		<div data-action="ignore-click">
			<Checkbox value={row[column.id]} onChange={change} />
		</div>
	);
}

export default CheckCell;
```

```jsx
import { Grid } from "@svar-ui/react-grid";
import CheckCell from "./CheckCell.jsx";
import HeaderTitle from "./HeaderTitle.jsx";

function CustomCellGrid() {
	const data = [{ id: 1, checked: true, name: "Alex" }];
	const columns = [
		{
			id: "checked",
			width: 44,
			cell: CheckCell,
			header: { cell: HeaderTitle, text: "Active" },
			footer: { text: "Active", css: "center" },
		},
		{ id: "name", header: "Name", flexgrow: 1 },
	];

	return (
		<Grid
			data={data}
			columns={columns}
			footer
			onCheckedChange={ev => console.log(ev.row, ev.value)}
		/>
	);
}
```

##### Custom Inline Editor

```jsx
// ColorEditor.jsx
import { useEffect, useRef, useState } from "react";
import { ColorBoard, Dropdown } from "@svar-ui/react-core";
import { clickOutside } from "@svar-ui/lib-dom";

function ColorEditor({ editor, onSave, onApply, onCancel }) {
	const [value, setValue] = useState(editor.value);
	const containerRef = useRef(null);

	function change({ value, input }) {
		setValue(value);
		if (input) onApply(value);
		else onSave();
	}

	useEffect(() => {
		if (!containerRef.current) return;
		const cleanup = clickOutside(containerRef.current, () => onSave(true));
		return () => cleanup?.destroy?.() ?? cleanup?.();
	}, [onSave]);

	return (
		<>
			<button onClick={onCancel}>{value}</button>
			<Dropdown width="auto" trackScroll onCancel={onCancel}>
				<div ref={containerRef}>
					<ColorBoard value={value} onChange={change} button />
				</div>
			</Dropdown>
		</>
	);
}

export default ColorEditor;
```

```jsx
import { Grid, registerInlineEditor } from "@svar-ui/react-grid";
import ColorEditor from "./ColorEditor.jsx";

registerInlineEditor("color", ColorEditor);

function ColorGrid() {
	const data = [{ id: 1, color: "#35D6A7" }];
	const columns = [
		{ id: "color", header: "Color", editor: "color", width: 180 },
	];

	return <Grid data={data} columns={columns} />;
}
```

##### Toolbar, Context Menu, And Header Menu

```jsx
import { useRef } from "react";
import { Grid, Toolbar, ContextMenu, HeaderMenu } from "@svar-ui/react-grid";

function ToolbarGrid() {
	const apiRef = useRef(null);
	const data = [
		{ id: 1, name: "Alex" },
		{ id: 2, name: "Sam" },
	];
	const columns = [
		{ id: "name", header: "Name", editor: "text", flexgrow: 1 },
	];

	return (
		<>
			<Toolbar api={apiRef.current} />
			<ContextMenu api={apiRef.current}>
				<HeaderMenu api={apiRef.current}>
					<Grid data={data} columns={columns} ref={apiRef} multiselect reorder undo />
				</HeaderMenu>
			</ContextMenu>
		</>
	);
}
```

##### Dynamic Data Loading

```jsx
import { useState } from "react";
import { Grid } from "@svar-ui/react-grid";

function DynamicGrid() {
	const raw = Array.from({ length: 10000 }, (_, id) => ({
		id,
		name: `Row ${id}`,
	}));

	const columns = [{ id: "name", header: "Name", flexgrow: 1 }];
	const [data, setData] = useState([]);

	function provideData({ row }) {
		setData(raw.slice(row.start, row.end));
	}

	return (
		<div style={{ height: 500 }}>
			<Grid
				data={data}
				columns={columns}
				dynamic={{ rowCount: raw.length }}
				onRequestData={provideData}
			/>
		</div>
	);
}
```

##### Responsive Columns And Fixed Columns

```jsx
import "./GridShell.css";
import { Grid } from "@svar-ui/react-grid";

function ResponsiveGrid() {
	const data = [{ id: 1, name: "Alex", email: "alex@example.com" }];
	const columns = [
		{ id: "id", width: 50 },
		{ id: "name", header: "Name", flexgrow: 1 },
		{ id: "email", header: "Email", flexgrow: 1 },
	];

	const responsive = {
		600: {
			columns: [
				{ id: "id", width: 50 },
				{ id: "name", header: "Name", flexgrow: 1 },
				{ id: "email", header: "Email", hidden: true },
			],
			sizes: { rowHeight: 44, columnWidth: 140 },
		},
	};

	return (
		<div className="grid-shell">
			<Grid data={data} columns={columns} responsive={responsive} split={{ left: 1 }} />
		</div>
	);
}

/* GridShell.css
.grid-shell {
	height: 420px;
}

.grid-shell .wx-grid.wx-responsive-600 .wx-cell {
	padding-top: 10px;
	padding-bottom: 10px;
}
*/
```

##### Tree Grid

```jsx
import { useRef } from "react";
import { Grid } from "@svar-ui/react-grid";

function TreeGrid() {
	const apiRef = useRef(null);
	const data = [
		{
			id: 1,
			name: "Project",
			open: true,
			data: [{ id: 2, name: "Task" }],
		},
	];

	const columns = [
		{ id: "name", header: "Name", treetoggle: true, flexgrow: 1 },
	];

	return (
		<>
			<button onClick={() => apiRef.current.exec("open-row", { id: 1, nested: true })}>
				Open
			</button>
			<button onClick={() => apiRef.current.exec("close-row", { id: 1, nested: true })}>
				Close
			</button>

			<Grid data={data} columns={columns} ref={apiRef} tree />
		</>
	);
}
```

##### External Editor From Grid Columns

```jsx
import { useRef, useState } from "react";
import { Grid, getEditorConfig } from "@svar-ui/react-grid";
import { Editor } from "@svar-ui/react-editor";

function ExternalEditorGrid() {
	const apiRef = useRef(null);
	const [editing, setEditing] = useState(null);

	const data = [{ id: 1, name: "Alex" }];
	const columns = [
		{ id: "name", header: "Name", editor: "text", flexgrow: 1 },
	];

	function init(grid) {
		grid.intercept("open-editor", ({ id }) => {
			setEditing(grid.getRow(id));
			return false;
		});
	}

	return (
		<>
			<Grid data={data} columns={columns} init={init} ref={apiRef} />

			{editing && (
				<Editor
					values={editing}
					items={getEditorConfig(columns)}
					onSave={({ values }) =>
						apiRef.current.exec("update-row", { id: editing.id, row: values })}
				/>
			)}
		</>
	);
}
```

#### Implementation Notes

- `Grid` reinitializes the store reactively from props; changing `data`, `columns`, `sizes`, `selectedRows`, `sortMarks`, `filterValues`, `split`, `tree`, `undo`, or `reorder` can reset or recalculate store state.
- When `data` identity changes, the store clears `_filterIds`, `filterValues`, `sortMarks`, and `search`, and resets history.
- Header/footer configs are copied and normalized internally, but source `columns` are mutated for `optionsMap`; row objects can also be mutated for generated ids and tree metadata.
- `column.tooltip` is used by `Tooltip` but is not present in `IColumn` types.
- `HeaderMenu` uses menu item `type: "table-header"`


## File: editor/index.md

> Source: `editor/index.md`

Use when building, configuring, styling, or modifying SVAR React Editor / @svar-ui/react-editor forms, field items, validation, save flows, panels, toolbars, sections, batches, or custom editor item renderers.

#### Package

```js
import {
	Editor,
	registerEditorItem,
	Willow,
	WillowDark,
} from "@svar-ui/react-editor";
import "@svar-ui/react-menu/all.css";
```

#### Supported functionality

##### Components

- `Editor` - main editor shell with inline, sidebar, or modal placement, optional top/bottom toolbars, sections, columns layout, validation, hotkeys, and save flow.
- `registerEditorItem(type, handler)` - registers a React component for `item.comp`.
- `Willow`, `WillowDark` - wrappers around matching `@svar-ui/react-core` themes

##### Built-in item components

- `text` - registered to `Text` from `@svar-ui/react-core`; default when `comp` is omitted.
- `textarea` - registered to `TextArea` from `@svar-ui/react-core`.
- `checkbox` - registered to `Checkbox` from `@svar-ui/react-core`.
- `section` - expandable section header; toggles items whose `section` matches its `key`.
- `readonly` - read-only field renderer used when `readonly={true}`.
- `hidden` - special `comp`; participates in value extraction/diffing but is filtered from rendering.

Common item configurations:

```js
{ comp: "text", key: "name", label: "Name" }
{ comp: "textarea", key: "descr", label: "Description", config: { placeholder: "Add description" } }
{ comp: "checkbox", key: "admin", label: "Is Admin" }
{ comp: "hidden", key: "state" }
{ comp: "section", key: "details", label: "Details", activeSection: true }
{ comp: "text", key: "email", label: "Email", section: "details" }
```

##### External and custom item components

- `item.comp` can be a registered string or a React component directly, use `registerEditorItem` to link component to string
- Normal field components receive `value`, `onChange`, `error`, all item fields, and promoted `config` fields; `label` is set to `undefined`
- `section` and `readonly` receives all item fields, and `onClick` for section toggling.
- A custom item must call `onChange({ value })`; it may include `input` to mark input-origin (in-progress) updates.

##### Values and binding

- `values` is an object; each rendered editor reads and writes `values[item.key]`
- String keys containing dots use nested getter/setter functions, for example `key: "user.name"` reads/writes `values.user.name`.
- `config` is shallow-merged into the item before rendering, so `config: { placeholder: "Name" }` becomes a direct prop.
- Custom `getter` and `setter` functions on an item replace the default key access.
- `labelTemplate(value)` replaces the displayed label for normal fields.
- `options` are passed through to item components and are also used by `readonly` to map `value` to `option.label` by matching `option.id`.

##### Events and save flow

- Field change order: child item `onChange({ value, input? })` -> editor `onChange({ key, value, update, input? })` -> diff/validation -> save handling.
- `onChange` can replace `ev.update` to update multiple fields from one field change.
- With `autoSave={true}`, valid changes are written back to the original `values` object and `onSave({ changes, values })` fires immediately.
- With `autoSave={false}`, changed keys stay in `notSaved` until "save" button click ( toolbar item `id: "save"` ) runs validation and save.
- Toolbar action order: internal save or section toggle is handled first, then `onAction({ item, values, changes })` fires.
- Parent code must hide modal/sidebar editors in `onAction`; `cancel`, `close`, and custom actions do not remove the component themselves.
- `onValidation({ errors, values })` fires when validation result changes; `errors` can be `null`.
- Runtime `changes` is an array of changed keys

##### Validation

- `required: true` fails when `!values[key]`
- `validation(value)` must return truthy for valid values.
- `validationMessage` overrides the displayed error text.
- Required errors use `{ errorType: "required" }`; custom validation errors use `{ errorType: "validation" }`.

##### Sections and batches

- A `section` item toggles all items whose `section` equals the section item `key`.
- `activeSection: true` opens a section initially.
- Normal sections can be toggled independently.
- `sectionMode: "accordion"` opens one section and closes other sections; an open accordion section does not close itself on click.
- `sectionMode: "exclusive"` shows only the active section header and its children.
- `activeBatch` hides every item whose `batch` does not equal `activeBatch`; when `activeBatch` is set, items without a matching `batch` are hidden.

##### Layout, placement, toolbar, and hotkeys

- `placement="inline"` renders `.wx-inline-form`; `placement="sidebar"` renders inside `SideArea`; `placement="modal"` renders inside `ModalArea`.
- `layout="columns"` splits items by `item.column`: `"left"` goes to `.wx-left`, everything else goes to `.wx-right`.
- `topBar` and `bottomBar` accept `false`, `true`, or `{ items: IToolbarItem[] }`; toolbar items are passed to `@svar-ui/react-toolbar`.
- Automatic default bars are generated only when `topBar === true && bottomBar === true`.
- Automatic manual-save modal uses bottom `{ spacer, save, cancel }`; modal columns use top `{ spacer, save, cancel }`; inline/sidebar manual save uses top `{ spacer, cancel, save }`; auto-save and read-only use top `{ spacer, close }`.
- Toolbar `onChange({ item, value })` is mapped into editor field changes as `{ key: item.key, value }`, so toolbar controls can edit `values`.
- Default hotkeys are enabled unless `hotkeys={false}`: `ctrl+s` triggers save, `escape` triggers cancel/close, and `delete` triggers a `delete` toolbar item when present.
- Custom `hotkeys` are merged with defaults.
- `focus={true}` selects and focuses the first enabled input, textarea, or select after mount.
- Editor `children` render above generated fields inside the content area; demos use this for tabs, segmented controls, and external toolbars.

#### Public Types

```ts
import type { ComponentType, ReactNode } from "react";
import type { IToolbarItem } from "@svar-ui/react-toolbar";

export declare const Editor: ComponentType<{
	values?: Record<string, any>;
	items?: {
		comp?: string | ComponentType<any>;
		key?: string;
		label?: string;
		labelTemplate?: (value: any) => string;
		column?: "right" | "left";
		batch?: string | number;
		hidden?: boolean;
		section?: string;
		sectionMode?: "accordion" | "exclusive";
		activeSection?: boolean;
		options?: {
			id?: string | number;
			label?: string;
			[key: string]: any;
		}[];
		required?: boolean;
		validation?: (value: any) => boolean;
		validationMessage?: string;
		config?: {
			[key: string]: any;
		};
		[key: string]: any;
	}[];
	css?: string;
	activeBatch?: string | number;
	topBar?: boolean | { items: IToolbarItem[] };
	bottomBar?: boolean | { items: IToolbarItem[] };
	autoSave?: boolean;
	layout?: "default" | "columns";
	placement?: "inline" | "sidebar" | "modal";
	readonly?: boolean;
	focus?: boolean;
	onChange?: (ev: {
		key: string;
		value: any;
		update: Record<string, any>;
		input?: boolean;
	}) => void;
	onSave?: (ev: {
		changes: string[];
		values: Record<string, any>;
	}) => void;
	onAction?: (ev: {
		item: IToolbarItem;
		values: Record<string, any>;
		changes: string[];
	}) => void;
	onValidation?: (ev: {
		errors: {
			[key: string]: {
				errorType: "validation" | "required";
			};
		};
		values: Record<string, any>;
	}) => void;
	hotkeys?:
		| false
		| { [key: string]: ((e?: KeyboardEvent) => void) | boolean };
	children?: ReactNode;
}>;

export declare function registerEditorItem(
	type: string,
	handler: ComponentType<any>
): void;

export declare const Willow: ComponentType<{
	fonts?: boolean;
	children?: ReactNode;
}>;

export declare const WillowDark: ComponentType<{
	fonts?: boolean;
	children?: ReactNode;
}>;
```

#### Styling

Import the package CSS before using the component (`all.css` includes dependency styles, `style.css` is this component only)

- `Editor` `css` is appended to the root panel: `.wx-inline-form {css}` for inline placement, `.wx-panel {css}` for modal/sidebar placement.
- Root panel classes: `.wx-inline-form`, `.wx-panel`.
- Content container: `.wx-content`; columns mode adds `.wx-layout-columns`.
- Form body: `.wx-sections` with `--wx-field-width: 600px`.
- Columns layout: `.wx-cols`, `.wx-left`, `.wx-right`; source defaults include `.wx-left { min-width: 640px }`, `.wx-right { width: 364px; background: var(--wx-background-alt) }`.
- Toolbar wrapper: `.wx-editor-toolbar`, `.wx-topbar`, `.wx-bottom`
- Section header: `.wx-section`, `.wx-section-active`, nested `.wx-icon`
- Validation and empty states: `.wx-message`, `.wx-overlay`

```jsx
import "./TaskEditor.css";

<Editor items={items} values={values} layout="columns" css="task-editor" />

/* TaskEditor.css
.task-editor .wx-sections {
	--wx-field-width: 520px;
	margin: 8px 16px 0;
}

.task-editor .wx-editor-toolbar {
	padding: 0 16px;
}

.task-editor .wx-cols .wx-left {
	min-width: 520px;
}

.task-editor .wx-cols .wx-right {
	width: 320px;
	margin-left: 20px;
}
*/
```

#### Recipes

##### Basic Inline Editor

```jsx
import { useState } from "react";
import { Editor } from "@svar-ui/react-editor";

function BasicEditor() {
	const items = [
		{ comp: "text", key: "name", label: "Name" },
		{ comp: "checkbox", key: "admin", label: "Is Admin" },
		{ comp: "textarea", key: "descr", label: "Description" },
	];

	const [values, setValues] = useState({
		name: "John Doe",
		admin: true,
		descr: "Notes",
	});

	return <Editor items={items} values={values} topBar={false} />;
}
```

##### Manual Save With Validation

```jsx
import { useState } from "react";
import { Editor } from "@svar-ui/react-editor";

function ManualSaveEditor() {
	const items = [
		{ comp: "text", key: "firstName", label: "First name", required: true },
		{
			comp: "text",
			key: "email",
			label: "Email",
			validation: value => value.includes("@"),
			validationMessage: "Incorrect email",
		},
	];

	const [values, setValues] = useState({ firstName: "John", email: "john@example.org" });
	const [visible, setVisible] = useState(true);

	function handleAction({ item, changes }) {
		if (item.id === "save" && changes.length) return;
		setVisible(false);
	}

	function handleSave({ values: next }) {
		setValues(next);
		setVisible(false);
	}

	return visible && (
		<Editor
			placement="sidebar"
			autoSave={false}
			items={items}
			values={values}
			onAction={handleAction}
			onSave={handleSave}
		/>
	);
}
```

##### Auto Save Sidebar With Custom Toolbar

```jsx
import { useState } from "react";
import { Editor } from "@svar-ui/react-editor";

function AutoSaveEditor() {
	const items = [
		{ comp: "text", key: "label", label: "Label" },
		{ comp: "textarea", key: "description", label: "Description" },
	];

	const [values, setValues] = useState({ id: 1, label: "Task", description: "" });
	const [open, setOpen] = useState(true);

	function handleAction({ item }) {
		if (item.id === "close" || item.id === "delete") setOpen(false);
	}

	function handleSave({ values: next }) {
		setValues(next);
	}

	return open && (
		<Editor
			placement="sidebar"
			autoSave={true}
			topBar={{
				items: [
					{ comp: "icon", icon: "wxi-close", id: "close" },
					{ comp: "spacer" },
					{ comp: "button", type: "danger", text: "Delete", id: "delete" },
					{ comp: "button", type: "primary", text: "Save", id: "save" },
				],
			}}
			items={items}
			values={values}
			onAction={handleAction}
			onSave={handleSave}
		/>
	);
}
```

##### Update Multiple Values From One Change

```jsx
import { useState } from "react";
import { Editor, registerEditorItem } from "@svar-ui/react-editor";
import { Combo } from "@svar-ui/react-core";

registerEditorItem("combo", Combo);

function MultiUpdateEditor() {
	const [items, setItems] = useState([
		{
			comp: "combo",
			key: "country",
			label: "Country",
			options: [
				{ id: "france", label: "France" },
				{ id: "poland", label: "Poland" },
			],
		},
		{ comp: "combo", key: "city", label: "City", disabled: true },
	]);

	const cities = {
		france: [{ id: "paris", label: "Paris" }],
		poland: [{ id: "warsaw", label: "Warsaw" }],
	};

	const [values, setValues] = useState({ country: "", city: "" });

	function handleChange(ev) {
		if (ev.key !== "country") return;

		setItems(prev => {
			const next = [...prev];
			next[1] = {
				...next[1],
				disabled: false,
				options: cities[ev.value],
			};
			return next;
		});

		ev.update = {
			country: ev.value,
			city: "",
		};
	}

	return <Editor items={items} values={values} onChange={handleChange} topBar={false} />;
}
```

##### Register A Custom Item

```jsx
// PriorityCombo.jsx
import { Combo } from "@svar-ui/react-core";

function PriorityCombo({ value, options, onChange, ...restProps }) {
	return (
		<Combo value={value} options={options} onChange={onChange} {...restProps}>
			{({ option }) => (
				<>
					<span className="priority-dot" style={{ background: option.color }}></span>
					{option.label}
				</>
			)}
		</Combo>
	);
}

export default PriorityCombo;
```

```jsx
import { useState } from "react";
import { Editor, registerEditorItem } from "@svar-ui/react-editor";
import PriorityCombo from "./PriorityCombo.jsx";

registerEditorItem("priority-combo", PriorityCombo);

function CustomItemEditor() {
	const items = [
		{
			comp: "priority-combo",
			key: "priority",
			label: "Priority",
			config: { clearButton: true },
			options: [
				{ id: 1, label: "High", color: "#FE6158" },
				{ id: 2, label: "Low", color: "#77D257" },
			],
		},
	];

	const [values, setValues] = useState({ priority: 1 });

	return <Editor items={items} values={values} topBar={false} />;
}
```

##### Sections And Accordion Panels

```jsx
import { useState } from "react";
import { Editor } from "@svar-ui/react-editor";

function AccordionEditor() {
	const items = [
		{
			comp: "section",
			key: "personal",
			label: "Personal Info",
			activeSection: true,
			sectionMode: "accordion",
		},
		{ comp: "text", key: "name", label: "Name", section: "personal" },
		{
			comp: "section",
			key: "settings",
			label: "Settings",
			sectionMode: "accordion",
		},
		{ comp: "checkbox", key: "admin", label: "Is admin", section: "settings" },
	];

	const [values, setValues] = useState({ name: "John", admin: false });

	return <Editor items={items} values={values} topBar={false} />;
}
```

##### Batch Switcher In Children

```jsx
import { useState } from "react";
import { Editor } from "@svar-ui/react-editor";
import { Segmented } from "@svar-ui/react-core";

function BatchEditor() {
	const options = [
		{ id: "main", label: "Personal" },
		{ id: "cfg", label: "Settings" },
	];

	const items = [
		{ comp: "text", key: "name", label: "Name", batch: "main" },
		{ comp: "textarea", key: "descr", label: "Description", batch: "main" },
		{ comp: "checkbox", key: "admin", label: "Is Admin", batch: "cfg" },
	];

	const [values, setValues] = useState({ name: "John", descr: "", admin: false });
	const [activeBatch, setActiveBatch] = useState("main");

	return (
		<Editor topBar={false} items={items} values={values} activeBatch={activeBatch}>
			<Segmented options={options} value={activeBatch} onChange={({ value }) => setActiveBatch(value)} />
		</Editor>
	);
}
```

##### Modal Columns Layout

```jsx
import { useState } from "react";
import { Editor } from "@svar-ui/react-editor";

function ModalColumnsEditor() {
	const items = [
		{ comp: "text", key: "name", label: "Name", column: "left" },
		{ comp: "textarea", key: "descr", label: "Description", column: "left" },
		{ comp: "checkbox", key: "admin", label: "Is Admin" },
	];

	const [values, setValues] = useState({ name: "John", descr: "", admin: false });
	const [visible, setVisible] = useState(true);

	return visible && (
		<Editor
			placement="modal"
			layout="columns"
			autoSave={false}
			items={items}
			values={values}
			onAction={() => setVisible(false)}
		/>
	);
}
```

#### Implementation Notes

- `onValidation` can receive `errors: null`
- Dot-path keys assume intermediate objects already exist for default getter/setter access.
- `config` is promoted into top-level item props and also remains as `item.config`.
- `readonly={true}` converts every rendered item to the built-in `readonly` renderer.
- `Action` toolbar items with `id: "save"` are special; other IDs are forwarded through `onAction`
- `SideArea` cancel trigger `onAction` with `item.id === "close"`.


## File: filter/index.md

> Source: `filter/index.md`

Use when building, configuring, styling, or modifying SVAR React Filter / @svar-ui/react-filter FilterBuilder, FilterEditor, FilterBar, or FilterQuery components

Package: `@svar-ui/react-filter`
Styles: `@svar-ui/react-filter/all.css`

The package ships `style.css` (this component only) and `all.css` (this component plus all dependencies).

Use this skill as an index. Load only the component reference needed for the task; each linked file is independent.

- `FilterBuilder.md` - visual query builder, nested filter groups, builder API/actions, builder styling.
- `FilterEditor.md` - standalone single-rule editor, field selector mode, option includes, editor styling.
- `FilterBar.md` - compact filter input row, `all` and `dynamic` field modes, bar styling.
- `FilterQuery.md` - query-string input, parse modes, autocomplete, natural text integrations, query styling.


## File: filter/FilterBar.md

> Source: `filter/FilterBar.md`

### FilterBar

Package: `@svar-ui/react-filter`

Use this file independently when building, configuring, styling, or modifying `FilterBar`.

#### Import

```js
import {
	FilterBar,
	Willow,
	WillowDark,
	createArrayFilter,
	createFilter,
	createFilterRule,
} from "@svar-ui/react-filter";
```

#### Supported Functionality

##### Data Contract

- `FilterBar` emits an `IFilterSet` through `onChange({ value })`.
- `IFilterSet`: `{ glue?: "and" | "or", rules?: (IFilter | IFilterSet)[] }`.
- string field shorthand becomes `{ id, type: "text", filter: "contains" }`.
- object fields produce one `IFilter` when the current value is truthy.
- `type: "all"` can emit an OR `IFilterSet` across multiple fields.
- empty fields are omitted from the emitted rules.
- when one rule is produced by `type: "all"` and it has `glue: "or"`, that OR set is returned directly.

##### Field Configurations

- simple field object: `{ id, type, filter?, options?, value?, label?, placeholder? }`.
- `type`: `"text"`, `"number"`, or `"date"` in source.
- `filter` defaults to `"equal"` when `options` exists, otherwise `"contains"`.
- non-date `options` render a `RichSelect`; string/number options become `{ id, label }`.
- `$empty` / `None` is prepended to select options and is converted back to `""`.
- `type: "all"` renders one text input and builds `contains` OR rules across every field in `by`.
- `type: "dynamic"` renders a field selector plus the selected field's input; switching fields clears the previous field value.
- `by` accepts strings or field config objects.

Common field configs:

```js
"last_name"
{ id: "age", type: "number", filter: "greater", placeholder: "Older than..." }
{ id: "country", type: "text", options: ["USA", "Germany"], value: "USA" }
{ id: "start", type: "date", filter: "between" }
{ type: "all", label: "Search", by: ["age", "first_name", "last_name"] }
{
	type: "dynamic",
	label: "Filter by",
	by: ["last_name", { id: "start", type: "date", filter: "greater" }],
}
```

##### Events And Timing

- `debounce` defaults to `300`.
- text and number input changes use `debounce`.
- select and date changes dispatch after `1ms`.
- `onChange({ value })` receives the current `IFilterSet`.
- initial `value` field configs populate controls but do not emit until a change happens.

#### Public Types

```ts
import type { ComponentType } from "react";
import type {
	IFilterSet,
	IFilterBarField,
} from "@svar-ui/filter-store";

export declare const FilterBar: ComponentType<{
	fields: (
		| string
		| IFilterBarField
		| {
				type: "all" | "dynamic";
				by: (string | IFilterBarField)[];
				label?: string;
				placeholder?: string;
		  }
	)[];
	debounce?: number;
	onChange?: (ev: { value: IFilterSet }) => void;
}>;
```

Relevant `@svar-ui/filter-store` public shapes:

```ts
export type AnyData = number | string | Date;
export type TGlue = "and" | "or";
export type TType = "number" | "text" | "date" | "tuple";
export type TFilterType =
	| "greater"
	| "less"
	| "greaterOrEqual"
	| "lessOrEqual"
	| "equal"
	| "notEqual"
	| "contains"
	| "notContains"
	| "beginsWith"
	| "notBeginsWith"
	| "endsWith"
	| "notEndsWith"
	| "between"
	| "notBetween";

export interface IFilterSet {
	rules?: (IFilter | IFilterSet)[];
	glue?: TGlue;
}

export interface IFilter {
	field: string | "*";
	type?: TType;
	predicate?: "month" | "year" | "yearMonth";
	filter?: TFilterType;
	includes?: AnyData[];
	value?: AnyData;
}

export interface IFilterBarField {
	type: string;
	id: string;
	filter?: TFilterType;
	options?: { id: string | number; label: string }[];
	value?: any;
	label?: string;
	placeholder?: string;
}
```

#### Styling

- no `css`, `class`, `className`, or `style` passthrough prop exists on `FilterBar`.
- use theme wrappers around the component: `<Willow>`, `<WillowDark>`.
- label variables consumed by source: `--wx-label-font-family`, `--wx-label-font-size`, `--wx-label-line-height`, `--wx-label-font-weight`, `--wx-label-font-color`.

Class hooks:

- root: `.wx-filter-bar`
- labels: `.wx-label`
- select wrappers: `.wx-select`
- text/number input wrappers: `.wx-text`
- date picker wrappers: `.wx-date`

Layout defaults:

- `.wx-filter-bar`: `display: flex`, `padding: 14px 2px`, `width: 610px`, `gap: 10px`.
- `.wx-label`: max width `160px`, no wrap, ellipsis overflow, centered with `align-content: center`.
- `.wx-select`: `flex: 1`.
- `.wx-text` and `.wx-date`: `flex: 2`.

```jsx
import "./BarScope.css";

<div className="bar-scope">
	<Willow>
		<FilterBar fields={fields} onChange={handleChange} />
	</Willow>
</div>

/* BarScope.css
.bar-scope {
	--wx-label-font-size: 14px;
	--wx-label-font-weight: 600;
}

.bar-scope .wx-filter-bar {
	width: 100%;
	gap: 16px;
	padding: 10px 0;
}
*/
```

#### Recipes

##### Basic Text, Number, And Select Fields

```jsx
import { useState } from "react";
import { FilterBar, createArrayFilter } from "@svar-ui/react-filter";

function BasicFilterBar() {
	const [rows, setRows] = useState(data);

	function apply({ value }) {
		setRows(createArrayFilter(value)(data));
	}

	return (
		<FilterBar
			fields={[
				"last_name",
				{ id: "age", type: "number", filter: "greater" },
				{
					id: "country",
					type: "text",
					options: ["USA", "Germany"],
					value: "USA",
				},
			]}
			onChange={apply}
		/>
	);
}
```

##### Date Fields And Ranges

```jsx
<FilterBar
	fields={[
		{
			id: "start",
			type: "date",
			filter: "greater",
			value: new Date("2025-01-01"),
		},
		{
			id: "end",
			type: "date",
			filter: "less",
			value: new Date("2025-05-01"),
		},
		{
			id: "created",
			type: "date",
			filter: "between",
		},
	]}
	onChange={({ value }) => applyFilter(value)}
/>
```

##### Search Across Many Fields

```jsx
<FilterBar
	fields={[
		{
			type: "all",
			label: "Search",
			placeholder: "Search people",
			by: ["age", "first_name", "last_name"],
		},
	]}
	onChange={({ value }) => applyFilter(value)}
/>
```

##### Dynamic Field Selector

```jsx
<FilterBar
	fields={[
		{
			type: "dynamic",
			label: "Filter by",
			placeholder: "Enter value",
			by: [
				{ id: "first_name", type: "text", filter: "contains" },
				"last_name",
				{ id: "age", type: "number", filter: "greater" },
				{
					id: "country",
					type: "text",
					options: ["USA", "Germany"],
					value: "USA",
				},
				{
					id: "start",
					type: "date",
					filter: "greater",
					value: new Date("2025-01-01"),
				},
			],
		},
	]}
	onChange={({ value }) => applyFilter(value)}
/>
```

##### Faster Text Updates

```jsx
<FilterBar
	debounce={100}
	fields={["first_name", "last_name"]}
	onChange={({ value }) => applyFilter(value)}
/>
```

#### Implementation Notes

- `FilterBar` stores one `lastField` for dynamic selectors; avoid multiple independent `type: "dynamic"` groups
- `normalizeField` only maps `options` for non-date fields.
- select options can be strings, numbers, or `{ id, label }` objects


## File: filter/FilterBuilder.md

> Source: `filter/FilterBuilder.md`

### FilterBuilder

Package: `@svar-ui/react-filter`

Use this file independently when building, configuring, styling, or modifying `FilterBuilder`.

#### Import

```js
import {
	FilterBuilder,
	Willow,
	WillowDark,
	createArrayFilter,
	createFilter,
	getOptionsMap,
} from "@svar-ui/react-filter";
```

#### Supported Functionality

##### Data Contract

- `fields`: array of `{ id, label, type, predicate?, format? }`.
- supported field `type`: `"text"`, `"number"`, `"date"`, `"tuple"`.
- `options`: `{ [fieldId]: AnyData[] }` or `(fieldId) => AnyData[] | Promise<AnyData[]>`.
- `value`: `IFilterSet`, default `{ glue: "and", rules: [] }`.
- `IFilterSet`: `{ glue?: "and" | "or", rules?: (IFilter | IFilterSet)[] }`.
- `IFilter`: `{ field, type?, predicate?, filter?, includes?, value? }`.
- `includes` matches exact option values; `filter + value` uses an operator.
- `between` and `notBetween` use `value: { start, end }`.
- date editor UI values should be `Date` objects or `{ start: Date, end: Date }`; convert date strings before passing visual editor values.

##### Built-In Filters

- text: `equal`, `notEqual`, `contains`, `notContains`, `beginsWith`, `notBeginsWith`, `endsWith`, `notEndsWith`
- number: text filters plus `greater`, `less`, `greaterOrEqual`, `lessOrEqual`, `between`, `notBetween`
- date: `equal`, `notEqual`, `greater`, `less`, `greaterOrEqual`, `lessOrEqual`, `between`, `notBetween`
- tuple: `greater`, `less`, `greaterOrEqual`, `lessOrEqual`, `equal`, `notEqual`

Common rule objects:

```js
{ field: "name", type: "text", filter: "contains", value: "Alex" }
{ field: "age", type: "number", filter: "greater", value: 30 }
{ field: "start", type: "date", filter: "between", value: { start, end } }
{ field: "country", includes: ["USA", "Germany"] }
{ glue: "or", rules: [/* filters or nested groups */] }
```

##### Props And Modes

- source props: `value = { glue: "and", rules: [] }`, `fields = []`, `options = null`, `type = "list"`, `init = null`, plus action callback props in `...restProps`.
- `type="list"`: vertical layout, nested groups, AND/OR glue, context menu, top Add filter button.
- `type="line"`: horizontal layout with scrollable rules, context menu, Add filter button at the right.
- `type="simple"`: horizontal flat layout; Add filter opens a dropdown of unused fields, no nested groups, no context menu, delete icon per rule.
- `onChange` receives `{ value: IFilterSet }` after store-changing actions.
- other action callback props use event names with hyphens removed and camelCased: `onAddRule`, `onAddGroup`, `onEditRule`, `onUpdateRule`, `onDeleteRule`, `onToggleGlue`, `onChangeRule`.
- `init(api)` runs once after initial store setup.
- `ref` exposes `exec`, `on`, `intercept`, `detach`, `setNext`, `getState`, `getReactiveState`, `getStores`, `getValue`.
- public actions: `add-rule`, `add-group`, `edit-rule`, `update-rule`, `delete-rule`, `toggle-glue`, `change-rule`, `change`.

#### Public Types

```ts
import type { ComponentType } from "react";
import type {
	IApi,
	TMethodsConfig,
	IConfig,
} from "@svar-ui/filter-store";

export declare const FilterBuilder: ComponentType<
	{
		type?: "list" | "line" | "simple";
		init?: (api: IApi) => void;
	} & IConfig &
		FilterBuilderActions<TMethodsConfig>
>;

/* get component events from store actions*/
type RemoveHyphen<S extends string> = S extends `${infer Head}-${infer Tail}`
	? `${Head}${Capitalize<RemoveHyphen<Tail>>}`
	: S;

type EventName<K extends string> = `on${Capitalize<RemoveHyphen<K>>}`;

export type FilterBuilderActions<TMethodsConfig extends Record<string, any>> = {
	[K in keyof TMethodsConfig as EventName<K & string>]?: (
		ev: TMethodsConfig[K]
	) => void;
} & {
	[key: `on${string}`]: (ev?: any) => void;
};
```

Relevant `@svar-ui/filter-store` public shapes:

```ts
export type AnyData = number | string | Date;
export type TGlue = "and" | "or";
export type TPredicate = "month" | "year" | "yearMonth";
export type TType = "number" | "text" | "date" | "tuple";
export type TFilterType =
	| "greater"
	| "less"
	| "greaterOrEqual"
	| "lessOrEqual"
	| "equal"
	| "notEqual"
	| "contains"
	| "notContains"
	| "beginsWith"
	| "notBeginsWith"
	| "endsWith"
	| "notEndsWith"
	| "between"
	| "notBetween";

export type TOptions =
	| IDataHash<AnyData[]>
	| ((field: string) => AnyData[] | Promise<AnyData[]>);

export interface IFilterSet {
	rules?: (IFilter | IFilterSet)[];
	glue?: TGlue;
}

export interface IFilter {
	field: string | "*";
	type?: TType;
	predicate?: TPredicate;
	filter?: TFilterType;
	includes?: AnyData[];
	value?: AnyData;
}

export interface IField {
	id: string;
	label: string;
	type: TType;
	predicate?: TPredicate;
	format?: string | ((value: AnyData) => string);
}

export interface IConfig {
	value?: IFilterSet;
	fields: IField[];
	options: TOptions;
}

export interface IDataHash<T> {
	[key: string]: T;
}
```

#### Styling

- no `css`, `class`, `className`, or `style` passthrough prop exists on `FilterBuilder`.
- use theme wrappers around the component: `<Willow>`, `<WillowDark>`.
- filter variables: `--wx-filter-value-color`, `--wx-filter-and-background`, `--wx-filter-or-background`, `--wx-filter-and-font-color`, `--wx-filter-or-font-color`, `--wx-filter-border`.
- shared variables used directly: `--wx-background`, `--wx-background-alt`, `--wx-border`, `--wx-border-radius`, `--wx-font-weight-md`, `--wx-line-height`.
- editor/input variables inside the rule editor come from `FilterEditor` and `@svar-ui/react-core`.

Class hooks:

- root and modes: `.wx-filter-builder`, `.wx-list`, `.wx-line`, `.wx-simple`
- toolbar/layout: `.wx-toolbar`, `.wx-filters`, `.wx-button`
- groups: `.wx-group`, `.wx-top`, `.wx-inner`
- rule wrappers: `.wx-rule-wrapper`, `.wx-glue-wrapper`, `.wx-editor-wrapper`, `.wx-panel`
- rule display: `.wx-rule`, `.wx-filter`, `.wx-field`, `.wx-value`, `.wx-menu-icon`
- glue display: `.wx-glue`, `.wx-and`, `.wx-or`

Layout defaults:

- `.wx-filter-builder.wx-list`: `padding: 0`, `max-width: 470px`.
- `.wx-toolbar.wx-line` and `.wx-toolbar.wx-simple`: flex rows with `gap: 20px`, `height: 67px`.
- `.wx-toolbar.wx-line`: `justify-content: space-between`.
- `.wx-filters`: horizontal scroll container in `line` and `simple`.
- `.wx-group.wx-inner.wx-list`: `margin-left: 20px`, `padding: 4px 0 0 8px`, `border-left: var(--wx-border)`.
- `.wx-group.wx-line`: `display: flex`, `gap: 10px`, `padding: 4px`.
- `.wx-rule.wx-list`: `padding: 12px 8px`, `margin: 10px 0`.
- `.wx-rule.wx-line`: `height: 36px`, `padding: 8px`.
- `.wx-editor-wrapper`: `padding: 0 10px`, `min-width: 280px`, `max-width: 320px`.

```jsx
import "./BuilderScope.css";

<div className="builder-scope">
	<Willow>
		<FilterBuilder fields={fields} options={options} onChange={handleChange} />
	</Willow>
</div>

/* BuilderScope.css
.builder-scope {
	--wx-filter-value-color: #7048e8;
	--wx-filter-and-background: #ffe066;
	--wx-filter-or-background: #b2f2bb;
}

.builder-scope .wx-rule {
	border-radius: 6px;
}

.builder-scope .wx-group.wx-line {
	gap: 14px;
}
*/
```

#### Recipes

##### Local Array Filtering

```jsx
import { useState } from "react";
import { FilterBuilder, Willow, createArrayFilter } from "@svar-ui/react-filter";

function LocalFilterBuilder() {
	const fields = [
		{ id: "first_name", label: "First Name", type: "text" },
		{ id: "age", label: "Age", type: "number" },
		{ id: "start", label: "Start Date", type: "date" },
	];
	const options = {
		first_name: ["Alex", "Daisy", "John"],
		age: [24, 35, 45],
	};
	const data = [
		{ first_name: "Alex", age: 45, start: new Date("2025-03-13") },
		{ first_name: "Daisy", age: 33, start: new Date("2024-12-04") },
	];
	const [rows, setRows] = useState(data);
	const [value, setValue] = useState({ glue: "and", rules: [] });

	function applyFilter({ value }) {
		setValue(value);
		setRows(createArrayFilter(value)(data));
	}

	return (
		<Willow>
			<FilterBuilder value={value} fields={fields} options={options} onChange={applyFilter} />
		</Willow>
	);
}
```

##### Line Or Simple Layout

```jsx
<FilterBuilder
	value={value}
	fields={fields}
	options={options}
	type="line"
	onChange={({ value }) => applyFilter(value)}
/>

<FilterBuilder
	value={value}
	fields={fields}
	options={options}
	type="simple"
	onChange={({ value }) => applyFilter(value)}
/>
```

##### Async Options

```jsx
import { FilterBuilder } from "@svar-ui/react-filter";

async function loadOptions(fieldId) {
	await new Promise(resolve => setTimeout(resolve, 300));
	return optionMap[fieldId] || [];
}

function AsyncOptions() {
	return <FilterBuilder value={value} fields={fields} options={loadOptions} />;
}
```

##### API And Event Interception

```jsx
import { useRef, useState } from "react";
import { FilterBuilder } from "@svar-ui/react-filter";

function ApiBuilder() {
	const apiRef = useRef(null);
	const [valueText, setValueText] = useState("");

	function init(api) {
		apiRef.current = api;
		api.intercept("add-rule", ev => {
			ev.edit = false;
		});
		api.on("change", ({ value }) => {
			setValueText(JSON.stringify(value, null, 2));
		});
	}

	function addAgeRule() {
		apiRef.current.exec("add-rule", {
			rule: { field: "age", type: "number", filter: "greater", value: 30 },
			edit: false,
		});
	}

	return (
		<>
			<button onClick={addAgeRule}>Add age rule</button>
			<FilterBuilder ref={apiRef} fields={fields} options={options} init={init} />
			<pre>{valueText}</pre>
		</>
	);
}
```

##### Convert Date Strings Around Builder UI

```jsx
import { useState } from "react";
import { FilterBuilder } from "@svar-ui/react-filter";

function ConvertDateBuilder() {
	const incoming = {
		rules: [{ field: "start", filter: "greater", value: "2025-01-01" }],
	};

	const [value, setValue] = useState({
		...incoming,
		rules: incoming.rules.map(rule =>
			rule.field === "start"
				? { ...rule, type: "date", value: new Date(rule.value) }
				: rule
		),
	});

	function init(api) {
		api.on("change", ({ value }) => {
			console.log(JSON.stringify(value));
		});
	}

	return <FilterBuilder value={value} fields={fields} options={options} init={init} />;
}
```


## File: filter/FilterEditor.md

> Source: `filter/FilterEditor.md`

### FilterEditor

Package: `@svar-ui/react-filter`

Use this file independently when building, configuring, styling, or modifying `FilterEditor`.

#### Import

```js
import {
	FilterEditor,
	Willow,
	WillowDark,
	createArrayFilter,
	createFilter,
	getOptions,
} from "@svar-ui/react-filter";
```

#### Supported Functionality

##### Data Contract

- emits one `IFilter` rule through `onApply` and `onChange`.
- `IFilter`: `{ field?, type, predicate?, filter, includes, value }`.
- `field` is present when the `field` prop is set or when `fields` mode is active.
- `includes` is a selected subset only when non-empty and smaller than visible options; otherwise it emits `[]`.
- `value` is a scalar for most filters and `{ start, end }` for `between` / `notBetween`.
- date editor UI values should be `Date` objects or `{ start: Date, end: Date }`.
- `options` can be a fixed array or `(fieldId) => AnyData[] | Promise<AnyData[]>` in field-aware mode.

##### Built-In Filters

- text: `equal`, `notEqual`, `contains`, `notContains`, `beginsWith`, `notBeginsWith`, `endsWith`, `notEndsWith`
- number: text filters plus `greater`, `less`, `greaterOrEqual`, `lessOrEqual`, `between`, `notBetween`
- date: `equal`, `notEqual`, `greater`, `less`, `greaterOrEqual`, `lessOrEqual`, `between`, `notBetween`
- tuple: `greater`, `less`, `greaterOrEqual`, `lessOrEqual`, `equal`, `notEqual`
- date predicates: `month`, `year`, `yearMonth`

##### Props And Behavior

- source props: `fields = null`, `fieldsSelector = true`, `field = null`, `buttons = true`, `options = null`, `includes = null`, `type = "text"`, `filter = ""`, `value = ""`, `format = null`, `predicate = null`, `onApply`, `onCancel`, `onChange`.
- single-field mode: pass `type`, `field`, `filter`, `value`, `options`, `includes`, `format`, and `predicate` directly.
- multi-field mode: pass `fields`; selected field controls type, format, predicate, and loaded options.
- `fieldsSelector={false}` hides the field dropdown while keeping the selected field.
- `type="date"` uses `DatePicker`, except `filter="between"`/`"notBetween"` use `DateRangePicker`.
- `type="number"` uses numeric `Text`; `type="text"` uses text `Text`.
- `type="tuple"` uses `Combo` with options plus an automatic empty `$empty` / `None` option.
- option checkboxes are filtered by the current operator/value.
- `onChange({ value })` fires for UI changes when operator, value, field, or includes change.
- `onApply({ value })` fires from the Apply button.
- `onCancel()` fires from Cancel with no payload in source.
- `buttons={false}` hides Apply/Cancel and is normally paired with `onChange`.

#### Public Types

```ts
import type { ComponentType } from "react";
import type {
	TSingleOptions,
	TFilterType,
	TType,
	TPredicate,
	AnyData,
	IFilter,
	IConfig,
	IField,
} from "@svar-ui/filter-store";

export declare const FilterEditor: ComponentType<{
	fields?: IConfig["fields"];
	fieldsSelector?: boolean;
	field?: string;
	buttons?: boolean;
	options?: TSingleOptions;
	includes?: AnyData[];
	type?: TType;
	filter?: TFilterType;
	value?: AnyData | { start?: Date; end: Date };
	format?: string | ((value: AnyData) => string);
	predicate: TPredicate;
	onApply: (ev: { value: IFilter }) => void;
	onCancel: (ev: { value: IFilter }) => void;
	onChange: (ev: { value: IFilter }) => void;
}>;
```

Relevant `@svar-ui/filter-store` public shapes:

```ts
export type AnyData = number | string | Date;
export type TGlue = "and" | "or";
export type TPredicate = "month" | "year" | "yearMonth";
export type TType = "number" | "text" | "date" | "tuple";
export type TFilterType =
	| "greater"
	| "less"
	| "greaterOrEqual"
	| "lessOrEqual"
	| "equal"
	| "notEqual"
	| "contains"
	| "notContains"
	| "beginsWith"
	| "notBeginsWith"
	| "endsWith"
	| "notEndsWith"
	| "between"
	| "notBetween";

export type TSingleOptions =
	| AnyData[]
	| ((field: string) => AnyData[] | Promise<AnyData[]>);

export type TOptions =
	| IDataHash<AnyData[]>
	| ((field: string) => AnyData[] | Promise<AnyData[]>);

export interface IFilterSet {
	rules?: (IFilter | IFilterSet)[];
	glue?: TGlue;
}

export interface IFilter {
	field: string | "*";
	type?: TType;
	predicate?: TPredicate;
	filter?: TFilterType;
	includes?: AnyData[];
	value?: AnyData;
}

export interface IField {
	id: string;
	label: string;
	type: TType;
	predicate?: TPredicate;
	format?: string | ((value: AnyData) => string);
}

export interface IConfig {
	value?: IFilterSet;
	fields: IField[];
	options: TOptions;
}

export interface IDataHash<T> {
	[key: string]: T;
}
```

#### Styling

- no `css`, `class`, `className`, or `style` passthrough prop exists on `FilterEditor`.
- use theme wrappers around the component: `<Willow>`, `<WillowDark>`.
- editor sets `--wx-input-border: var(--wx-filter-border)` on `.wx-filter-editor`.
- filter variables from themes: `--wx-filter-border`, `--wx-filter-value-color`, `--wx-filter-and-background`, `--wx-filter-or-background`, `--wx-filter-and-font-color`, `--wx-filter-or-font-color`.
- shared/core input variables come from `@svar-ui/react-core`, including `--wx-input-*`.

Class hooks:

- root: `.wx-filter-editor`
- rows and cells: `.wx-wrapper`, `.wx-cell`
- option list: `.wx-list`, `.wx-item`

Layout defaults:

- `.wx-wrapper`: `display: flex`, `justify-content: right`, `gap: 10px`, `align-items: center`, `margin: 8px 0`.
- `.wx-cell`: `flex: 1`.
- `.wx-list`: `height: 150px`, `overflow-y: auto`, `margin: 8px 0`, `border: var(--wx-filter-border)`.
- `.wx-item`: `user-select: none`, `padding: 8px 12px`, `border-bottom: var(--wx-filter-border)`.

```jsx
<div className="editor-scope">
	<Willow>
		<FilterEditor type="text" options={values} onApply={handleApply} />
	</Willow>
</div>
```

```css
.editor-scope {
	--wx-filter-border: 1px solid #d0d5dd;
}

.editor-scope .wx-item {
	padding: 12px 16px;
}
```

#### Recipes

##### Single Text Rule With Apply

```jsx
import { useState } from "react";
import { FilterEditor, createArrayFilter } from "@svar-ui/react-filter";

function Example() {
	const options = ["Alex", "Daisy", "John"];
	const [rows, setRows] = useState(data);

	function apply({ value }) {
		setRows(createArrayFilter({ rules: [value] })(data));
	}

	return (
		<FilterEditor
			type="text"
			field="first_name"
			options={options}
			onApply={apply}
		/>
	);
}
```

##### Live Rule Without Buttons

```jsx
import { useState } from "react";
import { FilterEditor, createArrayFilter } from "@svar-ui/react-filter";

function Example() {
	const [rule, setRule] = useState({});
	const [rows, setRows] = useState(data);

	function update({ value }) {
		setRule(value);
		setRows(createArrayFilter({ rules: [value] })(data));
	}

	return (
		<FilterEditor
			type="text"
			field="first_name"
			options={["Alex", "Daisy", "John"]}
			buttons={false}
			includes={rule.includes}
			filter={rule.filter}
			value={rule.value}
			onChange={update}
		/>
	);
}
```

##### Field Selector With Async Options

```jsx
import { FilterEditor } from "@svar-ui/react-filter";

function Example() {
	const fields = [
		{ id: "first_name", label: "First Name", type: "text" },
		{ id: "age", label: "Age", type: "number" },
		{ id: "start", label: "Start Date", type: "date" },
	];

	async function loadOptions(field) {
		return optionMap[field] || [];
	}

	return (
		<FilterEditor
			fields={fields}
			field="age"
			options={loadOptions}
			onApply={({ value }) => console.log(value)}
		/>
	);
}
```

##### Date Range Rule

```jsx
import { FilterEditor, getOptions } from "@svar-ui/react-filter";

function Example() {
	const options = getOptions(data, "start");

	return (
		<FilterEditor
			field="start"
			options={options}
			type="date"
			filter="between"
			value={{
				start: new Date("2024-11-01"),
				end: new Date("2025-05-01"),
			}}
			onApply={({ value }) => console.log(value)}
		/>
	);
}
```

##### Tuple With Formatted Options

```jsx
import { FilterEditor, getOptions } from "@svar-ui/react-filter";

function Example() {
	const options = getOptions(data, "start", {
		predicate: "month",
		sort: (a, b) => a - b,
	});
	const monthName = value => monthLabels[value] || String(value);

	return (
		<FilterEditor
			field="start"
			options={options}
			format={monthName}
			filter="greater"
			type="tuple"
			onApply={({ value }) => console.log(value)}
		/>
	);
}
```

#### Implementation Notes

- `FilterEditor` source treats `predicate`, `onApply`, `onCancel`, and `onChange` as optional
- source calls `onCancel()` with no payload, although the declaration types it as `(ev: { value: IFilter }) => void`.


## File: filter/FilterQuery.md

> Source: `filter/FilterQuery.md`

### FilterQuery

Package: `@svar-ui/react-filter`

Use this file independently when building, configuring, styling, or modifying `FilterQuery`.

#### Import

```js
import {
	FilterQuery,
	Willow,
	WillowDark,
	createArrayFilter,
	createFilter,
	getQueryHtml,
	getQueryString,
} from "@svar-ui/react-filter";
```

#### Supported Functionality

##### Data Contract

- `value` is a controlled prop and stores the query string with field IDs.
- displayed `text` uses sanitized field labels when `fields` include labels.
- field labels are sanitized by removing parser-special characters; `{ id: "first_name", label: "First Name" }` displays as `FirstName:`.
- `fields`: array of `{ id, label, type, predicate?, format? }`.
- `options`: `{ [fieldId]: AnyData[] }`; tag suggestions use `options["#"]`.
- parse-enabled callbacks receive `value: IFilterSet | IFilter | null`.
- `parse="none"` callbacks receive raw `value` and `text` strings.
- `startProgress()` and `endProgress()` control the top progress bar for async filtering.

##### Parse Modes

- `parse` defaults to `"allowFreeText"`.
- `parse="allowFreeText"` parses query syntax and converts plain words into `field: "*"` `contains` filters.
- `parse="strict"` parses query syntax but disables free-text fallback.
- `parse="none"` disables parser, syntax highlight, autocomplete, and validation; use it for natural-language endpoints.
- Enter and the Search button call `onChange`.
- clear button resets local text and controlled `value`, but does not call `onChange` until the user submits again.

##### Query Syntax Highlights

- field-value: `Status: Open`
- implicit AND: `Status: Open Age: >30`
- explicit logic: `Status: Open or Status: Review`
- multiple values: `Status: Open, Review`
- negation: `Status: -Closed`, `Name: -contains test`
- text operators: `contains`, `starts`, `ends`
- wildcards: `Name: Alex*`, `Email: *@company.com`, `Title: *urgent*`
- comparisons: `Age: >30`, `Age: <=60`
- ranges: `Age: 25 .. 50`, `StartDate: 2024-01-01 .. 2025-01-01`
- date predicates: `StartDate.year: 2024`, `StartDate.month: 6`; `YYYY` and `YYYY-MM` infer predicates.
- tags / any-field exact search: `#urgent`, `-#done`

##### Autocomplete

- field suggestions match field `id` and sanitized `label`, and insert the label into text.
- value suggestions come from `options[fieldId]`.
- tag suggestions come from `options["#"]`.
- date predicate suggestions are `year` and `month`.
- value suggestion labels use the field `format` function when present.
- suggestions rank starts-with matches before contains matches.
- keyboard support: ArrowDown/ArrowUp navigates, Enter selects when focused, Escape/Tab closes.

##### Events

- `onChange` runs on Enter, Search button, and external `value` updates after the first non-empty set.
- parse-enabled event shape: `{ parsed, value, text, error, startProgress, endProgress }`.
- `parsed` is a `ParseResult`.
- `error` is `null` or a localized `ValidationError` with `message`.
- with parse enabled, `text` is `parseResult.naturalText || ""` when there is no blocking error, otherwise the current query text.
- with `parse="none"`, event shape is `{ value, text, startProgress, endProgress }`.

#### Public Types

```ts
import type { ComponentType } from "react";
import type {
	IFilterSet,
	IFilter,
	IField,
	IDataHash,
	AnyData,
	ParseResult,
	ValidationError,
} from "@svar-ui/filter-store";

export interface FilterQueryEvent {
	value: string | IFilterSet | IFilter | null;
	text: string;
	parsed?: ParseResult;
	error?: ValidationError | null;
	startProgress: () => void;
	endProgress: () => void;
}

export declare const FilterQuery: ComponentType<{
	value?: string;
	placeholder?: string;
	parse?: "none" | "strict" | "allowFreeText";
	fields?: IField[];
	options?: IDataHash<AnyData[]>;
	onChange?: (ev: FilterQueryEvent) => void;
}>;
```

Relevant `@svar-ui/filter-store` public shapes:

```ts
export type AnyData = number | string | Date;
export type TGlue = "and" | "or";
export type TPredicate = "month" | "year" | "yearMonth";
export type TType = "number" | "text" | "date" | "tuple";
export type TFilterType =
	| "greater"
	| "less"
	| "greaterOrEqual"
	| "lessOrEqual"
	| "equal"
	| "notEqual"
	| "contains"
	| "notContains"
	| "beginsWith"
	| "notBeginsWith"
	| "endsWith"
	| "notEndsWith"
	| "between"
	| "notBetween";

export interface IFilterSet {
	rules?: (IFilter | IFilterSet)[];
	glue?: TGlue;
}

export interface IFilter {
	field: string | "*";
	type?: TType;
	predicate?: TPredicate;
	filter?: TFilterType;
	includes?: AnyData[];
	value?: AnyData;
}

export interface IField {
	id: string;
	label: string;
	type: TType;
	predicate?: TPredicate;
	format?: string | ((value: AnyData) => string);
}

export interface IDataHash<T> {
	[key: string]: T;
}

export type ValidationErrorCode =
	| "UNKNOWN_FIELD"
	| "EXPECTED_NUMBER"
	| "EXPECTED_DATE"
	| "PARSE_ERROR"
	| "NO_DATA";

export type HighlightTokenType =
	| "field"
	| "value"
	| "operator"
	| "textop"
	| "comparison"
	| "symbol"
	| "wildcard"
	| "negation"
	| "hash"
	| "error";

export interface HighlightToken {
	type: HighlightTokenType;
	start: number;
	end: number;
	invalid?: boolean;
}

export interface ValidationError {
	code: ValidationErrorCode;
	field?: string;
	value?: string;
	message?: string;
}

export interface ParseResult {
	config: IFilterSet | IFilter | null;
	isInvalid: boolean | ValidationError;
	startOperation: string | null;
	tokens: HighlightToken[];
	naturalText: string | null;
}
```

#### Styling

- no `css`, `class`, `className`, or `style` passthrough prop exists on `FilterQuery`.
- use theme wrappers around the component: `<Willow>`, `<WillowDark>`.
- token variables with fallbacks in `getQueryHtml`: `--wx-filter-query-field-color`, `--wx-filter-query-value-color`, `--wx-filter-query-operator-color`, `--wx-filter-query-comparison-color`, `--wx-filter-query-symbol-color`, `--wx-filter-query-negation-color`, `--wx-filter-query-error-color`.
- layout/input variables: `--wx-border`, `--wx-border-radius`, `--wx-background`, `--wx-background-alt`, `--wx-padding`, `--wx-color-font`, `--wx-color-font-alt`, `--wx-color-primary`, `--wx-color-primary-font`, `--wx-color-success`, `--wx-font-size`, `--wx-font-family`.
- autocomplete variables: `--wx-input-font-family`, `--wx-input-font-size`, `--wx-input-line-height`, `--wx-input-font-weight`, `--wx-input-font-color`, `--wx-input-padding`, `--wx-background-hover`.

Class hooks:

- root: `.wx-filter-query`
- progress: `.wx-progress-bar`, `.active`, `.wx-progress-fill`
- row/layout: `.wx-filter-query-row`, `.wx-filter-query-input-wrapper`
- overlay/input: `.wx-filter-query-highlight`, `.wx-placeholder`, `.wx-filter-query-input`, `.wx-parse-mode`
- buttons: `.wx-filter-query-clear`, `.wx-filter-query-search`
- autocomplete dropdown from `Suggest`: `.wx-list`, `.wx-item`, `.wx-focus`
- standalone highlight helper component: `.wx-query-highlight`

Layout defaults:

- `.wx-filter-query`: `display: flex`, `flex-direction: column`, `position: relative`.
- `.wx-progress-bar`: absolute top edge, `height: 3px`.
- `.wx-filter-query-row`: flex row with `border: var(--wx-border)`, `border-radius: var(--wx-border-radius)`, `background: var(--wx-background)`.
- `.wx-filter-query-highlight`: absolute overlay, `padding: 6px 12px`, `white-space: pre`, hidden scrollbars.
- `.wx-filter-query-input`: `width: 100%`, no border, `padding: var(--wx-padding) 12px`, transparent background.
- `.wx-filter-query-input.wx-parse-mode`: transparent text with visible caret so the highlight layer provides token colors.
- autocomplete `.wx-list`: `max-height: 250px`, vertical scroll.

```jsx
<div className="query-scope">
	<Willow>
		<FilterQuery fields={fields} options={options} onChange={handleFilter} />
	</Willow>
</div>
```

```css
.query-scope {
	--wx-filter-query-field-color: #7c3aed;
	--wx-filter-query-value-color: #059669;
	--wx-color-primary: #7c3aed;
}

.query-scope .wx-filter-query-search {
	background: #0f172a;
	color: #f8fafc;
}
```

#### Recipes

##### Structured Query With Local Filtering

```jsx
import { useState } from "react";
import { FilterQuery, createArrayFilter } from "@svar-ui/react-filter";

function Example() {
	const [value, setValue] = useState("");
	const [rows, setRows] = useState(data);

	function handleFilter({ value, error }) {
		setValue(value);
		if (error && error.code !== "NO_DATA") return;
		setRows(createArrayFilter(value, {}, fields)(data));
	}

	return (
		<FilterQuery
			value={value}
			placeholder="e.g. FirstName: Alex or #urgent"
			fields={fields}
			options={{ ...options, "#": ["urgent", "review", "done"] }}
			onChange={handleFilter}
		/>
	);
}
```

##### Strict Query Syntax

```jsx
<FilterQuery
	value={query}
	onChange={({ value, error }) => {
		setQuery(value);
		if (!error) applyFilter(value);
	}}
	parse="strict"
	placeholder="Status: Open and Age: >30"
	fields={fields}
	options={options}
/>
```

##### Natural Text Endpoint

```jsx
import { useState } from "react";
import { FilterQuery, createArrayFilter, getQueryString } from "@svar-ui/react-filter";

function Example() {
	const [normalizedQuery, setNormalizedQuery] = useState("");
	const [rows, setRows] = useState(data);

	async function handleNatural({ text, startProgress, endProgress }) {
		try {
			startProgress();
			const filter = await textToFilter(text, fields);
			setNormalizedQuery(filter ? getQueryString(filter).query : "");
			setRows(createArrayFilter(filter || { rules: [] })(data));
		} finally {
			endProgress();
		}
	}

	return (
		<>
			<FilterQuery
				parse="none"
				placeholder="first name contains Alex and age greater than 30"
				onChange={handleNatural}
			/>

			<pre>{normalizedQuery}</pre>
		</>
	);
}
```

##### Mixed Query And Natural Text

```jsx
import { useState } from "react";
import { FilterQuery, createArrayFilter, getQueryString } from "@svar-ui/react-filter";

function Example() {
	const [query, setQuery] = useState("start: 2024");
	const [rows, setRows] = useState(data);

	async function handleMixed({ value, error, text, startProgress, endProgress }) {
		if (text) {
			try {
				startProgress();
				value = await textToFilter(text, fields);
				setQuery(value ? getQueryString(value).query : "");
				error = null;
			} finally {
				endProgress();
			}
		} else {
			setQuery(value);
		}

		if (error && error.code !== "NO_DATA") return;
		setRows(createArrayFilter(value, {}, fields)(data));
	}

	return (
		<FilterQuery
			value={query}
			placeholder="FirstName: contains Alex and Age: >30"
			fields={fields}
			options={options}
			onChange={handleMixed}
		/>
	);
}
```

##### Render Query HTML

```jsx
import { useMemo } from "react";
import { getQueryHtml, getQueryString } from "@svar-ui/react-filter";

function Example({ filterValue, fields }) {
	const html = useMemo(
		() =>
			filterValue
				? getQueryHtml(getQueryString(filterValue).query, { fields })
				: "",
		[filterValue, fields]
	);

	return <div dangerouslySetInnerHTML={{ __html: html }} />;
}
```

#### Implementation Notes

- `parse="none"` bypasses highlight, autocomplete, parsing, and validation entirely.
- `NO_DATA` errors still pass parsed config and can be treated as non-blocking
- `getQueryHtml` returns inline styled HTML; only use it in trusted/internal query display contexts.


## File: gantt/index.md

> Source: `gantt/index.md`

Use when building, configuring, styling, or modifying SVAR React Gantt / @svar-ui/react-gantt timelines, grids, task editors, toolbars, context menus, tooltips, scales, links, and Gantt data actions.

#### Package

```js
import {
	Gantt,
	ContextMenu,
	HeaderMenu,
	Toolbar,
	Tooltip,
	Editor,
	Willow,
	WillowDark,
	version,
	defaultEditorItems,
	defaultToolbarButtons,
	defaultMenuOptions,
	defaultColumns,
	defaultTaskTypes,
	getEditorItems,
	getToolbarButtons,
	getMenuOptions,
	registerScaleUnit,
	registerEditorItem,
} from "@svar-ui/react-gantt";
import "@svar-ui/react-gantt/all.css";
```

#### Components

- `Gantt` - main grid plus timeline chart; `ref` exposes the Gantt API object from source.
- `Toolbar` - Gantt-aware wrapper around `@svar-ui/react-toolbar`; accepts `api` and optional `items`.
- `ContextMenu` - Gantt-aware wrapper around `@svar-ui/react-menu` context menu; resolves tasks from Gantt `data-id`.
- `Editor` - Gantt-aware wrapper around `@svar-ui/react-editor`; opens for `activeTask` / `show-editor`.
- `Tooltip` - wraps a Gantt and displays task text or a custom content component from `data-tooltip-id`.
- `HeaderMenu` - wraps `@svar-ui/react-grid` header menu and passes `api.getTable()` to it.
- `Willow`, `WillowDark` - theme wrappers; each accepts `fonts?: boolean` and optional children.

#### Supported functionality

##### Gantt Data

- `tasks` is an array of task objects; common fields are `id`, `text`, `start`, `end`, `duration`, `progress`, `parent`, `type`, `open`, `details`, `data`, `unscheduled`, `segments`, `base_start`, `base_end`, `base_duration`, `rollup`.
- `links` is an array of dependency links with `id`, `source`, `target`, `type`, optional `lag`.
- link `type` values are `s2s`, `s2e`, `e2s`, `e2e`.
- task `type` defaults are `task`, `summary`, `milestone`; custom types are supported through `taskTypes`.
- milestone tasks are normalized with `duration = 0` and no `end`.
- summary task dates are calculated from children when `start` / `end` are missing.
- `parseTaskDates(tasks, { durationUnit, splitTasks, calendar })` runs inside `Gantt` and mutates task date fields unless `_export` is set.

Common data objects:

```js
const tasks = [
	{
		id: 1,
		text: "Project",
		type: "summary",
		parent: 0,
		open: true,
	},
	{
		id: 10,
		text: "Task",
		type: "task",
		parent: 1,
		start: new Date(2026, 3, 2),
		duration: 3,
		progress: 40,
	},
	{
		id: 11,
		text: "Milestone",
		type: "milestone",
		parent: 1,
		start: new Date(2026, 3, 8),
	},
];

const links = [{ id: 1, source: 10, target: 11, type: "e2s" }];
```

##### Gantt Config

- default scales: `[{ unit: "month", step: 1, format: "%F %Y" }, { unit: "day", step: 1, format: "%j" }]`.
- `scales` rows accept `unit`, `step`, `format?: string | (date, next) => string`, `css?: (date) => string`.
- `start`, `end`, and `autoScale` control timeline bounds; `autoScale` includes tasks, markers, baselines, `projectStart`, and `projectEnd`.
- `zoom` accepts `true` or `IZoomConfig`; chart zoom is handled by Ctrl/Command + wheel and emits `zoom-scale`.
- `columns` defaults to `defaultColumns`; `columns={false}` hides the grid and resizer.
- the `text` column is rendered with the built-in `TextCell`; `add-task` uses `ActionCell`, is removed in `readonly`, and moves to the first column in compact chart mode.
- `cellWidth`, `cellHeight`, `scaleHeight` control timeline width, row height, and scale row height.
- `lengthUnit` controls chart math; `durationUnit` controls task duration calculation and is `"day"` or `"hour"`.
- `cellBorders` is `"column"` or `"full"`.
- `readonly` disables task drag, progress editing, link editing, grid add column behavior, and editor opening from double click.
- `selected` and `activeTask` are config inputs, not two-way bound props; read or change live selection through `api.getReactiveState()` and `api.exec("select-task", ...)`.
- `highlightTime(date, unit)` can return a CSS class for timescale cells and chart background cells when min unit is `day` or `hour`.
- compact mode is driven by a `ResizeObserver` on `document.body`; width `<= 650` switches the layout to grid/chart modes.

Common config objects:

```js
const columns = [
	{ id: "text", header: "Task name", flexgrow: 1, editor: "text" },
	{ id: "start", header: "Start date", align: "center", editor: "datepicker" },
	{ id: "duration", header: "Duration", width: 100, align: "center" },
	{ id: "add-task", header: "Add task", width: 50, align: "center" },
];

const scales = [
	{ unit: "month", step: 1, format: "%F %Y" },
	{ unit: "week", step: 1, format: "Week %w" },
	{ unit: "day", step: 1, format: "%j", css: date => date.getDay() === 0 ? "wx-weekend" : "" },
];

const zoom = {
	level: 2,
	minCellWidth: 40,
	maxCellWidth: 180,
};
```

##### Pro And Advanced Config

- `baselines` shows `base_start` / `base_end` / `base_duration`.
- `rollups` accepts `true` or `{ type: "all" | "closest" }`; tasks with `rollup: true` are drawn on summary rows.
- `markers` is an array of `{ start: Date, text?: string, css?: string }`.
- `criticalPath={{ type: "strict" | "flexible" }}` marks critical tasks and links.
- `schedule={{ type?: "forward", auto?: boolean }}` enables scheduling behavior; `projectStart` and `projectEnd` provide bounds.
- `calendar` accepts a `Calendar` from `@svar-ui/gantt-store`; Gantt then creates default weekend highlighting when `calendar` is set.
- `undo` enables history state plus `undo` / `redo` actions and toolbar buttons.
- `splitTasks` enables task `segments` editing, split toolbar/menu actions, and segment-aware editor/context-menu targets.
- `summary={{ autoProgress?: boolean, autoConvert?: boolean }}` controls summary progress and summary type conversion behavior.
- `slack` shows task slack visuals.
- `unscheduledTasks` enables task `unscheduled` support and editor scheduling controls.
- `api.exec("export-data", config)` supports `format: "pdf" | "png" | "xlsx" | "mspx"` through `IExportConfig`.
- `api.exec("import-data", { data, format: "mspx" })` imports MS Project XML.

##### API And Events

`Gantt` exposes this API from source through `ref` or `init(api)`:

- state: `getState()`, `getReactiveState()`, `getStores()`
- events/actions: `exec(action, data)`, `on(action, callback, config?)`, `intercept(action, callback, config?)`, `detach(tag)`, `setNext(eventBusOrProvider)`
- task/table helpers: `getTask(id)`, `getTable(waitRender?)`, `serialize()`, `getHistory()`

Component callback props are generated from action names by removing hyphens and prefixing `on` (camelCase in React):

- `add-task` -> `onAddTask`
- `update-task` -> `onUpdateTask`
- `select-task` -> `onSelectTask`
- custom `taskTemplate` action `"custom-click"` -> `onCustomClick`

Source routes actions through `DataStore` first, then calls the matching component callback prop if present.

Common actions:

```js
api.exec("add-task", {
	task: { text: "New task", type: "task" },
	target: 10,
	mode: "after",
	show: true,
});

api.exec("update-task", {
	id: 10,
	task: { text: "Updated", progress: 75 },
});

api.exec("select-task", {
	id: 10,
	toggle: false,
	range: false,
	show: "xy",
	focus: "grid",
});

api.exec("move-task", { id: 10, target: 1, mode: "child" });
api.exec("filter-tasks", { filter: task => task.text?.includes("API"), open: true });
api.exec("scroll-chart", { date: new Date(2026, 4, 1) });
```

Use `api.intercept(action, cb)` to block or replace built-in behavior; returning `false` blocks the action. Use `api.setNext(provider)` to forward data changes to a provider such as `RestDataProvider`.

##### Saving

- `RestDataProvider` from `@svar-ui/gantt-data-provider` persists data changes to a REST backend.
- Wire it once with `api.setNext(provider)` in `init`; the provider then forwards every data action (`add-task`, `update-task`, `delete-task`, `move-task`, `add-link`, `update-link`, `delete-link`, etc.) emitted on the event bus as the matching REST call. No per-action save handlers needed.
- Initial load uses `provider.getData()`; lazy branches use `provider.getData(id)` inside `request-data` and dispatch back through `provide-data`.
- Optional `{ batchURL }` constructor option batches concurrent writes into a single endpoint.

```js
import { RestDataProvider } from "@svar-ui/gantt-data-provider";

const provider = new RestDataProvider("/api/gantt");

function init(api) {
	api.setNext(provider); // forwards all task/link mutations to REST
}
```

##### Toolbar

- `Toolbar` source props are `api = null` and `items = []`.
- default items come from `getToolbarButtons({ undo: $undo, splitTasks: $splitTasks })`.
- default handled ids are wired through `handleAction(api, item.id, null, _)`.
- custom item `handler` functions are preserved only when the id is not one of the handled default action ids.
- if no task is selected, default toolbar keeps only targetless items such as `add-task` and history controls.
- `undo` adds `undo` and `redo`; `splitTasks` adds `split-task`.

Default toolbar ids:

```js
[
	"add-task",
	"edit-task",
	"delete-task",
	"move-task:up",
	"move-task:down",
	"copy-task",
	"cut-task",
	"paste-task",
	"indent-task:add",
	"indent-task:remove",
];
```

##### Context Menu

- `ContextMenu` source props are `options`, `api`, `resolver`, `filter`, `at = "point"`, `children`, `onClick`, `css`.
- the wrapper passes `dataKey="id"` to `@svar-ui/react-menu`; Gantt grid rows and bars expose `data-id`.
- built-in menu options are from `getMenuOptions({ splitTasks, taskTypes, summary })`.
- right-clicking a task selects it when it is not already selected.
- `resolver(id, event)` can return `true` to use the default task, return a replacement context object, or return a falsy value to prevent task resolution.
- `filter(option, task)` is applied across selected tasks; built-in `isHidden` and `isDisabled` are also applied.
- wrapper `onClick` receives the menu event used in demos as `{ context, action }`.
- built-in handled `action.id` values are executed through `handleAction(api, action.id, activeId, _)` before user `onClick`.
- with `splitTasks`, segment targets use `{ id, segmentIndex }` internally for edit/delete/split actions.

Default menu ids:

```js
[
	"add-task:child",
	"add-task:before",
	"add-task:after",
	"convert-task:<taskType>",
	"edit-task",
	"cut-task",
	"copy-task",
	"paste-task",
	"move-task:up",
	"move-task:down",
	"indent-task:add",
	"indent-task:remove",
	"delete-task",
];
```

##### Editor

- `Editor` source props are `api`, `items = []`, `css = ""`, `layout = "default"`, `readonly = false`, `placement = "sidebar"`, `bottomBar = true`, `topBar = true`, `autoSave = true`, `focus = false`, `hotkeys = {}`.
- editor renders only when `api.getReactiveState()._activeTask` exists.
- default items come from `getEditorItems({ unscheduledTasks, rollups, summary, taskTypes })`.
- built-in editor comps registered by the wrapper: `select`, `date`, `twostate`, `slider`, `counter`, `links`, `checkbox`.
- `registerEditorItem(name, Component)` registers custom comps for `items`.
- item `key` is the task field; editor values are task objects keyed by those `key` values.
- `autoSave={true}` saves valid changes on field change; `autoSave={false}` stores local values and saves from a `save` top/bottom bar action.
- saved task payload removes `links` and `data`; `duration` may be removed when no duration editor is present.
- `links` editor changes are batched in the wrapper and saved through link actions.
- default `topBar={true}` in editable mode creates close/spacer/delete buttons, plus save when `autoSave={false}`.

Default editor keys:

```js
["text", "details", "type", "start", "end", "duration", "progress", "links"]
```

##### Tooltip

- `Tooltip` source props are `api`, `content`, `children`.
- default tooltip text is the task `text`, or segment `text` when `data-segment` is present.
- custom `content` component receives `{ data }`; source also passes `segmentIndex` for split-task segments.
- direct tooltip override can use a DOM `data-tooltip` attribute; placement hint uses `data-tooltip-at="left"`.
- tooltip lookup is debounced by 300ms.

##### Header Menu

- `HeaderMenu` source props are `api`, `columns`, `children`.
- wrapper calls `api?.getTable()` and passes that table API to `@svar-ui/react-grid` `HeaderMenu`.
- use it when the grid table API is needed for column visibility/menu behavior.

#### Public Types

```ts
import type { ComponentType, ComponentProps, ReactNode } from "react";
import { ContextMenu as BaseContextMenu } from "@svar-ui/react-menu";
import { Toolbar as BaseToolbar } from "@svar-ui/react-toolbar";
import { Editor as BaseEditor } from "@svar-ui/react-editor";
import {
	HeaderMenu as BaseHeaderMenu,
	IColumnConfig as ITableColumn,
} from "@svar-ui/react-grid";

import type {
	TMethodsConfig,
	IApi,
	IConfig,
	ITask,
	IGanttColumn,
} from "@svar-ui/gantt-store";

export * from "@svar-ui/gantt-store";
export { registerEditorItem } from "@svar-ui/react-editor";

export interface IColumnConfig extends Omit<IGanttColumn, "header"> {
	cell?: ITableColumn["cell"];
	header?: ITableColumn["header"];
	editor?: ITableColumn["editor"];
}

export declare const Gantt: ComponentType<
	{
		columns?: false | IColumnConfig[];
		taskTemplate?: ComponentType<{
			data: ITask;
			api: IApi;
			onAction: (ev: {
				action: string;
				data: { [key: string]: any };
			}) => void;
		}>;
		readonly?: boolean;
		cellBorders?: "column" | "full";
		highlightTime?: (date: Date, unit: "day" | "hour") => string;
		init?: (api: IApi) => void;
	} & IConfig &
		GanttActions<TMethodsConfig>
>;

export declare const HeaderMenu: ComponentType<
	ComponentProps<typeof BaseHeaderMenu> & {
		api?: IApi;
	}
>;

export declare const ContextMenu: ComponentType<
	ComponentProps<typeof BaseContextMenu> & {
		api?: IApi;
	}
>;

export declare const Toolbar: ComponentType<
	ComponentProps<typeof BaseToolbar> & {
		api?: IApi;
	}
>;

export declare const Editor: ComponentType<
	ComponentProps<typeof BaseEditor> & {
		api?: IApi;
	}
>;

export declare const Tooltip: ComponentType<{
	content?: ComponentType<{
		data: ITask;
	}>;
	api?: IApi;
	children?: ReactNode;
}>;

export declare const Willow: ComponentType<{
	fonts?: boolean;
	children?: ReactNode;
}>;

export declare const WillowDark: ComponentType<{
	fonts?: boolean;
	children?: ReactNode;
}>;

/* get component events from store actions*/
type RemoveHyphen<S extends string> = S extends `${infer Head}-${infer Tail}`
	? `${Head}${Capitalize<RemoveHyphen<Tail>>}`
	: S;

type EventName<K extends string> = `on${Capitalize<RemoveHyphen<K>>}`;

export type GanttActions<TMethodsConfig extends Record<string, any>> = {
	[K in keyof TMethodsConfig as EventName<K & string>]?: (
		ev: TMethodsConfig[K]
	) => void;
} & {
	[key: `on${string}`]: (ev?: any) => void;
};
```

#### Styling

Import the package CSS before using the component (`all.css` includes dependency styles, `style.css` is this component only)

Main hooks:

- root/layout: `.wx-gantt`, `.wx-pseudo-rows`, `.wx-stuck`, `.wx-layout`, `.wx-content`
- grid: `.wx-table-container`, `.wx-table`, `.wx-grid`, `.wx-header`, `.wx-body`, `.wx-row`, `.wx-cell`, `.wx-action`, `.wx-toggle-icon`, `.wx-action-icon`
- chart: `.wx-chart`, `.wx-scale`, `.wx-area`, `.wx-bars`, `.wx-bar`, `.wx-task`, `.wx-summary`, `.wx-milestone`, `.wx-content`, `.wx-text-out`
- custom task types: built-ins render as `.wx-task`, `.wx-summary`, `.wx-milestone`; custom task types render as `.wx-task.<customType>`
- task state: `.wx-selected`, `.wx-critical`, `.wx-reorder-task`, `.wx-split`, `.wx-touch`
- progress/links: `.wx-progress-wrapper`, `.wx-progress-percent`, `.wx-progress-marker`, `.wx-link`, `.wx-line`, `.wx-line-selected`, `.wx-delete-link`
- split/rollup/baseline/slack: `.wx-segments`, `.wx-segment`, `.wx-rollup`, `.wx-task-rollup`, `.wx-summary-rollup`, `.wx-milestone-rollup`, `.wx-baseline`, `.wx-slack`, `.wx-slack-task`
- scales/markers/holidays: `.wx-scale`, `.wx-row`, `.wx-cell`, `.wx-weekend`, `.wx-markers`, `.wx-marker`
- companion components: `.wx-gantt-editor`, `.wx-gantt-tooltip`, `.wx-gantt-tooltip-text`, `.wx-tooltip-area`, `.wx-menu`, `.wx-option`
- resizer/display controls: `.wx-resizer`, `.wx-resizer-display-all`, `.wx-resizer-display-grid`, `.wx-resizer-display-chart`, `.wx-button-expand-left`, `.wx-button-expand-right`

Layout defaults:

- the host container must provide height; `.wx-gantt` uses `height: 100%; width: 100%; overflow-y: auto`.
- `.wx-layout` is a flex row with hidden overflow.
- `.wx-table-container` uses `flex: 0 0 <grid width>` and `height: 100%`.
- `.wx-chart` uses `flex: 1 1 auto` with horizontal scrolling.
- `.wx-scale` is sticky at the top of the chart.
- `columns={false}` removes grid and resizer; otherwise grid and chart are split by the resizer.

Important CSS variables:

- bars: `--wx-gantt-bar-font`, `--wx-gantt-bar-border-radius`, `--wx-gantt-bar-shadow`
- tasks: `--wx-gantt-task-color`, `--wx-gantt-task-fill-color`, `--wx-gantt-task-font-color`, `--wx-gantt-task-border`, `--wx-gantt-task-border-color`
- summaries/milestones: `--wx-gantt-summary-color`, `--wx-gantt-summary-fill-color`, `--wx-gantt-summary-font-color`, `--wx-gantt-milestone-color`, `--wx-gantt-milestone-border-radius`
- critical/slack: `--wx-gantt-critical-color`, `--wx-gantt-task-critical-color`, `--wx-gantt-task-critical-fill-color`, `--wx-gantt-task-slack-color`, `--wx-gantt-task-slack-border-color`
- links: `--wx-gantt-link-color`, `--wx-gantt-link-color-hovered`, `--wx-gantt-link-critical-color`, `--wx-gantt-link-critical-color-hovered`, `--wx-gantt-link-marker-background`, `--wx-gantt-link-marker-color`
- grid/scale: `--wx-gantt-border`, `--wx-gantt-select-color`, `--wx-grid-body-font`, `--wx-grid-header-font`, `--wx-timescale-font`, `--wx-timescale-border`, `--wx-timescale-shadow`
- markers/tooltips: `--wx-gantt-marker-color`, `--wx-gantt-marker-font`, `--wx-gantt-marker-font-color`, `--wx-tooltip-background`, `--wx-tooltip-font`, `--wx-tooltip-font-color`

```jsx
import "./GanttShell.css";
import { Gantt, Willow } from "@svar-ui/react-gantt";

<div className="gantt-shell">
	<Willow>
		<Gantt tasks={tasks} links={links} />
	</Willow>
</div>

/* GanttShell.css
.gantt-shell {
	height: 100%;
}

.gantt-shell .wx-gantt .wx-bar.wx-task.urgent {
	background-color: #f49a82;
	border: 1px solid #f45e36;
}

.gantt-shell .wx-gantt .wx-bar.wx-task.urgent .wx-progress-percent {
	background-color: #f45e36;
}

.gantt-shell .wx-gantt .my-marker {
	background-color: rgba(255, 84, 84, 0.77);
}
*/
```

#### Recipes

##### Basic Gantt With Theme

```jsx
import "./GtCell.css";
import { Gantt, Willow } from "@svar-ui/react-gantt";

function BasicGantt() {
	const tasks = [
		{ id: 1, text: "Planning", type: "summary", parent: 0, open: true },
		{
			id: 10,
			text: "Research",
			type: "task",
			parent: 1,
			start: new Date(2026, 3, 2),
			duration: 3,
			progress: 50,
		},
	];
	const links = [];

	return (
		<div className="gtcell">
			<Willow>
				<Gantt tasks={tasks} links={links} />
			</Willow>
		</div>
	);
}

/* GtCell.css
.gtcell {
	height: 100%;
}
*/
```

##### Toolbar, Context Menu, And Editor

```jsx
import "./GtCell.css";
import { useState } from "react";
import { Gantt, Toolbar, ContextMenu, Editor } from "@svar-ui/react-gantt";

function ToolbarGantt() {
	const [api, setApi] = useState();

	return (
		<>
			<Toolbar api={api} />

			<div className="gtcell">
				<ContextMenu api={api}>
					<Gantt ref={setApi} tasks={tasks} links={links} scales={scales} undo />
				</ContextMenu>
				{api && <Editor api={api} />}
			</div>
		</>
	);
}

/* GtCell.css
.gtcell {
	height: calc(100% - 50px);
	border-top: var(--wx-gantt-border);
}
*/
```

##### Initialize API And Handle Actions

```jsx
import { useState } from "react";
import { Gantt, Editor } from "@svar-ui/react-gantt";

function InitApiGantt() {
	const [api, setApi] = useState();

	function init(ganttApi) {
		setApi(ganttApi);

		ganttApi.on("add-task", ({ id }) => {
			ganttApi.exec("show-editor", { id });
		});

		ganttApi.intercept("sort-tasks", ev => {
			return ev.key === "text";
		});
	}

	return (
		<>
			<Gantt
				init={init}
				tasks={tasks}
				links={links}
				onUpdateTask={ev => console.log(ev.id, ev.task)}
			/>
			{api && <Editor api={api} />}
		</>
	);
}
```

##### Custom Columns And Inline Editors

```jsx
import { Gantt } from "@svar-ui/react-gantt";
import AvatarCell from "./AvatarCell.jsx";

function CustomColumnsGantt() {
	const columns = [
		{ id: "text", header: "Task name", width: 220, editor: "text" },
		{ id: "assigned", header: "Assigned", width: 160, cell: AvatarCell },
		{
			id: "start",
			header: ["Start date", { filter: { type: "datepicker" } }],
			align: "center",
			width: 130,
			editor: "datepicker",
		},
		{ id: "add-task", header: "Add task", width: 50, align: "center" },
	];

	return <Gantt tasks={tasks} links={links} columns={columns} cellHeight={40} />;
}
```

##### Custom Task Content And Custom Event

```jsx
// TaskContent.jsx
function TaskContent({ data, onAction }) {
	function toggle(ev) {
		ev.stopPropagation();
		onAction({
			action: "custom-click",
			data: { id: data.id, clicked: !data.clicked },
		});
	}

	return <button onClick={toggle}>{data.clicked ? "Clicked" : "Click"}</button>;
}

export default TaskContent;
```

```jsx
import { useRef } from "react";
import { Gantt } from "@svar-ui/react-gantt";
import TaskContent from "./TaskContent.jsx";

function TaskContentGantt() {
	const apiRef = useRef(null);

	return (
		<Gantt
			ref={apiRef}
			tasks={tasks}
			links={links}
			taskTemplate={TaskContent}
			onCustomClick={ev =>
				apiRef.current.exec("update-task", {
					id: ev.id,
					task: { clicked: ev.clicked },
				})}
		/>
	);
}
```

##### Custom Editor Items

```jsx
import { useState } from "react";
import {
	Gantt,
	Editor,
	getEditorItems,
	registerEditorItem,
	defaultTaskTypes,
} from "@svar-ui/react-gantt";
import { RadioButtonGroup } from "@svar-ui/react-core";

registerEditorItem("radio", RadioButtonGroup);

function CustomEditorItemsGantt() {
	const base = getEditorItems();
	const items = base.map(item =>
		item.key === "type"
			? {
					key: "type",
					comp: "radio",
					label: "Type",
					options: defaultTaskTypes.map(type => ({
						...type,
						value: type.id,
					})),
					config: { type: "inline" },
				}
			: item
	);

	const [api, setApi] = useState();

	return (
		<>
			<Gantt init={setApi} tasks={tasks} links={links} />
			{api && <Editor api={api} items={items} placement="modal" autoSave={false} />}
		</>
	);
}
```

##### Custom Menu Options

```jsx
import { useState } from "react";
import { Gantt, ContextMenu, Editor, getMenuOptions } from "@svar-ui/react-gantt";

function CustomMenuGantt() {
	const [api, setApi] = useState();
	const ids = ["cut-task", "copy-task", "paste-task", "delete-task"];
	const options = [
		{ id: "add-task:after", text: "Add below", icon: "wxi-plus" },
		...getMenuOptions().filter(op => ids.includes(op.id)),
		{
			id: "custom-action",
			text: "Custom action",
			icon: "wxi-empty",
			handler: () => console.log("custom action"),
		},
	];

	return (
		<>
			<ContextMenu
				api={api}
				options={options}
				onClick={({ context, action }) => console.log(context?.id, action?.id)}
			>
				<Gantt init={setApi} tasks={tasks} links={links} />
			</ContextMenu>
			{api && <Editor api={api} />}
		</>
	);
}
```

##### Scales, Zoom, Markers, And Holidays

```jsx
import { Gantt } from "@svar-ui/react-gantt";

function ScalesGantt() {
	const scales = [
		{ unit: "year", step: 1, format: "%Y" },
		{ unit: "month", step: 1, format: "%F" },
		{ unit: "day", step: 1, format: "%j" },
	];

	const markers = [
		{ start: new Date(2026, 3, 2), text: "Start" },
		{ start: new Date(2026, 3, 8), text: "Review", css: "my-marker" },
	];

	function highlightTime(date, unit) {
		const weekend = date.getDay() === 0 || date.getDay() === 6;
		return unit === "day" && weekend ? "wx-weekend" : "";
	}

	return (
		<Gantt
			tasks={tasks}
			links={links}
			scales={scales}
			markers={markers}
			highlightTime={highlightTime}
			start={new Date(2026, 3, 1)}
			end={new Date(2026, 4, 1)}
			cellWidth={60}
			zoom
		/>
	);
}
```

##### Pro Feature Bundle

```jsx
import { useState } from "react";
import {
	Gantt,
	ContextMenu,
	Editor,
	Toolbar,
	Tooltip,
} from "@svar-ui/react-gantt";
import { Calendar } from "@svar-ui/gantt-store";
import TooltipContent from "./TooltipContent.jsx";

function ProGantt() {
	const calendar = new Calendar({
		weekHours: {
			monday: 8,
			tuesday: 8,
			wednesday: 8,
			thursday: 8,
			friday: 8,
			saturday: 0,
			sunday: 0,
		},
	});

	const [api, setApi] = useState();

	return (
		<>
			<Toolbar api={api} />
			<div className="gtcell">
				<ContextMenu api={api}>
					<Tooltip api={api} content={TooltipContent}>
						<Gantt
							init={setApi}
							tasks={tasks}
							links={links}
							calendar={calendar}
							baselines
							splitTasks
							rollups={{ type: "closest" }}
							criticalPath={{ type: "flexible" }}
							summary={{ autoProgress: true }}
							undo
						/>
					</Tooltip>
				</ContextMenu>
				{api && <Editor api={api} />}
			</div>
		</>
	);
}
```

##### Server Provider And Lazy Data

```jsx
import { useEffect, useState } from "react";
import { Gantt, ContextMenu, Editor } from "@svar-ui/react-gantt";
import { RestDataProvider } from "@svar-ui/gantt-data-provider";

function ServerGantt() {
	const provider = new RestDataProvider("/api/gantt");
	const [api, setApi] = useState();
	const [tasks, setTasks] = useState([]);
	const [links, setLinks] = useState([]);

	useEffect(() => {
		provider.getData().then(data => {
			setTasks(data.tasks);
			setLinks(data.links);
		});
	}, []);

	function init(ganttApi) {
		setApi(ganttApi);
		ganttApi.setNext(provider);
		ganttApi.on("request-data", ev => {
			provider.getData(ev.id).then(data => {
				ganttApi.exec("provide-data", { id: ev.id, data });
			});
		});
	}

	return (
		<>
			<ContextMenu api={api}>
				<Gantt init={init} tasks={tasks} links={links} />
			</ContextMenu>
			{api && <Editor api={api} />}
		</>
	);
}
```

#### Implementation Notes

- `Tooltip.content` is typed as receiving only `{ data }`, but source also passes `segmentIndex` for split-task segment tooltips.
- `show-editor` public action type is `{ id: TID }`, but split-task source also passes `segmentIndex`.
- `Gantt` mutates task objects during date normalization; clone `tasks` before passing them if caller-owned data must remain unchanged.
- `columns` can be `false` for no grid; it is normalized to an empty column set by the store.
- date column templates are added automatically for `start`, `end`, and `duration` unless a column has a custom `template`.
- default `add-task` actions create `{ type: "task", text: _("New Task") }` and usually select or show the new task depending on caller.


## File: tasklist/index.md

> Source: `tasklist/index.md`

Use when building, configuring, styling, localizing, or modifying SVAR React Tasklist / @svar-ui/react-tasklist components

#### Package

```js
import { Tasklist } from "@svar-ui/react-tasklist";
import "@svar-ui/react-tasklist/all.css";
```

#### Supported functionality

`Tasklist` renders a vertical task list with built-in add, edit, delete, and status controls.

##### Data

- `value` accepts either an `ITask[]` array or a `string | number` key used with `ondata`.
- Without `ondata`, `value` is used as the task array.
- With `ondata`, `ondata(value)` is called only when `value` is truthy; it may return `ITask[]` or a promise.
- While async data is pending, the component renders an empty list in readonly mode.
- `ITask.content` is required; `status` is numeric and `1` marks a completed task in the UI.
- Existing tasks should have stable unique `id` values because rows are keyed by `task.id`.

##### Events and persistence

- `onChange` receives an `IChange` object for `add`, `update`, and `delete`.
- `Tasklist` adds `originalValue` to the event before calling the user handler.
- Add event shape: `{ action: "add", task, value, originalValue }`.
- Update event shape: `{ action: "update", id, task, value, originalValue }`.
- Delete event shape: `{ action: "delete", id, value, originalValue }`.
- `value` is not two-way bound; use `onChange` to persist `ev.value` in app state or a backend.
- For add only, if `onChange` returns an object or a promise resolving to an object, that object is merged into the newly added task (can't be used to change `id`)

##### Other

- `readonly={true}` hides the add, edit, and delete controls and prevents double-click edit.


#### Public Types

```ts
import type { ComponentType } from "react";

export interface IChange {
	action: "add" | "update" | "delete";
	id?: string | number;
	task?: ITask;
	value: ITask[];
	originalValue: string | number | ITask[];
}

export interface ITask {
	id?: string | number;
	content: string;
	status?: number;
}

export declare const Tasklist: ComponentType<{
	ondata?: (value: string | number) => Promise<ITask[]> | ITask[];
	onChange?: (ev: IChange) => void;
	value?: string | number | ITask[];
	readonly?: boolean;
}>;
```

#### Styling

Import the package CSS before using the component (`all.css` includes dependency styles, `style.css` is this component only)

- Parent layout matters: `.wx-tasks-list` is `height: 100%`, so give the containing element an explicit height when scroll behavior matters.
- List container: `.wx-list`
- Task row: `.wx-task`
- Editor textarea class is `.wx-texarea`

```jsx
import "./TasklistPanel.css";

<div className="tasklist-panel">
	<Tasklist value={tasks} />
</div>

/* TasklistPanel.css
.tasklist-panel {
	height: 420px;
	max-width: 768px;
	margin: 20px;
}

.tasklist-panel .wx-task {
	padding: 10px 0 6px;
}

.tasklist-panel .wx-list {
	gap: 2px;
}
*/
```

#### Recipes

##### Basic Tasklist

```jsx
import "./TasksScope.css";
import { Tasklist } from "@svar-ui/react-tasklist";

function BasicTasklist() {
	const tasks = [
		{ id: 1, content: "Write project notes", status: 0 },
		{ id: 2, content: "Send status update", status: 1 },
	];

	return (
		<div className="tasks">
			<Tasklist value={tasks} />
		</div>
	);
}

/* TasksScope.css
.tasks {
	height: 360px;
	max-width: 768px;
}
*/
```

##### Persist Changes

```jsx
import { useState } from "react";
import { Tasklist } from "@svar-ui/react-tasklist";

function PersistedTasklist() {
	const [tasks, setTasks] = useState([]);

	async function onChange(ev) {
		setTasks(ev.value);

		if (ev.action === "add") {
			return api.createTask(ev.task);
		}

		if (ev.action === "update") {
			await api.updateTask(ev.id, ev.task);
		}

		if (ev.action === "delete") {
			await api.deleteTask(ev.id);
		}
	}

	return <Tasklist value={tasks} onChange={onChange} />;
}
```

##### Resolve Data From A Key

```jsx
import { useState } from "react";
import { Tasklist } from "@svar-ui/react-tasklist";

function KeyedTasklist() {
	const [listId, setListId] = useState(1);

	return (
		<Tasklist
			value={listId}
			ondata={id => api.getTasks(id)}
			onChange={({ action, task, id: taskId, originalValue }) =>
				api.saveTaskChange(originalValue, action, task, taskId)}
		/>
	);
}
```

##### Readonly List

```jsx
import { Tasklist } from "@svar-ui/react-tasklist";

function ReadonlyTasklist() {
	const tasks = [{ id: 1, content: "Review release notes", status: 0 }];

	return <Tasklist value={tasks} readonly={true} />;
}
```


## File: comments/index.md

> Source: `comments/index.md`

Use when building, configuring, styling, localizing, or integrating SVAR React Comments / @svar-ui/react-comments components

#### Package

```js
import { Comments, Willow, WillowDark } from "@svar-ui/react-comments";
import "@svar-ui/react-comments/all.css";
```

Top-level exports:

- `Comments` - comments list with add, edit, delete, async data loading, built-in message layouts, and text/markdown rendering
- `Willow`, `WillowDark` - theme wrappers that forward to `@svar-ui/react-core` themes and add comments CSS variables

#### Supported functionality

##### Data And Users

- `value` is either an `IComment[]` or a truthy key passed to `ondata(value)`
- `ondata(value)` may return `IComment[]` or `Promise<IComment[]>`; while pending, the layout renders with `data=[]`
- `IComment.author` object wins when present; otherwise `IComment.user` is resolved against `users`
- users without `color` get a generated HSL color from `id + name`
- unknown users render as `{ id: 0, name: "Unknown", color: "hsl(0, 0%, 85%)" }`
- `activeUser` can be a user id or an `IUser`; new comments use it for `author` and `user`
- source date formatting uses `comments.dateFormat` or locale specific
-
Common data objects:

```js
const users = [
	{ id: 1, name: "Alice Smith", avatar: "/avatars/alice.png" },
	{ id: 2, name: "Marta Kowalska", color: "#e23a43" },
];

const value = [
	{ id: 1, user: 1, content: "Plain text", date: new Date() },
	{ id: 2, author: users[1], content: "**Markdown**", format: "markdown" },
];
```

##### Change Flow

- add creates `{ id: uid(), content, author, user: author.id, date: new Date() }`
- add/update/delete replace internal data with a new array before calling `onchange`
- add payload: `{ action: "add", value, comment, originalValue }`
- update payload: `{ action: "update", value, id, comment, originalValue }`
- delete payload: `{ action: "delete", value, id, originalValue }`
- if add `onchange` returns an object or promise, returned fields are merged into the newly added comment
- `value` is not two-way bound; keep parent state or backend state synchronized from `onchange`

##### Rendering Modes

- `render="flow"` is the default layout
- `render="bubbles"` uses chat-style bubbles
- custom `render` component receives `owned`, `edit`, `author`, `date`, and `children` from source
- `format="text"` is the default content renderer
- `format="markdown"` renders markdown content through the bundled Lima renderer
- custom `format` component receives `{ content }`
- per-comment `comment.format` overrides the component-level `format`

Built-ins:

```js
{ render: "flow" }
{ render: "bubbles" }
{ format: "text" }
{ format: "markdown" }
```

##### Editing And Deleting

- owned comments are comments where `message.author.id === active author id`
- only owned comments get the visible menu icon
- internal action menu options are `edit-comment` and `delete-comment`
- edit mode replaces message content with the same textarea component used for posting
- `Ctrl+Enter` or `Cmd+Enter` posts textarea content
- empty textarea content is ignored

#### Public Types

```ts
import type { ComponentType, ReactNode } from "react";

export interface IUser {
	id: string | number;
	name?: string;
	avatar?: string;
	color?: string;
}

export interface IComment {
	id?: string | number;
	content: string;
	author?: IUser;
	user?: string | number;
	date?: Date;
	format?: "text" | "markdown" | FormatComponent;
}

export interface IChange {
	action: "add" | "update" | "delete";
	id?: string | number;
	comment?: IComment;
	value: IComment[];
	originalValue: IComment[] | string | number;
}

export type FormatComponent = ComponentType<{
	content: string;
}>;

export type RenderComponent = ComponentType<{
	owned?: string | number;
	edit?: string | number;
	author: IUser;
	date: Date;
	children?: ReactNode;
}>;

export declare const Comments: ComponentType<{
	ondata?: (value: string | number) => Promise<IComment[]> | IComment[];
	onChange?: (ev: IChange) => void;
	value?: IComment[] | string | number;
	readonly?: boolean;
	render?: "bubbles" | "flow" | RenderComponent;
	format?: "text" | "markdown" | FormatComponent;
	users?: IUser[];
	activeUser?: string | number | IUser;
	focus?: boolean;
}>;

export declare const Willow: ComponentType<{
	fonts?: boolean;
	children?: ReactNode;
}>;

export declare const WillowDark: ComponentType<{
	fonts?: boolean;
	children?: ReactNode;
}>;
```

#### Styling

Import the package CSS before using the component (`all.css` includes dependency styles, `style.css` is this component only)

- root list: `.wx-comments-list` is `height: 100%`
- scroll body: `.wx-list` is flex column
- message stack: `.wx-messages`
- flow layout: `.wx-flow`, `.wx-flow.wx-owned`, `.wx-flow-toolbar`, `.wx-message`, `.wx-menu-icon`, `.wx-comment-date`
- bubble layout: `.wx-bubble`, `.wx-bubble.wx-owned`, `.wx-bubble-wrapper`, `.wx-main-bubble`, `.wx-agent-message`, `.wx-avatar`, `.wx-message`
- shared message hooks: `.wx-author-name`, `.wx-menu-icon`, `.wx-comment-date`, `.wx-owned`
- composer hooks: `.wx-comments-textarea`, `.wx-comments-textarea.wx-flow`, `.wx-textarea-wrapper`, `.wx-textarea-avatar`, `.wx-textarea-bottombar`
- avatar hooks: `.wx-user`, `.wx-user.wx-small`, `.wx-user.wx-normal`, `.wx-border`, `.wx-comments-avatar-color-light`, `.wx-comments-avatar-color-dark`
- edit/delete menu is rendered by `@svar-ui/react-menu`
- package CSS variables: `--wx-comments-msg-background`, `--wx-comments-msg-background-agent`, `--wx-avatar-color-dark`

```jsx
import "./CommentsPane.css";

<div className="comments-pane">
	<Comments value={comments} users={users} activeUser={1} />
</div>

/* CommentsPane.css
.comments-pane {
	height: 480px;
	max-width: 760px;
}

.comments-pane .wx-comments-list {
	border: var(--wx-border);
}

.comments-pane .wx-flow {
	padding: 12px 16px;
}

.comments-pane .wx-comments-textarea {
	padding-top: 8px;
}
*/
```

#### Recipes

##### Basic Comments

```jsx
import { useState } from "react";
import { Comments } from "@svar-ui/react-comments";

function BasicComments() {
	const [comments, setComments] = useState([
		{ id: 1, user: 1, content: "First comment", date: new Date() },
	]);

	const users = [
		{ id: 1, name: "Alice Smith", avatar: "/avatars/alice.png" },
		{ id: 2, name: "Marta Kowalska", color: "#e23a43" },
	];

	return <Comments value={comments} users={users} activeUser={1} focus={true} />;
}
```

##### Persist Changes

```jsx
import { useState } from "react";
import { Comments } from "@svar-ui/react-comments";

function PersistedComments() {
	const [comments, setComments] = useState([]);
	const activeUser = { id: 1, name: "Alice Smith" };

	async function saveChange(ev) {
		setComments(ev.value);

		if (ev.action === "add") {
			return await api.createComment(ev.comment);
		}

		if (ev.action === "update") {
			await api.updateComment(ev.id, ev.comment);
		}

		if (ev.action === "delete") {
			await api.deleteComment(ev.id);
		}
	}

	return <Comments value={comments} onChange={saveChange} activeUser={activeUser} />;
}
```

##### Load By External Key

```jsx
import { useState } from "react";
import { Comments } from "@svar-ui/react-comments";

function LoadByKey() {
	const [pageId, setPageId] = useState(1);
	const users = [{ id: 1, name: "Alice Smith" }];

	function loadComments(id) {
		return api.getComments(id);
	}

	function saveComment({ action, comment, id, originalValue }) {
		return api.forPage(originalValue).save(action, comment, id);
	}

	return (
		<Comments
			value={pageId}
			ondata={loadComments}
			onChange={saveComment}
			users={users}
			activeUser={1}
		/>
	);
}
```

##### Switch Layout Or Markdown

```jsx
import { useState } from "react";
import { Comments } from "@svar-ui/react-comments";

function LayoutSwitch() {
	const [render, setRender] = useState("flow");
	const comments = [
		{ id: 1, user: 1, content: "### Title\n\n**Markdown** text" },
	];
	const users = [{ id: 1, name: "Alice Smith" }];

	return (
		<Comments
			value={comments}
			users={users}
			activeUser={1}
			render={render}
			format="markdown"
		/>
	);
}
```

##### Custom Message And Content Renderers

```jsx
// MessageRenderer.jsx
function MessageRenderer({ owned, author, date, children }) {
	return (
		<div className={owned ? "owned" : ""} style={{ paddingLeft: 8 }}>
			<b>{author.name}</b>
			<span>{date.toLocaleString()}</span>
			{children}
		</div>
	);
}

export default MessageRenderer;
```

```jsx
// ContentRenderer.jsx
function ContentRenderer({ content }) {
	return <span className="content">{content.toUpperCase()}</span>;
}

export default ContentRenderer;
```

```jsx
import { Comments } from "@svar-ui/react-comments";
import MessageRenderer from "./MessageRenderer.jsx";
import ContentRenderer from "./ContentRenderer.jsx";

function CustomRenderers() {
	const users = [{ id: 1, name: "Alice Smith" }];
	const comments = [{ id: 1, user: 1, content: "Hello", date: new Date() }];

	return (
		<Comments
			value={comments}
			users={users}
			activeUser={1}
			render={MessageRenderer}
			format={ContentRenderer}
		/>
	);
}
```

#### Implementation Notes

- there is no public item registration API; custom renderers are passed directly through `render` and `format`


## File: filemanager/index.md

> Source: `filemanager/index.md`

Use when building, configuring, styling, or modifying SVAR React Filemanager / @svar-ui/react-filemanager components, menus, themes, store actions, or backend data provider integration.

#### Package

```js
import {
	Filemanager,
	Willow,
	WillowDark,
	getMenuOptions,
} from "@svar-ui/react-filemanager";
import "@svar-ui/react-filemanager/all.css";
```

#### Supported functionality

##### Components and themes

- `Filemanager` renders the full file explorer: toolbar, search, sidebar tree, cards/table/panels views, preview/info panel, context/action menus, upload drop area, and modals.
- `Willow`, and `WillowDark` wrap matching `@svar-ui/react-core` themes and add filemanager CSS variables.
- Theme components accept `fonts?: boolean` and optional React children.
- `Filemanager` has no `children`, `class`, `style`, or `css` passthrough prop.

##### Data model

- `data` is a flat `IEntity[]`; each item must have path-like `id`, such as `"/Code/Button.js"`.
- Root `"/"` is generated internally as a folder named `"My files"`.
- `FileTree.parseId` derives `parent`, `name`, and `ext` from `id`; missing `type` defaults to `"file"`.
- Folder items are the only records rendered in the sidebar tree.
- `date` is expected as a `Date` object for built-in formatting.
- `lazy: true` on a folder triggers `request-data` when the folder path is opened.
- Duplicate create/copy names are made unique by appending `.new` before the extension, for example `"/file.new.txt"`.
- `drive` is optional and only renders storage info when both `used` and `total` are present.

##### Modes and layout

- `mode` supports `"cards"`, `"table"`, `"panels"`, and `"search"`.
- Toolbar mode buttons only expose `"table"`, `"cards"`, and `"panels"`.
- Search runs `filter-files`; non-empty text switches to `"search"` mode and clearing text restores previous `mode` and `panels`.
- `preview` toggles the info pane; on containers narrower than `768px`, preview uses a narrow full-content layout.
- `panels` accepts partial panel state; common fields are `path` and `selected`.
- `activePanel` is `0` or `1` and is used in panels mode and upload drop handling.

##### API and events

- Use `init(api)` for first-time API setup; it is called once after initial store setup.
- `ref={apiRef}` exposes the same public methods: `exec`, `on`, `intercept`, `detach`, `setNext`, `getState`, `getReactiveState`, `getStores`, `getFile`, and `serialize`.
- Component event props are generated from store action names by removing hyphens and prefixing `on` (camelCase in React), for example `onRequestData`, `onDownloadFile`, `onOpenFile`, `onCreateFile`.
- Event callback payloads are the same objects passed to `api.exec(action, payload)`.
- Action flow is store first, then component event props, then any next bus set by `api.setNext(...)`.
- `api.intercept(action, callback)` can cancel or replace built-in behavior by returning `false`, as shown by backend filtering demos.
- The store mutates some action payloads before downstream handlers/providers: `rename-file.newId`, `create-file.newId`, `copy-files.newIds`, `move-files.newIds`, and `skipProvider` when copy/move into self is rejected.

##### Built-in actions

- Selection/navigation: `select-file`, `set-path`, `set-active-panel`, `open-tree-folder`.
- View/search/sort: `show-preview`, `filter-files`, `set-mode`, `sort-files`.
- File operations: `create-file`, `rename-file`, `delete-files`, `copy-files`, `move-files`.
- Backend/user hooks: `request-data`, `provide-data`, `download-file`, `open-file`.
- Hotkeys use the current `menuOptions` result, so removed menu items also remove their default hotkey behavior.
- Built-in hotkeys include `Ctrl/Cmd+C`, `Ctrl/Cmd+X`, `Ctrl/Cmd+V`, `Ctrl/Cmd+R`, `Ctrl/Cmd+D`, `Delete`, `Enter`, and arrow navigation with Ctrl/Cmd or Shift selection modifiers.

##### Menus

- `menuOptions(mode, item)` receives one of `"folder"`, `"file"`, `"body"`, `"add"`, or `"multiselect"` plus the current item when applicable.
- Return `false`, `null`, `undefined`, or an empty array to suppress a menu for that context.
- Default `"add"` menu: `add-file`, `add-folder`, and `upload` with `comp: "upload"`.
- Default `"body"` menu: `paste`.
- Default `"multiselect"` menu: `copy`, `move`, separator, `delete`.
- Default file menu: `download`, `copy`, `move`, `paste`, separator, `rename`, `delete`.
- Default folder menu omits `download`.
- Root folder context menu is filtered to `paste` only.
- Search mode filters out `paste`.
- Readonly mode hides add controls and edit menus; desktop readonly file menus include only `download`, while narrow mode prepends `preview`.
- Before menu display, item text is localized and `hotkey` is copied to `subtext`; tree-context menu options have `hotkey` cleared.
- Custom menu option `handler` receives a menu pack with `context`; use `context.id` for file operations.
- Filemanager registers the custom menu item type `"upload"` internally through `registerMenuItem("upload", UploadButton)`.

##### Icons, previews, and info

- `icons(file, size)` is used for image URLs in cards/table/info; `size` is `"big"` or `"small"`.
- `icons="simple"` is supported by source and demos and disables image icon URLs, falling back to icon font classes.
- Default icons use `https://cdn.svar.dev/icons/filemanager/vivid/${size}/${icon}.svg`.
- `previews(file, width, height)` is used for card thumbnails and info preview; return a URL string or a falsy value.
- `extraInfo(file)` runs for a single selected item in the info pane; it may return an object, a promise, or null.
- Extra info object entries are appended to the info grid as name/value rows.

##### Saving

- `RestDataProvider` from `@svar-ui/filemanager-data-provider` persists data changes to a REST backend.
- Wire it once with `api.setNext(provider)` in `init`; the provider then forwards every data action (`create-file`, `rename-file`, `move-files`, `copy-files`, `delete-files`) emitted on the event bus as the matching REST call. No per-action save handlers needed.
- Uploads are sent from `create-file` when `ev.file.file` exists; otherwise create sends JSON.
- Initial load and lazy folders use `provider.loadFiles(id)` / `loadInfo(id)`; dispatch results back through `provide-data` for `request-data`.
- Provider emits `"file-renamed"` when backend-generated ids differ from local ids - re-emit `rename-file` with `skipProvider: true` to sync the store.

```js
import { RestDataProvider } from "@svar-ui/filemanager-data-provider";

const provider = new RestDataProvider("/api/files");

function init(api) {
	api.setNext(provider); // forwards all file mutations to REST
}
```

#### Public Types

```ts
import type { ComponentType, ReactNode } from "react";
import type { IMenuOption } from "@svar-ui/react-menu";

import type {
	TMethodsConfig,
	IApi,
	IConfig,
	TContextMenuType,
	IExtraInfo,
	IParsedEntity,
} from "@svar-ui/filemanager-store";

export * from "@svar-ui/filemanager-store";

export interface IFileMenuOption extends IMenuOption {
	hotkey: string;
}

export type FilePreview = IParsedEntity & {
	type: "file" | "folder" | "search" | "multiple" | "none";
};

export declare const Filemanager: ComponentType<
	{
		readonly?: boolean;
		menuOptions?: (
			mode: TContextMenuType,
			item?: IParsedEntity
		) => IFileMenuOption[];
		extraInfo?: (
			file: IParsedEntity
		) => Promise<IExtraInfo> | IExtraInfo | null;
		icons?: (file: IParsedEntity, size: "big" | "small") => string;
		previews?: (
			file: FilePreview,
			width: number,
			height: number
		) => string | null;
		init?: (api: IApi) => void;
	} & IConfig &
		FilemanagerActions<TMethodsConfig>
>;

export declare const Willow: ComponentType<{
	fonts?: boolean;
	children?: ReactNode;
}>;

export declare const WillowDark: ComponentType<{
	fonts?: boolean;
	children?: ReactNode;
}>;

/* get component events from store actions*/
type RemoveHyphen<S extends string> = S extends `${infer Head}-${infer Tail}`
	? `${Head}${Capitalize<RemoveHyphen<Tail>>}`
	: S;

type EventName<K extends string> = `on${Capitalize<RemoveHyphen<K>>}`;

export type FilemanagerActions<TMethodsConfig extends Record<string, any>> = {
	[K in keyof TMethodsConfig as EventName<K & string>]?: (
		ev: TMethodsConfig[K]
	) => void;
} & {
	[key: `on${string}`]: (ev?: any) => void;
};
```

Important store shapes for wiring handlers, condensed from `store/dist/types`:

```ts
export type TID = string;
export type TContextMenuType =
	| "folder"
	| "file"
	| "body"
	| "add"
	| "multiselect";

export interface IEntity {
	id: TID;
	type?: "file" | "folder";
	size?: number;
	lazy?: boolean;
	date?: Date;
	[key: string]: any;
}

export interface IParsedEntity extends IEntity {
	parent: TID;
	name: string;
	ext: string;
	$level: number;
	open?: boolean;
	data?: IParsedEntity[];
}

export interface IFile {
	name: string;
	date?: Date;
	type?: "file" | "folder";
	size?: number;
	file?: File;
}

export type TMode = "cards" | "table" | "panels" | "search";
export type TActivePanel = 0 | 1;

export interface IPanel {
	path: TID;
	selected: TID[];
	_selected: IParsedEntity[];
	_files: IParsedEntity[];
	_crumbs: IParsedEntity[];
	_sorts: { [key: TID]: { key: string; order: "asc" | "desc" } };
	_lastSelected: TID;
	_selectNavigation: boolean;
}

export interface IConfig {
	data?: IEntity[];
	mode?: TMode;
	drive?: IDrive;
	preview?: boolean;
	panels?: Partial<IPanel>[];
	activePanel?: TActivePanel;
}

export interface IDrive {
	used?: number;
	total?: number;
}

export interface IExtraInfo {
	Size: string;
	Count: string;
	[key: string]: any;
}

type WithActionMeta<T> = T & {
	skipProvider?: boolean;
	[key: string]: any;
};

export type TMethodsConfig = {
	["select-file"]: WithActionMeta<{
		id?: TID;
		toggle?: boolean;
		range?: boolean;
		panel?: TActivePanel;
		type?: "navigation";
	}>;
	["set-path"]: WithActionMeta<{
		id: TID;
		selected?: TID[];
		panel?: TActivePanel;
	}>;
	["set-active-panel"]: WithActionMeta<{ panel: TActivePanel }>;
	["open-tree-folder"]: WithActionMeta<{ id: TID; mode: boolean }>;
	["show-preview"]: WithActionMeta<{ mode: boolean }>;
	["filter-files"]: WithActionMeta<{ text: string }>;
	["set-mode"]: WithActionMeta<{ mode: TMode }>;
	["rename-file"]: WithActionMeta<{ id: TID; name: string; newId?: string }>;
	["create-file"]: WithActionMeta<{
		file: IFile;
		parent: TID;
		newId?: string;
	}>;
	["delete-files"]: WithActionMeta<{ ids: TID[] }>;
	["move-files"]: WithActionMeta<{
		ids: TID[];
		target: TID;
		newIds?: TID[];
	}>;
	["copy-files"]: WithActionMeta<{
		ids: TID[];
		target: TID;
		newIds?: TID[];
	}>;
	["request-data"]: WithActionMeta<{ id: TID }>;
	["provide-data"]: WithActionMeta<{ id: TID; data: IEntity[] }>;
	["download-file"]: WithActionMeta<{ id: TID }>;
	["open-file"]: WithActionMeta<{ id: TID }>;
	["sort-files"]: WithActionMeta<{
		key: string;
		order: "asc" | "desc";
		panel?: TActivePanel;
		path?: string;
	}>;
};
```

#### Styling

Import the package CSS before using the component (`all.css` includes dependency styles, `style.css` is this component only)

- `Filemanager` does not accept `css`, `class`, `className`, or `style`; wrap it in a parent element and target global classes from that parent.
- The root component class is `.wx-filemanager`; it is `display: flex`, `flex-direction: column`, `height: 100%`, `max-width: 100vw`, `max-height: 100vh`, and `overflow: hidden`.
- The parent container must provide a usable height, usually `height: 100%` or a fixed height.
- Theme variables defined by package themes: `--wx-fm-background`, `--wx-fm-box-shadow`, `--wx-fm-select-background`, `--wx-fm-grid-border`, `--wx-fm-grid-header-color`, `--wx-fm-button-font-color`, `--wx-fm-toolbar-height`.
- Other consumed variables include core/theme variables such as `--wx-background`, `--wx-border`, `--wx-color-primary`, `--wx-color-primary-selected`, `--wx-color-font-alt`, `--wx-icon-color`, `--wx-button-background`, `--wx-table-select-background`, and `--wx-table-select-focus-background`.
- Toolbar: `.wx-toolbar`, `.wx-left`, `.wx-right`, `.wx-preview-icon`, `.wx-modes`; height comes from `--wx-fm-toolbar-height`, default theme value `56px`, with `gap: 8px` and `padding: 0 12px`.
- Layout: `.wx-content-wrapper` has `margin-top: 10px`; `.wx-sidebar` is `width: 238px` with `padding: 0 10px 10px`; `.wx-content-item` uses `width: 67%`; `.wx-info` uses `width: 38%`.
- Cards: `.wx-cards` uses flex wrapping and `padding: 30px 20px 10px`; card `.wx-item` is `210px x 200px` with `margin: 0 20px 20px 0`.
- Cards item hooks: `.wx-preview`, `.wx-file-preview`, `.wx-file-icon`, `.wx-card-preview`, `.wx-info`, `.wx-folder-name`, `.wx-file-name`, `.wx-more`, `.wx-back`, `.wx-selected`.
- Table hooks: `.wx-list`, `.wx-grid`, `.wx-row`, `.wx-header`, `.wx-cell`, `.wx-each-cell`; row/header height is configured as `42px`.
- Tree hooks: `.wx-tree`, `.wx-folder`, `.wx-toggle`, `.wx-toggle-placeholder`, `.wx-selected`; folder indentation is inline `padding-left` based on tree level.
- Breadcrumb hooks: `.wx-breadcrumbs`, `.wx-refresh-icon`, `.wx-item`.
- Search hooks: `.wx-search`, `.wx-search-input`, `.wx-icon`, `.wx-text`.
- Preview/info hooks: `.wx-info`, `.wx-info-narrow`, `.wx-wrapper`, `.wx-preview`, `.wx-info-panel`, `.wx-no-info-panel`, `.wx-img-wrapper`, `.wx-icon-wrapper`, `.wx-title`, `.wx-list`, `.wx-name`, `.wx-value`.
- Panels mode hooks: `.wx-panels`; child `.wx-item` uses `width: calc(50% - 10px)` and the first panel has `margin-right: 10px`.
- Upload hooks: `.wx-upload-area`, `.wx-upload-area.wx-active`; active drop background uses `--wx-color-primary-selected`.
- Menu popups come from `@svar-ui/react-menu` and use `.wx-menu`, `.wx-option`, `.wx-separator`, `.wx-subtext`, and related menu hooks; the popup is portaled outside the filemanager layout.
- Several classes are generic (`.wx-list`, `.wx-item`, `.wx-wrapper`, `.wx-name`); always scope selectors from a wrapper or a more specific filemanager section.

```jsx
import "./FmShell.css";

<div className="filemanager">
	<Filemanager data={data} drive={drive} />
</div>

/* FmShell.css
.filemanager {
	height: 100%;
	width: 100%;
	--wx-color-primary: rgb(11, 162, 208);
	--wx-fm-background: rgb(207, 209, 221);
	--wx-fm-select-background: rgb(235, 235, 255);
	--wx-table-select-background: rgba(33, 195, 255, 0.1);
	--wx-table-select-focus-background: rgba(33, 195, 255, 0.1);
}

.filemanager > .wx-filemanager .wx-cards .wx-back {
	color: rgb(74, 93, 237);
}
*/
```

#### Recipes

##### Basic Filemanager

```jsx
import { Filemanager, Willow } from "@svar-ui/react-filemanager";

function BasicFm() {
	const data = [
		{ id: "/Code", type: "folder", date: new Date(2023, 11, 2, 17, 25) },
		{ id: "/Code/Button.js", type: "file", size: 1177, date: new Date() },
	];

	const drive = {
		used: 15200000000,
		total: 50000000000,
	};

	return (
		<Willow>
			<Filemanager data={data} drive={drive} />
		</Willow>
	);
}
```

##### Initial Mode, Path, Selection, And Preview

```jsx
import { Filemanager } from "@svar-ui/react-filemanager";

function InitialFm() {
	const panels = [
		{ path: "/Code", selected: ["/Code/Button.js"] },
		{ path: "/", selected: ["/Music"] },
	];

	return (
		<Filemanager
			data={data}
			drive={drive}
			mode="panels"
			panels={panels}
			activePanel={0}
			preview
		/>
	);
}
```

##### Handle API And Component Events

```jsx
import { useRef, useState } from "react";
import { Filemanager } from "@svar-ui/react-filemanager";

function ApiFm() {
	const apiRef = useRef(null);
	const [saved, setSaved] = useState([]);

	function init(fm) {
		apiRef.current = fm;

		fm.on("download-file", ({ id }) => {
			window.open(`/download?id=${encodeURIComponent(id)}`, "_self");
		});

		fm.on("open-file", ({ id }) => {
			window.open(`/direct?id=${encodeURIComponent(id)}`, "_blank");
		});
	}

	function serializeCode() {
		setSaved(apiRef.current.serialize("/Code"));
		apiRef.current.exec("provide-data", { id: "/Code", data: [] });
	}

	function loadLazy({ id }) {
		fetch(`/files/${encodeURIComponent(id)}`)
			.then(res => res.json())
			.then(data => apiRef.current.exec("provide-data", { id, data }));
	}

	return (
		<>
			<button onClick={serializeCode}>Serialize /Code</button>

			<Filemanager
				ref={apiRef}
				init={init}
				data={data}
				drive={drive}
				onRequestData={loadLazy}
			/>
		</>
	);
}
```

##### Customize Context Menus

```jsx
import { useRef } from "react";
import { Filemanager, getMenuOptions } from "@svar-ui/react-filemanager";

function CustomMenusFm() {
	const apiRef = useRef(null);

	function init(fm) {
		apiRef.current = fm;
	}

	function menuOptions(mode, item) {
		if ((mode === "file" || mode === "folder") && item.id === "/Code") {
			return false;
		}

		if (mode === "file" || mode === "folder") {
			return [
				...getMenuOptions(mode),
				{ comp: "separator" },
				{
					id: "clone",
					text: "Clone",
					icon: "wxi-content-copy",
					hotkey: "Ctrl+Shift+V",
					handler: ({ context }) => {
						const { panels, activePanel } = apiRef.current.getState();
						apiRef.current.exec("copy-files", {
							ids: [context.id],
							target: panels[activePanel].path,
						});
					},
				},
			];
		}

		return getMenuOptions(mode);
	}

	return <Filemanager data={data} drive={drive} init={init} menuOptions={menuOptions} />;
}
```

##### Use Server Data And RestDataProvider

```jsx
import { useEffect, useRef, useState } from "react";
import { Filemanager } from "@svar-ui/react-filemanager";
import { RestDataProvider } from "@svar-ui/filemanager-data-provider";

function ServerFm() {
	const server = "https://example.com/api";
	const provider = new RestDataProvider(server);

	const apiRef = useRef(null);
	const [data, setData] = useState([]);
	const [drive, setDrive] = useState({});

	function init(fm) {
		apiRef.current = fm;
		fm.setNext(provider);

		fm.on("download-file", ({ id }) => {
			window.open(`${server}/direct?id=${encodeURIComponent(id)}&download=true`, "_self");
		});

		fm.on("open-file", ({ id }) => {
			window.open(`${server}/direct?id=${encodeURIComponent(id)}`, "_blank");
		});
	}

	function loadData({ id }) {
		provider.loadFiles(id).then(files => {
			apiRef.current.exec("provide-data", { id, data: files });
		});
	}

	useEffect(() => {
		provider.on("file-renamed", ({ id, newId }) => {
			const name = newId.slice(newId.lastIndexOf("/") + 1);
			apiRef.current.exec("rename-file", { id, name, skipProvider: true });
		});

		Promise.all([provider.loadFiles(), provider.loadInfo()]).then(([files, info]) => {
			setData(files);
			setDrive(info);
		});
	}, []);

	return <Filemanager init={init} data={data} drive={drive} onRequestData={loadData} />;
}
```

##### Custom Icons, Previews, And Extra Info

```jsx
import { Filemanager } from "@svar-ui/react-filemanager";
import { formatSize } from "@svar-ui/filemanager-store";

function CustomVisualsFm() {
	const server = "https://example.com/api";

	function icons(file, size) {
		const name = file.type === "file" ? file.ext : file.type;
		return `${server}/icons/${size}/${name}.svg`;
	}

	function previews(file, width, height) {
		if (file.ext === "png" || file.ext === "jpg" || file.ext === "jpeg") {
			return `${server}/preview?width=${width}&height=${height}&id=${encodeURIComponent(file.id)}`;
		}
		return null;
	}

	function extraInfo(file) {
		if (file.type === "folder") {
			return { Size: formatSize(file.size || 0), Count: "folder" };
		}
		return null;
	}

	return <Filemanager data={data} drive={drive} icons={icons} previews={previews} extraInfo={extraInfo} preview />;
}
```

##### Backend Search Intercept

```jsx
import { useRef } from "react";
import { Filemanager } from "@svar-ui/react-filemanager";

function SearchInterceptFm() {
	const apiRef = useRef(null);

	function init(fm) {
		apiRef.current = fm;

		fm.intercept("filter-files", ({ text }) => {
			const { panels, activePanel } = fm.getState();
			const id = panels[activePanel].path;

			fetch(`/files/${encodeURIComponent(id)}?text=${text || ""}`)
				.then(res => res.json())
				.then(data => {
					fm.exec("set-mode", { mode: text ? "search" : "cards" });
					fm.exec("provide-data", { id, data });
				});

			return false;
		});
	}

	return <Filemanager init={init} data={data} drive={drive} />;
}
```

##### Localize Filemanager

```jsx
import { Locale } from "@svar-ui/react-core";
import { cn } from "@svar-ui/filemanager-locales";
import { cn as cnCore } from "@svar-ui/core-locales";
import { Filemanager } from "@svar-ui/react-filemanager";

function LocalizedFm() {
	return (
		<Locale words={{ ...cn, ...cnCore }}>
			<Filemanager data={data} drive={drive} />
		</Locale>
	);
}
```

#### Implementation Notes

- `Filemanager` stores all unknown props in `restProps` for generated action callbacks; unknown props are not spread onto DOM.
- Source supports `icons="simple"`, but the declaration types `icons` only as a function.
- Source default `icons` can return `false` for folders, but the declaration says `string`.
- Source accepts falsy `previews` return values, but the declaration says `string | null`.
- `menuOptions` can suppress menus with falsy returns, but the declaration says it returns `IFileMenuOption[]`.
- Store source `IMenuOption.id` is `string | number`, while generated `store/dist/types/types.d.ts` has `id?: string`.
- `RestDataProvider.loadFiles()` and `loadInfo()` are called without arguments in demos, but generated provider declarations require `id: TID`.
- `DataStore` mutates the input file objects during parse by adding `parent`, `name`, `ext`, default `type`, and tree state fields.
- Context/action menus and tests rely on ids encoded by `setID`; use raw file ids in app code and let the library set data attributes.
- `registerMenuItem("upload", UploadButton)` runs inside `Sidebar`; a custom `"upload"` add item only works through the built-in sidebar add menu.
- `extraInfo` errors are caught and logged, then ignored.
- In readonly mode, hotkeys use readonly menu options, so edit hotkeys do not open modals.