@maltjoy/mcp-server 0.4.0 → 0.6.0-beta.0

package/dist/doc/VJoyFilterBar/guideline.md

@@ -0,0 +1,419 @@
+---
+component: VJoyFilterBar
+status: draft
+language: en
+dsds: JoyFilterBar.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Filter bar
+
+Use **`VJoyFilterBar`** when users need to refine a list or dataset with one or more filters presented as a connected button group — for example status filters, category chips, or dropdown-backed multi-select filters above a table.
+
+It is a **layout container** only: it groups `VJoyFilterBarButton` children (or `VJoyDropdown` triggers that embed them), applies seamless border-radius and overlap styling, and exposes a single `role="group"` landmark. Filter state, active styling, and selection counts are **managed by the parent**.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyFilterBar` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy components](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyFilterBar docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-forms-vjoyfilterbar--docs) |
+| **DSDS (machine)** | [`JoyFilterBar.dsds.json`](./JoyFilterBar.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyFilterBar")` |
+
+---
+
+## When to use this component
+
+Use a filter bar when the user should pick one or more criteria to narrow visible content on the same screen — for example filtering projects by status, narrowing a directory by location, or combining several facet filters above search results.
+
+`VJoyFilterBar` works best when filters are **peer controls** shown together as a segmented control. Pair it with `VJoyFilterBarButton` for simple toggle filters, or wrap buttons inside `VJoyDropdown` when a filter opens a panel of checkboxes, search, or other custom content.
+
+For a full toolbar (filters + reset + search), compose `VJoyFilterBar` inside `VJoyWrapper` alongside `VJoyButton` and `VJoyInput` — see Storybook **Advanced usage**.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| A single native form select in a field | `VJoySelect` |
+| One overflow / kebab menu of actions | `VJoyDropdown` alone (no grouped bar chrome) |
+| Mutually exclusive options always visible (2–7 choices) | `VJoyRadioGroup` or `VJoySelectableItemGroup` |
+| Primary page navigation between sections | `VJoyTabs` |
+| Free-text search only (no facet buttons) | `VJoyInput` with `icon="search"` |
+| Custom button group CSS for the same job | Still use `VJoyFilterBar` + `VJoyFilterBarButton` + Joy tokens |
+
+---
+
+## How it works
+
+`VJoyFilterBar` renders a flex row wrapper around its default slot. It does **not** own selection state, emit filter events, or render buttons by itself — you compose children explicitly.
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Group container | Yes | Root `div.joy-filter-bar` with `role="group"` |
+| Group label | Yes (implicit) | `aria-label` from `ariaLabel` prop, or default `"Filter bar"` |
+| Wrapper | Yes | `.joy-filter-bar__wrapper` — horizontal flex row for slot children |
+| Filter controls (`default` slot) | Yes | Typically `VJoyFilterBarButton` and/or `VJoyDropdown` wrapping those buttons |
+| Connected styling | Yes (automatic) | First/last child corner radius (`--joy-core-radius-3`); `-1px` overlap between siblings |
+
+### Default values
+
+- `ariaLabel` — when omitted, the group uses **`"Filter bar"`** as `aria-label` (see component tests).
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Composition
+
+**Simple toggle filters** — one `VJoyFilterBarButton` per filter; parent listens to `@filter` and toggles `active`:
+
+```vue
+<VJoyFilterBar>
+  <VJoyFilterBarButton
+    v-for="filter in filters"
+    :key="filter.value"
+    :value="filter.value"
+    :label="filter.label"
+    :active="activeFilter === filter.value"
+    @filter="activeFilter = $event"
+  />
+</VJoyFilterBar>
+```
+
+**Multi-select facet** — each filter is a `VJoyDropdown` with a `VJoyFilterBarButton` trigger, checkbox panel, optional `VJoyTag` count, and `reset` handler. Parent owns `v-model` on `VJoyCheckboxGroup` and sets `:active` when the selection array is non-empty.
+
+**Toolbar** — wrap `VJoyFilterBar` in `VJoyWrapper` with `justify-content`, `align-items`, and `gap` as needed; add `VJoyButton` (reset all) and `VJoyInput` (search) as siblings.
+
+### Child contract (`VJoyFilterBarButton`)
+
+Although defined in a sibling component, filter bars almost always use it:
+
+| Prop / API | Notes |
+| --- | --- |
+| `value` | **Required** — stable id emitted on `@filter` |
+| `label` | Visible filter name |
+| `active` | Highlights applied filter (`joy-filter-bar-button--active`) |
+| `@filter` | Emits `[value: string]` on click |
+| `default` slot | Extra content (e.g. `VJoyTag` with selection count) |
+| Inside `VJoyDropdown` | Chevron icon appears automatically via dropdown context |
+
+---
+
+## Variants
+
+`VJoyFilterBar` has **no variant or emphasis prop**. Visual treatment comes from its children (`VJoyFilterBarButton`, `VJoyDropdown`, `VJoyTag`) and the built-in connected-group chrome.
+
+Do not simulate filter-bar variants with custom CSS on `.joy-filter-bar` — compose the documented children instead.
+
+---
+
+## Sizes
+
+`VJoyFilterBar` has **no size prop**. `VJoyFilterBarButton` uses a fixed `min-height` of **40px** and Joy spacing / typography tokens internally — **don’t hardcode filter button heights** in product CSS.
+
+Match density by choosing appropriate child components (`VJoyTag` `size="xsmall"` for counts, `VJoyDropdown` `size="small"` for compact panels).
+
+---
+
+## States
+
+`VJoyFilterBar` itself is not focusable. States apply to its children; the bar only provides grouped layout.
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default | Neutral filter buttons; no selection applied (`active` false on buttons) |
+| Active filter | `VJoyFilterBarButton` with `active` true — secondary border/background (parent-driven) |
+| Hover / focus | Per-button hover and focus styles on `VJoyFilterBarButton` |
+| Dropdown open | `VJoyDropdown` panel visible; trigger button may show chevron (injected by dropdown context) |
+| Selection count | Optional `VJoyTag` in the button slot (e.g. `label="3"`) — parent updates count |
+| Reset | `VJoyDropdown` `reset` + `@dropdown:reset` per filter, or a separate `VJoyButton` for “reset all” |
+
+The component does **not** disable individual filters — hide unavailable filters or handle disabled state in the parent / dropdown content.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Structure / filtering
+
+- **MUST** manage filter state in the parent — `VJoyFilterBar` does not provide `v-model`.
+- **MUST** give every `VJoyFilterBarButton` a stable, unique `value` string.
+- **SHOULD** set `:active` on a button when that filter has an applied selection (non-empty array, non-default value, etc.).
+- **SHOULD** keep the number of visible filters modest (roughly **2–6**); move overflow into a “More filters” dropdown if needed.
+- **SHOULD** place the filter bar **above** the content it affects (table, list, map) so the relationship is obvious.
+- **MUST NOT** use `VJoyFilterBar` for non-filter actions (export, create) — use `VJoyButton` or `VJoyWrapper` toolbars instead.
+
+### Implementation
+
+- **MUST** put filter controls in the **default slot** — typically `VJoyFilterBarButton` or `VJoyDropdown`.
+- **MUST** use only documented props (`ariaLabel` on the bar; `value`, `label`, `active` on buttons).
+- **MUST** style with Joy tokens — no custom `.joy-filter-bar` or `.joy-filter-bar-button` chrome overrides.
+- **MUST NOT** invent props on `VJoyFilterBar` (no `variant`, `size`, `disabled`, or `v-model`).
+- **SHOULD** set a descriptive `aria-label` when `"Filter bar"` is too generic (e.g. `aria-label="Project filters"`).
+- **SHOULD** use `VJoyDropdown` `reset` + `@dropdown:reset` for per-filter clear; wire it to parent state.
+- **SHOULD** use `close-on-select="false"` on dropdowns with multi-select checkboxes; add a footer Apply button when needed (see `VJoyDropdown` docs).
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `VJoyFilterBar` + `VJoyFilterBarButton` for grouped filters | Hand-rolled flex divs with manual border overlap |
+| Parent-owned `active` and selection counts | Expect the bar to track state automatically |
+| `VJoyTag` for numeric selection badges | Long text inside the button for counts |
+| `VJoyWrapper` for filter + search + reset rows | Cram unrelated actions inside the bar slot |
+| Descriptive `aria-label` when context helps | Rely on default `"Filter bar"` on every page |
+
+---
+
+## Content
+
+Filter button labels name **what is being filtered**, not the current selection value (unless the product pattern explicitly shows state in the label).
+
+### Label formula
+
+**Short noun or facet name** — parallel across the bar:
+
+- ✅ Status · Location · Skills  
+- ✅ Continents · Countries  
+- ✅ Availability  
+
+For dropdown triggers, the **trigger label** names the facet; selected values appear in the panel, in a `VJoyTag` count, or in results — not as a long sentence on the button.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Keep labels scannable — aim for **≤ 20 characters**; never truncate with ellipsis |
+| **MUST** | Use consistent grammar across filters in the same bar |
+| **MUST** | Make each label distinct — no duplicate facet names |
+| **MUST NOT** | Use vague labels — ❌ `Filter`, `Options`, `More` without context |
+| **MUST NOT** | Put full selected value lists in the button — use tags/counts or panel content |
+| **SHOULD** | Prefer **1–2 words** (noun phrases) |
+| **SHOULD** | Use `VJoyTag` `label` for counts only (`"2"`, `"12"`) — facet name stays in `label` |
+| **SHOULD** | Reset actions name scope — `Reset filter`, `Reset all filters` |
+| **SHOULD** (FR) | Keep articles when grammar requires them — _Continents_, _Pays_ |
+
+### Patterns
+
+**Single-select toggle bar** — Labels are facet values (`All`, `Open`, `Closed`). One `active` button at a time; parent updates on `@filter`.
+
+**Multi-select dropdown facet** — Button label = facet (`Skills`); `VJoyTag` shows count when `active`; panel holds `VJoyCheckboxGroup`. Footer `Apply filters` when changes are deferred.
+
+**Filter + search toolbar** — Filter labels stay short; search placeholder is specific (`Search projects…`) in adjacent `VJoyInput`, not inside `VJoyFilterBar`.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Group role | Root uses `role="group"` — screen readers announce it as a group |
+| Group name | `aria-label` from `ariaLabel`, or default `"Filter bar"` — override when the default is ambiguous |
+| Focus | Focus moves to individual `VJoyFilterBarButton` / dropdown triggers — not the bar wrapper |
+| Keyboard | Buttons activate with **Enter** / **Space**; dropdowns follow `VJoyDropdown` keyboard behavior |
+| Active state | Don’t rely on color alone — `active` changes border and background; pair with tags/counts when useful |
+| Dropdown triggers | Icon-only or ambiguous triggers still need an accessible name (`label` on `VJoyFilterBarButton` or `aria-label` on dropdown trigger per `VJoyDropdown` docs) |
+| Live results | When filters update content, ensure the results region is announced if the product uses live regions |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { reactive, ref } from 'vue'
+import {
+  VJoyFilterBar,
+  VJoyFilterBarButton,
+  VJoyDropdown,
+  VJoyCheckboxGroup,
+  VJoyTag,
+  VJoyWrapper,
+  VJoyButton,
+  VJoyInput,
+} from '@maltjoy/core-vue'
+
+const activeStatus = ref('all')
+
+const continents = [
+  { value: 'europe', label: 'Europe', id: 'europe' },
+  { value: 'asia', label: 'Asia', id: 'asia' },
+]
+
+const filters = reactive({
+  continents: [] as string[],
+})
+
+function resetContinents() {
+  filters.continents = []
+}
+</script>
+
+<template>
+  <!-- Simple toggle filters -->
+  <VJoyFilterBar aria-label="Project status filters">
+    <VJoyFilterBarButton
+      value="all"
+      label="All"
+      :active="activeStatus === 'all'"
+      @filter="activeStatus = $event"
+    />
+    <VJoyFilterBarButton
+      value="open"
+      label="Open"
+      :active="activeStatus === 'open'"
+      @filter="activeStatus = $event"
+    />
+    <VJoyFilterBarButton
+      value="closed"
+      label="Closed"
+      :active="activeStatus === 'closed'"
+      @filter="activeStatus = $event"
+    />
+  </VJoyFilterBar>
+
+  <!-- Multi-select facet with dropdown -->
+  <VJoyFilterBar>
+    <VJoyDropdown
+      reset
+      reset-label="Reset filter"
+      :close-on-select="false"
+      @dropdown:reset="resetContinents"
+    >
+      <template #dropdown-button>
+        <VJoyFilterBarButton
+          value="continents"
+          label="Continents"
+          :active="filters.continents.length > 0"
+        >
+          <VJoyTag
+            v-if="filters.continents.length"
+            size="xsmall"
+            value="continent-count"
+            :label="String(filters.continents.length)"
+          />
+        </VJoyFilterBarButton>
+      </template>
+      <template #dropdown-items>
+        <VJoyCheckboxGroup
+          v-model:value="filters.continents"
+          :options="continents"
+        />
+      </template>
+    </VJoyDropdown>
+  </VJoyFilterBar>
+
+  <!-- Toolbar: filters + reset + search -->
+  <VJoyWrapper justify-content="space-between" align-items="center" gap="medium">
+    <VJoyFilterBar aria-label="Location filters">
+      <!-- …dropdown filters as above… -->
+    </VJoyFilterBar>
+    <VJoyButton
+      variant="ghost"
+      size="xsmall"
+      label="Reset all filters"
+      @click="resetContinents"
+    />
+    <VJoyInput
+      icon="search"
+      size="small"
+      name="search"
+      placeholder="Search any location…"
+    />
+  </VJoyWrapper>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if components are already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyFilterBarButton` | Required child for each filter control in the bar |
+| `VJoyDropdown` | Filter opens a panel (checkboxes, search, custom content) |
+| `VJoyCheckboxGroup` | Multi-select options inside a dropdown filter |
+| `VJoyTag` | Selection count badge inside a filter button |
+| `VJoyWrapper` | Lay out filter bar with search, reset, or other toolbar actions |
+| `VJoyButton` | Reset-all or secondary toolbar actions beside the bar |
+| `VJoyInput` | Search field adjacent to filters (`icon="search"`) |
+| `VJoySelect` | Single bounded choice in a form field — not a segmented filter bar |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyFilterBar.dsds.json`](./JoyFilterBar.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Grouped facet filters above a list/table | `VJoyFilterBar` + `VJoyFilterBarButton` | Raw flex `div` + styled buttons |
+| Filter with checkbox panel | `VJoyFilterBar` > `VJoyDropdown` > `VJoyFilterBarButton` + `VJoyCheckboxGroup` | `VJoySelect` for multi-select facets |
+| Single form enum in a field | `VJoySelect` or `VJoyRadioGroup` | `VJoyFilterBar` inside a form group |
+| Toolbar with filters + search | `VJoyWrapper` + `VJoyFilterBar` + `VJoyInput` | Everything crammed in one slot |
+| Overflow actions menu | `VJoyDropdown` alone | `VJoyFilterBar` with one kebab button |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyFilterBar")` and `joy_get_component_info("VJoyFilterBarButton")` (or read Storybook) before generating markup.
+2. **MUST** treat `VJoyFilterBar` as a **stateless container** — parent owns selection, `active`, and counts.
+3. **MUST** emit `VJoyFilterBarButton` with required `value` and handle `@filter` in the parent.
+4. **MUST** set `:active` on buttons when a filter is applied (parent logic).
+5. **MUST NOT** invent props on `VJoyFilterBar` (`variant`, `size`, `v-model`, `options`, …).
+6. **MUST NOT** override `.joy-filter-bar`, `.joy-filter-bar__wrapper`, or `.joy-filter-bar-button` styles.
+7. **SHOULD** set `aria-label` when `"Filter bar"` is not specific enough.
+8. **SHOULD** use `VJoyTag` `size="xsmall"` for selection counts inside buttons.
+9. **SHOULD** use `VJoyDropdown` `reset` + `@dropdown:reset` for per-filter clear handlers.
+
+### Valid props (from source)
+
+| Component | Prop | Type / notes |
+| --- | --- | --- |
+| `VJoyFilterBar` | `ariaLabel` | `string` — optional; defaults to `"Filter bar"` |
+| `VJoyFilterBar` | `default` slot | Filter children |
+| `VJoyFilterBarButton` | `value` | `string` — **required** |
+| `VJoyFilterBarButton` | `label` | `string` |
+| `VJoyFilterBarButton` | `active` | `boolean` — default `false` |
+| `VJoyFilterBarButton` | `@filter` | emits `value: string` |
+
+### Checklist
+
+- [ ] `VJoyFilterBar` wraps filter children — not standalone buttons without the container
+- [ ] Every `VJoyFilterBarButton` has a unique `value`
+- [ ] Parent handles `@filter`, `active`, and checkbox `v-model` — bar has no `v-model`
+- [ ] Props from MCP / Storybook / source only — no invented API
+- [ ] No custom filter-bar chrome CSS
+- [ ] `aria-label` set when default label is too generic
+- [ ] Multi-select dropdowns use `close-on-select="false"` when appropriate
+- [ ] Counts use `VJoyTag`, not long button labels
+- [ ] Search / reset live in `VJoyWrapper` siblings when building a full toolbar
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyFilterBar.dsds.json`](./JoyFilterBar.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| Variants / sizes | `variants` |
+| States | `states` |
+| Best practices / content rules | `guidelines` (+ `content`) |
+| Accessibility | `accessibility` |
+| Examples | `sections` |
+| For agents | `agentDocumentBlocks` |
+| Props detail | `api` in JSON + Joy MCP |
+| Imports | `imports` in JSON |
+| Connected-group radius / layout | `design-specifications` in JSON |