@turquoisehealth/pit-viper 2.179.1-dev.0 → 2.181.0

package/claude-plugin/skills/pit-viper/references/vue-guidelines.md

@@ -0,0 +1,513 @@
+# Vue Guidelines for Pit Viper
+
+Use this reference when generating Vue SFC code (Engineer Mode).
+
+## Adding Pit Viper to a Vue Project
+
+### Step 1: Install the package
+
+```bash
+npm install @turquoisehealth/pit-viper
+# or
+pnpm add @turquoisehealth/pit-viper
+```
+
+### Step 2: Import CSS in your app entry point
+
+```typescript
+// main.ts or App.vue
+import '@turquoisehealth/pit-viper/pit-viper-v2.css'
+// OR for consumer/marketing sites:
+// import '@turquoisehealth/pit-viper/pit-viper-consumer.css'
+```
+
+### Step 3: Import and use components
+
+```typescript
+import { PvButton, PvInput } from '@turquoisehealth/pit-viper/components'
+```
+
+For complete setup instructions and sandboxes, see the [Storybook Introduction](https://pit-viper-storybook.netlify.app/?path=/docs/introduction--documentation).
+
+## File Structure
+
+Components use Vue 3 Composition API with TypeScript. Block order is strict:
+
+1. `<script lang="ts">` — Only for generic type definitions (when needed)
+2. `<script setup lang="ts">` — Component logic
+3. `<template>` — Markup
+4. `<style scoped>` — Only when absolutely necessary (prefer pv-* classes)
+
+## Import Paths
+
+Never use barrel exports. Import directly from component paths:
+
+```typescript
+// Base components
+import { PvButton, PvInput, PvModal } from '@turquoisehealth/pit-viper/components'
+
+// Visualization components (tables, charts)
+import { PvDataTable, PvChart } from '@turquoisehealth/pit-viper/components/visualizations'
+
+// Layout components (must import directly)
+import PvSidePanel from '@turquoisehealth/pit-viper/components/layout/PvSidePanel/PvSidePanel.vue'
+```
+
+## Props Pattern
+
+Define props as interfaces. Use `withDefaults` for default values. Props should be alphabetically ordered.
+
+```typescript
+export interface MyComponentProps {
+  disabled?: boolean;
+  label: string;
+  options: Option[];
+  placeholder?: string;
+}
+
+const props = withDefaults(defineProps<MyComponentProps>(), {
+  disabled: false,
+  options: () => [],
+  placeholder: 'Select...',
+});
+```
+
+## Emits Pattern
+
+Define emits with kebab-case event names and typed payloads:
+
+```typescript
+const emit = defineEmits<{
+  (e: 'value-change', value: string): void;
+  (e: 'item-select', item: Option): void;
+}>();
+```
+
+## Generics Pattern
+
+When using generics, declare interfaces in a separate `<script>` block:
+
+```vue
+<script lang="ts">
+export interface ListProps<T> {
+  items: T[];
+  selected: T | null;
+}
+</script>
+
+<script setup lang="ts" generic="T">
+const props = defineProps<ListProps<T>>();
+</script>
+```
+
+## v-model Patterns
+
+### PvInput
+```vue
+<PvInput v-model="searchQuery" placeholder="Search..." />
+```
+
+### PvSelectButton
+```vue
+<PvSelectButton
+  v-model="selected"
+  :options="options"
+  label="Choose option"
+  placeholder="Select..."
+/>
+```
+
+### PvModal
+```vue
+<PvModal v-model="isOpen" header="Confirm Action">
+  <template #body>
+    <p>Are you sure?</p>
+  </template>
+  <template #footer>
+    <PvButton variant="ghost" @click="isOpen = false">Cancel</PvButton>
+    <PvButton @click="confirm">Confirm</PvButton>
+  </template>
+</PvModal>
+```
+
+### PvTabs
+```vue
+<PvTabs v-model="activeTab" :tabs="[
+  { label: 'Overview', value: 'overview' },
+  { label: 'Settings', value: 'settings' },
+]" />
+```
+
+## Naming Conventions
+
+Use PascalCase for component names AND HTML attributes (not kebab-case):
+
+```vue
+<!-- Correct -->
+<PvButton leftIcon="plus" isLoading />
+<PvSelectButton optionsVariant="checkbox" />
+
+<!-- Incorrect -->
+<pv-button left-icon="plus" is-loading />
+```
+
+## Common Mistakes
+
+| Mistake | Correct Approach |
+|---------|------------------|
+| Using kebab-case for props | Use PascalCase: `leftIcon` not `left-icon` |
+| Importing from barrel exports | Import directly from component path |
+| Adding `<style scoped>` blocks | Use pv-* utility classes instead |
+| Inline prop types in defineProps | Define interfaces in types.ts |
+| Using raw `<button>`, `<input>` | Use PvButton, PvInput components |
+| Guessing icon names | Verify at https://pitviper.turquoise.health/visual-style/icons/ |
+
+## Styling
+
+Use only Pit Viper utility classes. No custom CSS.
+
+```vue
+<!-- Correct -->
+<div class="pv-flex pv-stack-16">
+  <h1 class="pv-heading-1">Title</h1>
+  <p class="pv-text-body-md pv-text-subdued">Description</p>
+</div>
+
+<!-- Incorrect -->
+<div style="display: flex; margin-bottom: 16px;">
+  <h1 style="font-size: 20px;">Title</h1>
+</div>
+```
+
+## Tables & Charts
+
+### PvDataTable
+
+Use for all tabular data. Never use raw `<table>` elements or custom table markup.
+
+```typescript
+import { PvDataTable } from '@turquoisehealth/pit-viper/components/visualizations'
+
+const colDefs = [
+  { field: 'name', headerName: 'Name', flex: 1 },
+  { field: 'email', headerName: 'Email', flex: 1 },
+  { field: 'role', headerName: 'Role', width: 120 },
+]
+
+const rowData = ref([
+  { name: 'Alice', email: 'alice@example.com', role: 'Admin' },
+  { name: 'Bob', email: 'bob@example.com', role: 'Editor' },
+])
+```
+
+```vue
+<PvDataTable
+  :rowData="rowData"
+  :colDefs="colDefs"
+  :loading="isLoading"
+  style="height: 400px;"
+/>
+```
+
+### PvDataTableWithChart
+
+Use when you need a table with an integrated chart visualization.
+
+```typescript
+import { PvDataTableWithChart } from '@turquoisehealth/pit-viper/components/visualizations'
+```
+
+### PvChart
+
+Use for standalone charts. Never use D3, Chart.js, ApexCharts, or other charting libraries.
+
+```typescript
+import { PvChart } from '@turquoisehealth/pit-viper/components/visualizations'
+
+const chartOptions = {
+  data: [
+    { month: 'Jan', revenue: 50000 },
+    { month: 'Feb', revenue: 62000 },
+    { month: 'Mar', revenue: 58000 },
+  ],
+  series: [
+    {
+      type: 'bar',
+      xKey: 'month',
+      yKey: 'revenue',
+      yName: 'Revenue',
+    },
+  ],
+}
+```
+
+```vue
+<PvChart :options="chartOptions" style="height: 300px;" />
+```
+
+### Table & Chart Mistakes
+
+| Mistake | Correct Approach |
+|---------|------------------|
+| Using raw `<table>` elements | Use PvDataTable component |
+| Importing D3, Chart.js, ApexCharts | Use PvChart component |
+| Custom table CSS/styling | PvDataTable has built-in Pit Viper theme |
+| Building custom sorting/filtering | PvDataTable has AG Grid features built-in |
+
+## Web Component Compatibility
+
+If the component may be used as a web component:
+
+- All non-primitive props (not string/number/boolean) must be optional
+- Boolean props default to `false`
+- Use `::slotted()` in styles for Shadow DOM
+- No scoped or conditional slots (`v-if="$slots.name"`)
+- Complex props must be reactive for post-initialization assignment
+
+---
+
+## Anti-Patterns
+
+### Custom Classes on Components
+
+Don't invent classes. Use pv-* utilities or inline styles for one-offs.
+
+```vue
+<!-- BAD: Custom classes -->
+<template>
+  <div class="settings-container">
+    <PvCard class="settings-card">
+      <PvButton class="submit-btn" label="Save" />
+    </PvCard>
+  </div>
+</template>
+
+<style scoped>
+.settings-container { padding: 24px; }
+.settings-card { max-width: 500px; }
+.submit-btn { margin-top: 16px; }
+</style>
+
+<!-- GOOD: Pit Viper classes + inline for one-offs -->
+<template>
+  <div class="pv-inset-square-24">
+    <PvCard style="max-width: 500px;">
+      <div class="pv-stack-16">
+        <PvButton label="Save" />
+      </div>
+    </PvCard>
+  </div>
+</template>
+```
+
+### Custom CSS / SCSS
+
+Never add `<style>` blocks with custom styling. This defeats the design system.
+
+```vue
+<!-- BAD: Custom SCSS -->
+<template>
+  <div class="error-label">
+    <PvIcon name="info-circle" />
+    <span class="error-label--text">{{ message }}</span>
+  </div>
+</template>
+
+<style lang="scss" scoped>
+.error-label {
+  color: $red-base;
+  display: flex;
+  gap: 8px;
+  
+  &--text {
+    @include text-medium;
+  }
+}
+</style>
+
+<!-- GOOD: Pit Viper classes only -->
+<template>
+  <div class="pv-flex pv-text-error" style="--flex-gap: 0.5rem;">
+    <PvIcon name="info-circle" />
+    <span class="pv-text-body-md">{{ message }}</span>
+  </div>
+</template>
+```
+
+### Raw Tables with Custom Styling
+
+Never build custom tables. Use PvDataTable.
+
+```vue
+<!-- BAD: Raw table with custom styling -->
+<template>
+  <table class="my-table">
+    <thead>
+      <tr>
+        <th>Name</th>
+        <th>Email</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr v-for="user in users" :key="user.id">
+        <td>{{ user.name }}</td>
+        <td>{{ user.email }}</td>
+      </tr>
+    </tbody>
+  </table>
+</template>
+
+<style scoped>
+.my-table { width: 100%; border-collapse: collapse; }
+.my-table th { background: #f5f5f5; padding: 8px; }
+.my-table td { border-bottom: 1px solid #eee; padding: 8px; }
+</style>
+
+<!-- GOOD: PvDataTable -->
+<script setup lang="ts">
+import { PvDataTable } from "@turquoisehealth/pit-viper/components/visualizations";
+
+const colDefs = [
+  { field: "name", headerName: "Name", flex: 1 },
+  { field: "email", headerName: "Email", flex: 1 },
+];
+</script>
+
+<template>
+  <PvDataTable :rowData="users" :colDefs="colDefs" style="height: 400px;" />
+</template>
+```
+
+---
+
+## Good Patterns
+
+### Modal with Proper Structure
+
+```vue
+<script setup lang="ts">
+import { PvButton, PvModal } from "@turquoisehealth/pit-viper/components";
+import { ref } from "vue";
+
+const showModal = defineModel<boolean>({ required: true });
+
+const emit = defineEmits<{
+  (e: "confirm"): void;
+}>();
+
+const close = () => {
+  showModal.value = false;
+};
+</script>
+
+<template>
+  <PvModal
+    v-model="showModal"
+    header="Delete Report?"
+    @close="close"
+    style="--flow-size: 16px; width: 298px"
+  >
+    <template #body>
+      <p class="pv-text-body-sm pv-text-subdued">
+        This action cannot be undone.
+      </p>
+    </template>
+    <template #footer>
+      <div class="pv-flex" style="--flex-justify: flex-end;">
+        <PvButton variant="ghost" @click="close" label="Cancel" size="lg" />
+        <PvButton variant="destructive" @click="emit('confirm')" label="Delete" size="lg" />
+      </div>
+    </template>
+  </PvModal>
+</template>
+```
+
+**What makes this good:**
+- Uses `label` attribute on buttons
+- Proper modal structure with `#body` and `#footer` slots
+- Semantic `variant="destructive"` for delete action
+- Inline style for one-off width constraint
+- CSS custom property `--flow-size` instead of custom class
+
+### Form Actions with Feedback
+
+```vue
+<script setup lang="ts">
+import { PvButton, PvToast } from "@turquoisehealth/pit-viper/components";
+import { ref } from "vue";
+
+const submitting = ref(false);
+const submitError = ref<string | null>(null);
+const submitSuccess = ref(false);
+</script>
+
+<template>
+  <div class="pv-flex-vertical pv-full-width">
+    <div class="pv-space-between pv-inset-block-24 pv-full-width">
+      <PvButton size="xl" label="Cancel" variant="secondary" @click="cancel" />
+      <PvButton
+        size="xl"
+        label="Save"
+        @click="submit"
+        :disabled="submitting"
+        :loading="submitting"
+      />
+    </div>
+    <PvToast
+      v-if="submitSuccess"
+      icon="check-circle"
+      label="Saved successfully!"
+      variant="info"
+    />
+    <PvToast
+      v-if="submitError"
+      icon="alert-circle"
+      :label="submitError"
+      variant="error"
+    />
+  </div>
+</template>
+```
+
+**What makes this good:**
+- Uses `pv-space-between` for button layout
+- Uses `pv-inset-block-24` for vertical padding
+- Uses `:loading` prop instead of custom spinner
+- Uses `PvToast` for feedback instead of custom alerts
+
+### Card with Content Sections
+
+```vue
+<template>
+  <PvCard style="max-width: 500px;">
+    <template #header>
+      <h2 class="pv-heading-3">User Settings</h2>
+    </template>
+    
+    <div class="pv-flex-vertical" style="--flex-gap: 1rem;">
+      <div>
+        <label class="pv-text-title-sm pv-stack-4">Name</label>
+        <PvInput v-model="name" placeholder="Full name" />
+      </div>
+      <div>
+        <label class="pv-text-title-sm pv-stack-4">Email</label>
+        <PvInput v-model="email" type="email" />
+      </div>
+    </div>
+    
+    <template #footer>
+      <div class="pv-flex" style="--flex-justify: flex-end; --flex-gap: 0.5rem;">
+        <PvButton variant="ghost" label="Cancel" @click="cancel" />
+        <PvButton label="Save" @click="save" />
+      </div>
+    </template>
+  </PvCard>
+</template>
+```
+
+**What makes this good:**
+- Uses proper card slots (`#header`, default, `#footer`)
+- Uses `--flex-gap` CSS custom property instead of custom class
+- Uses `--flex-justify` for alignment
+- Inline style for max-width constraint (one-off)
+- Primary action on the right

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turquoisehealth/pit-viper",
-  "version": "2.179.1-dev.0",
+  "version": "2.181.0",
   "description": "Turquoise Health's design system.",
   "main": "README.md",
   "publishConfig": {
@@ -138,8 +138,8 @@
     "build:eleventy": "eleventy",
     "build:pagefind": "pagefind --site _site",
     "build:pv-components": "pnpm --filter pv-components run build",
-    "build:mcp": "pnpm --filter pit-viper-mcp run build",
-    "build:mcp-index": "pnpm --filter pit-viper-mcp run build:index",
+    "build:llm": "pnpm --filter pit-viper-llm run build",
+    "build:llm-index": "pnpm --filter pit-viper-llm run build:index",
     "start": "npm-run-all build:sass --parallel watch:*",
     "build": "npm-run-all build:*",
     "test": "pnpm --filter pv-components run test && pnpm --filter pv-storybook run test:e2e",