npm - @turquoisehealth/pit-viper - Versions diffs - 2.179.1-dev.0 → 2.181.0 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (33) hide show

package/claude-plugin/skills/pit-viper/references/html-patterns.md ADDED Viewed

@@ -0,0 +1,451 @@
+# HTML / Web Component Patterns
+Use this reference when generating HTML with Pit Viper CSS classes and web components (Prototype Mode).
+## Adding Pit Viper to Your Project
+### Step 1: Include CSS
+Choose one CSS theme based on your use case:
+| Theme | File | Use Case |
+|-------|------|----------|
+| Platform | `pit-viper-v2.css` | Internal tools, dashboards |
+| Consumer | `pit-viper-consumer.css` | Marketing, public-facing sites |
+### Step 2: Include Web Components
+**Option A: Combined bundle (recommended for 2+ components)**
+```html
+<script src="https://unpkg.com/@turquoisehealth/pit-viper/pv-components/dist/web/pv-components.iife.js"></script>
+```
+Includes all base components. The Vue runtime (~16kb) is bundled automatically.
+**Option B: Standalone components (for minimal usage)**
+```html
+<script src="https://unpkg.com/@turquoisehealth/pit-viper/pv-components/dist/web/pv-button/pv-button.js"></script>
+```
+Import only specific components. Note: each standalone component bundles the Vue runtime, so use the combined bundle if using more than a few components.
+### Complete Setup Example
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Page Title</title>
+  <!-- Pit Viper CSS (choose one) -->
+  <link rel="stylesheet" href="https://pitviper.turquoise.health/assets/css/pit-viper-v2.css">
+  <!-- OR for consumer/marketing sites: -->
+  <!-- <link rel="stylesheet" href="https://pitviper.turquoise.health/assets/css/pit-viper-consumer.css"> -->
+  <!-- Pit Viper Web Components (combined bundle) -->
+  <script src="https://unpkg.com/@turquoisehealth/pit-viper/pv-components/dist/web/pv-components.iife.js"></script>
+</head>
+<body>
+  <!-- Your content here -->
+</body>
+</html>
+```
+## Naming Conventions
+Web components use kebab-case (unlike Vue which uses PascalCase):
+| Vue Component | Web Component |
+|---------------|---------------|
+| `<PvButton>` | `<pv-button>` |
+| `<PvInput>` | `<pv-input>` |
+| `<PvSelectButton>` | `<pv-select-button>` |
+| `<PvCard>` | `<pv-card>` |
+Properties are also kebab-case:
+| Vue Prop | HTML Attribute |
+|----------|----------------|
+| `leftIcon` | `left-icon` |
+| `isLoading` | `is-loading` |
+| `optionsVariant` | `options-variant` |
+## Web Component Best Practices
+These rules are critical for web components to work correctly:
+### 1. Always Use Complete End Tags
+Web components **require** full closing tags. Self-closing tags will break slots.
+```html
+<!-- CORRECT -->
+<pv-button>Click me</pv-button>
+<pv-card></pv-card>
+<!-- WRONG - slots will not work -->
+<pv-button />
+<pv-card />
+```
+### 2. Slots Must Use Div Wrappers
+Unlike Vue's `<template #slot-name>`, web component slots need a wrapper element with the `slot` attribute:
+```html
+<!-- CORRECT for web components -->
+<pv-card>
+  <div slot="header">Header content</div>
+  <div slot="default">Body content</div>
+  <div slot="footer">Footer content</div>
+</pv-card>
+<!-- Vue shorthand (does NOT work in web components) -->
+<PvCard>
+  <template #header>Header content</template>
+</PvCard>
+```
+### 3. No Scoped or Conditional Slots
+Web components do not support:
+- Scoped slots (slots that pass data back to the parent)
+- Conditional slots (`v-if="$slots.someSlot"` patterns)
+Always render slot content statically.
+### 4. Complex Props Require JavaScript
+Arrays, objects, and functions cannot be passed as HTML attributes:
+```html
+<!-- Primitive props work as attributes -->
+<pv-button variant="secondary" disabled>OK</pv-button>
+<!-- Complex props must be set via JavaScript -->
+<pv-select-button id="my-select"></pv-select-button>
+<script>
+  document.getElementById('my-select').options = [
+    { label: 'Option 1', value: '1' },
+    { label: 'Option 2', value: '2' },
+  ];
+</script>
+```
+### 5. Base Components Only
+Web component support is limited to **base components** (buttons, inputs, cards, etc.).
+**Not available as web components:**
+- `PvDataTable` (use Vue or CSS tables)
+- `PvChart` (requires Vue)
+- Other visualization components
+For more details, see the [Vue Web Components documentation](https://vuejs.org/guide/extras/web-components).
+## Component Examples
+### Button
+The pv-button web component uses the `label` attribute for button text (not slot content).
+```html
+<pv-button label="Click me"></pv-button>
+<pv-button label="Secondary" variant="secondary"></pv-button>
+<pv-button label="Add Item" variant="ghost" left-icon="plus"></pv-button>
+<pv-button label="Saving..." loading></pv-button>
+```
+### Input
+```html
+<pv-input placeholder="Enter text..." id="my-input"></pv-input>
+<script>
+  const input = document.getElementById('my-input');
+  input.addEventListener('input', (e) => {
+    console.log('Value:', e.target.value);
+  });
+</script>
+```
+### Card
+```html
+<pv-card>
+  <div slot="header">
+    <h2 class="pv-heading-2">Card Title</h2>
+  </div>
+  <div slot="default">
+    <p class="pv-text-body-md">Card content goes here.</p>
+  </div>
+  <div slot="footer">
+    <pv-button>Action</pv-button>
+  </div>
+</pv-card>
+```
+## Event Handling
+Web components emit custom events. Use `addEventListener`:
+```html
+<pv-button id="my-button">Click me</pv-button>
+<script>
+  document.getElementById('my-button').addEventListener('click', () => {
+    console.log('Button clicked');
+  });
+</script>
+```
+For components with custom events:
+```html
+<pv-select-button id="my-select"></pv-select-button>
+<script>
+  const select = document.getElementById('my-select');
+  // Set options via JavaScript (complex props can't be set as attributes)
+  select.options = [
+    { label: 'Option 1', value: '1' },
+    { label: 'Option 2', value: '2' },
+  ];
+  // Listen for value changes
+  select.addEventListener('update:modelValue', (e) => {
+    console.log('Selected:', e.detail);
+  });
+</script>
+```
+## Complex Props
+Non-primitive props (arrays, objects) must be set via JavaScript, not HTML attributes:
+```html
+<pv-data-table id="my-table"></pv-data-table>
+<script>
+  const table = document.getElementById('my-table');
+  table.colDefs = [
+    { field: 'name', headerName: 'Name' },
+    { field: 'email', headerName: 'Email' },
+  ];
+  table.rowData = [
+    { name: 'Alice', email: 'alice@example.com' },
+    { name: 'Bob', email: 'bob@example.com' },
+  ];
+</script>
+```
+## CSS Classes
+Use pv-* utility classes for layout and styling:
+```html
+<div class="pv-flex pv-flex-vertical pv-stack-16">
+  <h1 class="pv-heading-1">Page Title</h1>
+  <p class="pv-text-body-md pv-text-subdued">Description text</p>
+</div>
+<div class="pv-card pv-inset-square-24 pv-radius">
+  <p class="pv-text-body-md">Card content</p>
+</div>
+```
+## Tables
+Use pv-table CSS classes for static tables. For interactive tables with sorting/filtering, use Vue with PvDataTable instead.
+### Basic Table
+```html
+<table class="pv-table">
+  <thead>
+    <tr>
+      <th>Name</th>
+      <th>Email</th>
+      <th>Role</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Alice Johnson</td>
+      <td>alice@example.com</td>
+      <td>Admin</td>
+    </tr>
+    <tr>
+      <td>Bob Smith</td>
+      <td>bob@example.com</td>
+      <td>Editor</td>
+    </tr>
+  </tbody>
+</table>
+```
+### Table Variants
+| Class | Use Case |
+|-------|----------|
+| `.pv-table` | Standard table with header styling |
+| `.pv-table-compressed` | Compact rows for dense data |
+| `.pv-table-bordered` | Full borders on all cells |
+| `.pv-table-matrix` | Matrix/grid layout with sticky headers |
+### Sortable Headers
+Use `data-sort` attribute for sort indicators:
+```html
+<th data-sort>Name</th>
+<th data-sort="ascending">Email</th>
+<th data-sort="descending">Date</th>
+```
+## Charts
+**Charts are NOT available in HTML/Prototype mode.** Charting requires Vue components (PvChart, PvDataTableWithChart).
+If the user requests a chart in HTML mode:
+1. Explain that charts require Vue components
+2. Offer to switch to Vue (Engineer Mode) if appropriate
+3. Or use a placeholder with a note: "Chart visualization requires Vue implementation"
+## Limitations
+Web components have some differences from Vue components:
+| Limitation | Workaround |
+|------------|------------|
+| No v-model | Use events + property assignment |
+| No scoped slots | Use named slots with `slot="name"` |
+| No conditional slots | Always render slot content |
+| Complex props as attributes | Set via JavaScript |
+| No Vue reactivity | Manually update properties |
+| No charts | Charts require Vue — use PvChart |
+## Complete Example
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Login</title>
+  <link rel="stylesheet" href="https://pitviper.turquoise.health/assets/css/pit-viper-v2.css">
+  <script src="https://unpkg.com/@turquoisehealth/pit-viper/pv-components/dist/web/pv-components.iife.js"></script>
+</head>
+<body class="pv-surface-accent">
+  <div class="pv-flex" style="min-height: 100vh; align-items: center; justify-content: center;">
+    <pv-card style="width: 400px;">
+      <div slot="header">
+        <h1 class="pv-heading-2">Sign In</h1>
+      </div>
+      <div slot="default" class="pv-flow-16">
+        <div>
+          <label class="pv-text-title-sm pv-stack-4">Email</label>
+          <pv-input id="email" type="email" placeholder="you@example.com"></pv-input>
+        </div>
+        <div>
+          <label class="pv-text-title-sm pv-stack-4">Password</label>
+          <pv-input id="password" type="password" placeholder="Enter password"></pv-input>
+        </div>
+      </div>
+      <div slot="footer">
+        <pv-button id="submit" label="Sign In" style="width: 100%;"></pv-button>
+      </div>
+    </pv-card>
+  </div>
+  <script>
+    document.getElementById('submit').addEventListener('click', () => {
+      const email = document.getElementById('email').value;
+      const password = document.getElementById('password').value;
+      console.log('Login attempt:', { email, password });
+    });
+  </script>
+</body>
+</html>
+```
+---
+## Anti-Patterns
+### Button Slot Content Instead of Label
+Web components require the `label` attribute. Slot content won't render.
+```html
+<!-- BAD: Slot content -->
+<pv-button>Click me</pv-button>
+<pv-button variant="secondary">Cancel</pv-button>
+<!-- GOOD: Label attribute -->
+<pv-button label="Click me"></pv-button>
+<pv-button variant="secondary" label="Cancel"></pv-button>
+```
+---
+## Good Patterns
+### Sidebar Navigation
+```html
+<div class="pv-card pv-inset-square-8 pv-flex pv-stack-24 pv-full-width">
+  <div class="pv-flex">
+    <img src="logo.png" alt="Logo" class="pv-icon-24" />
+    <span class="pv-text-title-lg pv-text-default">Organization Name</span>
+  </div>
+</div>
+<ul role="list" class="pv-popover-list" style="padding: 0px; --flow-size: 2px;">
+  <li data-active>
+    <a href="/overview" style="text-decoration: none; cursor: pointer;">
+      <svg aria-hidden="true" class="pv-icon pv-text-subdued">
+        <use xlink:href="#file"></use>
+      </svg>
+      <span class="pv-text-body-md">Overview</span>
+    </a>
+  </li>
+  <li>
+    <a href="/settings" style="text-decoration: none; cursor: pointer;">
+      <svg aria-hidden="true" class="pv-icon pv-text-subdued">
+        <use xlink:href="#sliders-horizontal"></use>
+      </svg>
+      <span class="pv-text-body-md">Settings</span>
+    </a>
+  </li>
+</ul>
+```
+**What makes this good:**
+- Uses `pv-card` with `pv-inset-square-8` for consistent padding
+- Uses `pv-popover-list` for nav styling (reused for sidebar nav — same visual pattern)
+- Uses `data-active` attribute for active state
+- Uses `pv-icon` and `pv-text-subdued` for icon styling
+- Minimal inline styles for link resets only
+### Form Fields with Labels
+```html
+<div class="pv-stack-24">
+  <div>
+    <label class="pv-text-title-sm pv-stack-4">Group Name</label>
+    <pv-input placeholder="Enter group name"></pv-input>
+  </div>
+  <div>
+    <label class="pv-text-title-sm pv-stack-4">Description</label>
+    <pv-input placeholder="Optional description"></pv-input>
+  </div>
+</div>
+```
+**What makes this good:**
+- Uses `pv-stack-4` between label and input (tight coupling)
+- Uses `pv-stack-24` between field groups (section spacing)
+- Uses `pv-text-title-sm` for labels (consistent typography)