# svar-vue - full bundle

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

## 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 Vue ships as a family of `@svar-ui/vue-*` 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/vue-core` | buttons, inputs, selectors, calendars, dropdowns, popups, modals, themes, locale (40+ widgets) |
| `menu/index.md` | `@svar-ui/vue-menu` | `Menu`, `MenuBar`, `DropDownMenu`, `ContextMenu`, `ActionMenu` |
| `toolbar/index.md` | `@svar-ui/vue-toolbar` | `Toolbar` |
| `layout/index.md` | `@svar-ui/vue-layout` | `Layout`, `Cell`, `Panel` |
| `grid/index.md` | `@svar-ui/vue-grid` | `Grid`, `HeaderMenu`, `Tooltip`, `ContextMenu`, `Toolbar` |
| `editor/index.md` | `@svar-ui/vue-editor` | `Editor` |
| `filter/index.md` | `@svar-ui/vue-filter` | `FilterBuilder`, `FilterEditor`, `FilterBar`, `FilterQuery` |
| `gantt/index.md` | `@svar-ui/vue-gantt` | `Gantt`, `Toolbar`, `ContextMenu`, `Editor`, `Tooltip`, `HeaderMenu` |
| `tasklist/index.md` | `@svar-ui/vue-tasklist` | `Tasklist` |
| `comments/index.md` | `@svar-ui/vue-comments` | `Comments` |
| `filemanager/index.md` | `@svar-ui/vue-filemanager` | `Filemanager` |

#### Common Techniques

These apply to every `@svar-ui/vue-*` 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 Vue components - Locale wrapper, bundled language packs, extending words and formats

### Localizing SVAR Vue Components

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

#### Locale Wrapper

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

```vue
<script setup>
import { Calendar, Locale } from "@svar-ui/vue-core";
import { de } from "@svar-ui/core-locales";
</script>

<template>
  <Locale :words="de">
    <Calendar :value="new Date(2025, 4, 1)" />
  </Locale>
</template>
```

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 the injected 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:

```vue
<script setup>
import { Gantt } from "@svar-ui/vue-gantt";
import { Locale } from "@svar-ui/vue-core";
import { cn } from "@svar-ui/gantt-locales";
import { cn as cnCore } from "@svar-ui/core-locales";
</script>

<template>
  <Locale :words="{ ...cn, ...cnCore }">
    <Gantt v-bind="settings" />
  </Locale>
</template>
```

#### 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:

```vue
<script setup>
import { Calendar, Locale } from "@svar-ui/vue-core";
import { cn } from "@svar-ui/core-locales";

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

<template>
  <Locale :words="words">
    <Calendar :value="new Date(2025, 4, 1)" />
  </Locale>
</template>
```

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/vue-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 Vue Components

All `@svar-ui/vue-*` widgets share the same theming pipeline. The mechanics live in `@svar-ui/vue-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/vue-gantt/style.css";
```

#### Theme Wrapper

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

```vue
<script setup>
import { Willow } from "@svar-ui/vue-core";
</script>

<template>
  <Willow>
    <App />
  </Willow>
</template>
```

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

- provides the Vue inject key `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/vue-core` - base
- `@svar-ui/vue-gantt`
- `@svar-ui/vue-grid`
- `@svar-ui/vue-editor`
- `@svar-ui/vue-filter`
- `@svar-ui/vue-filemanager`
- `@svar-ui/vue-comments`
- `@svar-ui/vue-kanban`

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

```vue
<script setup>
import { Willow } from "@svar-ui/vue-core";
defineProps({ fonts: { type: Boolean, default: true } });
</script>

<template>
  <Willow :fonts="fonts">
    <slot v-if="$slots.default" />
  </Willow>
</template>

<style scoped>
:global(.wx-willow-theme) {
    --wx-gantt-border-color: #e6e6e6;
    --wx-gantt-task-color: #3983eb;
    /* ...widget-specific overrides... */
}
</style>
```

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:

```vue
<script setup>
import { Willow, Gantt } from "@svar-ui/vue-gantt";
</script>

<template>
  <Willow />
  <Gantt v-bind="settings" />
</template>
```

#### 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.

```vue
<template>
  <Willow>
    <div class="brand">
      <App />
    </div>
  </Willow>
</template>

<style scoped>
.brand {
    --wx-color-primary: #0f766e;
    --wx-input-width: 280px;
    --wx-button-border-radius: 4px;
    --wx-calendar-cell-size: 30px;
}
</style>
```

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:

```vue
<template>
  <Toolbar css="my-toolbar" :items="items" />
</template>

<style scoped>
.my-toolbar {
    padding: 8px 12px;
}
</style>
```

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 {}`). Vue scopes its component styles by appending a hash attribute which has 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 Vue Core / @svar-ui/vue-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/vue-core";

import "@svar-ui/vue-core/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 bindable `value` 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 Vue Core Avatar

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

#### Package

```js
import { Avatar } from "@svar-ui/vue-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 { Component } from "vue";

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

export declare const Avatar: Component<{
	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`

```vue
<template>
  <div class="people">
    <Avatar :value="users" :size="36" :limit="5" />
  </div>
</template>

<style scoped>
.people {
	width: 180px;
}

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

#### Recipes

##### User Stack With Responsive Overflow

```vue
<script setup>
import { Avatar } from "@svar-ui/vue-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" },
];
</script>

<template>
  <div style="width: 160px">
    <Avatar :value="users" :size="32" :limit="4" />
  </div>
</template>
```

##### Single Initial Avatar

```vue
<script setup>
import { Avatar } from "@svar-ui/vue-core";
</script>

<template>
  <Avatar :value="{ id: 1, name: 'Jane Smith', color: '#2f77e3' }" :size="40" />
</template>
```


## File: core/button.md

> Source: `core/button.md`

### SVAR Vue Core Button

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

#### Package

```js
import { Button } from "@svar-ui/vue-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` slot when provided; otherwise renders `text`.
- `onclick` receives the native `MouseEvent`.

#### Public Types

```ts
import type { Component } from "vue";

export declare const Button: Component<{
	type?:
		| "primary"
		| "secondary"
		| "danger"
		| "link"
		| "primary block"
		| "secondary block"
		| "danger block"
		| "link block";
	css?: string;
	icon?: string;
	disabled?: boolean;
	title?: string;
	text?: string;
	children?: () => any;
	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`.

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

<style scoped>
:.wx-button.save-button {
	min-width: 120px;
}
</style>
```

#### Recipes

##### Variants And Click Handler

```vue
<script setup>
import { Button } from "@svar-ui/vue-core";

function save(ev) {
	console.log(ev.currentTarget);
}
</script>

<template>
  <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>
</template>
```

##### Icon-Only Button

```vue
<script setup>
import { Button } from "@svar-ui/vue-core";
</script>

<template>
  <Button
    icon="wxi-search"
    title="Search"
    :onclick="() => console.log('search')"
  />
</template>
```

#### 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 Vue Core Calendar

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

#### Package

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

#### Supported Functionality

- Full single-date calendar with header navigation and optional action buttons.
- `value` is bindable and is a `Date` or `null`.
- `current` is bindable 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 { Component } from "vue";

export declare const Calendar: Component<{
	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`

```vue
<template>
  <div class="compact-calendar">
    <Calendar :value="new Date(2025, 4, 1)" />
  </div>
</template>

<style scoped>
.compact-calendar {
	--wx-calendar-cell-size: 28px;
	--wx-calendar-padding: 8px;
}

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

#### Recipes

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

```vue
<script setup>
import { ref } from "vue";
import { Calendar } from "@svar-ui/vue-core";

const value = ref(new Date(2025, 4, 1));
const current = ref(new Date(2025, 4, 1));

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

<template>
  <Calendar
    v-model:value="value"
    v-model:current="current"
    :markers="markers"
    :buttons="['today']"
    :onchange="ev => console.log(ev.value)"
  />
</template>
```

##### Hide Action Buttons

```vue
<script setup>
import { Calendar } from "@svar-ui/vue-core";
</script>

<template>
  <Calendar :buttons="false" :onchange="ev => console.log(ev.value)" />
</template>
```

#### Implementation Notes

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


## File: core/checkbox.md

> Source: `core/checkbox.md`

### SVAR Vue Core Checkbox

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

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

#### Package

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

#### Supported Functionality

- `Checkbox.value` is a bindable 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 bindable 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 { Component } from "vue";

export declare const Checkbox: Component<{
	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: Component<{
	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`

```vue
<template>
  <div class="todo-checks">
    <CheckboxGroup :options="options" v-model:value="value" />
  </div>
</template>

<style scoped>
.todo-checks .wx-checkboxgroup .wx-item {
	margin-top: 8px;
}
</style>
```

#### Recipes

##### Single Checkbox

```vue
<script setup>
import { ref } from "vue";
import { Checkbox } from "@svar-ui/vue-core";

const done = ref(false);
</script>

<template>
  <Checkbox
    label="Done"
    inputValue="done"
    v-model:value="done"
    :onchange="ev => console.log(ev.value, ev.inputValue)"
  />
</template>
```

##### Checkbox Group

```vue
<script setup>
import { ref } from "vue";
import { CheckboxGroup } from "@svar-ui/vue-core";

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

const selected = ref(["new"]);
</script>

<template>
  <CheckboxGroup :options="options" v-model:value="selected" type="inline" />
</template>
```

#### Implementation Notes

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


## File: core/colorboard.md

> Source: `core/colorboard.md`

### SVAR Vue Core ColorBoard

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

#### Package

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

#### Supported Functionality

- HSV color board with hue line, saturation/value block, text input, preview, and optional select button.
- `value` is bindable 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 { Component } from "vue";

export declare const ColorBoard: Component<{
	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`

```vue
<template>
  <div class="picker-board">
    <ColorBoard v-model:value="value" />
  </div>
</template>

<style scoped>
.picker-board .wx-color-block {
	height: 180px;
}
</style>
```

#### Recipes

##### Inline Color Board

```vue
<script setup>
import { ref } from "vue";
import { ColorBoard } from "@svar-ui/vue-core";

const value = ref("#48C8E2");
</script>

<template>
  <div style="width: 300px">
    <ColorBoard
      v-model:value="value"
      :onchange="ev => {
        if (!ev.input) console.log(ev.value);
      }"
    />
  </div>
</template>
```


## File: core/colorpicker.md

> Source: `core/colorpicker.md`

### SVAR Vue Core ColorPicker

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

#### Package

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

#### Supported Functionality

- Input-like color picker that opens `ColorBoard` in a `Dropdown`.
- `value` is a bindable 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 { Component } from "vue";

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: Component<{
	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`.


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

<style scoped>
.wx-popup.color-popup {
	width: 300px;
}
</style>
```

#### Recipes

##### Color Picker In A Field

```vue
<script setup>
import { ref } from "vue";
import { ColorPicker, Field } from "@svar-ui/vue-core";

const color = ref("#65D3B3");
</script>

<template>
  <Field label="Color" position="left">
    <ColorPicker
      v-model:value="color"
      placeholder="Select a color"
      clear
      :onchange="ev => console.log(ev.value)"
    />
  </Field>
</template>
```

#### Implementation Notes

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


## File: core/colorselect.md

> Source: `core/colorselect.md`

### SVAR Vue Core ColorSelect

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

#### Package

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

#### Supported Functionality

- Input-like color palette selector.
- `value` is a bindable 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 { Component } from "vue";

export declare const ColorSelect: Component<{
	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`


```vue
<template>
  <ColorSelect :colors="colors" v-model:value="value" clear />
</template>

<style scoped>
.wx-colorselect .wx-color {
	border-radius: 50%;
}
</style>
```

#### Recipes

##### Custom Palette

```vue
<script setup>
import { ref } from "vue";
import { ColorSelect, Field } from "@svar-ui/vue-core";

const color = ref("");
</script>

<template>
  <Field label="Color" position="left">
    <ColorSelect
      :colors="['#65D3B3', '#FFC975', '#58C3FE']"
      v-model:value="color"
      placeholder="Select a color"
      clear
    />
  </Field>
</template>
```


## File: core/combo.md

> Source: `core/combo.md`

### SVAR Vue Core Combo

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

#### Package

```js
import { Combo } from "@svar-ui/vue-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 bindable `value` and emits `{ value }`.
- `children` slot receives `{ option }` for custom list row content.
- `dropdown` is forwarded to `SuggestDropdown`/`Dropdown`.

#### Public Types

```ts
import type { Component } from "vue";

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: Component<{
	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?: () => any;
	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`.


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

<style scoped>
.wx-popup.users-popup .wx-list {
	max-height: 360px;
}
</style>
```

#### Recipes

##### Custom Option Template And Virtualized List

```vue
<script setup>
import { ref } from "vue";
import { Combo } from "@svar-ui/vue-core";

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

const value = ref(9000);
</script>

<template>
  <Combo
    :options="users"
    v-model:value="value"
    :dropdown="{ virtualized: true, width: '320px' }"
  >
    <template #children="{ option }">
      <div class="user-option">
        <strong>{{ option.label }}</strong>
        <span>{{ option.email }}</span>
      </div>
    </template>
  </Combo>
</template>
```

##### Hidden Selected Option

```vue
<script setup>
import { Combo } from "@svar-ui/vue-core";

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

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

<template>
  <Combo :textOptions="allUsers" :options="visibleUsers" :value="87" clear />
</template>
```

#### Implementation Notes

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


## File: core/counter.md

> Source: `core/counter.md`

### SVAR Vue Core Counter

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

#### Package

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

#### Supported Functionality

- Numeric input with decrement and increment buttons.
- Bindable `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 { Component } from "vue";

export declare const Counter: Component<{
	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`

```vue
<template>
  <Counter v-model:value="value" :min="0" :max="30" />
</template>

<style scoped>
.wx-counter .wx-input {
	width: 64px;
}
</style>
```

#### Recipes

##### Counter With Final Change Handling

```vue
<script setup>
import { ref } from "vue";
import { Counter, Field } from "@svar-ui/vue-core";

const count = ref(5);
</script>

<template>
  <Field label="Quantity">
    <Counter
      v-model:value="count"
      :min="0"
      :max="30"
      :step="3"
      :onchange="ev => {
        if (!ev.input) console.log(ev.value);
      }"
    />
  </Field>
</template>
```


## File: core/datepicker.md

> Source: `core/datepicker.md`

### SVAR Vue Core DatePicker

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

#### Package

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

#### Supported Functionality

- Input-like single-date picker backed by `Text`, `Dropdown`, and `Calendar`.
- `value` is bindable 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 bindable value is updated.

#### Public Types

```ts
import type { Component } from "vue";

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: Component<{
	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`.


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

<style scoped>
.wx-text.date-input {
	--wx-input-width: 220px;
}

.wx-popup.date-popup {
	padding: 4px;
}
</style>
```

#### Recipes

##### Bound Date In A Field

```vue
<script setup>
import { ref } from "vue";
import { DatePicker, Field } from "@svar-ui/vue-core";

const value = ref(new Date(2025, 4, 1));
</script>

<template>
  <Field label="Date" position="left">
    <DatePicker v-model:value="value" clear :onchange="ev => console.log(ev.value)" />
  </Field>
</template>
```

##### Editable Date With Custom Parser

```vue
<script setup>
import { ref } from "vue";
import { DatePicker } from "@svar-ui/vue-core";

const value = ref(new Date(2025, 4, 1));

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

<template>
  <DatePicker
    v-model:value="value"
    :editable="parseDate"
    format="%m%d%Y"
    clear
    :dropdown="{ width: '280px', align: 'start' }"
  />
</template>
```

#### 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 Vue Core DateRangePicker

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

#### Package

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

#### Supported Functionality

- Input-like date range picker backed by `Text`, `Dropdown`, and `RangeCalendar`.
- `value` is bindable 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 { Component } from "vue";

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: Component<{
	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`.

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

<style scoped>
.wx-text.range-input {
	--wx-input-width: 280px;
}
</style>
```

#### Recipes

##### Two-Month Range Picker

```vue
<script setup>
import { ref } from "vue";
import { DateRangePicker, Field } from "@svar-ui/vue-core";

const value = ref({
	start: new Date(2025, 4, 1),
	end: new Date(2025, 4, 7),
});
</script>

<template>
  <Field label="Range" position="left">
    <DateRangePicker
      v-model:value="value"
      :months="2"
      :buttons="['done', 'clear', 'today']"
      clear
      :onchange="ev => console.log(ev.value)"
    />
  </Field>
</template>
```

##### Editable Range

```vue
<script setup>
import { ref } from "vue";
import { DateRangePicker } from "@svar-ui/vue-core";

const value = ref();
</script>

<template>
  <DateRangePicker
    v-model:value="value"
    editable
    placeholder="Start - end"
    :dropdown="{ width: 'unset', align: 'start' }"
  />
</template>
```

#### 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 Vue Core Dropdown

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

#### Package

```js
import { Dropdown } from "@svar-ui/vue-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 { Component } from "vue";

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: Component<
	DropdownOptions & {
		children?: () => any;
		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`


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

<style scoped>
.wx-popup.calendar-popup {
	padding: 8px;
}
</style>
```

#### Recipes

##### Anchored Dropdown

```vue
<script setup>
import { ref } from "vue";
import { Button, Calendar, Dropdown } from "@svar-ui/vue-core";

const open = ref(false);
</script>

<template>
  <Button :onclick="() => (open = true)">Open</Button>
  <Dropdown
    v-if="open"
    width="300px"
    position="bottom"
    align="start"
    css="calendar-popup"
    :oncancel="() => (open = false)"
  >
    <Calendar />
  </Dropdown>
</template>
```

##### Inline Dropdown

```vue
<script setup>
import { Dropdown } from "@svar-ui/vue-core";
</script>

<template>
  <div style="position: relative">
    <Dropdown inline width="200px" position="bottom" align="end">
      <div style="padding: 8px">Inline content</div>
    </Dropdown>
  </div>
</template>
```

#### 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 Vue Core Field

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

#### Package

```js
import { Field } from "@svar-ui/vue-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 Vue inject key `wx-input-id`; child controls that call `getInputId` share the generated id with the label.

#### Public Types

```ts
import type { Component } from "vue";

export declare const Field: Component<{
	label?: string;
	position?: "left";
	width?: string;
	error?: boolean;
	type?: "checkbox" | "slider" | "switch";
	required?: boolean;
	children?: () => any;
}>;
```

#### 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`


```vue
<template>
  <Field label="Owner" position="left" width="480px">
    <slot />
  </Field>
</template>

<style scoped>
.wx-field.wx-left > .wx-label {
	width: 140px;
}
</style>
```

#### Recipes

##### Labeled Control

```vue
<script setup>
import { ref } from "vue";
import { Field, Text } from "@svar-ui/vue-core";

const name = ref("");
</script>

<template>
  <Field label="Name" required>
    <Text v-model:value="name" />
  </Field>
</template>
```

##### Nested Fields

```vue
<script setup>
import { Field, Text } from "@svar-ui/vue-core";
</script>

<template>
  <Field label="Name">
    <Field label="First" position="left">
      <Text />
    </Field>
    <Field label="Last" position="left">
      <Text />
    </Field>
  </Field>
</template>
```


## File: core/fullscreen.md

> Source: `core/fullscreen.md`

### SVAR Vue Core Fullscreen

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

#### Package

```js
import { Fullscreen } from "@svar-ui/vue-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` slot 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 { Component, Slot } from "vue";

export declare const Fullscreen: Component<{
	toggleButton?: Slot<[(ev: MouseEvent) => void, boolean]>;
	children?: () => any;
	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.

```vue
<template>
  <Fullscreen>
    <div class="report">Report content</div>
  </Fullscreen>
</template>

<style scoped>
.wx-fullscreen .wx-fullscreen-button {
	right: 12px;
	bottom: 12px;
}
</style>
```

#### Recipes

##### Custom Toggle Button

```vue
<script setup>
import { Button, Fullscreen } from "@svar-ui/vue-core";
</script>

<template>
  <Fullscreen hotkey="ctrl+shift+f">
    <div class="panel">Report content</div>

    <template #toggleButton="{ toggle, inFullscreen }">
      <Button :onclick="toggle">
        {{ inFullscreen ? "Exit fullscreen" : "Enter fullscreen" }}
      </Button>
    </template>
  </Fullscreen>
</template>
```

#### Implementation Notes

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


## File: core/globals.md

> Source: `core/globals.md`

### SVAR Vue Core Globals

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

#### Package

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

#### Supported Functionality

- Renders children and installs Vue inject key `wx-helpers`.
- `wx-helpers.showNotice(msg)` appends a notice.
- `wx-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 { Component } from "vue";

export declare const Globals: Component<{
	children?: () => any;
}>;
```

#### 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`

```vue
<template>
  <Globals>
    <App />
  </Globals>
</template>

<style scoped>
.wx-notices {
	top: 12px;
	right: 12px;
}
</style>
```

#### Recipes

##### Install Globals At App Root

```vue
<script setup>
import { Globals } from "@svar-ui/vue-core";
import Actions from "./Actions.vue";
</script>

<template>
  <Globals>
    <Actions />
  </Globals>
</template>
```

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

```vue
<script setup>
import { Button } from "@svar-ui/vue-core";
import { inject } from "vue";

const { showNotice, showModal } = inject("wx-helpers");

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

<template>
  <Button type="danger" :onclick="confirmDelete">Delete</Button>
  <Button :onclick="() => showNotice({ type: 'info', text: 'Saved' })">
    Notice
  </Button>
</template>
```

#### Implementation Notes

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


## File: core/icon.md

> Source: `core/icon.md`

### SVAR Vue Core Icon

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

#### Package

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

#### Supported Functionality

- Renders `<i class="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` slot is provided, it is rendered inside the `<i>` and `role="img"` is added.

#### Public Types

```ts
import type { Component } from "vue";

export declare const Icon: Component<{
	css?: string;
	title?: string;
	children?: () => any;
	onclick?: (ev: MouseEvent) => void;
}>;
```

#### Styling

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

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

<style scoped>
.wx-icon.app-icon {
	color: var(--wx-color-primary);
}
</style>
```

#### Recipes

##### Clickable Icon

```vue
<script setup>
import { Icon } from "@svar-ui/vue-core";
</script>

<template>
  <Icon
    css="wxi-information-outline"
    title="Info"
    :onclick="() => console.log('info')"
  />
</template>
```

#### Implementation Notes

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


## File: core/locale.md

> Source: `core/locale.md`

### SVAR Vue Core Locale

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

#### Package

```js
import { Locale, locale, en } from "@svar-ui/vue-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 Vue inject key `wx-i18n`.
- 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 { Component } from "vue";

export declare const Locale: Component<{
	words?: any;
	optional?: boolean;
	children?: () => any;
}>;

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

```vue
<script setup>
import { Calendar, Locale } from "@svar-ui/vue-core";
import { de } from "@svar-ui/core-locales";
</script>

<template>
  <Locale :words="de">
    <Calendar :value="new Date(2025, 4, 1)" />
  </Locale>
</template>
```

##### Override Date Formats

```vue
<script setup>
import { Calendar, Locale } from "@svar-ui/vue-core";
import { cn } from "@svar-ui/core-locales";

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

<template>
  <Locale :words="words">
    <Calendar :value="new Date(2025, 4, 1)" />
  </Locale>
</template>
```

##### Use The Locale Helper Directly

```vue
<script setup>
import { en, locale } from "@svar-ui/vue-core";

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

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

#### 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 Vue Core Modal

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

#### Package

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

#### Supported Functionality

- Fixed-position backdrop and centered window.
- `title` renders the default header unless a `header` slot is supplied.
- `children` renders the modal body.
- `footer` slot 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 { Component, Slot } from "vue";

export declare const Modal: Component<{
	title?: string;
	buttons?: boolean | string[];
	header?: Slot<[]>;
	footer?: Slot<[]>;
	children?: () => any;
	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`

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

<style scoped>
.wx-modal .wx-window {
	--wx-modal-width: 360px;
}
</style>
```

#### Recipes

##### Portal Modal With Default Buttons

```vue
<script setup>
import { ref } from "vue";
import { Button, Modal, Portal } from "@svar-ui/vue-core";

const open = ref(false);
</script>

<template>
  <Button type="primary" :onclick="() => (open = true)">Show</Button>

  <Portal v-if="open">
    <Modal
      title="Confirm"
      :onconfirm="() => (open = false)"
      :oncancel="() => (open = false)"
    >
      Continue?
    </Modal>
  </Portal>
</template>
```

##### Custom Header And Footer

```vue
<script setup>
import { Button, Modal } from "@svar-ui/vue-core";
</script>

<template>
  <Modal :buttons="false">
    <template #header>
      <h2>Custom Title</h2>
    </template>

    <div>Body</div>

    <template #footer>
      <Button type="primary">Apply</Button>
    </template>
  </Modal>
</template>
```

#### 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 Vue Core ModalArea

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

#### Package

```js
import { ModalArea } from "@svar-ui/vue-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 { Component } from "vue";

export declare const ModalArea: Component<{
	children?: () => any;
}>;
```

#### 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.

```vue
<template>
  <div class="local-area">
    <ModalArea>
      <div class="inner">Local modal content</div>
    </ModalArea>
  </div>
</template>

<style scoped>
.local-area {
	position: relative;
	min-height: 300px;
}
</style>
```

#### Recipes

##### Local Modal Overlay

```vue
<script setup>
import { ref } from "vue";
import { Button, ModalArea } from "@svar-ui/vue-core";

const open = ref(false);
</script>

<template>
  <div style="position: relative; min-height: 300px">
    <Button :onclick="() => (open = true)">Open local modal</Button>

    <ModalArea v-if="open">
      <Button :onclick="() => (open = false)">Close</Button>
    </ModalArea>
  </div>
</template>
```

#### 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 Vue Core Month

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

#### Package

```js
import { Month } from "@svar-ui/vue-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 { Component } from "vue";

export declare const Month: Component<{
	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`.

```vue
<template>
  <Month :current="new Date(2025, 4, 1)" part="normal" :markers="markers" />
</template>

<style scoped>
.wx-day.payday {
	font-weight: 700;
}
</style>
```

#### Recipes

##### Standalone Single-Month Picker

```vue
<script setup>
import { ref } from "vue";
import { Month } from "@svar-ui/vue-core";

const value = ref(new Date(2025, 4, 15));
const current = ref(new Date(2025, 4, 1));
</script>

<template>
  <Month
    v-model:value="value"
    v-model:current="current"
    part="normal"
    :onchange="date => (value = date)"
  />
</template>
```

##### Range Markup Preview

```vue
<script setup>
import { Month } from "@svar-ui/vue-core";

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

<template>
  <Month
    :value="value"
    :current="value.start"
    part="both"
    :onchange="date => console.log(date)"
  />
</template>
```

#### 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 Vue Core MultiCombo

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

#### Package

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

#### Supported Functionality

- Multi-select searchable input backed by `SuggestDropdown`.
- `value` is a bindable array of selected ids.
- `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` slot receives `{ option }` for both tags and list rows.
- `onchange` emits `{ value }`.

#### Public Types

```ts
import type { Component } from "vue";

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: Component<{
	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?: () => any;
	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`

```vue
<template>
  <MultiCombo :options="options" v-model:value="value" :dropdown="{ css: 'roles-popup' }" />
</template>

<style scoped>
.wx-multicombo .wx-tag {
	max-width: 180px;
}
</style>
```

#### Recipes

##### Multi Select With Checkboxes

```vue
<script setup>
import { ref } from "vue";
import { MultiCombo } from "@svar-ui/vue-core";

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

const roles = ref(["viewer"]);
</script>

<template>
  <MultiCombo
    :options="options"
    v-model:value="roles"
    checkboxes
    placeholder="Select roles"
  />
</template>
```

##### Custom Tag And Row Content

```vue
<script setup>
import { MultiCombo } from "@svar-ui/vue-core";

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

<template>
  <MultiCombo :options="users" :value="[104]">
    <template #children="{ option }">
      <strong>{{ option.label }}</strong>
    </template>
  </MultiCombo>
</template>
```

#### 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 Vue Core Pager

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

#### Package

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

#### Supported Functionality

- Pagination control with rows-per-page input, page navigation icons, current page input, and total page count.
- `value` is the bindable current page; default is `1`.
- `pageSize` is bindable; 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 { Component } from "vue";

export declare const Pager: Component<{
	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.

```vue
<template>
  <div class="grid-footer">
    <Pager :total="100" />
  </div>
</template>

<style scoped>
.grid-footer .wx-pager {
	justify-content: flex-end;
}
</style>
```

#### Recipes

##### Bound Page And Page Size

```vue
<script setup>
import { ref } from "vue";
import { Pager } from "@svar-ui/vue-core";

const page = ref(2);
const pageSize = ref(10);
</script>

<template>
  <Pager
    :total="100"
    v-model:value="page"
    v-model:pageSize="pageSize"
    :onchange="ev => console.log(ev.value, ev.from, ev.to)"
  />
</template>
```

#### 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 Vue Core Popup

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

#### Package

```js
import { Popup } from "@svar-ui/vue-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 { Component } from "vue";

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

#### Styling

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

```vue
<template>
  <Popup :parent="buttonNode" css="help-popup">
    <div class="body">Help</div>
  </Popup>
</template>

<style scoped>
.wx-popup.help-popup {
	padding: 12px;
}
</style>
```

#### Recipes

##### Popup Anchored To A Button

```vue
<script setup>
import { ref } from "vue";
import { Button, Popup } from "@svar-ui/vue-core";

const parent = ref(null);
</script>

<template>
  <div ref="parent">
    <Button>Anchor</Button>
  </div>

  <Popup v-if="parent" :parent="parent" at="bottom" :oncancel="() => (parent = null)">
    <div style="padding: 12px">Popup content</div>
  </Popup>
</template>
```

#### 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 Vue Core Portal

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

#### Package

```js
import { Portal, popupContainer } from "@svar-ui/vue-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 `wx-theme` context when not supplied.
- Children receive an internal `{ mount }` callback argument in source.
- `popupContainer(node)` marks a local portal root with a generated `data-wx-portal-root` attribute.

#### Public Types

```ts
import type { Component } from "vue";

export declare const Portal: Component<{
	theme?: "willow" | "willow-dark";
	target?: HTMLElement;
	children?: () => any;
}>;

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.

```vue
<script setup>
import { asDirective } from "@svar-ui/lib-vue";
import { popupContainer } from "@svar-ui/vue-core";
const vPopupContainer = asDirective(popupContainer);
</script>

<template>
  <div v-popup-container class="local-root">
    <slot />
  </div>
</template>
```

#### Recipes

##### Render A Modal Through Portal

```vue
<script setup>
import { ref } from "vue";
import { Button, Modal, Portal } from "@svar-ui/vue-core";

const open = ref(false);
</script>

<template>
  <Button :onclick="() => (open = true)">Open</Button>

  <Portal v-if="open">
    <Modal title="Portal Modal" :oncancel="() => (open = false)">
      Content
    </Modal>
  </Portal>
</template>
```

##### Local Portal Root

```vue
<script setup>
import { asDirective } from "@svar-ui/lib-vue";
import { DatePicker, popupContainer } from "@svar-ui/vue-core";
const vPopupContainer = asDirective(popupContainer);
</script>

<template>
  <div v-popup-container class="local-root">
    <DatePicker />
  </div>
</template>
```


## File: core/radio.md

> Source: `core/radio.md`

### SVAR Vue Core Radio

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

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

#### Package

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

#### Supported Functionality

- `RadioButton.value` is a bindable 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 { Component } from "vue";

export declare const RadioButton: Component<{
	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: Component<{
	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`

```vue
<template>
  <RadioButtonGroup :options="options" v-model:value="value" type="grid" />
</template>

<style scoped>
.wx-radiogroup.wx-grid .wx-item {
	flex-basis: 33.333%;
	max-width: 33.333%;
}
</style>
```

#### Recipes

##### Standalone Radio Buttons

```vue
<script setup>
import { RadioButton } from "@svar-ui/vue-core";
</script>

<template>
  <RadioButton label="One" name="mode" inputValue="one" :value="true" />
  <RadioButton label="Two" name="mode" inputValue="two" />
</template>
```

##### Radio Group

```vue
<script setup>
import { ref } from "vue";
import { RadioButtonGroup } from "@svar-ui/vue-core";

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

const value = ref(1);
</script>

<template>
  <RadioButtonGroup :options="options" v-model:value="value" type="inline" />
</template>
```

#### Implementation Notes

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


## File: core/rangecalendar.md

> Source: `core/rangecalendar.md`

### SVAR Vue Core RangeCalendar

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

#### Package

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

#### Supported Functionality

- Date range calendar with bindable `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 { Component } from "vue";

export declare const RangeCalendar: Component<{
	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`

```vue
<template>
  <div class="range-shell">
    <RangeCalendar :months="2" />
  </div>
</template>

<style scoped>
.range-shell {
	--wx-calendar-cell-size: 30px;
}
</style>
```

#### Recipes

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

```vue
<script setup>
import { ref } from "vue";
import { RangeCalendar } from "@svar-ui/vue-core";

const start = ref(new Date(2025, 4, 1));
const end = ref(new Date(2025, 4, 7));
</script>

<template>
  <RangeCalendar
    v-model:start="start"
    v-model:end="end"
    :months="2"
    :buttons="['done', 'clear', 'today']"
    :onchange="ev => console.log(ev.start, ev.end)"
  />
</template>
```

##### Single-Month Range

```vue
<script setup>
import { ref } from "vue";
import { RangeCalendar } from "@svar-ui/vue-core";

const start = ref();
const end = ref();
</script>

<template>
  <RangeCalendar
    v-model:start="start"
    v-model:end="end"
    :months="1"
    :buttons="false"
    :onchange="ev => console.log(ev.start, ev.end)"
  />
</template>
```

#### 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 Vue Core RichSelect

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

#### Package

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

#### Supported Functionality

- Non-input single-select control backed by `SuggestDropdown`.
- `value` is the selected id and is bindable.
- `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` slot receives the option object directly for both selected content and list rows.
- `onchange` emits `{ value }`.

#### Public Types

```ts
import type { Component } from "vue";

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: Component<{
	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?: () => any;
	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`

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

<style scoped>
.wx-popup.user-select-menu .wx-item {
	min-height: 40px;
}
</style>
```

#### Recipes

##### Rich Select With Custom Template

```vue
<script setup>
import { RichSelect } from "@svar-ui/vue-core";

const users = [
	{ id: 104, label: "Lord Varys", email: "little.birds@mail" },
	{ id: 103, label: "Ned Stark", email: "winterhell@mail" },
];
</script>

<template>
  <RichSelect :options="users" :value="104">
    <template #children="option">
      <div>
        <strong>{{ option.label }}</strong>
        <span>{{ option.email }}</span>
      </div>
    </template>
  </RichSelect>
</template>
```

##### Hidden Selected Option

```vue
<script setup>
import { RichSelect } from "@svar-ui/vue-core";

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

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

<template>
  <RichSelect :textOptions="allUsers" :options="visibleUsers" :value="87" clear />
</template>
```

#### Implementation Notes

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


## File: core/segmented.md

> Source: `core/segmented.md`

### SVAR Vue Core Segmented

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

#### Package

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

#### Supported Functionality

- Renders an inline segmented button group.
- `options` are `{ id, label, icon?, title? }`.
- `value` is the selected id and is bindable.
- 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` slot receives `{ option }` for custom option content.

#### Public Types

```ts
import type { Component } from "vue";

export declare const Segmented: Component<{
	options?: {
		id: string | number;
		label: string;
		icon?: string;
		title?: string;
	}[];
	value?: string | number;
	css?: string;
	children?: () => any;
	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`

```vue
<template>
  <Segmented css="view-mode" :options="options" v-model:value="value" />
</template>

<style scoped>
.wx-segmented.view-mode {
	--wx-segmented-padding: 3px;
}
</style>
```

#### Recipes

##### Basic Segmented Control

```vue
<script setup>
import { ref } from "vue";
import { Segmented } from "@svar-ui/vue-core";

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

const value = ref("list");
</script>

<template>
  <Segmented :options="options" v-model:value="value" :onchange="ev => console.log(ev.value)" />
</template>
```

##### Custom Option Content

```vue
<script setup>
import { Segmented } from "@svar-ui/vue-core";

const options = [
	{ id: "left", label: "Left", icon: "wxi-align-left" },
	{ id: "right", label: "Right", icon: "wxi-align-right" },
];
</script>

<template>
  <Segmented :options="options" value="left">
    <template #children="{ option }">
      <i :class="option.icon"></i>
      <span>{{ option.label }}</span>
    </template>
  </Segmented>
</template>
```


## File: core/select.md

> Source: `core/select.md`

### SVAR Vue Core Select

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

#### Package

```js
import { Select } from "@svar-ui/vue-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 bindable 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 { Component } from "vue";

export declare const Select: Component<{
	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`.

```vue
<template>
  <div class="owner-select">
    <Select :options="users" v-model:value="value" clear />
  </div>
</template>

<style scoped>
.owner-select .wx-select {
	--wx-input-width: 280px;
}
</style>
```

#### Recipes

##### Native Select With Clear

```vue
<script setup>
import { ref } from "vue";
import { Field, Select } from "@svar-ui/vue-core";

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

const owner = ref("");
</script>

<template>
  <Field label="Owner" position="left">
    <Select
      :options="users"
      v-model:value="owner"
      placeholder="Select owner"
      clear
    />
  </Field>
</template>
```

#### Implementation Notes

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


## File: core/sidearea.md

> Source: `core/sidearea.md`

### SVAR Vue Core SideArea

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

#### Package

```js
import { SideArea } from "@svar-ui/vue-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 { Component } from "vue";

export declare const SideArea: Component<{
	position?: "right";
	children?: () => any;
	oncancel?: () => void;
}>;
```

#### Styling

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

```vue
<template>
  <div class="side-host">
    <SideArea>
      <div class="side-content">Panel</div>
    </SideArea>
  </div>
</template>

<style scoped>
.side-host {
	position: relative;
	min-height: 300px;
}

.side-content {
	width: 400px;
	padding: 20px;
}
</style>
```

#### Recipes

##### Right-Side Local Panel

```vue
<script setup>
import { ref } from "vue";
import { Button, SideArea } from "@svar-ui/vue-core";

const open = ref(false);
</script>

<template>
  <div style="position: relative; min-height: 300px">
    <Button :onclick="() => (open = true)">Open side panel</Button>

    <SideArea v-if="open" :oncancel="() => (open = false)">
      <div style="width: 400px; padding: 20px">Panel content</div>
    </SideArea>
  </div>
</template>
```


## File: core/slider.md

> Source: `core/slider.md`

### SVAR Vue Core Slider

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

#### Package

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

#### Supported Functionality

- Renders an input range with optional label.
- Bindable `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 { Component } from "vue";

export declare const Slider: Component<{
	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`.

```vue
<template>
  <Slider width="240px" v-model:value="value" />
</template>

<style scoped>
.wx-slider {
	--wx-slider-thumb-size: 18px;
}
</style>
```

#### Recipes

##### Slider With Drag And Final Events

```vue
<script setup>
import { ref } from "vue";
import { Field, Slider } from "@svar-ui/vue-core";

const progress = ref(50);
</script>

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


## File: core/suggest-dropdown.md

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

### SVAR Vue Core SuggestDropdown

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

#### Package

```js
import { SuggestDropdown } from "@svar-ui/vue-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` slot receives `{ option }`.

#### Public Types

```ts
import type { Component } from "vue";

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: Component<
	DropdownOptions & {
		items?: { id: string | number; label: string }[];
		children?: () => any;
		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`.

```vue
<template>
  <SuggestDropdown :items="items" css="suggest-menu" />
</template>

<style scoped>
.wx-popup.suggest-menu .wx-list {
	max-height: 180px;
}
</style>
```

#### Recipes

##### Controlled Suggest Dropdown

```vue
<script setup>
import { ref } from "vue";
import { SuggestDropdown } from "@svar-ui/vue-core";

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

let api;
</script>

<template>
  <button :onclick="() => api.navigate(0)">Open</button>

  <SuggestDropdown
    :items="items"
    :onready="ev => (api = ev)"
    :onselect="ev => console.log(ev.id)"
  />
</template>
```

#### 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 Vue Core Switch

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

#### Package

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

#### Supported Functionality

- Renders a labeled checkbox styled as a switch.
- `value` is a bindable 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 { Component } from "vue";

export declare const Switch: Component<{
	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`.

```vue
<template>
  <Switch v-model:value="value" />
</template>

<style scoped>
.wx-switch {
	--wx-switch-width: 56px;
}
</style>
```

#### Recipes

##### Bound Switch In A Field

```vue
<script setup>
import { ref } from "vue";
import { Field, Switch } from "@svar-ui/vue-core";

const enabled = ref(true);
</script>

<template>
  <Field :label="`Enabled: ${enabled}`" position="left" type="switch">
    <Switch v-model:value="enabled" :onchange="ev => console.log(ev.value)" />
  </Field>
</template>
```

#### 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 Vue Core Tabs

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

#### Package

```js
import { Tabs } from "@svar-ui/vue-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 bindable.
- 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 { Component } from "vue";

export declare const Tabs: Component<{
	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`

```vue
<template>
  <Tabs :options="tabs" v-model:value="active" />
</template>

<style scoped>
.wx-tabs {
	--wx-tabs-cell-min-width: 80px;
}
</style>
```

#### Recipes

##### Tabs With Panels

```vue
<script setup>
import { ref } from "vue";
import { Tabs } from "@svar-ui/vue-core";

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

const active = ref("info");
</script>

<template>
  <Tabs :options="tabs" v-model:value="active" />

  <div v-if="active === 'info'">Info panel</div>
  <div v-else-if="active === 'audit'">Audit panel</div>
  <div v-else>Done panel</div>

  <Tabs :options="tabs" v-model:value="active" type="bottom" />
</template>
```

#### 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 Vue Core Text

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

#### Package

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

#### Supported Functionality

- Bindable `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 { Component } from "vue";

export declare const Text: Component<{
	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`.

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

<style scoped>
.wx-text.search-input {
	--wx-input-width: 320px;
}
</style>
```

#### Recipes

##### Text With Clear And Left Icon

```vue
<script setup>
import { ref } from "vue";
import { Field, Text } from "@svar-ui/vue-core";

const query = ref("");
</script>

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

##### Focus And Select On Mount

```vue
<script setup>
import { Text } from "@svar-ui/vue-core";
</script>

<template>
  <Text value="Some value" focus select />
</template>
```

#### 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 Vue Core TextArea

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

#### Package

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

#### Supported Functionality

- Renders a native `<textarea class="wx-textarea">`.
- `value` is bindable.
- `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 { Component } from "vue";

export declare const TextArea: Component<{
	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]`.

```vue
<template>
  <TextArea placeholder="Details" />
</template>

<style scoped>
.wx-textarea {
	min-height: 140px;
}
</style>
```

#### Recipes

##### TextArea In A Field

```vue
<script setup>
import { ref } from "vue";
import { Field, TextArea } from "@svar-ui/vue-core";

const details = ref("");
</script>

<template>
  <Field label="Details" error>
    <TextArea
      v-model:value="details"
      error
      title="Details are required"
      placeholder="Type here"
    />
  </Field>
</template>
```

#### 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 Vue Core Themes

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

#### Package

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

#### Supported Functionality

- Theme components provide Vue inject key `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 { Component } from "vue";

export declare const Willow: Component<{
	fonts?: boolean;
	children?: () => any;
}>;

export declare const WillowDark: Component<{
	fonts?: boolean;
	children?: () => any;
}>;
```

#### Styling


```vue
<template>
  <Willow :fonts="false">
    <div class="app-theme">
      <App />
    </div>
  </Willow>
</template>

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

#### Recipes

##### Wrap An App In A Theme

```vue
<script setup>
import { Willow } from "@svar-ui/vue-core";
import AppRoutes from "./AppRoutes.vue";
</script>

<template>
  <Willow>
    <AppRoutes />
  </Willow>
</template>
```

##### Dark Theme Without CDN Font Injection

```vue
<script setup>
import { WillowDark } from "@svar-ui/vue-core";
</script>

<template>
  <WillowDark :fonts="false">
    <div class="screen">Dark UI</div>
  </WillowDark>
</template>
```

#### Other information

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


## File: core/timepicker.md

> Source: `core/timepicker.md`

### SVAR Vue Core TimePicker

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

#### Package

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

#### Supported Functionality

- Input-like time picker backed by `Text`, `Dropdown`, `Slider`, and optional `TwoState`.
- `value` is bindable 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 bindable value.

#### Public Types

```ts
import type { Component } from "vue";

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: Component<{
	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.

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

<style scoped>
.wx-text.time-input {
	--wx-input-width: 180px;
}
</style>
```

#### Recipes

##### Bound Time

```vue
<script setup>
import { ref } from "vue";
import { Field, TimePicker } from "@svar-ui/vue-core";

const value = ref(new Date(0, 0, 0, 14, 30));
</script>

<template>
  <Field label="Time" position="left">
    <TimePicker v-model:value="value" :onchange="ev => console.log(ev.value)" />
  </Field>
</template>
```

##### Twelve-Hour Locale

```vue
<script setup>
import { ref } from "vue";
import { Field, Locale, TimePicker } from "@svar-ui/vue-core";

const value = ref(new Date(0, 0, 0, 14, 30));
</script>

<template>
  <Locale
    :words="{
      formats: { timeFormat: '%g:%i %a' },
      calendar: { clockFormat: 12 },
    }"
  >
    <Field label="Time" position="left">
      <TimePicker v-model:value="value" :dropdown="{ width: '100%' }" />
    </Field>
  </Locale>
</template>
```

#### 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 Vue Core TwoState

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

#### Package

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

#### Supported Functionality

- Wraps `Button` and toggles bindable 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` slot 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 { Component, Slot } from "vue";

export declare const TwoState: Component<{
	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?: Slot<[]>;
	children?: () => any;
	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.

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

<style scoped>
.wx-button.favorite-button.wx-pressed {
	font-weight: 700;
}
</style>
```

#### Recipes

##### Toggle With Active Content

```vue
<script setup>
import { ref } from "vue";
import { TwoState } from "@svar-ui/vue-core";

const active = ref(false);
</script>

<template>
  <TwoState
    v-model:value="active"
    type="primary"
    icon="wxi-star"
    iconActive="wxi-check"
    :onchange="ev => console.log(ev.value)"
  >
    Favorite
    <template #active>
      Favorited
    </template>
  </TwoState>
</template>
```

##### Prevent Toggle

```vue
<script setup>
import { TwoState } from "@svar-ui/vue-core";

function beforeToggle(ev) {
	if (!confirm("Toggle?")) ev.preventDefault();
}
</script>

<template>
  <TwoState :onclick="beforeToggle">Toggle</TwoState>
</template>
```

#### Implementation Notes

- The active slot is rendered 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/vue-menu components

#### Package

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

import "@svar-ui/vue-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 Vue 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 Vue component directly.

#### Public Types

```ts
import type { Component } from "vue";

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

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

export declare const Menu: Component<{
	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: Component<{
	css?: string;
	menuCss?: string;
	options?: IMenuOption[];
	onclick?: (ev: IMenuOptionClick) => void;
}>;

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

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

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

export declare function registerMenuItem(
	type: string,
	handler: Component<{ 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

```vue
<script setup>
import { DropDownMenu } from "@svar-ui/vue-menu";

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);
}
</script>

<template>
  <DropDownMenu :options="options" :onclick="clicked" at="bottom-fit">
    <button>Open</button>
  </DropDownMenu>
</template>
```

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

```vue
<script setup>
import { ref } from "vue";
import { Menu } from "@svar-ui/vue-menu";

const options = [{ id: "copy", text: "Copy" }];
const parent = ref(null);

function clicked() {
	parent.value = null;
}
</script>

<template>
  <button :onclick="ev => (parent = ev.currentTarget)">Open</button>

  <Menu v-if="parent" :options="options" :parent="parent" at="right" :onclick="clicked" />
</template>
```

##### Menu Bar With Submenus

```vue
<script setup>
import { MenuBar } from "@svar-ui/vue-menu";

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" },
];
</script>

<template>
  <MenuBar
    :options="options"
    css="app-menubar"
    menuCss="app-menu"
    :onclick="ev => console.log(ev.option?.id)"
  />
</template>
```

##### Context Menu With Resolver And Filter

```vue
<script setup>
import { ContextMenu } from "@svar-ui/vue-menu";

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";
}
</script>

<template>
  <ContextMenu
    :options="options"
    at="point"
    :resolver="resolver"
    :filter="filter"
    :onclick="ev => console.log(ev.context, ev.option?.id)"
  >
    <div v-for="row in rows" :key="row.id" :data-context-id="row.id">{{ row.name }}</div>
  </ContextMenu>
</template>
```

##### Programmatic Action Menu

```vue
<script setup>
import { ref } from "vue";
import { ActionMenu } from "@svar-ui/vue-menu";

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

const selected = ref(["a", "b"]);
const menu = ref(null);

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

function clicked(ev) {
	if (ev.option) selected.value[ev.context] = ev.option.id;
}
</script>

<template>
  <ActionMenu :options="options" :filter="markSelected" :onclick="clicked" ref="menu" />

  <button v-for="(value, index) in selected" :key="index" :onclick="ev => menu.show(ev, index)">{{ value }}</button>
</template>
```

##### Custom Menu Item Renderer

```vue
<!-- UserMenuItem.vue -->
<script setup>
const props = defineProps({ option: {} });
</script>

<template>
  <div class="user-option">{{ props.option.name }}</div>
</template>
```

```vue
<script setup>
import { DropDownMenu, registerMenuItem } from "@svar-ui/vue-menu";
import AddUserItem from "./AddUserItem.vue";
import UserMenuItem from "./UserMenuItem.vue";

registerMenuItem("user", UserMenuItem);

const options = [
	{ id: "u1", comp: "user", name: "Alex Wolensy" },
	{ id: "add", comp: AddUserItem, name: "Add New" },
];
</script>

<template>
  <DropDownMenu :options="options">
    <button>Select user</button>
  </DropDownMenu>
</template>
```

#### 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 Vue Toolbar / @svar-ui/vue-toolbar components

#### Package

```js
import { Toolbar, registerToolbarItem } from "@svar-ui/vue-toolbar";

import "@svar-ui/vue-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 Vue 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/vue-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 { Component } from "vue";

export interface IToolbarItem {
	id?: string | number;
	comp?: string | Component<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: Component<{
	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: Component<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

```vue
<script setup>
import { ref } from "vue";

const message = ref("");
function onClick(item) {
	message.value = `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,
	},
];
</script>

<template>
  <Toolbar :items="items" />
</template>
```

##### 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

```vue
<template>
  <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)"
  />
</template>
```

##### Keyed Values

```vue
<script setup>
import { ref } from "vue";
// component must support `value` handler and `onchange` callback to be bound, most vue-core controls fit
import { Slider } from "@svar-ui/vue-core";
const values = ref({ size: 15 });
</script>

<template>
  <Toolbar
    :items="[{ comp: Slider, min: 0, max: 100, key: 'size' }]"
    v-model:values="values"
    :onchange="ev => console.log(ev.item.key, ev.value)"
  />
</template>
```

##### Common core controls

```vue
<script setup>
import { Slider, Segmented, Switch } from "@svar-ui/vue-core";

const options = [
	{ id: 1, label: "One" },
	{ id: 2, label: "Two" },
];
</script>

<template>
  <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' },
    ]"
  />
</template>
```

##### Custom Component Contract

```vue
<!-- CustomToolbarItem.vue -->
<script setup>
const props = defineProps({
  value: {},
  onchange: { type: Function },
  onclick: { type: Function },
  menu: {},
  text: { default: "" },
  disabled: { default: false },
});
</script>

<template>
  <button
    :class="{ 'in-menu': props.menu }"
    :disabled="props.disabled"
    :onclick="() => {
      props.onclick?.();
      props.onchange?.({ value: !props.value });
    }"
  >
    {{ props.text }}
  </button>
</template>
```

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

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

```vue
<template>
  <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',
          },
        ],
      },
    ]"
  />
</template>
```

##### Vertical Toolbar

```vue
<template>
  <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' },
    ]"
  />
</template>
```


## File: layout/index.md

> Source: `layout/index.md`

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

#### Package

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

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

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` slot 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 Slot, type Component } from "vue";

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

interface ICellProps {
	label?: string;
	width?: number;
	height?: number;
	minWidth?: number;
	minHeight?: number;
	grow?: number;
	scroll?: boolean;
	css?: string;
	children: Slot;
	header?: Slot;
}

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

export declare const Layout: Component<ILayoutProps>;
export declare const Cell: Component<ICellProps>;
export declare const Panel: Component<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`.

```vue
<template>
  <Layout direction="row" preset="line" css="app-layout">
    <Cell label="Files" :width="220" css="app-pane">Files</Cell>
    <Cell label="Editor">Editor</Cell>
  </Layout>
</template>

<style scoped>
.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;
}
</style>
```

#### Recipes

##### Basic Fixed And Flexible Panes

```vue
<script setup>
import { Layout, Cell } from "@svar-ui/vue-layout";
</script>

<template>
  <div class="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>
</template>

<style scoped>
.workspace {
	width: 100%;
	height: 100vh;
}
</style>
```

##### Resizable IDE Layout

```vue
<script setup>
import { ref } from "vue";
import { Layout, Cell, Panel } from "@svar-ui/vue-layout";

const sidebarWidth = ref(220);
</script>

<template>
  <Layout
    direction="row"
    :padding="6"
    resizable
    :oncellresize="sizes => (sidebarWidth = sizes[0])"
  >
    <Panel label="Files" :width="sidebarWidth" :minWidth="120">
      <div>File tree</div>
    </Panel>

    <Cell>
      <Layout preset="line">
        <Cell :grow="3">
          <template #header><span>Editor</span></template>
          <div>Editor area</div>
        </Cell>
        <Panel :grow="1" label="Terminal">
          <div>Terminal</div>
        </Panel>
      </Layout>
    </Cell>
  </Layout>
</template>
```

##### Controlled Panel Collapse

```vue
<script setup>
import { ref } from "vue";
import { Layout, Cell, Panel } from "@svar-ui/vue-layout";

const collapsed = ref(false);
</script>

<template>
  <Layout direction="row" preset="line">
    <Panel
      label="Sidebar"
      :width="220"
      :minWidth="140"
      :collapsed="collapsed"
      :oncollapse="value => (collapsed = value)"
    >
      <div>Sidebar content</div>
    </Panel>
    <Cell>
      <div>Main content</div>
    </Cell>
  </Layout>
</template>
```

##### Custom Header Slot

```vue
<script setup>
import { Layout, Cell } from "@svar-ui/vue-layout";
</script>

<template>
  <Layout>
    <Cell :height="48">
      <template #header>
        <div class="bar">
          <span>Toolbar</span>
          <button>Save</button>
        </div>
      </template>
      <div>Body</div>
    </Cell>
    <Cell scroll>
      <div>Long content</div>
    </Cell>
  </Layout>
</template>
```

##### Presets And Explicit Spacing

```vue
<script setup>
import { Layout, Cell } from "@svar-ui/vue-layout";
</script>

<template>
  <Layout direction="row" preset="space" :gap="12" :padding="16">
    <Cell css="wx-border">Left</Cell>
    <Cell css="wx-border">Right</Cell>
  </Layout>
</template>
```

#### 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 Vue Grid / @svar-ui/vue-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/vue-grid";

import "@svar-ui/vue-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="api"` 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`: `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 Vue 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/vue-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/vue-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/vue-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 { Component, ComponentProps } from "vue";
import { ContextMenu as BaseContextMenu } from "@svar-ui/vue-menu";
import { Toolbar as BaseToolbar } from "@svar-ui/vue-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?: Component<{
			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?: Component<
		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?: Component<ICellProps>;
	editor?: TEditorType | IColumnEditorConfig | TEditorHandlerConfig;
	header?: TColumnHeaderConfig;
	footer?: TColumnHeaderConfig;
}

export declare const Grid: Component<
	{
		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 | Component;
		columns: IColumnConfig[];
		hotkeys?:
			| false
			| { [key: string]: ((e?: KeyboardEvent) => void) | boolean };
	} & IConfig &
		GridActions<TMethodsConfig>
>;

export declare const HeaderMenu: Component<{
	columns?: { [key: string]: boolean };
	api?: IApi;
	children?: () => any;
}>;

export declare const ContextMenu: Component<
	ComponentProps<typeof BaseContextMenu> & {
		api?: IApi;
	}
>;

export declare const Toolbar: Component<
	ComponentProps<typeof BaseToolbar> & {
		api?: IApi;
	}
>;

export declare const Tooltip: Component<{
	content?: Component;
	api?: IApi;
	children?: () => any;
}>;

export declare const Willow: Component<{
	fonts?: boolean;
	children?: () => any;
}>;

export declare const WillowDark: Component<{
	fonts?: boolean;
	children?: () => any;
}>;

export declare function registerInlineEditor(
	type: string,
	component: Component<{
		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}${RemoveHyphen<Tail>}`
	: S;

type EventName<K extends string> = `on${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.vue`.

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:

```vue
<template>
  <div class="orders-grid">
    <Grid :data="data" :columns="columns" :rowStyle="row => (row.priority ? 'is-priority' : '')" />
  </div>
</template>

<style scoped>
.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;
}
</style>
```

#### Recipes

##### Basic Grid

```vue
<script setup>
import { Grid } from "@svar-ui/vue-grid";

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 },
];
</script>

<template>
  <div style="height: 360px;">
    <Grid :data="data" :columns="columns" />
  </div>
</template>
```

##### API, Events, And Selection

```vue
<script setup>
import { ref } from "vue";
import { Grid } from "@svar-ui/vue-grid";

const api = ref();
const selected = ref([]);

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() {
	api.value.exec("add-row", { row: { city: "New city" } });
}

function updateSelected() {
	selected.value = api.value.getState().selectedRows;
}
</script>

<template>
  <button :onclick="addRow">Add</button>
  <Grid
    :data="data"
    :columns="columns"
    :init="init"
    ref="api"
    multiselect
    :onselectrow="updateSelected"
  />
</template>
```

##### Sort, Header Filters, And Inline Editors

```vue
<script setup>
import { Grid } from "@svar-ui/vue-grid";

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,
	},
];
</script>

<template>
  <Grid :data="data" :columns="columns" />
</template>
```

##### Custom Body, Header, And Footer Cells

```vue
<!-- CheckCell.vue -->
<script setup>
import { Checkbox } from "@svar-ui/vue-core";

const props = defineProps({
  api: {},
  row: {},
  column: {},
  onaction: { type: Function },
});

function change({ value }) {
	props.api.exec("update-cell", { id: props.row.id, column: props.column.id, value });
	props.onaction?.({
		action: "checked-change",
		data: { row: props.row.id, column: props.column.id, value },
	});
}
</script>

<template>
  <div data-action="ignore-click">
    <Checkbox :value="props.row[props.column.id]" :onchange="change" />
  </div>
</template>
```

```vue
<script setup>
import { Grid } from "@svar-ui/vue-grid";
import CheckCell from "./CheckCell.vue";
import HeaderTitle from "./HeaderTitle.vue";

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 },
];
</script>

<template>
  <Grid
    :data="data"
    :columns="columns"
    footer
    :oncheckedchange="ev => console.log(ev.row, ev.value)"
  />
</template>
```

##### Custom Inline Editor

```vue
<!-- ColorEditor.vue -->
<script setup>
import { ref } from "vue";
import { ColorBoard, Dropdown } from "@svar-ui/vue-core";
import { clickOutside } from "@svar-ui/lib-dom";
import { asDirective } from "@svar-ui/lib-vue";

const vClickOutside = asDirective(clickOutside);

const props = defineProps({
  editor: {},
  onsave: { type: Function },
  onapply: { type: Function },
  oncancel: { type: Function },
});
const value = ref(props.editor.value);

function change({ value, input }) {
	if (input) props.onapply(value);
	else props.onsave();
}
</script>

<template>
  <button :onclick="props.oncancel">{{ value }}</button>
  <Dropdown width="auto" trackScroll :oncancel="props.oncancel">
    <div v-click-outside="() => props.onsave(true)">
      <ColorBoard :value="value" :onchange="change" button />
    </div>
  </Dropdown>
</template>
```

```vue
<script setup>
import { Grid, registerInlineEditor } from "@svar-ui/vue-grid";
import ColorEditor from "./ColorEditor.vue";

registerInlineEditor("color", ColorEditor);

const data = [{ id: 1, color: "#35D6A7" }];
const columns = [
	{ id: "color", header: "Color", editor: "color", width: 180 },
];
</script>

<template>
  <Grid :data="data" :columns="columns" />
</template>
```

##### Toolbar, Context Menu, And Header Menu

```vue
<script setup>
import { ref } from "vue";
import { Grid, Toolbar, ContextMenu, HeaderMenu } from "@svar-ui/vue-grid";

const api = ref();
const data = [
	{ id: 1, name: "Alex" },
	{ id: 2, name: "Sam" },
];
const columns = [
	{ id: "name", header: "Name", editor: "text", flexgrow: 1 },
];
</script>

<template>
  <Toolbar :api="api" />
  <ContextMenu :api="api">
    <HeaderMenu :api="api">
      <Grid :data="data" :columns="columns" ref="api" multiselect reorder undo />
    </HeaderMenu>
  </ContextMenu>
</template>
```

##### Dynamic Data Loading

```vue
<script setup>
import { ref } from "vue";
import { Grid } from "@svar-ui/vue-grid";

const raw = Array.from({ length: 10000 }, (_, id) => ({
	id,
	name: `Row ${id}`,
}));

const columns = [{ id: "name", header: "Name", flexgrow: 1 }];
const data = ref([]);

function provideData({ row }) {
	data.value = raw.slice(row.start, row.end);
}
</script>

<template>
  <div style="height: 500px;">
    <Grid
      :data="data"
      :columns="columns"
      :dynamic="{ rowCount: raw.length }"
      :onrequestdata="provideData"
    />
  </div>
</template>
```

##### Responsive Columns And Fixed Columns

```vue
<script setup>
import { Grid } from "@svar-ui/vue-grid";

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 },
	},
};
</script>

<template>
  <div class="grid-shell">
    <Grid :data="data" :columns="columns" :responsive="responsive" :split="{ left: 1 }" />
  </div>
</template>

<style scoped>
.grid-shell {
	height: 420px;
}

.grid-shell .wx-grid.wx-responsive-600 .wx-cell {
	padding-top: 10px;
	padding-bottom: 10px;
}
</style>
```

##### Tree Grid

```vue
<script setup>
import { ref } from "vue";
import { Grid } from "@svar-ui/vue-grid";

const api = ref();
const data = [
	{
		id: 1,
		name: "Project",
		open: true,
		data: [{ id: 2, name: "Task" }],
	},
];

const columns = [
	{ id: "name", header: "Name", treetoggle: true, flexgrow: 1 },
];
</script>

<template>
  <button :onclick="() => api.exec('open-row', { id: 1, nested: true })">
    Open
  </button>
  <button :onclick="() => api.exec('close-row', { id: 1, nested: true })">
    Close
  </button>

  <Grid :data="data" :columns="columns" ref="api" tree />
</template>
```

##### External Editor From Grid Columns

```vue
<script setup>
import { ref } from "vue";
import { Grid, getEditorConfig } from "@svar-ui/vue-grid";
import { Editor } from "@svar-ui/vue-editor";

const api = ref();
const editing = ref(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 }) => {
		editing.value = grid.getRow(id);
		return false;
	});
}
</script>

<template>
  <Grid :data="data" :columns="columns" :init="init" ref="api" />

  <Editor
    v-if="editing"
    :values="editing"
    :items="getEditorConfig(columns)"
    :onsave="({ values }) =>
      api.exec('update-row', { id: editing.id, row: values })"
  />
</template>
```

#### 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.vue` 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 Vue Editor / @svar-ui/vue-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/vue-editor";

import "@svar-ui/vue-editor/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 Vue component for `item.comp`.
- `Willow`, `WillowDark` - wrappers around matching `@svar-ui/vue-core` themes

##### Built-in item components

- `text` - registered to `Text` from `@svar-ui/vue-core`; default when `comp` is omitted.
- `textarea` - registered to `TextArea` from `@svar-ui/vue-core`.
- `checkbox` - registered to `Checkbox` from `@svar-ui/vue-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 Vue 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/vue-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 { Component } from "vue";
import type { IToolbarItem } from "@svar-ui/vue-toolbar";

export declare const Editor: Component<{
	values?: Record<string, any>;
	items?: {
		comp?: string | Component;
		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?: () => any;
}>;

export declare function registerEditorItem(
	type: string,
	handler: Component<any>
): void;

export declare const Willow: Component<{
	fonts?: boolean;
	children?: () => any;
}>;

export declare const WillowDark: Component<{
	fonts?: boolean;
	children?: () => any;
}>;
```

#### 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`

```vue
<template>
  <Editor :items="items" :values="values" layout="columns" css="task-editor" />
</template>

<style scoped>
.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;
}
</style>
```

#### Recipes

##### Basic Inline Editor

```vue
<script setup>
import { ref } from "vue";
import { Editor } from "@svar-ui/vue-editor";

const items = [
	{ comp: "text", key: "name", label: "Name" },
	{ comp: "checkbox", key: "admin", label: "Is Admin" },
	{ comp: "textarea", key: "descr", label: "Description" },
];

const values = ref({
	name: "John Doe",
	admin: true,
	descr: "Notes",
});
</script>

<template>
  <Editor :items="items" :values="values" :topBar="false" />
</template>
```

##### Manual Save With Validation

```vue
<script setup>
import { ref } from "vue";
import { Editor } from "@svar-ui/vue-editor";

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 = ref({ firstName: "John", email: "john@example.org" });
const visible = ref(true);

function handleAction({ item, changes }) {
	if (item.id === "save" && changes.length) return;
	visible.value = false;
}

function handleSave({ values: next }) {
	values.value = next;
	visible.value = false;
}
</script>

<template>
  <Editor
    v-if="visible"
    placement="sidebar"
    :autoSave="false"
    :items="items"
    :values="values"
    :onaction="handleAction"
    :onsave="handleSave"
  />
</template>
```

##### Auto Save Sidebar With Custom Toolbar

```vue
<script setup>
import { ref } from "vue";
import { Editor } from "@svar-ui/vue-editor";

const items = [
	{ comp: "text", key: "label", label: "Label" },
	{ comp: "textarea", key: "description", label: "Description" },
];

const values = ref({ id: 1, label: "Task", description: "" });
const open = ref(true);

function handleAction({ item }) {
	if (item.id === "close" || item.id === "delete") open.value = false;
}

function handleSave({ values: next }) {
	values.value = next;
}
</script>

<template>
  <Editor
    v-if="open"
    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"
  />
</template>
```

##### Update Multiple Values From One Change

```vue
<script setup>
import { ref } from "vue";
import { Editor, registerEditorItem } from "@svar-ui/vue-editor";
import { Combo } from "@svar-ui/vue-core";

registerEditorItem("combo", Combo);

const items = ref([
	{
		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 = ref({ country: "", city: "" });

function handleChange(ev) {
	if (ev.key !== "country") return;

	items.value[1] = {
		...items.value[1],
		disabled: false,
		options: cities[ev.value],
	};

	ev.update = {
		country: ev.value,
		city: "",
	};
}
</script>

<template>
  <Editor :items="items" :values="values" :onchange="handleChange" :topBar="false" />
</template>
```

##### Register A Custom Item

```vue
<!-- PriorityCombo.vue -->
<script setup>
import { Combo } from "@svar-ui/vue-core";

const props = defineProps({
  value: {},
  options: {},
  onchange: { type: Function },
});
</script>

<template>
  <Combo :value="props.value" :options="props.options" :onchange="props.onchange">
    <template #children="{ option }">
      <span class="priority-dot" :style="{ background: option.color }"></span>
      {{ option.label }}
    </template>
  </Combo>
</template>
```

```vue
<script setup>
import { ref } from "vue";
import { Editor, registerEditorItem } from "@svar-ui/vue-editor";
import PriorityCombo from "./PriorityCombo.vue";

registerEditorItem("priority-combo", PriorityCombo);

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 = ref({ priority: 1 });
</script>

<template>
  <Editor :items="items" :values="values" :topBar="false" />
</template>
```

##### Sections And Accordion Panels

```vue
<script setup>
import { ref } from "vue";
import { Editor } from "@svar-ui/vue-editor";

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 = ref({ name: "John", admin: false });
</script>

<template>
  <Editor :items="items" :values="values" :topBar="false" />
</template>
```

##### Batch Switcher In Children

```vue
<script setup>
import { ref } from "vue";
import { Editor } from "@svar-ui/vue-editor";
import { Segmented } from "@svar-ui/vue-core";

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 = ref({ name: "John", descr: "", admin: false });
const activeBatch = ref("main");
</script>

<template>
  <Editor :topBar="false" :items="items" :values="values" :activeBatch="activeBatch">
    <Segmented :options="options" v-model:value="activeBatch" />
  </Editor>
</template>
```

##### Modal Columns Layout

```vue
<script setup>
import { ref } from "vue";
import { Editor } from "@svar-ui/vue-editor";

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 = ref({ name: "John", descr: "", admin: false });
const visible = ref(true);
</script>

<template>
  <Editor
    v-if="visible"
    placement="modal"
    layout="columns"
    :autoSave="false"
    :items="items"
    :values="values"
    :onaction="() => (visible = false)"
  />
</template>
```

#### 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 Vue Filter / @svar-ui/vue-filter FilterBuilder, FilterEditor, FilterBar, or FilterQuery components

Package: `@svar-ui/vue-filter`
Syles: `@svar-ui/vue-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/vue-filter`

Use this file independently when building, configuring, styling, or modifying `FilterBar`.

#### Import

```js
import {
	FilterBar,
	Willow,
	WillowDark,
	createArrayFilter,
	createFilter,
	createFilterRule,
} from "@svar-ui/vue-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 { Component } from "vue";
import type {
	IFilterSet,
	IFilterBarField,
} from "@svar-ui/filter-store";

export declare const FilterBar: Component<{
	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

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

- 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`.

```vue
<template>
	<div class="bar-scope">
		<Willow>
			<FilterBar :fields="fields" :onchange="handleChange" />
		</Willow>
	</div>
</template>

<style scoped>
.bar-scope {
	--wx-label-font-size: 14px;
	--wx-label-font-weight: 600;
}

.bar-scope .wx-filter-bar {
	width: 100%;
	gap: 16px;
	padding: 10px 0;
}
</style>
```

#### Recipes

##### Basic Text, Number, And Select Fields

```vue
<script setup>
import { ref } from "vue";
import { FilterBar, createArrayFilter } from "@svar-ui/vue-filter";

const rows = ref(data);

function apply({ value }) {
	rows.value = createArrayFilter(value)(data);
}
</script>

<template>
	<FilterBar
		:fields="[
			'last_name',
			{ id: 'age', type: 'number', filter: 'greater' },
			{
				id: 'country',
				type: 'text',
				options: ['USA', 'Germany'],
				value: 'USA',
			},
		]"
		:onchange="apply"
	/>
</template>
```

##### Date Fields And Ranges

```vue
<template>
	<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)"
	/>
</template>
```

##### Search Across Many Fields

```vue
<template>
	<FilterBar
		:fields="[
			{
				type: 'all',
				label: 'Search',
				placeholder: 'Search people',
				by: ['age', 'first_name', 'last_name'],
			},
		]"
		:onchange="({ value }) => applyFilter(value)"
	/>
</template>
```

##### Dynamic Field Selector

```vue
<template>
	<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)"
	/>
</template>
```

##### Faster Text Updates

```vue
<template>
	<FilterBar
		:debounce="100"
		:fields="['first_name', 'last_name']"
		:onchange="({ value }) => applyFilter(value)"
	/>
</template>
```

#### 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/vue-filter`

Use this file independently when building, configuring, styling, or modifying `FilterBuilder`.

#### Import

```js
import {
	FilterBuilder,
	Willow,
	WillowDark,
	createArrayFilter,
	createFilter,
	getOptionsMap,
} from "@svar-ui/vue-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: `onaddrule`, `onaddgroup`, `oneditrule`, `onupdaterule`, `ondeleterule`, `ontoggleglue`, `onchangerule`.
- `init(api)` runs once after initial store setup.
- `ref="api"` 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 { Component } from "vue";
import type {
	IApi,
	TMethodsConfig,
	IConfig,
} from "@svar-ui/filter-store";

export declare const FilterBuilder: Component<
	{
		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}${RemoveHyphen<Tail>}`
	: S;

type EventName<K extends string> = `on${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

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

- 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/vue-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`.

```vue
<template>
	<div class="builder-scope">
		<Willow>
			<FilterBuilder :fields="fields" :options="options" :onchange="handleChange" />
		</Willow>
	</div>
</template>

<style scoped>
.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;
}
</style>
```

#### Recipes

##### Local Array Filtering

```vue
<script setup>
import { ref } from "vue";
import { FilterBuilder, Willow, createArrayFilter } from "@svar-ui/vue-filter";

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 = ref(data);
const value = ref({ glue: "and", rules: [] });

function applyFilter({ value }) {
	rows.value = createArrayFilter(value)(data);
}
</script>

<template>
	<Willow>
		<FilterBuilder :value="value" :fields="fields" :options="options" :onchange="applyFilter" />
	</Willow>
</template>
```

##### Line Or Simple Layout

```vue
<template>
	<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)"
	/>
</template>
```

##### Async Options

```vue
<script setup>
import { FilterBuilder } from "@svar-ui/vue-filter";

async function loadOptions(fieldId) {
	await new Promise(resolve => setTimeout(resolve, 300));
	return optionMap[fieldId] || [];
}
</script>

<template>
	<FilterBuilder :value="value" :fields="fields" :options="loadOptions" />
</template>
```

##### API And Event Interception

```vue
<script setup>
import { ref } from "vue";
import { FilterBuilder } from "@svar-ui/vue-filter";

const api = ref(null);
const valueText = ref("");

function init(api) {
	api.intercept("add-rule", ev => {
		ev.edit = false;
	});
	api.on("change", ({ value }) => {
		valueText.value = JSON.stringify(value, null, 2);
	});
}

function addAgeRule() {
	api.value.exec("add-rule", {
		rule: { field: "age", type: "number", filter: "greater", value: 30 },
		edit: false,
	});
}
</script>

<template>
	<button :onclick="addAgeRule">Add age rule</button>
	<FilterBuilder ref="api" :fields="fields" :options="options" :init="init" />
	<pre>{{ valueText }}</pre>
</template>
```

##### Convert Date Strings Around Builder UI

```vue
<script setup>
import { ref } from "vue";
import { FilterBuilder } from "@svar-ui/vue-filter";

const incoming = {
	rules: [{ field: "start", filter: "greater", value: "2025-01-01" }],
};

const value = ref({
	...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));
	});
}
</script>

<template>
	<FilterBuilder :value="value" :fields="fields" :options="options" :init="init" />
</template>
```


## File: filter/FilterEditor.md

> Source: `filter/FilterEditor.md`

### FilterEditor

Package: `@svar-ui/vue-filter`

Use this file independently when building, configuring, styling, or modifying `FilterEditor`.

#### Import

```js
import {
	FilterEditor,
	Willow,
	WillowDark,
	createArrayFilter,
	createFilter,
	getOptions,
} from "@svar-ui/vue-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 { Component } from "vue";
import type {
	TSingleOptions,
	TFilterType,
	TType,
	TPredicate,
	AnyData,
	IFilter,
	IConfig,
	IField,
} from "@svar-ui/filter-store";

export declare const FilterEditor: Component<{
	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

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

- 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/vue-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)`.

```vue
<template>
	<div class="editor-scope">
		<Willow>
			<FilterEditor type="text" :options="values" :onapply="handleApply" />
		</Willow>
	</div>
</template>

<style scoped>
.editor-scope {
	--wx-filter-border: 1px solid #d0d5dd;
}

.editor-scope .wx-item {
	padding: 12px 16px;
}
</style>
```

#### Recipes

##### Single Text Rule With Apply

```vue
<script setup>
import { ref } from "vue";
import { FilterEditor, createArrayFilter } from "@svar-ui/vue-filter";

const options = ["Alex", "Daisy", "John"];
const rows = ref(data);

function apply({ value }) {
	rows.value = createArrayFilter({ rules: [value] })(data);
}
</script>

<template>
	<FilterEditor
		type="text"
		field="first_name"
		:options="options"
		:onapply="apply"
	/>
</template>
```

##### Live Rule Without Buttons

```vue
<script setup>
import { ref } from "vue";
import { FilterEditor, createArrayFilter } from "@svar-ui/vue-filter";

const rule = ref({});
const rows = ref(data);

function update({ value }) {
	rule.value = value;
	rows.value = createArrayFilter({ rules: [value] })(data);
}
</script>

<template>
	<FilterEditor
		type="text"
		field="first_name"
		:options="['Alex', 'Daisy', 'John']"
		:buttons="false"
		:includes="rule.includes"
		:filter="rule.filter"
		:value="rule.value"
		:onchange="update"
	/>
</template>
```

##### Field Selector With Async Options

```vue
<script setup>
import { FilterEditor } from "@svar-ui/vue-filter";

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] || [];
}
</script>

<template>
	<FilterEditor
		:fields="fields"
		field="age"
		:options="loadOptions"
		:onapply="({ value }) => console.log(value)"
	/>
</template>
```

##### Date Range Rule

```vue
<script setup>
import { FilterEditor, getOptions } from "@svar-ui/vue-filter";

const options = getOptions(data, "start");
</script>

<template>
	<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)"
	/>
</template>
```

##### Tuple With Formatted Options

```vue
<script setup>
import { FilterEditor, getOptions } from "@svar-ui/vue-filter";

const options = getOptions(data, "start", {
	predicate: "month",
	sort: (a, b) => a - b,
});
const monthName = value => monthLabels[value] || String(value);
</script>

<template>
	<FilterEditor
		field="start"
		:options="options"
		:format="monthName"
		filter="greater"
		type="tuple"
		:onapply="({ value }) => console.log(value)"
	/>
</template>
```

#### 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/vue-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/vue-filter";
```

#### Supported Functionality

##### Data Contract

- `value` is bindable 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 bound `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 { Component } from "vue";
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: Component<{
	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

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

- 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.

```vue
<template>
	<div class="query-scope">
		<Willow>
			<FilterQuery :fields="fields" :options="options" :onchange="handleFilter" />
		</Willow>
	</div>
</template>

<style scoped>
.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;
}
</style>
```

#### Recipes

##### Structured Query With Local Filtering

```vue
<script setup>
import { ref } from "vue";
import { FilterQuery, createArrayFilter } from "@svar-ui/vue-filter";

const value = ref("");
const rows = ref(data);

function handleFilter({ value, error }) {
	if (error && error.code !== "NO_DATA") return;
	rows.value = createArrayFilter(value, {}, fields)(data);
}
</script>

<template>
	<FilterQuery
		v-model:value="value"
		placeholder="e.g. FirstName: Alex or #urgent"
		:fields="fields"
		:options="{ ...options, '#': ['urgent', 'review', 'done'] }"
		:onchange="handleFilter"
	/>
</template>
```

##### Strict Query Syntax

```vue
<template>
	<FilterQuery
		v-model:value="query"
		parse="strict"
		placeholder="Status: Open and Age: >30"
		:fields="fields"
		:options="options"
		:onchange="({ value, error }) => {
			if (!error) applyFilter(value);
		}"
	/>
</template>
```

##### Natural Text Endpoint

```vue
<script setup>
import { ref } from "vue";
import { FilterQuery, createArrayFilter, getQueryString } from "@svar-ui/vue-filter";

const normalizedQuery = ref("");
const rows = ref(data);

async function handleNatural({ text, startProgress, endProgress }) {
	try {
		startProgress();
		const filter = await textToFilter(text, fields);
		normalizedQuery.value = filter ? getQueryString(filter).query : "";
		rows.value = createArrayFilter(filter || { rules: [] })(data);
	} finally {
		endProgress();
	}
}
</script>

<template>
	<FilterQuery
		parse="none"
		placeholder="first name contains Alex and age greater than 30"
		:onchange="handleNatural"
	/>

	<pre>{{ normalizedQuery }}</pre>
</template>
```

##### Mixed Query And Natural Text

```vue
<script setup>
import { ref } from "vue";
import { FilterQuery, createArrayFilter, getQueryString } from "@svar-ui/vue-filter";

const query = ref("start: 2024");
const rows = ref(data);

async function handleMixed({ value, error, text, startProgress, endProgress }) {
	if (text) {
		try {
			startProgress();
			value = await textToFilter(text, fields);
			query.value = value ? getQueryString(value).query : "";
			error = null;
		} finally {
			endProgress();
		}
	}

	if (error && error.code !== "NO_DATA") return;
	rows.value = createArrayFilter(value, {}, fields)(data);
}
</script>

<template>
	<FilterQuery
		v-model:value="query"
		placeholder="FirstName: contains Alex and Age: >30"
		:fields="fields"
		:options="options"
		:onchange="handleMixed"
	/>
</template>
```

##### Render Query HTML

```vue
<script setup>
import { computed } from "vue";
import { getQueryHtml, getQueryString } from "@svar-ui/vue-filter";

const html = computed(() =>
	filterValue
		? getQueryHtml(getQueryString(filterValue).query, { fields })
		: ""
);
</script>

<template>
	<div v-html="html"></div>
</template>
```

#### 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 Vue Gantt / @svar-ui/vue-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/vue-gantt";

import "@svar-ui/vue-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/vue-toolbar`; accepts `api` and optional `items`.
- `ContextMenu` - Gantt-aware wrapper around `@svar-ui/vue-menu` context menu; resolves tasks from Gantt `data-id`.
- `Editor` - Gantt-aware wrapper around `@svar-ui/vue-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/vue-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 bindable 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`:

- `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/vue-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/vue-grid` `HeaderMenu`.
- use it when the grid table API is needed for column visibility/menu behavior.

#### Public Types

```ts
import type { Component, ComponentProps } from "vue";
import { ContextMenu as BaseContextMenu } from "@svar-ui/vue-menu";
import { Toolbar as BaseToolbar } from "@svar-ui/vue-toolbar";
import { Editor as BaseEditor } from "@svar-ui/vue-editor";
import {
	HeaderMenu as BaseHeaderMenu,
	IColumnConfig as ITableColumn,
} from "@svar-ui/vue-grid";

import type {
	TMethodsConfig,
	IApi,
	IConfig,
	ITask,
	IGanttColumn,
} from "@svar-ui/gantt-store";

export * from "@svar-ui/gantt-store";
export { registerEditorItem } from "@svar-ui/vue-editor";

export interface IColumnConfig extends Omit<IGanttColumn, "header"> {
	cell?: ITableColumn["cell"];
	header?: ITableColumn["header"];
	editor?: ITableColumn["editor"];
}

export declare const Gantt: Component<
	{
		columns?: false | IColumnConfig[];
		taskTemplate?: Component<{
			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: Component<
	ComponentProps<typeof BaseHeaderMenu> & {
		api?: IApi;
	}
>;

export declare const ContextMenu: Component<
	ComponentProps<typeof BaseContextMenu> & {
		api?: IApi;
	}
>;

export declare const Toolbar: Component<
	ComponentProps<typeof BaseToolbar> & {
		api?: IApi;
	}
>;

export declare const Editor: Component<
	ComponentProps<typeof BaseEditor> & {
		api?: IApi;
	}
>;

export declare const Tooltip: Component<{
	content?: Component<{
		data: ITask;
	}>;
	api?: IApi;
	children?: () => any;
}>;

export declare const Willow: Component<{
	fonts?: boolean;
	children?: () => any;
}>;

export declare const WillowDark: Component<{
	fonts?: boolean;
	children?: () => any;
}>;

/* get component events from store actions*/
type RemoveHyphen<S extends string> = S extends `${infer Head}-${infer Tail}`
	? `${Head}${RemoveHyphen<Tail>}`
	: S;

type EventName<K extends string> = `on${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`

```vue
<script setup>
import { Gantt, Willow } from "@svar-ui/vue-gantt";
</script>

<template>
  <div class="gantt-shell">
    <Willow>
      <Gantt :tasks="tasks" :links="links" />
    </Willow>
  </div>
</template>

<style scoped>
.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);
}
</style>
```

#### Recipes

##### Basic Gantt With Theme

```vue
<script setup>
import { Gantt, Willow } from "@svar-ui/vue-gantt";

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 = [];
</script>

<template>
  <div class="gtcell">
    <Willow>
      <Gantt :tasks="tasks" :links="links" />
    </Willow>
  </div>
</template>

<style scoped>
.gtcell {
	height: 100%;
}
</style>
```

##### Toolbar, Context Menu, And Editor

```vue
<script setup>
import { ref } from "vue";
import { Gantt, Toolbar, ContextMenu, Editor } from "@svar-ui/vue-gantt";

const api = ref();
</script>

<template>
  <Toolbar :api="api" />

  <div class="gtcell">
    <ContextMenu :api="api">
      <Gantt ref="api" :tasks="tasks" :links="links" :scales="scales" undo />
    </ContextMenu>
    <Editor :api="api" />
  </div>
</template>

<style scoped>
.gtcell {
	height: calc(100% - 50px);
	border-top: var(--wx-gantt-border);
}
</style>
```

##### Initialize API And Handle Actions

```vue
<script setup>
import { ref } from "vue";
import { Gantt, Editor } from "@svar-ui/vue-gantt";

const api = ref();

function init(ganttApi) {
	api.value = ganttApi;

	api.value.on("add-task", ({ id }) => {
		api.value.exec("show-editor", { id });
	});

	api.value.intercept("sort-tasks", ev => {
		return ev.key === "text";
	});
}
</script>

<template>
  <Gantt
    :init="init"
    :tasks="tasks"
    :links="links"
    :onupdatetask="ev => console.log(ev.id, ev.task)"
  />
  <Editor :api="api" />
</template>
```

##### Custom Columns And Inline Editors

```vue
<script setup>
import { Gantt } from "@svar-ui/vue-gantt";
import AvatarCell from "./AvatarCell.vue";

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" },
];
</script>

<template>
  <Gantt :tasks="tasks" :links="links" :columns="columns" :cellHeight="40" />
</template>
```

##### Custom Task Content And Custom Event

```vue
<!-- TaskContent.vue -->
<script setup>
const props = defineProps({
  data: {},
  onaction: { type: Function },
});

function toggle(ev) {
	ev.stopPropagation();
	props.onaction?.({
		action: "custom-click",
		data: { id: props.data.id, clicked: !props.data.clicked },
	});
}
</script>

<template>
  <button :onclick="toggle">{{ props.data.clicked ? "Clicked" : "Click" }}</button>
</template>
```

```vue
<script setup>
import { ref } from "vue";
import { Gantt } from "@svar-ui/vue-gantt";
import TaskContent from "./TaskContent.vue";

const api = ref();
</script>

<template>
  <Gantt
    ref="api"
    :tasks="tasks"
    :links="links"
    :taskTemplate="TaskContent"
    :oncustomclick="ev =>
      api.exec('update-task', {
        id: ev.id,
        task: { clicked: ev.clicked },
      })"
  />
</template>
```

##### Custom Editor Items

```vue
<script setup>
import { ref } from "vue";
import {
	Gantt,
	Editor,
	getEditorItems,
	registerEditorItem,
	defaultTaskTypes,
} from "@svar-ui/vue-gantt";
import { RadioButtonGroup } from "@svar-ui/vue-core";

registerEditorItem("radio", RadioButtonGroup);

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 = ref();
</script>

<template>
  <Gantt ref="api" :tasks="tasks" :links="links" />
  <Editor :api="api" :items="items" placement="modal" :autoSave="false" />
</template>
```

##### Custom Menu Options

```vue
<script setup>
import { ref } from "vue";
import { Gantt, ContextMenu, Editor, getMenuOptions } from "@svar-ui/vue-gantt";

const api = ref();
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"),
	},
];
</script>

<template>
  <ContextMenu
    :api="api"
    :options="options"
    :onclick="({ context, action }) => console.log(context?.id, action?.id)"
  >
    <Gantt ref="api" :tasks="tasks" :links="links" />
  </ContextMenu>
  <Editor :api="api" />
</template>
```

##### Scales, Zoom, Markers, And Holidays

```vue
<script setup>
import { Gantt } from "@svar-ui/vue-gantt";

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" : "";
}
</script>

<template>
  <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
  />
</template>
```

##### Pro Feature Bundle

```vue
<script setup>
import { ref } from "vue";
import {
	Gantt,
	ContextMenu,
	Editor,
	Toolbar,
	Tooltip,
} from "@svar-ui/vue-gantt";
import { Calendar } from "@svar-ui/gantt-store";
import TooltipContent from "./TooltipContent.vue";

const calendar = new Calendar({
	weekHours: {
		monday: 8,
		tuesday: 8,
		wednesday: 8,
		thursday: 8,
		friday: 8,
		saturday: 0,
		sunday: 0,
	},
});

const api = ref();
</script>

<template>
  <Toolbar :api="api" />
  <div class="gtcell">
    <ContextMenu :api="api">
      <Tooltip :api="api" :content="TooltipContent">
        <Gantt
          ref="api"
          :tasks="tasks"
          :links="links"
          :calendar="calendar"
          baselines
          splitTasks
          :rollups="{ type: 'closest' }"
          :criticalPath="{ type: 'flexible' }"
          :summary="{ autoProgress: true }"
          undo
        />
      </Tooltip>
    </ContextMenu>
    <Editor :api="api" />
  </div>
</template>
```

##### Server Provider And Lazy Data

```vue
<script setup>
import { ref } from "vue";
import { Gantt, ContextMenu, Editor } from "@svar-ui/vue-gantt";
import { RestDataProvider } from "@svar-ui/gantt-data-provider";

const provider = new RestDataProvider("/api/gantt");
const api = ref();
const tasks = ref([]);
const links = ref([]);

provider.getData().then(data => {
	tasks.value = data.tasks;
	links.value = data.links;
});

function init(ganttApi) {
	api.value = ganttApi;
	api.value.setNext(provider);
	api.value.on("request-data", ev => {
		provider.getData(ev.id).then(data => {
			api.value.exec("provide-data", { id: ev.id, data });
		});
	});
}
</script>

<template>
  <ContextMenu :api="api">
    <Gantt :init="init" ref="api" :tasks="tasks" :links="links" />
  </ContextMenu>
  <Editor :api="api" />
</template>
```

#### 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 Vue Tasklist / @svar-ui/vue-tasklist components

#### Package

```js
import { Tasklist } from "@svar-ui/vue-tasklist";

import "@svar-ui/vue-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 bindable; 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 { Component } from "vue";

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: Component<{
	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`

```vue
<template>
  <div class="tasklist-panel">
    <Tasklist :value="tasks" />
  </div>
</template>

<style scoped>
.tasklist-panel {
	height: 420px;
	max-width: 768px;
	margin: 20px;
}

.tasklist-panel .wx-task {
	padding: 10px 0 6px;
}

.tasklist-panel .wx-list {
	gap: 2px;
}
</style>
```

#### Recipes

##### Basic Tasklist

```vue
<script setup>
import { Tasklist } from "@svar-ui/vue-tasklist";

const tasks = [
	{ id: 1, content: "Write project notes", status: 0 },
	{ id: 2, content: "Send status update", status: 1 },
];
</script>

<template>
  <div class="tasks">
    <Tasklist :value="tasks" />
  </div>
</template>

<style scoped>
.tasks {
	height: 360px;
	max-width: 768px;
}
</style>
```

##### Persist Changes

```vue
<script setup>
import { ref } from "vue";
import { Tasklist } from "@svar-ui/vue-tasklist";

const tasks = ref([]);

async function onchange(ev) {
	tasks.value = 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);
	}
}
</script>

<template>
  <Tasklist :value="tasks" :onchange="onchange" />
</template>
```

##### Resolve Data From A Key

```vue
<script setup>
import { ref } from "vue";
import { Tasklist } from "@svar-ui/vue-tasklist";

const listId = ref(1);
</script>

<template>
  <Tasklist
    :value="listId"
    :ondata="id => api.getTasks(id)"
    :onchange="({ action, task, id: taskId, originalValue }) =>
      api.saveTaskChange(originalValue, action, task, taskId)"
  />
</template>
```

##### Readonly List

```vue
<script setup>
import { Tasklist } from "@svar-ui/vue-tasklist";

const tasks = [{ id: 1, content: "Review release notes", status: 0 }];
</script>

<template>
  <Tasklist :value="tasks" :readonly="true" />
</template>
```


## File: comments/index.md

> Source: `comments/index.md`

Use when building, configuring, styling, localizing, or integrating SVAR Vue Comments / @svar-ui/vue-comments components

#### Package

```js
import { Comments, Willow, WillowDark } from "@svar-ui/vue-comments";
import "@svar-ui/vue-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/vue-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 bindable; 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 a `children` slot 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 { Component } from "vue";

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 = Component<{
	content: string;
}>;

export type RenderComponent = Component<{
	owned?: string | number;
	edit?: string | number;
	author: IUser;
	date: Date;
}>;

export declare const Comments: Component<{
	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: Component<{
	fonts?: boolean;
	children?: () => any;
}>;

export declare const WillowDark: Component<{
	fonts?: boolean;
	children?: () => any;
}>;
```

#### 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/vue-menu`
- package CSS variables: `--wx-comments-msg-background`, `--wx-comments-msg-background-agent`, `--wx-avatar-color-dark`

```vue
<template>
  <div class="comments-pane">
    <Comments :value="comments" :users="users" :activeUser="1" />
  </div>
</template>

<style scoped>
.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;
}
</style>
```

#### Recipes

##### Basic Comments

```vue
<script setup>
import { ref } from "vue";
import { Comments } from "@svar-ui/vue-comments";

const comments = ref([
	{ 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" },
];
</script>

<template>
  <Comments :value="comments" :users="users" :activeUser="1" :focus="true" />
</template>
```

##### Persist Changes

```vue
<script setup>
import { ref } from "vue";
import { Comments } from "@svar-ui/vue-comments";

const comments = ref([]);
const activeUser = { id: 1, name: "Alice Smith" };

async function saveChange(ev) {
	comments.value = 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);
	}
}
</script>

<template>
  <Comments :value="comments" :onchange="saveChange" :activeUser="activeUser" />
</template>
```

##### Load By External Key

```vue
<script setup>
import { ref } from "vue";
import { Comments } from "@svar-ui/vue-comments";

const pageId = ref(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);
}
</script>

<template>
  <Comments
    :value="pageId"
    :ondata="loadComments"
    :onchange="saveComment"
    :users="users"
    :activeUser="1"
  />
</template>
```

##### Switch Layout Or Markdown

```vue
<script setup>
import { ref } from "vue";
import { Comments } from "@svar-ui/vue-comments";

const render = ref("flow");
const comments = [
	{ id: 1, user: 1, content: "### Title\n\n**Markdown** text" },
];
const users = [{ id: 1, name: "Alice Smith" }];
</script>

<template>
  <Comments
    :value="comments"
    :users="users"
    :activeUser="1"
    :render="render"
    format="markdown"
  />
</template>
```

##### Custom Message And Content Renderers

```vue
<!-- MessageRenderer.vue -->
<script setup>
const props = defineProps({
  owned: {},
  author: {},
  date: {},
});
</script>

<template>
  <div :class="{ owned: props.owned }" style="padding-left: 8px">
    <b>{{ props.author.name }}</b>
    <span>{{ props.date.toLocaleString() }}</span>
    <slot />
  </div>
</template>
```

```vue
<!-- ContentRenderer.vue -->
<script setup>
const props = defineProps({ content: {} });
</script>

<template>
  <span class="content">{{ props.content.toUpperCase() }}</span>
</template>
```

```vue
<script setup>
import { Comments } from "@svar-ui/vue-comments";
import MessageRenderer from "./MessageRenderer.vue";
import ContentRenderer from "./ContentRenderer.vue";

const users = [{ id: 1, name: "Alice Smith" }];
const comments = [{ id: 1, user: 1, content: "Hello", date: new Date() }];
</script>

<template>
  <Comments
    :value="comments"
    :users="users"
    :activeUser="1"
    :render="MessageRenderer"
    :format="ContentRenderer"
  />
</template>
```

#### 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 Vue Filemanager / @svar-ui/vue-filemanager components, menus, themes, store actions, or backend data provider integration.

#### Package

```js
import {
	Filemanager,
	Willow,
	WillowDark,
	getMenuOptions,
} from "@svar-ui/vue-filemanager";

import "@svar-ui/vue-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/vue-core` themes and add filemanager CSS variables.
- Theme components accept `fonts?: boolean` and optional Vue children.
- `Filemanager` has no `children` slot, `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="api"` 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`, 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 { Component } from "vue";
import type { IMenuOption } from "@svar-ui/vue-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: Component<
	{
		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: Component<{
	fonts?: boolean;
	children?: () => any;
}>;

export declare const WillowDark: Component<{
	fonts?: boolean;
	children?: () => any;
}>;

/* get component events from store actions*/
type RemoveHyphen<S extends string> = S extends `${infer Head}-${infer Tail}`
	? `${Head}${RemoveHyphen<Tail>}`
	: S;

type EventName<K extends string> = `on${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/vue-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.

```vue
<template>
  <div class="filemanager">
    <Filemanager :data="data" :drive="drive" />
  </div>
</template>

<style scoped>
.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);
}
</style>
```

#### Recipes

##### Basic Filemanager

```vue
<script setup>
import { Filemanager, Willow } from "@svar-ui/vue-filemanager";

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,
};
</script>

<template>
  <Willow>
    <Filemanager :data="data" :drive="drive" />
  </Willow>
</template>
```

##### Initial Mode, Path, Selection, And Preview

```vue
<script setup>
import { Filemanager } from "@svar-ui/vue-filemanager";

const panels = [
	{ path: "/Code", selected: ["/Code/Button.js"] },
	{ path: "/", selected: ["/Music"] },
];
</script>

<template>
  <Filemanager
    :data="data"
    :drive="drive"
    mode="panels"
    :panels="panels"
    :activePanel="0"
    preview
  />
</template>
```

##### Handle API And Component Events

```vue
<script setup>
import { Filemanager } from "@svar-ui/vue-filemanager";

let api;
let saved = [];

function init(fm) {
	api = fm;

	api.on("download-file", ({ id }) => {
		window.open(`/download?id=${encodeURIComponent(id)}`, "_self");
	});

	api.on("open-file", ({ id }) => {
		window.open(`/direct?id=${encodeURIComponent(id)}`, "_blank");
	});
}

function serializeCode() {
	saved = api.serialize("/Code");
	api.exec("provide-data", { id: "/Code", data: [] });
}

function loadLazy({ id }) {
	fetch(`/files/${encodeURIComponent(id)}`)
		.then(res => res.json())
		.then(data => api.exec("provide-data", { id, data }));
}
</script>

<template>
  <button :onclick="serializeCode">Serialize /Code</button>

  <Filemanager
    ref="api"
    :init="init"
    :data="data"
    :drive="drive"
    :onrequestdata="loadLazy"
  />
</template>
```

##### Customize Context Menus

```vue
<script setup>
import { Filemanager, getMenuOptions } from "@svar-ui/vue-filemanager";

let api;

function init(fm) {
	api = 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 } = api.getState();
					api.exec("copy-files", {
						ids: [context.id],
						target: panels[activePanel].path,
					});
				},
			},
		];
	}

	return getMenuOptions(mode);
}
</script>

<template>
  <Filemanager :data="data" :drive="drive" :init="init" :menuOptions="menuOptions" />
</template>
```

##### Use Server Data And RestDataProvider

```vue
<script setup>
import { ref } from "vue";
import { Filemanager } from "@svar-ui/vue-filemanager";
import { RestDataProvider } from "@svar-ui/filemanager-data-provider";

const server = "https://example.com/api";
const provider = new RestDataProvider(server);

let api;
const data = ref([]);
const drive = ref({});

function init(fm) {
	api = fm;
	api.setNext(provider);

	api.on("download-file", ({ id }) => {
		window.open(`${server}/direct?id=${encodeURIComponent(id)}&download=true`, "_self");
	});

	api.on("open-file", ({ id }) => {
		window.open(`${server}/direct?id=${encodeURIComponent(id)}`, "_blank");
	});
}

function loadData({ id }) {
	provider.loadFiles(id).then(files => {
		api.exec("provide-data", { id, data: files });
	});
}

provider.on("file-renamed", ({ id, newId }) => {
	const name = newId.slice(newId.lastIndexOf("/") + 1);
	api.exec("rename-file", { id, name, skipProvider: true });
});

Promise.all([provider.loadFiles(), provider.loadInfo()]).then(([files, info]) => {
	data.value = files;
	drive.value = info;
});
</script>

<template>
  <Filemanager :init="init" :data="data" :drive="drive" :onrequestdata="loadData" />
</template>
```

##### Custom Icons, Previews, And Extra Info

```vue
<script setup>
import { Filemanager } from "@svar-ui/vue-filemanager";
import { formatSize } from "@svar-ui/filemanager-store";

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;
}
</script>

<template>
  <Filemanager :data="data" :drive="drive" :icons="icons" :previews="previews" :extraInfo="extraInfo" preview />
</template>
```

##### Backend Search Intercept

```vue
<script setup>
import { Filemanager } from "@svar-ui/vue-filemanager";

let api;

function init(fm) {
	api = fm;

	api.intercept("filter-files", ({ text }) => {
		const { panels, activePanel } = api.getState();
		const id = panels[activePanel].path;

		fetch(`/files/${encodeURIComponent(id)}?text=${text || ""}`)
			.then(res => res.json())
			.then(data => {
				api.exec("set-mode", { mode: text ? "search" : "cards" });
				api.exec("provide-data", { id, data });
			});

		return false;
	});
}
</script>

<template>
  <Filemanager :init="init" :data="data" :drive="drive" />
</template>
```

##### Localize Filemanager

```vue
<script setup>
import { Locale } from "@svar-ui/vue-core";
import { cn } from "@svar-ui/filemanager-locales";
import { cn as cnCore } from "@svar-ui/core-locales";
import { Filemanager } from "@svar-ui/vue-filemanager";
</script>

<template>
  <Locale :words="{ ...cn, ...cnCore }">
    <Filemanager :data="data" :drive="drive" />
  </Locale>
</template>
```

#### Implementation Notes

- `Filemanager.vue` 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.vue`; 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.