@salesql/sql_components_vue3 2.1.1 → 3.1.0

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @salesql/sql_components_vue3 — SalesQL Design System (v2.1.1)
+# @salesql/sql_components_vue3 — SalesQL Design System (v3.1.0)
 
 > Librería de componentes Vue 3 (SalesQL) Presentational-only Vue 3 components (props in, events out; the consuming app owns state, i18n and data). This file is auto-generated from the component stories for LLM/agent consumption — do not edit by hand.
 
@@ -11,7 +11,7 @@ import '@salesql/sql_components_vue3/dist/style.css'; // once, at app entry
 
 All components are named exports with the `Ds` prefix. Variant constants and TypeScript types ship alongside each component (e.g. `DS_BUTTON_VARIANTS`, `DsButtonVariant`). Components never fetch data or hold app state — drive them with props and listen to their events.
 
-## Components (30)
+## Components (32)
 
 - **DsAvatar** (Core) — Contact/user avatar: an image, generated initials with a deterministic color hash, or an
 - **DsBadge** (Core) — Solid, white-text pill for value types and counts (e.g. "Work", "New"). **Presentational
@@ -43,6 +43,8 @@ All components are named exports with the `Ds` prefix. Variant constants and Typ
 - **DsTextarea** (Forms) — Multi-line text field — the DS "Textarea", sibling of `DsInput` with the same
 - **DsMenuItem** (Navigation) — Sidebar navigation row: an icon with an optional label, usable full-width or collapsed to
 - **DsWizardStepper** (Navigation) — Numbered multi-step flow: a row of step chips (completed / active / incomplete / neutral)
+- **DsDrawer** (Overlays) — Side panel over a backdrop. Built **native** — no `element-plus` — so the Vue 2 twin
+- **DsPopover** (Overlays) — Click-triggered card panel anchored to a trigger. Built **native** — no `element-plus`,
 
 ---
 <!-- DsAvatar · Core -->
@@ -1348,3 +1350,166 @@ the current step (`value`) and the button copy.
   user needs to see progress and jump back to prior steps.
 - For a non-linear sidebar/rail instead, use `DsMenuItem`; for an unlabeled
   percentage/quota breakdown use `DsSegmentedProgressBar`.
+
+---
+
+<!-- DsDrawer · Overlays -->
+
+## DsDrawer
+
+Side panel over a backdrop. Built **native** — no `element-plus` — so the Vue 2 twin
+(`@salesql/sql_components`, for `front` and `extension-lite`) can replicate the same API
+and markup; Element Plus is Vue 3 only (SALESQL-3968).
+
+Everything `el-drawer` used to give for free is carried here: portal to `body`, backdrop,
+enter/leave transition, Escape, body scroll lock, **focus trap + focus restoration**,
+cancelable `before-close`, and an edge dragger clamped **during** the drag.
+
+**Presentational only**: it never closes itself — the consumer holds `open` and flips it
+off on `close`. It never stores a width either — it clamps and emits; persisting is the
+consumer's job (frontend-app's `usePersistedWidth`).
+
+### Props
+
+| Prop             | Type                    | Default   | Description                                                                       |
+| ---------------- | ----------------------- | --------- | --------------------------------------------------------------------------------- |
+| `open`           | `boolean`               | `false`   | Controls visibility.                                                              |
+| `title`          | `string`                | `''`      | Header text; shows the header row (with `showClose`).                             |
+| `showClose`      | `boolean`               | `true`    | Show the icon-only × close button.                                                |
+| `closeLabel`     | `string`                | `'Close'` | `aria-label` for the × button.                                                    |
+| `direction`      | `'rtl' \| 'ltr'`        | `'rtl'`   | Edge the panel is pinned to. `rtl` = right (ring on its left border).             |
+| `width`          | `number`                | `440`     | Panel width in **px**. 440 is the frozen contract's value (SALESQL-3548).         |
+| `resizable`      | `boolean`               | `false`   | Enable the edge dragger.                                                          |
+| `minWidth`       | `number`                | `360`     | Lower bound, enforced **during** the drag.                                        |
+| `maxWidth`       | `number`                | `720`     | Upper bound, enforced **during** the drag.                                        |
+| `closeOnOverlay` | `boolean`               | `true`    | Clicking the backdrop requests a close.                                           |
+| `closeOnEscape`  | `boolean`               | `true`    | Escape requests a close.                                                          |
+| `beforeClose`    | `() => boolean \| void` | `null`    | Return `false` (or a promise of it) to **cancel** the close — gates every path.   |
+| `fixed`          | `boolean`               | `true`    | `false` renders in-flow (no portal / backdrop / scroll lock), for specimen cards. |
+
+### Slots
+
+| Slot     | Description                                              |
+| -------- | -------------------------------------------------------- |
+| default  | Panel body.                                              |
+| `header` | Replaces the default title element (the × button stays). |
+| `footer` | Optional action row; omitted entirely when not provided. |
+
+### Events
+
+| Event          | Payload         | When                                                                 |
+| -------------- | --------------- | -------------------------------------------------------------------- |
+| `close`        | —               | ×, backdrop or Escape — **after** `beforeClose` allowed it.          |
+| `resize-start` | `width: number` | Drag began.                                                          |
+| `resize`       | `width: number` | Every move while dragging, already clamped to `minWidth`/`maxWidth`. |
+| `resize-end`   | `width: number` | Drag released, final clamped width.                                  |
+
+A consumer that only wants to store the result listens to `resize-end` alone:
+
+```vue
+<DsDrawer :width="width" resizable :min-width="360" :max-width="720" @resize-end="setWidth" />
+```
+
+### Accessibility
+
+- `role="dialog"` + `aria-modal="true"` in portal mode.
+- `aria-labelledby` points at the visible title; a custom `#header` falls back to
+  `aria-label="drawer"` rather than referencing a node that no longer exists.
+- **Focus trap**: Tab from the last control returns to the first, Shift+Tab from the first
+  goes to the last, and with nothing focusable inside, Tab cannot reach the page behind
+  the overlay. Focus moves into the panel on open and **restores to the opener** on close.
+- Body scroll locks while a fixed/open drawer is mounted.
+- The dragger is `aria-hidden` — it is a pointer affordance, not a control to land on.
+
+### Chrome
+
+**Header — from the DS, not from the app.** 48px tall, title left-aligned at body size and
+bold (`slate-main`), truncating with an ellipsis, `slate-tint` hairline underneath, and the
+control cluster at the trailing edge.
+
+frontend-app's `el-drawer.scss` override had drifted from the DS on five counts — 50px,
+centred title, 16px, a 24px inset and `slate-shadow`. `DESIGN-SYSTEM.md` makes the DS the
+only style authority and forbids taking values from a consuming app, so the DS wins:
+**the full profile will look different once it adopts this**, by design.
+
+Residual deltas, reconciled onto the 8px grid instead of copied off-grid: the DS's
+`0 14px 0 16px` inset becomes a symmetric 16px, and its 10px gap becomes 12px.
+
+**Header controls.** The close is a bare glyph (20px, `slate-main`) with **no hover
+surface** — it is a plain icon in the DS, not a filled button. It stays a real `<button>`
+with an `aria-label` and a focus-visible ring, which the DS's `<span onClick>` is not.
+`#actions` renders before it in the softer `slate-soft`, glyphs at 18px.
+
+**Surfaces.** The panel is the grey surface (`slate-bg`) and the chrome bars — header and
+footer — paint white on top of it. The body paints nothing and shows the grey through,
+with a 16px inset. That is why the drawer needs neither an inner wrapper nor a background
+prop: the DS answers it structurally, and a colour prop would be a style escape hatch the
+DS never defines. The footer's white is the one inferred value here — the DS full profile
+has no footer, and white matches the header as the other chrome bar.
+
+**Edge.** A **1px grey ring** on the opening edge. The dragger's rule is `slate-mid` on
+hover and while dragging — **grey in every state**. Element Plus painted it with
+`--el-color-primary` (the lavender accent); that is the bug this component inherits
+already fixed.
+
+---
+
+<!-- DsPopover · Overlays -->
+
+## DsPopover
+
+Click-triggered card panel anchored to a trigger. Built **native** — no `element-plus`,
+no `floating-ui` — for the same reason as `DsDrawer`: the Vue 2 twin has to replicate this
+API and markup, and Element Plus is Vue 3 only (SALESQL-3968).
+
+It replaces frontend-app's `el-popper` override (the company card), which added a 1px grey
+ring and 8px of padding on top of Element Plus. Positioning is pure CSS, 4-way, like
+`DsTooltip`.
+
+**Presentational only**: it never closes itself — it asks the consumer through
+`v-model:open`.
+
+### Props
+
+| Prop             | Type                                     | Default    | Description                                                   |
+| ---------------- | ---------------------------------------- | ---------- | ------------------------------------------------------------- |
+| `open`           | `boolean`                                | `false`    | Visibility. Pair with `v-model:open`.                         |
+| `placement`      | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | Side of the trigger the panel opens on.                       |
+| `width`          | `string`                                 | `''`       | Panel width (any CSS length). Empty = fit content.            |
+| `closeOnEscape`  | `boolean`                                | `true`     | Escape requests a close.                                      |
+| `closeOnOutside` | `boolean`                                | `true`     | A press outside the trigger and panel requests a close.       |
+| `triggerOnClick` | `boolean`                                | `true`     | Let the trigger slot toggle the panel. Off = consumer-driven. |
+
+### Slots
+
+| Slot      | Description                       |
+| --------- | --------------------------------- |
+| `trigger` | The element the panel anchors to. |
+| default   | Panel content.                    |
+
+### Events
+
+| Event         | Payload   | When                                                        |
+| ------------- | --------- | ----------------------------------------------------------- |
+| `update:open` | `boolean` | Trigger clicked, Escape pressed, or a press landed outside. |
+
+```vue
+<DsPopover v-model:open="open" width="260px">
+  <template #trigger><DsButton variant="tertiary">Stripe</DsButton></template>
+  <CompanyCard :company="company" />
+</DsPopover>
+```
+
+### Accessibility
+
+- `role="dialog"` on the panel; it takes focus on open and **returns focus to the trigger**
+  on close, so a keyboard user is never dumped at the top of the document.
+- Escape closes when `closeOnEscape` is true.
+- Outside dismissal listens on `mousedown`, so a press that starts outside dismisses the
+  panel even if the pointer is released over it.
+
+### Chrome
+
+**1px grey ring** (`slate-tint`), `spacing(1)` (8px) padding, card radius and the dropdown
+shadow — the values carried over from the `.el-popper.card-popover` override. Grey, never
+the accent.

package/llms.txt

@@ -34,6 +34,8 @@
 - DsTextarea (Forms): Multi-line text field — the DS "Textarea", sibling of `DsInput` with the same
 - DsMenuItem (Navigation): Sidebar navigation row: an icon with an optional label, usable full-width or collapsed to
 - DsWizardStepper (Navigation): Numbered multi-step flow: a row of step chips (completed / active / incomplete / neutral)
+- DsDrawer (Overlays): Side panel over a backdrop. Built **native** — no `element-plus` — so the Vue 2 twin
+- DsPopover (Overlays): Click-triggered card panel anchored to a trigger. Built **native** — no `element-plus`,
 
 ## Full documentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesql/sql_components_vue3",
-  "version": "2.1.1",
+  "version": "3.1.0",
   "description": "Librería de componentes Vue 3 (SalesQL)",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -12,7 +12,8 @@
       "import": "./dist/index.es.js",
       "require": "./dist/index.cjs"
     },
-    "./dist/style.css": "./dist/sql_components_vue3.css"
+    "./dist/style.css": "./dist/sql_components_vue3.css",
+    "./dist/reset.css": "./dist/reset.css"
   },
   "files": [
     "dist",