@usevyre/ai-context 1.0.1 → 1.2.0

package/dist/cursor-rules.md

@@ -4,7 +4,7 @@ alwaysApply: true
 ---
 
 # useVyre Design System — Cursor Rules
-# Version: 1.0.0
+# Version: 1.2.0
 
 You are working in a project using the useVyre design system (@usevyre/react).
 Follow these rules strictly when generating any UI code.
@@ -83,13 +83,26 @@ Never do:
 - ❌ size="icon" without aria-label → ✅ Add aria-label describing the action
 
 ## Calendar
-Date picker calendar widget for selecting single dates or ranges.
+Inline date-grid widget (always visible, no input). mode: single | range | multiple, optional time picker. For an input + popover use DatePicker; for start/end ranges with presets use DateRangePicker.
 Import: `import { Calendar } from "@usevyre/react"`
 
 Valid props:
 
 Never do:
-- ❌ Using Calendar for time selection → ✅ Combine with a separate time Input if time selection is needed
+- ❌ Calendar for an input field that opens a popover → ✅ Use <DatePicker /> (single date) or <DateRangePicker /> (range)
+- ❌ value as tuple for mode="single" → ✅ Pass value matching mode; use mode="range" for [start,end]
+
+## DatePicker
+Input trigger that opens a Calendar in a popover. Same modes as Calendar (single | range | multiple) plus a placeholder. Use this for a compact date field; use Calendar for an always-visible grid, or DateRangePicker for start/end ranges with presets.
+Import: `import { DatePicker } from "@usevyre/react"`
+
+Valid props:
+- mode: "single" | "range" | "multiple" [default: single]
+- weekStartsOn: "0" | "1" [default: 1]
+
+Never do:
+- ❌ DatePicker mode="range" for { from, to } object → ✅ Use <DateRangePicker /> for the { from, to } object API + presets + dual month
+- ❌ DatePicker without value/onChange → ✅ Provide value and onChange (e.g. from useState)
 
 ## Card
 Content container with optional header, body, and footer sections.
@@ -111,6 +124,30 @@ Valid props:
 Never do:
 - ❌ size="lg" → ✅ Use size="md"
 
+## RadioGroup
+Controlled single-choice group. RadioGroup owns the selected value; render it data-driven via the options array OR with composable <Radio> children for custom content. role=radiogroup with proper labelling. For multi-select use Checkbox; for a compact dropdown use Select.
+Import: `import { RadioGroup, Radio } from "@usevyre/react"`
+
+Valid props:
+- size: "sm" | "md" [default: md]
+- orientation: "vertical" | "horizontal" [default: vertical]
+
+Never do:
+- ❌ <Radio> used outside a <RadioGroup> → ✅ Always wrap <Radio> in <RadioGroup>
+- ❌ RadioGroup without value/onChange (React) or v-model (Vue) → ✅ Bind value + onChange (React) or v-model (Vue); or defaultValue for uncontrolled in React
+- ❌ Using Checkbox for mutually-exclusive choices → ✅ Use RadioGroup + Radio (or options) for one-of-many
+
+## RichTextEditor
+Controlled WYSIWYG editor. value is an HTML string; you own it in state and set it in onChange (React) / v-model (Vue). Native contentEditable + execCommand — zero dependencies. Toolbar: bold, italic, underline, strike, h1-h3, ordered/unordered lists, quote, code block, link, clear formatting.
+Import: `import { RichTextEditor } from "@usevyre/react"`
+
+Valid props:
+
+Never do:
+- ❌ RichTextEditor without value/onChange (React) or v-model (Vue) → ✅ Keep the HTML string in state and update it in onChange / v-model
+- ❌ Rendering value as text or with dangerouslySetInnerHTML elsewhere without sanitising → ✅ Sanitise (e.g. DOMPurify) before re-rendering untrusted RTE output
+- ❌ toolbar="bold" (string) → ✅ Pass an array, e.g. toolbar={["bold","italic","link"]}
+
 ## Command
 Command palette / search dialog. Use for search-first navigation or quick actions.
 Import: `import { Command, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandDialog } from "@usevyre/react"`
@@ -128,7 +165,7 @@ Never do:
 - ❌ DropdownItem variant="primary" → ✅ Use variant="danger" for destructive items only
 
 ## Field
-Form field wrapper providing label, hint text, and validation state for Input or Textarea.
+Form field wrapper. Two ways to use it (both supported): (1) props-based — pass label/hint/state/required for the common case; (2) composable — use the parts FieldLabel, FieldDescription, FieldError, FieldGroup, FieldSet for richer layouts (multiple controls, custom error placement). The props-based API is unchanged and still works.
 Import: `import { Field, Input, Textarea } from "@usevyre/react"`
 
 Valid props:
@@ -136,6 +173,7 @@ Valid props:
 
 Never do:
 - ❌ Applying state prop directly to Input → ✅ Wrap Input in <Field state="error"> to apply validation styling
+- ❌ Mixing props label/hint AND FieldLabel/FieldError for the same field → ✅ Pick one: either props-based (label/hint/state) OR composable parts
 
 ## Input
 Text input field. Wrap in Field for labels and validation. Use leftElement/rightElement for icons.
@@ -147,6 +185,7 @@ Valid props:
 Never do:
 - ❌ size="icon" → ✅ Use size="sm" | "md" | "lg"
 - ❌ type="search" for search UI → ✅ Import Command from @usevyre/react for search palettes
+- ❌ Vue: binding Input/Textarea value without v-model → ✅ Use v-model on <Input>/<Textarea> in Vue; in React use value + onChange
 
 ## Label
 Accessible form label. Associate with input via htmlFor.
@@ -283,6 +322,127 @@ Import: `import { Text, Heading, Lead, Code, Blockquote } from "@usevyre/react"`
 Never do:
 - ❌ Using raw <h1>, <p> tags instead of Typography components → ✅ Use <Heading>, <Text>, <Lead> from @usevyre/react
 
+## ButtonGroup
+Groups multiple Button components into one visual unit (toolbar, segmented control). Pure layout — no internal state.
+Import: `import { ButtonGroup, Button } from "@usevyre/react"`
+
+Valid props:
+- orientation: "horizontal" | "vertical" [default: horizontal]
+- size: "sm" | "md" | "lg" | "icon"
+
+Never do:
+- ❌ ButtonGroup variant="..." → ✅ Set variant on each <Button> inside the group
+- ❌ ButtonGroup without Button children → ✅ Place <Button> elements as direct children
+
+## TagsInput
+Multi-tag input. Type and press Enter or comma to add a tag, click x to remove, Backspace on empty input removes the last tag. Controlled.
+Import: `import { TagsInput } from "@usevyre/react"`
+
+Valid props:
+- size: "sm" | "md" | "lg" [default: md]
+
+Never do:
+- ❌ TagsInput value={string} → ✅ Pass an array: value={['react','vue']}
+- ❌ TagsInput without onChange → ✅ Provide value and onChange (React) or v-model (Vue)
+
+## Combobox
+Searchable single-select dropdown with typeahead filtering and keyboard navigation. Use when the list is long enough to need search. Differs from Select (no search) and Command (palette).
+Import: `import { Combobox } from "@usevyre/react"`
+
+Valid props:
+- size: "sm" | "md" | "lg" [default: md]
+
+Never do:
+- ❌ Combobox value="" → ✅ Use value={null} for no selection
+- ❌ Combobox options={string[]} → ✅ Use [{ value: 'ts', label: 'TypeScript' }]
+- ❌ Using Combobox for command palette → ✅ Use Command for command palettes
+
+## DataGrid
+Table with built-in column sorting, loading skeletons, and empty state. Filtering and pagination are out of scope — compose with the Pagination component.
+Import: `import { DataGrid } from "@usevyre/react"`
+
+Valid props:
+- sortDir: "asc" | "desc"
+
+Never do:
+- ❌ DataGrid expecting built-in pagination → ✅ Slice rows yourself and use the Pagination component
+- ❌ DataGrid expecting built-in filtering → ✅ Filter the rows array before passing it in
+- ❌ sortable without onSort → ✅ Handle onSort and sort the rows array in your state
+
+## Tag
+Standalone display tag/chip for categories, labels, or filter chips. NOT an input — for tag input use TagsInput. Group multiple with TagGroup.
+Import: `import { Tag } from "@usevyre/react"`
+
+Valid props:
+- variant: "default" | "accent" | "danger" [default: default]
+- size: "sm" | "md" | "lg" [default: md]
+
+Never do:
+- ❌ Tag variant="success" → ✅ Use Badge for success/warning/teal status colors; Tag is for categories/filters
+- ❌ Using Tag for tag input → ✅ Use TagsInput for adding/removing tags via keyboard
+- ❌ Tag size="xl" → ✅ Use size="lg"
+
+## TagGroup
+Read-only container that lays out multiple Tag elements with automatic wrapping and consistent spacing. For tag input use TagsInput.
+Import: `import { TagGroup, Tag } from "@usevyre/react"`
+
+Valid props:
+- gap: "sm" | "md" | "lg" [default: md]
+
+Never do:
+- ❌ TagGroup without Tag children → ✅ Place <Tag> elements as direct children
+- ❌ Using TagGroup for tag input → ✅ Use TagsInput for an editable tag field
+
+## Item
+Layout primitive for list rows, settings rows, and notification rows. Denser than Card — use Item (not Card) for repeated list rows.
+Import: `import { Item, ItemMedia, ItemContent, ItemTitle, ItemDescription, ItemActions, ItemGroup } from "@usevyre/react"`
+
+Valid props:
+- variant: "default" | "outlined" | "muted" | "plain" [default: default]
+- size: "sm" | "md" | "lg" [default: md]
+
+Never do:
+- ❌ Card used for repeated list rows → ✅ Use <Item> (optionally inside <ItemGroup separated>) for list/settings rows
+- ❌ Item variant="primary" → ✅ Use variant="default" | "outlined" | "muted"
+- ❌ raw text directly inside Item → ✅ Wrap text in <ItemContent><ItemTitle>…</ItemTitle></ItemContent>
+
+## Kanban
+Drag-and-drop board: cards move between columns (or reorder within a column). CONTROLLED & data-driven like DataGrid. While dragging, a placeholder shows the exact drop position. Each card is wrapped in a Card (variant="outlined"); renderCard (React) / #card slot (Vue) can render ANY content incl. complex components (Avatar/Badge/Progress). Columns and cards accept an optional semantic color tint. Native HTML5 DnD, zero deps.
+Import: `import { Kanban } from "@usevyre/react"`
+
+Valid props:
+
+Never do:
+- ❌ Kanban without onChange (or ignoring it) → ✅ Store columns in state and setColumns in onChange (v-model in Vue)
+- ❌ Duplicate card ids across columns → ✅ Use globally-unique card ids across the entire board
+- ❌ Mutating value in place then calling onChange → ✅ Pass the new array Kanban gives you straight to setState / v-model
+- ❌ color="blue" (or any non-semantic value) → ✅ Use one of: "default" | "accent" | "teal" | "success" | "warning" | "danger"
+
+## Conversation
+Chat / inbox message thread. CONTROLLED & data-driven like Kanban — you own `value` (messages array) and append in your own send handler; Conversation holds no message state. Consecutive messages from the same author are grouped (avatar + name shown once), day separators are inserted on date change, and outgoing messages (authorId === currentUserId) align right.
+Import: `import { Conversation } from "@usevyre/react"`
+
+Valid props:
+
+Never do:
+- ❌ Conversation without currentUserId → ✅ Always pass currentUserId matching one of the message authorId values
+- ❌ Expecting Conversation to store/append messages → ✅ Append to your own state in onSend (or @send) and pass it back via value
+- ❌ composer without onSend (React) / @send (Vue) → ✅ Provide onSend / @send to append the message to value
+- ❌ Treating onSend as (text) only when using allowAttachments → ✅ Handle onSend(text, files) — map files to message attachments and append
+
+## DateRangePicker
+Start/end date range picker. Built on Calendar (mode=range) with a friendlier { from, to } object API, a two-month side-by-side view, and preset shortcuts. Use this for report/filter date ranges; use DatePicker for a single date.
+Import: `import { DateRangePicker } from "@usevyre/react"`
+
+Valid props:
+- numberOfMonths: "1" | "2" [default: 2]
+- weekStartsOn: "0" | "1" [default: 1]
+
+Never do:
+- ❌ value={[from, to]} → ✅ Use value={{ from, to }} and read range.from / range.to
+- ❌ DateRangePicker for a single date → ✅ Use <DatePicker /> for a single date
+- ❌ presets="true" (string) → ✅ Use the bare prop: presets  (or presets={true})
+
 ## Token Rules
 
 Use --vyre-color-semantic-* for all colors. Never use primitive tokens.