addon-stack · atldays · Mar 13, 2026 · Feb 4, 2026 · Mar 12, 2026 · Mar 12, 2026
diff --git a/README.md b/README.md
@@ -68,15 +68,18 @@ This library now ships with dedicated documentation files for each component in
 - [List](docs/List.md) (covers List and ListItem)
 - [Modal](docs/Modal.md)
 - [Odometer](docs/Odometer.md) (component + `useOdometer` hook)
+- [Popover](docs/Popover.md)
 - [ScrollArea](docs/ScrollArea.md)
 - [Select](docs/Select.md)
+- [Shift](docs/Shift.md)
 - [SvgSprite](docs/SvgSprite.md)
 - [Switch](docs/Switch.md)
 - [Tabs](docs/Tabs.md) (includes `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`)
 - [Tag](docs/Tag.md)
 - [TextArea](docs/TextArea.md)
 - [TextField](docs/TextField.md)
 - [Toast](docs/Toast.md)
+- [ToggleGroup](docs/ToggleGroup.md)
 - [Tooltip](docs/Tooltip.md)
 - [Truncate](docs/Truncate.md)
 - [TruncateList](docs/TruncateList.md)

diff --git a/docs/Popover.md b/docs/Popover.md
@@ -0,0 +1,136 @@
+### Popover
+
+Documentation for the Popover component and its subcomponents: Popover, PopoverTrigger, PopoverContent, PopoverAnchor, PopoverClose. The implementation is built on top of `@radix-ui/react-popover` and adds visual features, support for global configuration, and additional props.
+
+See the official Radix documentation: https://www.radix-ui.com/primitives/docs/components/popover
+
+#### Import
+
+```ts
+import {Popover, PopoverTrigger, PopoverContent, PopoverAnchor, PopoverClose} from "addon-ui";
+```
+
+#### Basic usage
+
+```tsx
+<Popover>
+    <PopoverTrigger>Open Popover</PopoverTrigger>
+    <PopoverContent arrow>
+        <p>Popover content goes here.</p>
+        <PopoverClose>Close</PopoverClose>
+    </PopoverContent>
+</Popover>
+```
+
+---
+
+#### Props: Popover (Root)
+
+Only the prop name, type, and default are listed below.
+
+| Prop             | Type                          | Default |
+| ---------------- | ----------------------------- | ------- |
+| `defaultOpen`    | `boolean`                     | —       |
+| `open`           | `boolean`                     | —       |
+| `onOpenChange`   | `(open: boolean) => void`     | —       |
+| `modal`          | `boolean`                     | —       |
+| Radix Root props | all `PopoverProps` from Radix | —       |
+
+Supports contextual props via the UI provider: `useComponentProps("popover")`.
+
+#### Props: PopoverTrigger
+
+| Prop                | Type                      | Default |
+| ------------------- | ------------------------- | ------- |
+| `center`            | `boolean`                 | `false` |
+| Radix Trigger props | all `PopoverTriggerProps` | —       |
+
+Supports contextual props: `useComponentProps("popoverTrigger")`.
+
+#### Props: PopoverContent
+
+| Prop                | Type                      | Default |
+| ------------------- | ------------------------- | ------- |
+| `maxWidth`          | `number`                  | —       |
+| `minWidth`          | `number`                  | —       |
+| `fullWidth`         | `boolean`                 | —       |
+| `arrow`             | `boolean`                 | —       |
+| `arrowWidth`        | `number`                  | —       |
+| `arrowHeight`       | `number`                  | —       |
+| `overlay`           | `boolean`                 | —       |
+| `overlayClassname`  | `string`                  | —       |
+| `container`         | `HTMLElement`             | —       |
+| Radix Content props | all `PopoverContentProps` | —       |
+
+Supports contextual props: `useComponentProps("popoverContent")`.
+
+#### Props: PopoverAnchor
+
+| Prop               | Type                     | Default |
+| ------------------ | ------------------------ | ------- |
+| Radix Anchor props | all `PopoverAnchorProps` | —       |
+
+Supports contextual props: `useComponentProps("popoverAnchor")`.
+
+#### Props: PopoverClose
+
+| Prop              | Type                    | Default |
+| ----------------- | ----------------------- | ------- |
+| Radix Close props | all `PopoverCloseProps` | —       |
+
+Supports contextual props: `useComponentProps("popoverClose")`.
+
+---
+
+### CSS variables for Popover
+
+Only variables actually referenced in `src/components/Popover/popover.module.scss` are listed, with their exact fallback chains.
+
+| Variable                                | Fallback chain                                                                                        |
+| :-------------------------------------- | :---------------------------------------------------------------------------------------------------- |
+| `--popover-overlay-bg`                  | `var(--popover-overlay-bg, var(--overlay-bg, rgba(0, 0, 0, 0.5)))`                                    |
+| `--popover-trigger-color`               | none (define in theme)                                                                                |
+| `--popover-trigger-bg-color`            | `var(--popover-trigger-bg-color, var(--bg-secondary-color))`                                          |
+| `--popover-trigger-shadow-offset`       | none (define in theme)                                                                                |
+| `--popover-trigger-shadow-color`        | none (define in theme)                                                                                |
+| `--popover-trigger-border-width`        | `var(--popover-trigger-border-width, 1px)`                                                            |
+| `--popover-trigger-border-style`        | `var(--popover-trigger-border-style, solid)`                                                          |
+| `--popover-trigger-border-color`        | `var(--popover-trigger-border-color, var(--border-color))`                                            |
+| `--popover-trigger-border-radius`       | `var(--popover-trigger-border-radius, 10px)`                                                          |
+| `--popover-trigger-font-size`           | `var(--popover-trigger-font-size, var(--popover-font-size, 14px))`                                    |
+| `--popover-trigger-font-weight`         | `var(--popover-trigger-font-weight, 500)`                                                             |
+| `--popover-trigger-padding`             | `var(--popover-trigger-padding, 8px 12px)`                                                            |
+| `--popover-trigger-height`              | none (define in theme)                                                                                |
+| `--popover-trigger-gap`                 | `var(--popover-trigger-gap, 5px)`                                                                     |
+| `--popover-trigger-shadow-offset-hover` | none (define in theme)                                                                                |
+| `--popover-trigger-border-width-hover`  | `var(--popover-trigger-border-width-hover, var(--popover-trigger-border-width, 1px))`                 |
+| `--popover-trigger-border-color-hover`  | `var(--popover-trigger-border-color-hover, var(--popover-trigger-border-color, var(--border-color)))` |
+| `--popover-content-padding`             | `var(--popover-content-padding, 16px)`                                                                |
+| `--popover-content-bg-color`            | `var(--popover-content-bg-color, var(--bg-primary-color))`                                            |
+| `--popover-content-border-radius`       | `var(--popover-content-border-radius, 8px)`                                                           |
+| `--popover-content-shadow-offset`       | `var(--popover-content-shadow-offset, 0 0 5px 0)`                                                     |
+| `--popover-content-shadow-color`        | `var(--popover-content-shadow-color, rgba(0, 0, 0, 0.25))`                                            |
+| `--popover-content-height`              | none (define in theme)                                                                                |
+| `--popover-content-max-height`          | `var(--popover-content-max-height, var(--radix-popover-content-available-height))`                    |
+| `--popover-content-full-width`          | `var(--popover-content-full-width, var(--radix-popover-content-available-width))`                     |
+| `--popover-arrow-bg-color`              | `var(--popover-arrow-bg-color, var(--popover-content-bg-color, var(--bg-primary-color)))`             |
+| `--popover-speed-color`                 | `var(--popover-speed-color, var(--speed-color))`                                                      |
+| `--popover-speed-background`            | `var(--popover-speed-background, var(--speed-color))`                                                 |
+| `--popover-speed-shadow`                | `var(--popover-speed-shadow, var(--speed-color))`                                                     |
+| `--popover-speed-border-color`          | `var(--popover-speed-border-color, var(--speed-color))`                                               |
+
+---
+
+### Accessibility (A11y)
+
+Components inherit behavior and ARIA attributes from Radix Popover: keyboard navigation, correct roles, and states. It adheres to the [WAI-ARIA Popover Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/popover/).
+
+Useful: https://www.radix-ui.com/primitives/docs/components/popover
+
+---
+
+### Usage notes
+
+- The component supports global configuration via `ui.config.ts`.
+- `PopoverContent` can be customized with `arrow`, `fullWidth`, and `overlay` props.
+- `PopoverTrigger` supports `center` alignment.
diff --git a/docs/Select.md b/docs/Select.md
@@ -1,13 +1,22 @@
 ### Select
 
-Documentation for the Select component and its subcomponents: Select, SelectTrigger, SelectContent, SelectItem. The implementation is built on top of `@radix-ui/react-select` and adds visual features, support for localization (RTL), and global configuration.
+Documentation for the Select component and its subcomponents: Select, SelectTrigger, SelectContent, SelectItem, SelectItemText, SelectItemIndicator, SelectIcon, SelectValue. The implementation is built on top of `@radix-ui/react-select` and adds visual features, support for localization (RTL), and global configuration.
 
 See the official Radix documentation: https://www.radix-ui.com/primitives/docs/components/select
 
 #### Import
 
 ```ts
-import {Select, SelectTrigger, SelectContent, SelectItem} from "addon-ui";
+import {
+    Select,
+    SelectTrigger,
+    SelectContent,
+    SelectItem,
+    SelectItemText,
+    SelectItemIndicator,
+    SelectIcon,
+    SelectValue,
+} from "addon-ui";
 ```
 
 #### Basic usage
@@ -61,17 +70,18 @@ Supports contextual props: `useComponentProps("selectTrigger")`.
 
 #### Props: SelectContent
 
-| Prop                | Type                     | Default |
-| ------------------- | ------------------------ | ------- |
-| `arrow`             | `boolean`                | —       |
-| `arrowWidth`        | `number`                 | —       |
-| `arrowHeight`       | `number`                 | —       |
-| `fullWidth`         | `boolean`                | —       |
-| `viewportProps`     | `SelectViewportProps`    | —       |
-| `scrollUpButton`    | `ReactNode`              | —       |
-| `scrollDownButton`  | `ReactNode`              | —       |
-| `container`         | `HTMLElement`            | —       |
-| Radix Content props | all `SelectContentProps` | —       |
+| Prop                | Type                         | Default    |
+| ------------------- | ---------------------------- | ---------- |
+| `arrow`             | `boolean`                    | —          |
+| `arrowWidth`        | `number`                     | —          |
+| `arrowHeight`       | `number`                     | —          |
+| `fullWidth`         | `boolean`                    | `true`     |
+| `position`          | `"popper" \| "item-aligned"` | `"popper"` |
+| `viewportProps`     | `SelectViewportProps`        | —          |
+| `scrollUpButton`    | `ReactNode`                  | —          |
+| `scrollDownButton`  | `ReactNode`                  | —          |
+| `container`         | `HTMLElement`                | —          |
+| Radix Content props | all `SelectContentProps`     | —          |
 
 Supports contextual props: `useComponentProps("selectContent")`.
 
@@ -87,6 +97,14 @@ Supports contextual props: `useComponentProps("selectContent")`.
 
 Supports contextual props: `useComponentProps("selectItem")`.
 
+#### Props: SelectItemText, SelectItemIndicator, SelectIcon, SelectValue
+
+These components are wrappers around Radix UI primitives and do not have additional custom props.
+
+| Prop        | Type                          | Default |
+| ----------- | ----------------------------- | ------- |
+| Radix props | all corresponding Radix props | —       |
+
 ---
 
 ### CSS variables for Select
@@ -108,6 +126,7 @@ Only variables actually referenced in `src/components/Select/select.module.scss`
 | `--select-trigger-padding`             | `var(--select-trigger-padding, 8px 12px)`                                                           |
 | `--select-trigger-height`              | none (define in theme)                                                                              |
 | `--select-trigger-gap`                 | `var(--select-trigger-gap, 5px)`                                                                    |
+| `--select-placeholder-color`           | `var(--select-placeholder-color, var(--placeholder-color))`                                         |
 | `--select-trigger-shadow-offset-hover` | none (define in theme)                                                                              |
 | `--select-trigger-border-width-hover`  | `var(--select-trigger-border-width-hover, var(--select-trigger-border-width, 1px))`                 |
 | `--select-trigger-border-color-hover`  | `var(--select-trigger-border-color-hover, var(--select-trigger-border-color, var(--border-color)))` |
@@ -138,6 +157,7 @@ Only variables actually referenced in `src/components/Select/select.module.scss`
 | `--select-scroll-btn-bg-color`         | `var(--select-scroll-btn-bg-color, var(--select-content-bg-color, var(--bg-primary-color)))`        |
 | `--select-scroll-btn-cursor`           | `var(--select-scroll-btn-cursor, default)`                                                          |
 | `--select-scroll-btn-hover-bg-color`   | `var(--select-scroll-btn-hover-bg-color, var(--bg-secondary-color))`                                |
+| `--select-arrow-bg-color`              | `var(--select-arrow-bg-color, var(--select-content-bg-color, var(--bg-primary-color)))`             |
 
 ---
 

diff --git a/docs/Shift.md b/docs/Shift.md
@@ -0,0 +1,75 @@
+### Shift
+
+The `Shift` component is a container designed for smooth vertical transitions between multiple children. It is useful for building multi-step forms, tab-like switching, or replacing UI elements with a sliding effect.
+
+#### Import
+
+```ts
+import {Shift} from "addon-ui";
+```
+
+#### Basic usage
+
+```tsx
+const [step, setStep] = useState(1);
+
+<Shift active={step} adaptiveHeight>
+    <div>
+        <h2>Step 1</h2>
+        <p>First step content</p>
+        <button onClick={() => setStep(2)}>Next</button>
+    </div>
+    <div>
+        <h2>Step 2</h2>
+        <p>Second step content</p>
+        <button onClick={() => setStep(1)}>Back</button>
+    </div>
+</Shift>;
+```
+
+---
+
+#### Props: Shift
+
+Only the prop name, type, and default are listed below.
+
+| Prop             | Type                       | Default |
+| ---------------- | -------------------------- | ------- |
+| `active`         | `number`                   | `1`     |
+| `height`         | `number`                   | —       |
+| `adaptiveHeight` | `boolean`                  | `true`  |
+| `itemClassName`  | `string`                   | —       |
+| —                | all `HTMLDivElement` props | —       |
+
+#### Notes on props:
+
+- `active`: A 1-based index (1, 2, 3...) that determines which child is currently visible.
+- `height`: Fixed height for the container. If provided, `adaptiveHeight` behavior is effectively overridden.
+- `adaptiveHeight`: If `true`, the container automatically adjusts its height to match the current child's height with a smooth transition.
+
+---
+
+### CSS variables for Shift
+
+The following variables are used in `src/components/Shift/shift.module.scss` to control the transition animations.
+
+| Variable                  | Fallback chain                                  |
+| :------------------------ | :---------------------------------------------- |
+| `--shift-speed-height`    | `var(--shift-speed-height, var(--speed-sm))`    |
+| `--shift-speed-transform` | `var(--shift-speed-transform, var(--speed-sm))` |
+| `--shift-speed-opacity`   | `var(--shift-speed-opacity, var(--speed-sm))`   |
+
+---
+
+### Accessibility (A11y)
+
+`Shift` is a layout-oriented component and does not provide specific ARIA roles or keyboard interactions by itself. Ensure that the children inside `Shift` are accessible. When switching the `active` index, consider using ARIA live regions or manual focus management if the context changes significantly for screen reader users.
+
+---
+
+### Usage notes
+
+- Each child of the `Shift` component is wrapped in an absolute-positioned container to allow smooth transitions.
+- If a child is not a valid React element (e.g., a string or number), it is automatically wrapped in a `<span>`.
+- `adaptiveHeight` is enabled by default, which is recommended when children have varying heights to ensure a smooth layout experience.
+- The component uses `translate3d` and `opacity` for high-performance animations.