@appsbd/vue3-appsbd-ui 1.0.23 → 1.0.25

package/.ai/ai_ref_AbDropdownMenu.md

@@ -0,0 +1,89 @@
+# AbDropdownMenu — AI Reference
+
+A standalone dropdown **menu** (teleported to `body`). It has **no trigger of its own**: it attaches to whatever opens it — `AbButton`, `AbActionButton`, an icon, an avatar, any element. Build the menu from an `items` array (each item can have its own `onClick` and/or be reported via the `select` event) or put custom content in the default slot. Width: fixed via `width`, otherwise at least as wide as the element it is attached to (`matchWidth`) and never narrower than `minWidth`.
+
+## Installation
+
+Not globally registered — import explicitly.
+
+```js
+import { AbDropdownMenu } from "vue3-appsbd-ui";
+```
+
+## Usage
+
+Open it from the trigger through a template ref (`toggle($event)` anchors the menu to the clicked element):
+
+```vue
+<template>
+  <ab-button color="primary" @click="menu.toggle($event)">Actions</ab-button>
+  <ab-action-button action="edit" @action="(a, e) => menu.toggle(e)" />
+  <ab-dropdown-menu ref="menu" :items="items" @select="handle" />
+</template>
+
+<script setup>
+import { ref } from "vue";
+const menu = ref(null);
+const items = [
+  { label: "Edit", value: "edit", icon: Pencil },
+  { divider: true },
+  { label: "Delete", value: "delete", icon: Trash2, color: "danger", onClick: () => remove() },
+];
+</script>
+```
+
+`v-model` + `target` (element, component instance or CSS selector):
+
+```vue
+<ab-button id="more-btn" @click="open = !open">More</ab-button>
+<ab-dropdown-menu v-model="open" target="#more-btn" :items="items" />
+```
+
+Slot mode:
+
+```vue
+<ab-dropdown-menu ref="menu" :width="240">
+  <template #default="{ close }">
+    <div class="apbd-dropdown-header">Account</div>
+    <button type="button" class="apbd-dropdown-item" @click="profile(); close()">Profile</button>
+    <div class="apbd-dropdown-divider"></div>
+    <button type="button" class="apbd-dropdown-item apbd-dropdown-item-danger" @click="logout(); close()">Log out</button>
+  </template>
+</ab-dropdown-menu>
+```
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `modelValue` | `Boolean` | `false` | `v-model` open state. |
+| `target` | `Object \| String` | `null` | Element, component instance or CSS selector to attach to. Optional if `toggle($event)` / `show(el)` is used. |
+| `items` | `Array` | `[]` | `{ label, value?, icon?, color?, disabled?, show?, onClick?(item, event), children?, open? }`, `{ divider: true }` or `{ header: "Text" }`. `children` (same item shape, any depth) renders a collapsible sub tree like the sidebar (indent + vertical line + curved connectors); clicking the parent only toggles it (no `select`, menu stays open), `open: true` starts it expanded. `color` is a Bootstrap theme color name. `show: false` hides an item. Ignored when the default slot is used. |
+| `placement` | `String` | `"bottom-start"` | `bottom-end`, `top-start`, …; flips when out of room. |
+| `offset` | `Number \| String` | `4` | Gap (px) between the element and the menu. |
+| `width` | `Number \| String` | `null` | Fixed width (number = px). When unset, `minWidth` / `matchWidth` apply. |
+| `minWidth` | `Number \| String` | `160` | Minimum width when `width` is unset. |
+| `matchWidth` | `Boolean` | `true` | Menu at least as wide as the element it is attached to (ignored when `width` is set). |
+| `closeOnSelect` | `Boolean` | `true` | Close after an `items` entry is clicked. |
+| `closeOnClickOutside` | `Boolean` | `true` | Close on a click outside the menu and its anchor. `Esc` always closes. |
+| `contentClass` | `String` | `""` | Extra class on the menu element. |
+| `bordered` | `Boolean` | `false` | Separator line under every item except the last, edge to edge. |
+| `static` | `Boolean` | `false` | Render the menu inline where it is placed, always visible, instead of a popup (docs, sidebars, panels). |
+
+## Events
+
+| Event | Payload | Description |
+| --- | --- | --- |
+| `update:modelValue` | `Boolean` | Open state changed. |
+| `select` | `(value, item, event)` | `items` entry clicked; `value` = `item.value ?? item.label`. The item's `onClick` also runs. |
+| `show` / `hide` | — | Menu opened / closed. |
+
+## Slots
+
+| Name | Scope | Description |
+| --- | --- | --- |
+| `default` | `{ close }` | Custom menu content, replaces `items`. Style with `.apbd-dropdown-item` (+ `-danger` etc.), `.apbd-dropdown-divider`, `.apbd-dropdown-header`. |
+
+## Exposed
+
+`show(elementOrEvent?)`, `hide()`, `toggle(elementOrEvent?)` — the argument is the element to attach to (an element, component instance, selector or a DOM event, whose `currentTarget` is used).

package/.ai/ai_ref_AbFilterPanel.md

@@ -10,6 +10,12 @@ Standard-search, advance-search, and quick-advance field layouts are all plain f
 
 The standard-mode property-selector (and the scan field it swaps for) isn't part of `filterOptions` — it's not tied to one field, it lists all of them — so it has no `width`/`minWidth`/`maxWidth` key to set. It's also the only item in its row until a property is picked (or whenever `showScanFld` is on), so without sizing it it'll stretch to fill the row the same way an unsized `filterOptions` field would. Use the panel-level `propertySelectWidth`/`propertySelectMinWidth`/`propertySelectMaxWidth` props for that slot instead.
 
+## Variations (modes)
+
+Pick exactly one with `variant` (recommended): `"standard"` (property select + value input), `"single"`, `"advance"`, `"quick-advance"`, `"builder"`. `variant` overrides the legacy `isSingle` / `isAdvance` / `isQuickAdvance` / `isBuilderFilter` booleans, so mode props can never conflict. With no `variant` and none of those booleans, the panel is **standard**.
+
+Props that only apply to one variation: standard — `defaultFilterId`, `alwaysShowValueField`, `propertySelectWidth`/`MinWidth`/`MaxWidth`; standard & single — `canScan`, `scanProps`, `showScanFld`; single — `isAutoSearch`; advance — `advanceContainerClass`; quick-advance — `isQuickAdvanceAutoSearch`, `mobileBuilder` (on <768px quick-advance turns into the builder layout); builder — `isBuilderAutoSearch`. `isAllowed` and `showDrGroupText` are declared but currently unused. Props from another variation are ignored.
+
 ## Usage
 
 ```vue
@@ -41,7 +47,8 @@ function handleSearch(data) {
 
 | Name                       | Type      | Default         | Description                                                |
 | -------------------------- | --------- | --------------- | ---------------------------------------------------------- |
-| `isAdvance`                | `Boolean` | `false`         | Show all filters in an expanded layout.                    |
+| `variant`                  | `String`  | `undefined`     | Picks the variation: `"standard"` \| `"single"` \| `"advance"` \| `"quick-advance"` \| `"builder"`. When set, it **overrides** `isSingle` / `isAdvance` / `isQuickAdvance` / `isBuilderFilter` — only that variation is active and the other mode booleans are treated as `false`. When unset, the boolean props below decide (old behaviour; no mode prop set = standard). |
+| `isAdvance`                | `Boolean` | `false`         | Show all filters in an expanded layout. Ignored when `variant` is set. |
 | `isQuickAdvance`           | `Boolean` | `false`         | Quick advance mode.                                        |
 | `isBuilderFilter`          | `Boolean` | `false`         | Shopify-style "+" add-filter builder — see mode description above. |
 | `isBuilderAutoSearch`      | `Boolean` | `false`         | In `isBuilderFilter` mode, automatically fire `searchFilter` on Apply/Remove chip (no Search button). Default is `false` (shows Search button). |
@@ -55,12 +62,14 @@ function handleSearch(data) {
 | `showDrGroupText`          | `Boolean` | `true`          | Show date-range group label.                               |
 | `dateFormat`               | `String`  | `"MMM DD,YYYY"` | Date display format.                                       |
 | `isSearchable`             | `Boolean` | `false`         | Allow searching within option lists.                       |
+| `alwaysShowValueField`     | `Boolean` | `false`         | Standard mode only: show the value input even before a property is chosen (placeholder "Enter value", prefix "Value"; choosing a property swaps in that property's prefix/placeholder). Search stays disabled until both a property and a value are filled. |
 | `isMaxDate`                | `Boolean` | `true`          | Limit date pickers to today as max.                        |
 | `size`                     | `String`  | `"xs"`          | Control size.                                              |
 | `advanceContainerClass`    | `String`  | `""`            | Extra class on each field's flex-item wrapper in advance mode (base sizing is `flex: 1 1 240px`, wraps as needed — not a Bootstrap grid). To fix a single field's width instead, use that field's own `width` prop (`AbInputField`/`AbMultiSelect`/`AbDateTimePicker`). |
 | `propertySelectWidth`      | `String` \| `Number` | `undefined` | Width of the standard-mode property-selector / scan-field slot (number = px). Applied as `min(<value>, 100%)`, so it shrinks on small screens instead of overflowing. |
 | `propertySelectMinWidth`   | `String` \| `Number` | `undefined` | `min-width` of that same slot (same `min(<value>, 100%)` clamp). |
 | `propertySelectMaxWidth`   | `String` \| `Number` | `undefined` | `max-width` of that same slot — it's the only item in its row until a property is picked (or in scan mode), so it stretches to fill it without one (same `min(<value>, 100%)` clamp). |
+| `mobileBuilder`            | `Boolean` | `true`          | Quick-advance only: on screens narrower than 768px the panel renders as the builder filter (`+` button, chips, popover editor) using the same `filterOptions`; `isQuickAdvanceAutoSearch` then acts as the builder's auto-search. Wider screens, and every other variation, are unaffected. Set `false` to keep the quick layout on mobile. |
 | `isQuickAdvanceAutoSearch` | `Boolean` | `false`         | Fire search automatically on field change (quick advance). |
 | `defaultFilterId`          | `String` \| `Number` | `""` | Pre-selects a default filter property in standard search mode (when `!isSingle && !isAdvance && !isQuickAdvance`). |
 

package/.ai/ai_ref_AbInputField.md

@@ -131,6 +131,14 @@ Not a dedicated prop — pass the native `readonly` attribute (it falls through
 <ab-input-field v-model="accountId" name="account_id" label="Account ID" readonly />
 ```
 
+## Textarea mode
+
+Not a dedicated prop or component — pass the `as` attribute (it falls through to VeeValidate's `<Field>` via `$attrs`, like `disabled`/`readonly`). `as="textarea"` renders a native `<textarea>` instead of `<input>`, with the same label, `rules`, `hints`, `size`, prefix/postfix slots and validation error as a normal field. Other textarea attributes (`rows`, `cols`) fall through the same way; `type` is ignored by the textarea. `v-model` works unchanged.
+
+```vue
+<ab-input-field v-model="description" name="description" label="Description" as="textarea" rows="4" rules="required" />
+```
+
 ## Events
 
 | Event | Payload | Description |

package/.ai/ai_ref_AbMultiSelect.md

@@ -32,7 +32,7 @@ Searchable single/multi/tag select. Custom built-in replacement for `@vueform/mu
 | `maxWidth` | `String \| Number` | `undefined` | `max-width` on the wrapper `<div>` (same number/string rules as `width`, same `min(<value>, 100%)` clamp) — caps growth inside a flex/grid parent without a fixed `width`. |
 | `hints` | `String` | `""` | Helper text. |
 | `multiple` | `Boolean` | `false` | Deprecated — use `mode` instead. |
-| `searchable` | `Boolean` | `false` | Enable option search/filter. |
+| `searchable` | `Boolean` | `false` | Enable option search/filter (single mode; `tags`/`multiple` always have a search input). Filters `options` locally by label (case-insensitive) unless `isAjaxSearch` is set. Focusing the input does not open the dropdown — it opens on click, typing, `ArrowDown` or `Enter`. |
 | `mode` | `String` | `"single"` | `single`, `multiple`, or `tags`. |
 | `size` | `String` | `undefined` | Adjusts component size (`xs`, `sm`, `md`, `lg`, `xl`, `xxl`). |
 | `options` | `Array` | `[]` | Available options. |

package/.ai/ai_ref_AbSettingsForm.md

@@ -1,6 +1,6 @@
 # AbSettingsForm — AI Reference
 
-Composite settings-style form layout. When nested inside an `AbWizardStep`, auto-registers itself as the wizard step's validator — returning `false` from `onSubmit` blocks the wizard from advancing.
+Settings-style form wrapper around VeeValidate's `<Form>`. Runs the fields' validation rules first, then calls `onSubmit` with the form values. While `onSubmit` runs the form shows a sending state (`is_sending`: submit buttons disabled + spinner). When nested inside an `AbWizardStep`, it auto-registers itself as the wizard step's validator — returning `false` from `onSubmit` blocks the wizard from advancing.
 
 ## Usage
 
@@ -29,11 +29,32 @@ async function validateProfile(values) {
 </script>
 ```
 
+Standalone (no wizard) — submit with a `type="submit"` button:
+
+```vue
+<ab-settings-form :on-submit="save">
+  <ab-card body-class="apbd-loading-target">
+    <template #body>
+      <ab-input-field v-model="form.name" name="name" label="Name" rules="required" />
+    </template>
+    <template #footer>
+      <ab-button class="btn-primary" type="submit">Save</ab-button>
+    </template>
+  </ab-card>
+</ab-settings-form>
+```
+
 ## Props
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
-| `onSubmit` | `Function` | `() => {}` | Called with form values on submit. Return `false` (or throw) to block wizard progression. |
+| `onSubmit` | `Function` | `() => {}` | Called as `onSubmit(values)` (`values` = the VeeValidate form values keyed by field `name`) only after every field's `rules` pass. May be `async` — the sending state lasts until the returned Promise settles. In a wizard step, returning `false` or throwing blocks progression to the next step (a throw is also logged with `console.error`). Standalone, the return value is ignored. |
+
+## Behavior
+
+- **Validation first** — `onSubmit` never runs while any field is invalid (standalone: VeeValidate blocks the submit; in a wizard: the step validator checks `validate()` before calling it).
+- **Sending state** — while `onSubmit` runs the form gets the `apbd-form-sending` class: every `button[type=submit]` inside becomes non-clickable, semi-transparent and shows a spinner, and any `.apbd-loading-target` element gets an animated skeleton overlay (e.g. `AbCard` `body-class="apbd-loading-target"`). Fields themselves are not disabled. The class is removed when `onSubmit` finishes, even if it throws.
+- **Wizard background** — inside an `AbWizard` with a custom `backgroundColor`, the form becomes transparent (`apbd-settings-form-transparent`) so the wizard background shows through. Standalone, or with the default wizard background, nothing changes.
 
 ## Slots
 
@@ -43,4 +64,4 @@ async function validateProfile(values) {
 
 ## Notes
 
-Standalone use (outside a wizard) is supported — the component works as a plain VeeValidate `<Form>` wrapper.
+Standalone use (outside a wizard) is supported — the component works as a plain VeeValidate `<Form>` wrapper with the sending state above.

package/AI_REFERENCE.md

@@ -47,6 +47,7 @@
 | `AbSlider`                     |  —  | Single or range numeric slider.                                                                                        | [.ai/ai_ref_AbSlider.md](./.ai/ai_ref_AbSlider.md)                     |
 | `AbColorPicker`                |  —  | Radio-style color swatch picker.                                                                                       | [.ai/ai_ref_AbColorPicker.md](./.ai/ai_ref_AbColorPicker.md)           |
 | `AbColorChooser`               |  —  | Round color swatch that opens a color-picking popover (saturation area, hue/opacity sliders, hex input, eyedropper, contrast ratio, preset swatches). `v-model` is a hex string. | [.ai/ai_ref_AbColorChooser.md](./.ai/ai_ref_AbColorChooser.md)         |
+| `AbDropdownMenu`               |  —  | Standalone dropdown menu (no trigger) that attaches to any button/element via `menu.toggle($event)`, `v-model` + `target` — `items` array (per-item `onClick` + `select`) or default slot; fixed `width`, else matches the element width with a `minWidth`. | [.ai/ai_ref_AbDropdownMenu.md](./.ai/ai_ref_AbDropdownMenu.md)         |
 | `AbFileUploader`               |  —  | File upload field with size validation; image mode (default, preview) or file mode (`allowedTypes` + extension icons); `variant="dropzone"` for a large icon/title/description/button card with drag & drop. | [.ai/ai_ref_AbFileUploader.md](./.ai/ai_ref_AbFileUploader.md)         |
 | `AbFilterPanel`                |  —  | Advanced filter panel with search and scan modes.                                                                      | [.ai/ai_ref_AbFilterPanel.md](./.ai/ai_ref_AbFilterPanel.md)           |
 | `AbSettingsForm`               |  —  | Settings-style form that auto-registers as a wizard step validator.                                                    | [.ai/ai_ref_AbSettingsForm.md](./.ai/ai_ref_AbSettingsForm.md)         |

package/CHANGELOG.md

@@ -2,7 +2,32 @@
 
 All notable changes to `@appsbd/vue3-appsbd-ui` are documented here. Format loosely follows [Keep a Changelog](https://keepachangelog.com/).
 
-## [1.0.23] - Unreleased
+## [1.0.25] - Unreleased
+
+- **Added**: `AbDropdownMenu` item `children` (+ optional `open`) — an item can now have sub items rendered as a collapsible sidebar-style tree (indented, vertical line with curved connectors, rotating chevron), nested to any depth. Clicking a parent only expands/collapses it (no `select`, menu stays open); leaf items behave as before. See `.ai/ai_ref_AbDropdownMenu.md`.
+- **Added**: `AbFilterPanel` `alwaysShowValueField` (`Boolean`, default `false`) — standard-mode variation that shows both the property select and the value input from the start (before, the value input only appeared after a property was chosen). Choosing a property swaps the value input's prefix/placeholder to that property's; Search is disabled until both fields have data. See `.ai/ai_ref_AbFilterPanel.md`.
+- **Added**: `AbFilterPanel` `variant` (`"standard"` | `"single"` | `"advance"` | `"quick-advance"` | `"builder"`, default unset) — picks the variation with one prop. When set it overrides `isSingle` / `isAdvance` / `isQuickAdvance` / `isBuilderFilter`, so only that variation is active and the other mode booleans are forced off. The boolean props still work unchanged when `variant` is unset. See `.ai/ai_ref_AbFilterPanel.md`.
+- **Added**: `AbFilterPanel` `mobileBuilder` (`Boolean`, default `true`) — in quick-advance mode, screens narrower than 768px now render the builder filter (`+` button, chips, popover editor) from the same `filterOptions`; `isQuickAdvanceAutoSearch` acts as its auto-search and fields that already have a value show as chips. Wider screens and every other variation are unchanged. Set `:mobile-builder="false"` to keep the quick layout on mobile. See `.ai/ai_ref_AbFilterPanel.md`.
+- **Docs**: `AbFilterPanel` playground page — a sizes example (`xs` … `xxl`, with full code) for every variation: Standard (existing "Sizes"), Single, Advance, Quick Advance and Builder Filter.
+- **Fixed**: `AbFilterPanel` builder filter — on narrow screens a long value (e.g. a "Date Between" range like `২৪/১০/২০২৬ ↔ ২৬/১০/২০২৬`) was cut off inside the popover's input. The input's font size now shrinks automatically (down to 9px) only when the text doesn't fit, and returns to normal when it does.
+- **Fixed**: `AbPopover` — when the popover's content changed size after opening (e.g. the `AbFilterPanel` builder popover switching from the property list to the wider value editor), it was not repositioned and could run off the right edge of a mobile screen. It now re-measures whenever its content resizes, and keeps itself inside the visible viewport width (scrollbar excluded).
+- **Fixed**: `AbFilterPanel` builder filter — the `+` (add filter) button now matches the height of the chips, Search/Reset buttons and inputs for every `size` (it stays square).
+- **Fixed**: `AbSettingsForm` — `onSubmit` was called with no arguments (both standalone and inside an `AbWizardStep`), so `onSubmit(values)` always got `undefined`. It now receives the form values. Standalone, `is_sending` is also reset if `onSubmit` throws (before, the form stayed in its sending state). See `.ai/ai_ref_AbSettingsForm.md`.
+- **Fixed**: `AbSettingsForm` — the component's internal `name` was `AbForm`; it is now `AbSettingsForm`, so Vue devtools and `<KeepAlive include="AbSettingsForm">` match its real name.
+- **Docs**: `AbSettingsForm` playground page — new "Submitted Values" and "Inside a Wizard" examples (live preview + full code), the Simple Example code is now `v-pre`, and the Usage code is properly indented and uses `onSubmit(values)`.
+- **Docs**: `AbSettingsForm` AI reference and playground API table — `onSubmit(values)`, async handling, the sending state (`apbd-form-sending` / `.apbd-loading-target`), wizard blocking on `false`/throw, and the wizard background override.
+- **Docs**: `AbInputField` AI reference — documented that passing `as="textarea"` renders a native `<textarea>` (with the same label, rules, hints and validation; `rows`/`cols` fall through). See `.ai/ai_ref_AbInputField.md`.
+
+## [1.0.24] - 2026-10-27
+
+- **Added**: `AbDropdownMenu` component — a standalone dropdown menu (no trigger of its own) that attaches to whatever opens it: an `AbButton`, `AbActionButton`, an icon, an avatar, any element. Open it from the trigger with `menu.toggle($event)` / `menu.show(elementOrEvent)` / `menu.hide()` (template ref), with `v-model` plus a `target` (element, component instance or CSS selector). Build the menu from an `items` array (`{ label, value?, icon?, color?, disabled?, show?, onClick? }`, `{ divider: true }`, `{ header }`; reported through `select` and/or each item's `onClick`) or put anything in the default slot (`{ close }`; style with `.apbd-dropdown-item` / `-divider` / `-header`). Width: fixed with `width`, otherwise at least as wide as the element it is attached to (`matchWidth`, default `true`) and never narrower than `minWidth` (default `160`). Closes on item click (`closeOnSelect`), outside click (`closeOnClickOutside`) and `Esc`. Also `placement` (default `"bottom-start"`), `offset`, `contentClass`, `bordered` (a separator line under every item except the last), and `static` (render the menu inline, always visible, instead of a popup). See `.ai/ai_ref_AbDropdownMenu.md`.
+- **Fixed**: `AbMultiSelect` — focusing the search input (Tab key, a label, or code such as modal autofocus) no longer opens the dropdown by itself. Previously the next click on the field hit the open/close toggle and closed it, so the dropdown looked like it would not open. It now opens on click, typing, `ArrowDown` or `Enter`, like the rest of the keyboard handling. See `.ai/ai_ref_AbMultiSelect.md`.
+- **Fixed**: `AbMultiSelect` `mode="tags"` / `"multiple"` — picking an option closed the dropdown (the picked option is removed from the list by `hideSelected`, and the outside-click check then treated the click as outside). The dropdown now stays open so several options can be picked in a row.
+- **Docs**: playground pages — every example now has its live preview and its exact full code (`<script setup>` + `<template>`) together. `AbSidebar` gets a dedicated live "Submenus" section (and `popoverTrigger` in its API table) with Installation/Usage right under the first preview; `AbConfirmPopover`, `AbFormCheck` (Card Width, Custom Check Icon, Pill Variant), `AbTabs` (one code block per variant), `AbCustomField`, `AbProgressbar`, `AbToggle`, `AbBottomNav`, `useResponsive`, `AbModal` and `AbWizard` got the missing live previews / code blocks; code samples that contain `{{ }}` no longer get evaluated by Vue.
+- **Docs**: `AbMainLayout` playground page — new "Body Header & Footer" (`#bodyHeader` / `#bodyFooter`), "Elevated Variation" (`variation="elevated"` without `gradient`) and "Bottom Navigation" (`bottom-nav` + `#bottomNav`) examples.
+- **Docs**: `AbMultiSelect` playground page — new "Searchable" section showing local (non-ajax) search in `single`, `tags` and `multiple` modes.
+
+## [1.0.23] - 2026-10-20
 
 - **Fixed**: `AbCard` — `bgColorVariant` / `borderBottomVariant` default `""` failed their own validators, so every card that didn't set them logged `[Vue warn]: Invalid prop: custom validator check failed`. The validators now accept `""`.
 - **Fixed**: `AbInputField` — `update:modelValue` on input sent the whole `InputEvent` instead of the field's value (the `input` event already sent the value). It now sends `event.target.value`.