npm - spoko-design-system - Versions diffs - 1.11.1 → 1.11.2 - Mend

spoko-design-system 1.11.1 → 1.11.2

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 (6) hide show

package/CHANGELOG.md +2 -0
package/TOOLTIPS.md +236 -0
package/package.json +2 -2
package/src/pages/components/pr-code.mdx +1 -0
package/src/pages/components/product-engine.mdx +18 -14
package/src/pages/core/tooltips.mdx +491 -0

package/CHANGELOG.md CHANGED Viewed

@@ -1,3 +1,5 @@
+## [1.11.2](https://github.com/polo-blue/sds/compare/v1.11.1...v1.11.2) (2025-10-30)
 ## [1.11.1](https://github.com/polo-blue/sds/compare/v1.11.0...v1.11.1) (2025-10-30)
 ### Bug Fixes

package/TOOLTIPS.md ADDED Viewed

@@ -0,0 +1,236 @@
+# Tooltip System Documentation
+## Overview
+SDS includes a complete tooltip system built on [Tippy.js](https://atomiks.github.io/tippyjs/) with custom styling and automatic initialization.
+## Features
+- 🎨 Custom SDS theme matching design system colors
+- ⚡ Performance-optimized delegation pattern
+- 🔄 Automatic support for Astro View Transitions
+- 🎯 Simple data-attribute API
+- 📦 All dependencies bundled (no need to install tippy.js separately)
+## Installation
+**Option 1: Automatic initialization (recommended)**
+Import the complete tooltip system in your layout's script tag:
+```astro
+---
+// In your BaseLayout.astro or HeadCommon.astro
+---
+<head>
+  <!-- ... other head elements -->
+  <script src="/src/scripts/tooltips.ts"></script>
+</head>
+```
+```ts
+// In your /src/scripts/tooltips.ts
+import 'spoko-design-system/scripts/tooltips';
+```
+**Option 2: Manual initialization**
+If you need more control:
+```ts
+import { initTooltips } from 'spoko-design-system';
+// Initialize tooltips manually
+initTooltips();
+```
+## Usage
+Add tooltips to any element using the `data-tippy-content` attribute:
+```astro
+<span data-tippy-content="This is a tooltip">
+  Hover over me
+</span>
+```
+### With HTML content
+```astro
+<span data-tippy-content="<strong>Bold text</strong> and <em>italic</em>">
+  Rich tooltip
+</span>
+```
+### Structured tooltips (like engine codes)
+The system supports structured tooltips with headers and specs:
+```astro
+<span
+  class="engine-code"
+  data-tippy-content={tooltipHTML}
+>
+  CAYA
+</span>
+```
+Where `tooltipHTML` can be generated using:
+```ts
+import { getEngineTooltipContent } from 'spoko-design-system';
+const tooltipHTML = getEngineTooltipContent(engine, translations);
+```
+## Components with built-in tooltips
+These SDS components automatically include tooltip functionality:
+- `<ProductEngine>` - Engine codes with detailed specs
+- `<ProductEngines>` - List of engine codes
+- `<ProductCodes>` - PR codes (when descriptions are available)
+## Styling
+The tooltip theme uses SDS design tokens:
+- Background: `neutral-lightest` (#f3f4f6)
+- Text: `slate-darkest` (#1e293b)
+- Border: `neutral-lighter` (#e5e7eb)
+- Header (engine tooltips): `accent-deepBlue` (#001e50)
+To customize, override the `.tippy-box[data-theme~='sds']` class in your project.
+## Dependencies
+SDS includes `tippy.js` as a dependency, so your project **does not need to install it separately**.
+If your project already has `tippy.js` installed, you can safely remove it:
+```bash
+pnpm remove tippy.js
+```
+## Technical Details
+### Delegation Pattern
+The tooltip system uses Tippy.js's delegation pattern for optimal performance:
+- Single event listener on `body`
+- Targets all `[data-tippy-content]` elements
+- No need to re-initialize when DOM changes
+- Works with dynamically added content
+### Astro View Transitions
+The system automatically re-initializes on Astro page navigation:
+```ts
+document.addEventListener('astro:page-load', () => {
+  initTooltips();
+});
+```
+### Configuration
+Default configuration (in `src/scripts/tooltips.ts`):
+```ts
+{
+  target: '[data-tippy-content]',
+  allowHTML: true,
+  theme: 'sds',
+  placement: 'top',
+  arrow: true,
+  animation: 'shift-away',
+  duration: [200, 150],
+  maxWidth: 280
+}
+```
+## Troubleshooting
+### Tooltips not showing
+1. Verify the script is imported in your layout
+2. Check that elements have `data-tippy-content` attribute
+3. Ensure content is not empty or "undefined"
+4. Check browser console for errors
+### Double tooltips or conflicts
+If you see duplicate tooltips:
+1. Make sure you're only importing the tooltip script once
+2. Don't call `initTooltips()` manually if using auto-initialization
+3. Remove any local tippy.js installations that might conflict
+### Styling not applied
+1. Verify SDS theme CSS is imported (included in script import)
+2. Check CSS specificity - SDS uses `!important` for some properties
+3. Ensure your build process handles CSS imports from node_modules
+## Examples
+### Basic tooltip
+```astro
+<button data-tippy-content="Click to save">
+  Save
+</button>
+```
+### Engine code tooltip
+```astro
+---
+import { ProductEngine } from 'spoko-design-system';
+const engine = {
+  code: 'CAYA',
+  name: '1.6 TDI',
+  power: { kw: 55, ps: 75, ps_label: 'PS', label: 'Power' },
+  displacement: { value: 1598, label: 'Displacement' },
+  euro: { value: 5, label: 'Standard' }
+};
+---
+<ProductEngine engine={engine} />
+```
+### Custom structured tooltip
+```astro
+<span data-tippy-content={`
+  <div class="tooltip-header">
+    <strong>Custom Header</strong>
+  </div>
+  <div class="tooltip-specs">
+    <div class="tooltip-row">
+      <span class="tooltip-label">Label:</span>
+      <span class="tooltip-value">Value</span>
+    </div>
+  </div>
+`}>
+  Custom tooltip
+</span>
+```
+## Migration from standalone Tippy.js
+If migrating from a direct Tippy.js implementation:
+1. Remove `tippy.js` from package.json
+2. Remove local tooltip initialization code
+3. Import SDS tooltip script: `import 'spoko-design-system/scripts/tooltips'`
+4. Update elements to use `data-tippy-content` instead of manual initialization
+5. Update custom styles to target `.tippy-box[data-theme~='sds']`
+## Support
+For issues or feature requests, please open an issue at:
+https://github.com/polo-blue/sds/issues

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "spoko-design-system",
-  "version": "1.11.1",
+  "version": "1.11.2",
   "type": "module",
   "private": false,
   "main": "./index.ts",
@@ -128,7 +128,7 @@
     "@vitejs/plugin-vue": "^6.0.1",
     "@vue/compiler-sfc": "^3.5.22",
     "@vue/eslint-config-typescript": "^14.6.0",
-    "astro": "^5.15.2",
+    "astro": "^5.15.3",
     "conventional-changelog-conventionalcommits": "^9.1.0",
     "eslint": "^9.38.0",
     "eslint-plugin-astro": "^1.4.0",

package/src/pages/components/pr-code.mdx CHANGED Viewed

@@ -204,6 +204,7 @@ When using data from the API, pass the `pr_codes` array directly:
 ## Notes
+- **Tooltip setup required**: Import `'spoko-design-system/scripts/tooltips'` once in your layout (see [Tooltips documentation](/core/tooltips))
 - Hover over any PR code to see its full description
 - Colors are based on semantic variant categories, not hardcoded per code
 - Combined codes are displayed as `CODE+CODE` with each code colored independently

package/src/pages/components/product-engine.mdx CHANGED Viewed

@@ -25,18 +25,28 @@ Display a single engine code with tooltip showing detailed engine information.
 import { ProductEngine } from 'spoko-design-system'
 ```
-**2. Initialize tooltips in your layout (once):**
+**2. Initialize tooltips (one-time setup):**
+Create a tooltip script in your project:
+```ts
+// src/scripts/tooltips.ts
+import 'spoko-design-system/scripts/tooltips';
+```
+Then import it in your layout's `<head>`:
 ```astro
 ---
-// In your layout file (e.g., Layout.astro)
+// In your layout file (e.g., HeadCommon.astro)
 ---
-<script>
-  import { initTooltips } from 'spoko-design-system';
-  initTooltips();
-</script>
+<head>
+  <script src="/src/scripts/tooltips.ts"></script>
+</head>
 ```
+See [Tooltips documentation](/core/tooltips) for details.
 ### Basic Usage (New API Structure):
 <div class="component-preview">
@@ -385,7 +395,7 @@ Special engine codes are automatically color-coded:
 ## Notes
-- **Setup required**: Call `initTooltips()` once in your layout to enable tooltips
+- **Setup required**: Import `'spoko-design-system/scripts/tooltips'` once in your layout (see [Tooltips docs](/core/tooltips))
 - Hover over any engine code to see full specifications in a detailed tooltip
 - Tooltips use Tippy.js delegation pattern (one global handler for all tooltips)
 - **Performance**: No client-side hydration needed - pure Astro components
@@ -403,12 +413,6 @@ Special engine codes are automatically color-coded:
 If upgrading from the old Vue version:
 1. **Remove `client:load`** directive from all ProductEngine/ProductEngines usage
-2. **Add tooltip initialization** to your layout:
-   ```astro
-   <script>
-     import { initTooltips } from 'spoko-design-system';
-     initTooltips();
-   </script>
-   ```
+2. **Set up tooltips** in your layout (see [Tooltips documentation](/core/tooltips))
 3. **Update imports** to use Astro components (automatically handled by package exports)
 4. **No other changes needed** - props and API structure remain the same

package/src/pages/core/tooltips.mdx ADDED Viewed

@@ -0,0 +1,491 @@
+---
+title: "Tooltips"
+layout: "../../layouts/MainLayout.astro"
+---
+# Tooltips
+A complete tooltip system built on [Tippy.js](https://atomiks.github.io/tippyjs/) with custom SDS styling and automatic initialization.
+## Features
+- 🎨 **Custom SDS Theme** - Matches design system colors
+- ⚡ **Performance Optimized** - Delegation pattern handles thousands of tooltips efficiently
+- 🔄 **Astro View Transitions** - Automatic re-initialization on navigation
+- 🎯 **Simple API** - Just add a data attribute
+- 📦 **Bundled** - No need to install tippy.js separately in your project
+- 🔍 **SEO Friendly** - Content rendered in HTML, enhanced progressively
+## Installation
+### Step 1: Create a tooltip initialization script
+In your project, create a script file (e.g., `src/scripts/tooltips.ts`):
+```ts
+// src/scripts/tooltips.ts
+import 'spoko-design-system/scripts/tooltips';
+```
+That's it! This single import includes:
+- ✅ Tippy.js library
+- ✅ Base Tippy.js CSS
+- ✅ SDS custom theme CSS
+- ✅ Auto-initialization logic
+- ✅ Astro View Transitions support
+### Step 2: Import in your layout
+Add the script to your main layout's `<head>`:
+```astro
+---
+// src/layouts/BaseLayout.astro or HeadCommon.astro
+---
+<head>
+  <!-- ... other head elements -->
+  <script src="/src/scripts/tooltips.ts"></script>
+</head>
+```
+## Usage
+### Basic Tooltip
+Add the `data-tippy-content` attribute to any element:
+<div class="component-preview">
+  <div class="bg-white p-6 w-full">
+    <button
+      class="px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700"
+      data-tippy-content="This is a basic tooltip">
+      Hover over me
+    </button>
+  </div>
+</div>
+```astro
+<button data-tippy-content="This is a basic tooltip">
+  Hover over me
+</button>
+```
+### HTML Content
+Tooltips support HTML content:
+<div class="component-preview">
+  <div class="bg-white p-6 w-full">
+    <span
+      class="underline decoration-dotted cursor-help"
+      data-tippy-content="<strong>Bold text</strong> and <em>italic text</em>">
+      HTML tooltip
+    </span>
+  </div>
+</div>
+```astro
+<span data-tippy-content="<strong>Bold text</strong> and <em>italic text</em>">
+  HTML tooltip
+</span>
+```
+### Structured Tooltips
+For complex tooltips with headers and multiple sections:
+<div class="component-preview">
+  <div class="bg-white p-6 w-full">
+    <span
+      class="underline decoration-dotted cursor-help text-blue-600"
+      data-tippy-content='<div class="tooltip-header"><strong>Product Details</strong></div><div class="tooltip-specs"><div class="tooltip-row"><span class="tooltip-label">SKU:</span><span class="tooltip-value">12345</span></div><div class="tooltip-row"><span class="tooltip-label">Weight:</span><span class="tooltip-value">2.5 kg</span></div></div>'>
+      Product Info
+    </span>
+  </div>
+</div>
+```astro
+<span data-tippy-content={`
+  <div class="tooltip-header">
+    <strong>Product Details</strong>
+  </div>
+  <div class="tooltip-specs">
+    <div class="tooltip-row">
+      <span class="tooltip-label">SKU:</span>
+      <span class="tooltip-value">12345</span>
+    </div>
+    <div class="tooltip-row">
+      <span class="tooltip-label">Weight:</span>
+      <span class="tooltip-value">2.5 kg</span>
+    </div>
+  </div>
+`}>
+  Product Info
+</span>
+```
+## Components with Built-in Tooltips
+These SDS components automatically include tooltips:
+### ProductEngine & ProductEngines
+Engine codes with detailed specification tooltips:
+```astro
+import { ProductEngines } from 'spoko-design-system';
+<ProductEngines engines={product.part_engines} />
+```
+See [ProductEngine documentation](/components/product-engine) for details.
+### ProductCodes
+PR codes with description tooltips (when available):
+```astro
+import { ProductCodes } from 'spoko-design-system';
+<ProductCodes prcodes={product.pr_codes} isPdp={true} />
+```
+## Styling
+### SDS Theme
+The default SDS theme uses these design tokens:
+| Property | Value | Token |
+|----------|-------|-------|
+| Background | `#f3f4f6` | `neutral-lightest` |
+| Text Color | `#1e293b` | `slate-darkest` |
+| Border | `#e5e7eb` | `neutral-lighter` |
+| Header Background | `#001e50` | `accent-deepBlue` |
+| Max Width | `280px` | - |
+| Border Radius | `0.5rem` | - |
+### Custom Styling
+To customize the tooltip appearance, override these CSS classes:
+```css
+/* Main tooltip box */
+.tippy-box[data-theme~='sds'] {
+  background-color: your-color !important;
+  color: your-text-color !important;
+}
+/* Tooltip content area */
+.tippy-box[data-theme~='sds'] .tippy-content {
+  padding: 0.5rem 0.75rem;
+}
+/* Structured tooltip header */
+.tippy-box[data-theme~='sds'] .tooltip-header {
+  background-color: your-header-color;
+  color: white;
+  padding: 0.375rem 0.5rem;
+}
+/* Tooltip specs rows */
+.tippy-box[data-theme~='sds'] .tooltip-row {
+  display: flex;
+  justify-content: space-between;
+  padding: 0.25rem 0;
+}
+```
+### Available CSS Classes
+For structured tooltips:
+| Class | Purpose |
+|-------|---------|
+| `.tooltip-header` | Dark blue header section |
+| `.tooltip-specs` | Container for specification rows |
+| `.tooltip-row` | Single specification row |
+| `.tooltip-label` | Left-aligned label text |
+| `.tooltip-value` | Right-aligned value text |
+## Configuration
+The tooltip system uses these default settings:
+```ts
+{
+  target: '[data-tippy-content]',  // Target selector
+  allowHTML: true,                  // Allow HTML in content
+  theme: 'sds',                     // SDS custom theme
+  placement: 'top',                 // Default placement
+  arrow: true,                      // Show arrow
+  animation: 'shift-away',          // Animation style
+  duration: [200, 150],            // [show, hide] duration (ms)
+  maxWidth: 280,                    // Maximum width (px)
+}
+```
+To customize, you can create your own initialization:
+```ts
+// src/scripts/custom-tooltips.ts
+import { delegate } from 'tippy.js';
+import 'tippy.js/dist/tippy.css';
+import 'spoko-design-system/styles/tippy-theme.css';
+export function initCustomTooltips() {
+  delegate('body', {
+    target: '[data-tippy-content]',
+    allowHTML: true,
+    theme: 'sds',
+    placement: 'bottom',  // Changed from 'top'
+    maxWidth: 400,        // Wider tooltips
+    // ... other options
+  });
+}
+// Initialize
+if (typeof document !== 'undefined') {
+  document.addEventListener('astro:page-load', () => {
+    initCustomTooltips();
+  });
+}
+```
+## Technical Details
+### Delegation Pattern
+The tooltip system uses Tippy.js's delegation pattern:
+- **Single event listener** on `body` handles all tooltips
+- **No re-initialization needed** when DOM changes
+- **Efficient memory usage** - scales to thousands of tooltips
+- **Dynamic content support** - works with client-side rendering
+### How It Works
+1. One global event listener watches for mouseenter/focus on `[data-tippy-content]` elements
+2. Tooltip instance created on-demand when user hovers
+3. Instance destroyed when tooltip hides
+4. No memory leaks from orphaned instances
+### Astro View Transitions
+The system automatically handles Astro's View Transitions:
+```ts
+document.addEventListener('astro:page-load', () => {
+  initTooltips();
+});
+```
+This ensures tooltips work correctly after client-side navigation.
+## API Reference
+### initTooltips()
+Initializes the global tooltip delegation.
+**Import:**
+```ts
+import { initTooltips } from 'spoko-design-system';
+```
+**Usage:**
+```ts
+initTooltips();
+```
+**Note:** Usually not needed if you import `'spoko-design-system/scripts/tooltips'` which auto-initializes.
+### getEngineTooltipContent()
+Generates HTML content for engine tooltips.
+**Import:**
+```ts
+import { getEngineTooltipContent } from 'spoko-design-system';
+```
+**Usage:**
+```ts
+const tooltipHTML = getEngineTooltipContent(engine, translations);
+```
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `engine` | `Engine` | Yes | Engine object with nested structure |
+| `translations` | `EngineTranslations` | No | Optional translation overrides |
+**Returns:** HTML string for tooltip content
+See [ProductEngine documentation](/components/product-engine) for `Engine` interface details.
+## Dependencies
+SDS includes `tippy.js` as a dependency. **Your project does not need to install it separately.**
+If you have `tippy.js` in your project's `package.json`, you can safely remove it:
+```bash
+pnpm remove tippy.js
+# or
+npm uninstall tippy.js
+```
+## Troubleshooting
+### Tooltips not showing
+**Check these items:**
+1. ✅ Script imported in layout: `<script src="/src/scripts/tooltips.ts"></script>`
+2. ✅ Elements have `data-tippy-content` attribute
+3. ✅ Content is not empty or "undefined"
+4. ✅ Hard refresh browser (Ctrl+Shift+R) to clear cache
+### Double tooltips or conflicts
+If you see duplicate tooltips:
+1. Only import the tooltip script **once** in your layout
+2. Don't call `initTooltips()` manually if using auto-initialization
+3. Remove any local `tippy.js` installations that might conflict
+### Tooltips not working after navigation
+If tooltips break after Astro View Transitions:
+1. Verify `astro:page-load` event listener is registered (included in SDS script)
+2. Check browser console for errors
+3. Make sure View Transitions are properly configured in Astro
+### Styling not applied
+1. Verify SDS theme CSS is imported (included in SDS tooltip script)
+2. Check CSS specificity - SDS uses `!important` for some properties
+3. Ensure your build process handles CSS imports from `node_modules`
+### Performance issues
+If you have thousands of tooltips and notice lag:
+1. The delegation pattern should handle this efficiently
+2. Check if you're calling `initTooltips()` multiple times
+3. Consider lazy-loading tooltip-heavy sections
+## Browser Support
+Tooltips work in all modern browsers:
+- ✅ Chrome/Edge (latest)
+- ✅ Firefox (latest)
+- ✅ Safari (latest)
+- ✅ Mobile browsers (iOS Safari, Chrome Android)
+**Note:** Requires JavaScript. Content is still visible if JS is disabled (progressive enhancement).
+## Examples
+### Product Specification
+```astro
+<dl>
+  <dt>Weight</dt>
+  <dd>
+    <span data-tippy-content="Includes packaging">
+      2.5 kg
+    </span>
+  </dd>
+</dl>
+```
+### Help Icons
+```astro
+<label>
+  Email
+  <span
+    class="inline-block ml-1 text-gray-400 cursor-help"
+    data-tippy-content="We'll never share your email">
+    ⓘ
+  </span>
+</label>
+```
+### Technical Terms
+```astro
+<p>
+  The part fits all
+  <abbr
+    data-tippy-content="Volkswagen Aktiengesellschaft Group"
+    class="cursor-help underline decoration-dotted">
+    VAG
+  </abbr>
+  vehicles from 2009-2014.
+</p>
+```
+## Best Practices
+### ✅ Do
+- Use semantic HTML with tooltips as enhancement
+- Keep tooltip content concise (< 50 words)
+- Use structured tooltips for multiple data points
+- Include proper ARIA labels when needed
+- Test on mobile devices
+### ❌ Don't
+- Put critical information only in tooltips
+- Use tooltips for large blocks of text
+- Nest interactive elements inside tooltips
+- Use tooltips on disabled elements
+- Initialize tooltips multiple times
+## Migration
+### From Direct Tippy.js
+If migrating from a direct Tippy.js implementation:
+1. **Remove** `tippy.js` from your `package.json`
+2. **Remove** local tooltip initialization code
+3. **Add** SDS tooltip script import
+4. **Update** elements to use `data-tippy-content`
+5. **Update** custom styles to target `.tippy-box[data-theme~='sds']`
+### From Old SDS Setup
+If you had the old setup with manual initialization:
+**Old way (remove this):**
+```astro
+<script>
+  import { initTooltips } from 'spoko-design-system';
+  initTooltips();
+</script>
+```
+**New way (use this):**
+```astro
+<script src="/src/scripts/tooltips.ts"></script>
+```
+```ts
+// src/scripts/tooltips.ts
+import 'spoko-design-system/scripts/tooltips';
+```
+## Related Documentation
+- [ProductEngine Component](/components/product-engine) - Engine codes with tooltips
+- [ProductCodes Component](/components/pr-code) - PR codes with tooltips
+- [Tippy.js Documentation](https://atomiks.github.io/tippyjs/) - Underlying library