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

package/dist/doc/VJoyFilterBarButton/guideline.md

@@ -0,0 +1,359 @@
+---
+component: VJoyFilterBarButton
+status: draft
+language: en
+dsds: JoyFilterBarButton.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Filter bar button
+
+Use **`VJoyFilterBarButton`** when the user needs a segmented control inside a filter bar — a compact button that represents one filter dimension (status, location, category) and can open a panel or toggle filter state.
+
+It renders a native `<button>` with Joy filter-bar styling, an optional `label`, a required `value` identifier, and an `active` state you control from the parent. Inside `VJoyDropdown`, it automatically shows a chevron-down icon. Use the default slot for extras such as a `VJoyTag` with the number of applied filters.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyFilterBarButton` from `@maltjoy/core-vue` |
+| **Design** | [Joy — Filter Bar](https://zeroheight.com/6bf479565/) (page id `4675975`) |
+| **Storybook** | [VJoyFilterBar docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-forms-vjoyfilterbar--docs) (subcomponent) |
+| **DSDS (machine)** | [`JoyFilterBarButton.dsds.json`](./JoyFilterBarButton.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyFilterBarButton")` |
+
+---
+
+## When to use this component
+
+Use a filter bar button when building **grouped filter UIs** — typically inside `VJoyFilterBar` — where each segment represents a filter category the user can interact with. Common jobs: opening a dropdown of checkboxes (`VJoyDropdown` + `VJoyCheckboxGroup`), showing how many values are applied via a tag, or switching which filter panel is active in a simple segmented control.
+
+The parent owns filter state. Set `active` when that dimension has applied values or should read as selected; listen to `@filter` when you need the `value` identifier on click (for example toggling panels in a custom filter bar).
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| A general-purpose action (Save, Cancel, Submit) | `VJoyButton` |
+| Icon-only control with no filter label | `VJoyIconButton` |
+| Single labeled form field with native select semantics | `VJoySelect` |
+| Standalone toggle on/off for one setting | `VJoyToggle` |
+| Filter chips outside a connected filter-bar group | `VJoyTag` (selectable) or confirm with design |
+| Custom segmented `<button>` styling in a filter row | Still use `VJoyFilterBarButton` inside `VJoyFilterBar` + Joy tokens |
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root `<button>` | Yes | `type="button"`, class `joy-filter-bar-button`, `data-joy-form-field` |
+| Label text | Yes* | `label` prop (*or meaningful content in the default slot) |
+| `value` identifier | Yes | Stable string sent with the `filter` event — identifies this filter dimension |
+| Default slot | No | Extra inline content (e.g. `VJoyTag` with selection count) |
+| Chevron icon | No | `VJoyIcon` (`chevron-down`) when the button is rendered inside `VJoyDropdown` |
+| Focus / hover chrome | Yes | Border and background from Joy tokens — do not remove in product CSS |
+
+`VJoyFilterBar` wraps siblings and applies connected border radius and overlap (`margin-left: -1px`) so segments read as one control. Place each button (or `VJoyDropdown` wrapping a button) as a direct child of `VJoyFilterBar`.
+
+### Default values
+
+- `active` defaults to **`false`**
+- `label` is optional (string) — prefer setting it for an accessible name
+- `value` is **required** (string)
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Visual treatment
+
+There is **no `variant` or `size` prop**. Height, border, padding, and colors come from component CSS (`--button-height: 40px`, Joy neutral/secondary tokens) — **don’t hardcode filter-button height or border colors** in apps.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default (`active={false}`) | Neutral border and white background; label in neutral text color |
+| Hover | Secondary border; pointer cursor |
+| Focus | Secondary border, secondary-tinted background, elevated `z-index` — keep visible for keyboard users |
+| Active (`active={true}`) | Same as focus styling — use when this filter has applied values or should read as selected |
+| With dropdown chevron | Chevron appears automatically when the button is a child of `VJoyDropdown` (via `VJoyDropdownContext`) |
+| With selection tag | Default slot content (e.g. `VJoyTag` with count) appears inline after the label |
+
+`active` is **controlled by the parent** — the component does not compute applied filters. Typical pattern: `:active="Boolean(selectedValues.length)"` or `:active="selectedValues.length > 0"`.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Composition
+
+- **MUST** place filter bar buttons inside `VJoyFilterBar` so connected borders and corner radius apply correctly.
+- **SHOULD** wrap a button in `VJoyDropdown` when the filter opens a panel of options (checkboxes, custom list).
+- **SHOULD** set `aria-label` on the parent `VJoyFilterBar` when the group purpose isn’t obvious from page context.
+- **MUST NOT** use `VJoyFilterBarButton` for non-filter primary actions — use `VJoyButton`.
+
+### Implementation
+
+- **MUST** pass a stable, unique `value` per filter dimension (e.g. `"continents"`, `"countries"`).
+- **MUST** use only documented props from MCP or the component source.
+- **MUST** style with Joy tokens — no custom `.joy-filter-bar-button` chrome (border, height, padding, radius).
+- **MUST NOT** invent props (`variant`, `size`, `disabled` as a documented API, `icon`, …).
+- **SHOULD** drive `active` from real filter state (applied selections), not from dropdown open/close alone unless that matches the design intent.
+- **SHOULD** show applied count in the default slot with `VJoyTag` (`size="xsmall"`) when multiple values can be selected.
+
+### Interaction
+
+- **SHOULD** listen to `@filter` when the parent needs the clicked `value` (simple segmented bars without dropdown).
+- **SHOULD** pair dropdown filters with `VJoyDropdown` reset behavior when users need to clear one dimension.
+- **MUST** keep filter state in the parent (`v-model` on checkbox groups, reactive objects, etc.) — this button does not store selections.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `VJoyFilterBar` + `VJoyFilterBarButton` | Lone custom-styled buttons pretending to be a filter bar |
+| `:active` tied to applied filter values | Hard-coded `active` that never reflects state |
+| `VJoyTag` in default slot for counts | Long text or paragraphs inside the button |
+| `VJoyDropdown` for multi-select filter panels | `VJoySelect` disguised as a filter chip |
+| Joy token styling | Hardcoded `40px` height or custom border colors |
+
+---
+
+## Content
+
+Filter bar button labels name the **filter dimension** — what will be refined when the user opens or activates this segment. Keep labels short; put counts in a `VJoyTag`, not in the label string.
+
+### Label formula
+
+**Noun or short noun phrase** naming the dimension (English):
+
+- ✅ Continents  
+- ✅ Countries  
+- ✅ Status  
+- ✅ Date range  
+
+Avoid action verbs on the chip itself — the control’s job is implied by the filter bar pattern.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Every button has a discernible name — `label` prop and/or slot content that screen readers can read |
+| **MUST** | Label names the dimension, not the action — ✅ `Countries` · ❌ `Filter countries` |
+| **MUST NOT** | Duplicate the count in the label when a `VJoyTag` already shows it — ✅ `Countries` + tag `3` · ❌ `Countries (3)` + tag `3` |
+| **MUST NOT** | Use generic labels (`Filter`, `Options`, `More`) when a specific dimension exists |
+| **SHOULD** | ≤ 20 characters for the primary label; abbreviate only when space is tight and meaning stays clear |
+| **SHOULD** | Use parallel grammar across segments in the same bar (all nouns: `Status`, `Region`, `Owner`) |
+| **SHOULD** | Match terminology with column headers or facet names elsewhere on the page |
+| **SHOULD** (FR) | Use French grammar for labels and tags when the UI is localized |
+
+### Patterns
+
+**Simple segmented bar** — Several `VJoyFilterBarButton` siblings with distinct `value`s; parent sets `:active` on the current segment and handles `@filter`.
+
+**Dropdown with multi-select** — `VJoyDropdown` → `dropdown-button` slot → `VJoyFilterBarButton` with `:active="selections.length > 0"` and optional `VJoyTag` showing `selections.length`. Options live in `dropdown-items` (e.g. `VJoyCheckboxGroup`).
+
+**Toolbar row** — Compose `VJoyFilterBar` with `VJoyWrapper` alongside search (`VJoyInput`) and a global reset (`VJoyButton` `variant="ghost"`). See `VJoyFilterBar` Storybook **Advanced usage**.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Native `<button type="button">` |
+| Name | From `label` prop and/or default slot text; tag counts should not be the only name |
+| Grouping | Parent `VJoyFilterBar` exposes `role="group"` with `aria-label` (default `"Filter bar"` — override with `ariaLabel` when needed) |
+| Keyboard | **Enter** and **Space** activate the button; **Tab** moves between segments |
+| Focus | Visible focus styling (secondary border + background) — do not remove in product CSS |
+| Dropdown trigger | When inside `VJoyDropdown`, ensure the dropdown trigger remains focusable; set `aria-label` on icon-only or ambiguous triggers per `VJoyDropdown` guidance |
+| State | `active` is visual only — expose applied filters in page content or live region if results change |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { reactive } from 'vue'
+import {
+  VJoyFilterBar,
+  VJoyFilterBarButton,
+  VJoyDropdown,
+  VJoyCheckboxGroup,
+  VJoyTag,
+  VJoyButton,
+  VJoyInput,
+  VJoyWrapper,
+} from '@maltjoy/core-vue'
+
+const filters = reactive({
+  continents: [] as string[],
+  countries: [] as string[],
+})
+
+const continents = [
+  { value: 'europe', label: 'Europe', id: 'europe' },
+  { value: 'asia', label: 'Asia', id: 'asia' },
+]
+
+const countries = [
+  { value: 'france', label: 'France', id: 'france' },
+  { value: 'spain', label: 'Spain', id: 'spain' },
+]
+
+function resetAll() {
+  filters.continents = []
+  filters.countries = []
+}
+</script>
+
+<template>
+  <!-- Simple segmented filters -->
+  <VJoyFilterBar aria-label="Project filters">
+    <VJoyFilterBarButton
+      value="open"
+      label="Open"
+      :active="true"
+      @filter="(id) => console.log('filter', id)"
+    />
+    <VJoyFilterBarButton value="closed" label="Closed" />
+    <VJoyFilterBarButton value="archived" label="Archived" />
+  </VJoyFilterBar>
+
+  <!-- Dropdown filters with selection counts -->
+  <VJoyWrapper row-gap="4">
+    <VJoyFilterBar aria-label="Location filters">
+      <VJoyDropdown :reset="true" reset-label="Reset filter">
+        <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>
+
+      <VJoyDropdown :reset="true" reset-label="Reset filter">
+        <template #dropdown-button>
+          <VJoyFilterBarButton
+            value="countries"
+            label="Countries"
+            :active="filters.countries.length > 0"
+          >
+            <VJoyTag
+              v-if="filters.countries.length"
+              size="xsmall"
+              value="country-count"
+              :label="String(filters.countries.length)"
+            />
+          </VJoyFilterBarButton>
+        </template>
+        <template #dropdown-items>
+          <VJoyCheckboxGroup v-model:value="filters.countries" :options="countries" />
+        </template>
+      </VJoyDropdown>
+    </VJoyFilterBar>
+
+    <VJoyButton variant="ghost" size="xsmall" label="Reset all filters" @click="resetAll" />
+    <VJoyInput
+      name="search"
+      size="small"
+      icon="search"
+      placeholder="Search locations…"
+    />
+  </VJoyWrapper>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if components are already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyFilterBar` | Container that connects segments with shared border radius |
+| `VJoyDropdown` | Filter opens a panel of options; provides chevron on the button |
+| `VJoyCheckboxGroup` | Multi-select values inside a filter dropdown |
+| `VJoyTag` | Inline count of applied filters in the default slot |
+| `VJoyInput` | Search field beside the filter bar in a toolbar |
+| `VJoyButton` | Global reset or actions adjacent to filters (`ghost`, `xsmall`) |
+| `VJoyWrapper` | Layout spacing for filter bar + search + actions |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyFilterBarButton.dsds.json`](./JoyFilterBarButton.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Segmented filter control in a filter bar | `VJoyFilterBarButton` inside `VJoyFilterBar` | `VJoyButton` with custom filter CSS |
+| Filter opens checkbox / custom panel | `VJoyDropdown` + `VJoyFilterBarButton` in `dropdown-button` | Raw `VJoyButton` as dropdown trigger in a filter bar |
+| Show count of applied filters | `VJoyTag` in default slot | Long label like `Countries (3)` |
+| Primary page CTA | `VJoyButton` | `VJoyFilterBarButton` |
+| Single form select field | `VJoySelect` | Filter bar button |
+| Icon-only filter | `VJoyIconButton` + tooltip (rare) | Unlabeled `VJoyFilterBarButton` |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyFilterBarButton")` before generating props.  
+2. **MUST** set `value` on every instance (required prop).  
+3. **MUST** wrap segments in `VJoyFilterBar` for correct grouped styling.  
+4. **MUST NOT** invent props — there is no `variant`, `size`, or `icon` prop.  
+5. **MUST NOT** override `.joy-filter-bar-button` height, border, padding, or radius.  
+6. **MUST** control `active` from parent filter state.  
+7. **SHOULD** use `VJoyDropdown` when the filter reveals a list of options.  
+8. **SHOULD** use `VJoyTag` (`size="xsmall"`) for selection counts in the default slot.
+
+### Checklist
+
+- [ ] Correct component (`VJoyFilterBarButton` or named alternative)
+- [ ] Inside `VJoyFilterBar` (unless design explicitly documents an exception)
+- [ ] `value` set; `label` or meaningful slot content for accessible name
+- [ ] `active` reflects applied filters (parent-controlled)
+- [ ] Dropdown filters use `VJoyDropdown` + checkbox group or documented slot content
+- [ ] No invented props / no custom filter-button chrome CSS
+- [ ] `VJoyFilterBar` `aria-label` set when default is insufficient
+- [ ] Counts in `VJoyTag`, not duplicated in `label`
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyFilterBarButton.dsds.json`](./JoyFilterBarButton.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| 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 |
+| Token sizing | `design-specifications` in JSON (`--button-height`, Joy neutral/secondary colors) |