@turquoisehealth/pit-viper 2.182.1-dev.5 → 2.183.1-dev.0

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

@@ -1,526 +0,0 @@
-# Vue Guidelines for Pit Viper
-
-Use this reference when generating Vue SFC code (Vue Mode).
-
-## Contents
-
-- Adding Pit Viper (install, CSS, imports)
-- File Structure (script/template/style order)
-- Import Paths (base, visualizations, layout)
-- Props, Emits, Generics Patterns
-- v-model Patterns (input, select, modal, tabs)
-- Naming Conventions
-- Common Mistakes
-- Styling (pv-* classes only)
-- Tables & Charts (PvDataTable, PvChart)
-- Anti-Patterns / Good Patterns
-
-## 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-critical" 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