snice 4.9.0 → 4.10.0

package/docs/components/map.md

@@ -0,0 +1,203 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/map.md instead)
+
+# Map Component
+
+`<snice-map>`
+
+An interactive slippy map component using OpenStreetMap tiles. Supports markers with popups, drag panning, scroll zoom, and programmatic control over the viewport.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Methods](#methods)
+- [Events](#events)
+- [Types](#types)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Basic Usage
+
+```typescript
+import 'snice/components/map/snice-map';
+```
+
+```html
+<snice-map zoom="13"></snice-map>
+```
+
+## Importing
+
+**ESM (bundler)**
+```typescript
+import 'snice/components/map/snice-map';
+```
+
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-map.min.js"></script>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `center` | `MapCenter` | `{ lat: 51.505, lng: -0.09 }` | Map center coordinates (set via JavaScript) |
+| `zoom` | `number` | `13` | Current zoom level |
+| `minZoom` (attr: `min-zoom`) | `number` | `1` | Minimum allowed zoom level |
+| `maxZoom` (attr: `max-zoom`) | `number` | `18` | Maximum allowed zoom level |
+| `markers` | `MapMarker[]` | `[]` | Array of marker data (set via JavaScript) |
+| `tileUrl` (attr: `tile-url`) | `string` | `'https://tile.openstreetmap.org/{z}/{x}/{y}.png'` | Tile server URL template with `{x}`, `{y}`, `{z}` placeholders |
+
+## Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `setCenter()` | `lat: number, lng: number` | Pan the map to the specified coordinates |
+| `setZoom()` | `zoom: number` | Set the zoom level (clamped to min/max range) |
+| `addMarker()` | `marker: MapMarker` | Add a single marker to the map |
+| `removeMarker()` | `id: string` | Remove a marker by its ID |
+| `fitBounds()` | `markers?: MapMarker[]` | Auto-zoom and center to fit all markers. Defaults to all current markers if none specified |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `map-click` | `{ lat: number; lng: number }` | Fired when the map is clicked (not on a marker) |
+| `marker-click` | `{ marker: MapMarker }` | Fired when a marker is clicked. Also toggles the marker's popup |
+| `map-move` | `{ center: MapCenter; zoom: number }` | Fired after a drag pan operation completes |
+| `map-zoom` | `{ zoom: number }` | Fired when the zoom level changes |
+
+## Types
+
+### MapCenter
+
+```typescript
+interface MapCenter {
+  lat: number;
+  lng: number;
+}
+```
+
+### MapMarker
+
+```typescript
+interface MapMarker {
+  id: string;       // Unique identifier
+  lat: number;      // Latitude
+  lng: number;      // Longitude
+  label?: string;   // Marker label text
+  icon?: string;    // Custom icon URL
+  popup?: string;   // Popup text shown on marker click
+}
+```
+
+## Examples
+
+### Setting the Map Center
+
+Set the `center` property via JavaScript to position the map on a specific location.
+
+```html
+<snice-map id="my-map" zoom="10"></snice-map>
+
+<script type="module">
+  import 'snice/components/map/snice-map';
+
+  const map = document.getElementById('my-map');
+  map.center = { lat: 40.7128, lng: -74.006 };
+</script>
+```
+
+### Adding Markers
+
+Use the `markers` property to display pins on the map with optional labels and popups.
+
+```html
+<snice-map id="city-map" zoom="5"></snice-map>
+
+<script type="module">
+  import 'snice/components/map/snice-map';
+
+  const map = document.getElementById('city-map');
+  map.center = { lat: 39.8283, lng: -98.5795 };
+  map.markers = [
+    { id: 'nyc', lat: 40.7128, lng: -74.006, label: 'New York', popup: 'The Big Apple' },
+    { id: 'chi', lat: 41.8781, lng: -87.6298, label: 'Chicago', popup: 'The Windy City' },
+    { id: 'la', lat: 34.0522, lng: -118.2437, label: 'Los Angeles', popup: 'City of Angels' }
+  ];
+</script>
+```
+
+### Fit to Markers
+
+Use `fitBounds()` to automatically zoom and center the map so all markers are visible.
+
+```html
+<snice-map id="auto-fit-map"></snice-map>
+
+<script type="module">
+  import 'snice/components/map/snice-map';
+
+  const map = document.getElementById('auto-fit-map');
+  map.markers = [
+    { id: 'paris', lat: 48.8566, lng: 2.3522, popup: 'Paris' },
+    { id: 'london', lat: 51.5074, lng: -0.1278, popup: 'London' },
+    { id: 'berlin', lat: 52.52, lng: 13.405, popup: 'Berlin' }
+  ];
+  map.fitBounds();
+</script>
+```
+
+### Handling Map Events
+
+Listen for click and marker events to build interactive map features.
+
+```html
+<snice-map id="interactive-map" zoom="12"></snice-map>
+<div id="map-output"></div>
+
+<script type="module">
+  import 'snice/components/map/snice-map';
+
+  const map = document.getElementById('interactive-map');
+  const output = document.getElementById('map-output');
+  map.center = { lat: 51.505, lng: -0.09 };
+
+  map.addEventListener('map-click', (e) => {
+    const { lat, lng } = e.detail;
+    output.textContent = `Clicked at: ${lat.toFixed(4)}, ${lng.toFixed(4)}`;
+
+    // Add a marker at the clicked location
+    map.addMarker({
+      id: `pin-${Date.now()}`,
+      lat,
+      lng,
+      popup: `Lat: ${lat.toFixed(4)}, Lng: ${lng.toFixed(4)}`
+    });
+  });
+
+  map.addEventListener('marker-click', (e) => {
+    output.textContent = `Marker: ${e.detail.marker.label || e.detail.marker.id}`;
+  });
+</script>
+```
+
+### Custom Tile Server
+
+Use the `tile-url` attribute to load tiles from a different provider.
+
+```html
+<snice-map
+  zoom="10"
+  tile-url="https://tiles.example.com/{z}/{x}/{y}.png"
+></snice-map>
+```
+
+## Accessibility
+
+- The map supports mouse drag to pan and scroll wheel to zoom
+- Zoom in/out buttons are provided in the top-right corner for keyboard and pointer access
+- Markers are interactive and toggle popup display on click
+- OpenStreetMap attribution is included automatically
+- For keyboard-only users, the zoom buttons provide an accessible alternative to scroll-wheel zoom

package/docs/components/markdown.md

@@ -0,0 +1,220 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/markdown.md instead)
+
+# Markdown Component
+
+`<snice-markdown>`
+
+A lightweight GFM-compatible markdown renderer that converts markdown text to styled HTML inside shadow DOM. Includes built-in sanitization to prevent XSS attacks.
+
+## Table of Contents
+- [Basic Usage](#basic-usage)
+- [Properties](#properties)
+- [Events](#events)
+- [CSS Custom Properties](#css-custom-properties)
+- [Supported Syntax](#supported-syntax)
+- [Examples](#examples)
+- [Accessibility](#accessibility)
+
+## Basic Usage
+
+```typescript
+import 'snice/components/markdown/snice-markdown';
+```
+
+```html
+<snice-markdown content="# Hello World"></snice-markdown>
+```
+
+## Importing
+
+**ESM (bundler)**
+```typescript
+import 'snice/components/markdown/snice-markdown';
+```
+
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-markdown.min.js"></script>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `content` | `string` | `''` | The markdown source text to render |
+| `sanitize` | `boolean` | `true` | Whether to sanitize the HTML output to prevent XSS |
+| `theme` | `'default' \| 'github'` | `'default'` | Visual theme for the rendered output |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `markdown-render` | `{ html: string }` | Fired after the markdown has been rendered to HTML |
+| `link-click` | `{ href: string; text: string }` | Fired when a link in the rendered content is clicked. Default navigation is prevented |
+
+## CSS Custom Properties
+
+| Property | Description |
+|----------|-------------|
+| `--snice-font-family` | Font family for rendered text |
+| `--snice-color-text` | Primary text color |
+| `--snice-color-primary` | Link color |
+| `--snice-color-border` | Border color for headings, tables, code blocks, and blockquotes |
+| `--snice-color-text-secondary` | Color for strikethrough text and blockquote text |
+| `--snice-color-text-tertiary` | Color for h6 headings |
+| `--snice-color-background-element` | Background color for code blocks, blockquotes, and alternating table rows |
+| `--snice-line-height-normal` | Line height for body text |
+| `--snice-font-size-md` | Base font size |
+| `--snice-spacing-*` | Various spacing tokens for margins and padding |
+| `--snice-border-radius-md` | Border radius for inline code |
+| `--snice-border-radius-lg` | Border radius for code blocks |
+| `--snice-font-weight-semibold` | Font weight for headings and bold text |
+
+## Supported Syntax
+
+The component supports GitHub Flavored Markdown (GFM):
+
+- **Headings** (h1 through h6)
+- **Inline formatting**: bold, italic, strikethrough
+- **Lists**: ordered, unordered, and task lists with checkboxes
+- **Code**: inline code and fenced code blocks with language class
+- **Blockquotes**
+- **Tables** (GFM pipe-delimited)
+- **Images** and **links** (including autolinks)
+- **Horizontal rules**
+
+## Examples
+
+### Rendering Static Content
+
+Use the `content` attribute to render a markdown string.
+
+```html
+<snice-markdown
+  content="# Welcome
+
+This is **bold** and *italic* text.
+
+- Item one
+- Item two
+- Item three"
+></snice-markdown>
+```
+
+### Dynamic Content Updates
+
+Set the `content` property via JavaScript to update the rendered markdown dynamically.
+
+```html
+<snice-markdown id="preview"></snice-markdown>
+<textarea id="editor" rows="10" cols="60">## Write Markdown Here
+
+Type some **markdown** and see it render in real time.</textarea>
+
+<script type="module">
+  import 'snice/components/markdown/snice-markdown';
+
+  const preview = document.getElementById('preview');
+  const editor = document.getElementById('editor');
+
+  // Set initial content
+  preview.content = editor.value;
+
+  // Update on input
+  editor.addEventListener('input', () => {
+    preview.content = editor.value;
+  });
+</script>
+```
+
+### GitHub Theme
+
+Use the `theme="github"` attribute for GitHub-style markdown rendering.
+
+```html
+<snice-markdown
+  theme="github"
+  content="# GitHub Style
+
+> This blockquote uses GitHub-style rendering.
+
+| Feature | Supported |
+|---------|-----------|
+| Tables  | Yes       |
+| GFM     | Yes       |
+
+```javascript
+console.log('Syntax highlighting');
+```"
+></snice-markdown>
+```
+
+### Intercepting Link Clicks
+
+Listen for the `link-click` event to handle navigation within your application instead of following the default link behavior.
+
+```html
+<snice-markdown
+  id="docs"
+  content="Check out [the documentation](/docs) or visit [our website](https://example.com)."
+></snice-markdown>
+
+<script type="module">
+  import 'snice/components/markdown/snice-markdown';
+
+  const md = document.getElementById('docs');
+
+  md.addEventListener('link-click', (e) => {
+    const { href, text } = e.detail;
+    console.log(`Link clicked: "${text}" -> ${href}`);
+
+    // Handle internal navigation
+    if (href.startsWith('/')) {
+      window.history.pushState({}, '', href);
+    } else {
+      window.open(href, '_blank');
+    }
+  });
+</script>
+```
+
+### Code Blocks and Tables
+
+Render markdown that includes fenced code blocks and GFM tables.
+
+```html
+<snice-markdown
+  content="## API Response
+
+The endpoint returns the following JSON:
+
+```json
+{
+  &quot;id&quot;: 1,
+  &quot;name&quot;: &quot;Example&quot;,
+  &quot;active&quot;: true
+}
+```
+
+### Status Codes
+
+| Code | Meaning |
+|------|---------|
+| 200  | Success |
+| 404  | Not found |
+| 500  | Server error |
+
+- [x] GET endpoint
+- [x] POST endpoint
+- [ ] DELETE endpoint"
+></snice-markdown>
+```
+
+## Accessibility
+
+- Rendered HTML preserves semantic heading hierarchy (h1-h6) for screen readers
+- Links within rendered content are fully keyboard accessible
+- Task list checkboxes are rendered as visual indicators
+- Tables include proper `<thead>` and `<tbody>` structure for assistive technology
+- The `link-click` event allows developers to implement custom navigation while maintaining accessibility

package/docs/components/masonry.md

@@ -1,34 +1,37 @@
-# Masonry Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/masonry.md instead)
 
-The masonry component provides a Pinterest-style layout that arranges items in columns with variable heights. Items flow top-to-bottom within each column, filling space efficiently. Built with CSS columns for simplicity and reliability.
+# Masonry
+`<snice-masonry>`
 
-## Table of Contents
-- [Basic Usage](#basic-usage)
-- [Properties](#properties)
-- [Examples](#examples)
+A Pinterest-style layout that arranges items in columns with variable heights using CSS columns.
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/masonry/snice-masonry';
+```
+
 ```html
 <snice-masonry columns="3" gap="1rem">
-  <div class="card">Item 1</div>
-  <div class="card">Item 2</div>
-  <div class="card">Item 3</div>
-  <div class="card">Item 4</div>
+  <div>Card 1</div>
+  <div>Card 2</div>
+  <div>Card 3</div>
+  <div>Card 4</div>
 </snice-masonry>
 ```
 
+## Importing
+
+**ESM (bundler)**
 ```typescript
 import 'snice/components/masonry/snice-masonry';
 ```
 
-## Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `columns` | `number` | `3` | Number of columns. Set to `0` for auto-calculation based on `minColumnWidth` |
-| `gap` | `string` | `'1rem'` | Gap between items (any CSS length value) |
-| `minColumnWidth` | `string` | `'250px'` | Minimum column width when `columns` is `0` |
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-masonry.min.js"></script>
+```
 
 ## Examples
 
@@ -36,41 +39,39 @@ import 'snice/components/masonry/snice-masonry';
 
 ```html
 <snice-masonry columns="3" gap="1rem">
-  <div class="card" style="height: 200px;">Card 1</div>
-  <div class="card" style="height: 150px;">Card 2</div>
-  <div class="card" style="height: 250px;">Card 3</div>
-  <div class="card" style="height: 180px;">Card 4</div>
-  <div class="card" style="height: 220px;">Card 5</div>
-  <div class="card" style="height: 160px;">Card 6</div>
+  <div style="height:200px">Card 1</div>
+  <div style="height:150px">Card 2</div>
+  <div style="height:250px">Card 3</div>
+  <div style="height:180px">Card 4</div>
 </snice-masonry>
 ```
 
 ### Auto-Responsive Columns
 
-When `columns` is set to `0`, the layout automatically calculates column count based on `minColumnWidth`:
+Set `columns` to `0` to auto-calculate column count based on `min-column-width`.
 
 ```html
 <snice-masonry columns="0" min-column-width="300px" gap="1rem">
-  <div class="card">Card 1</div>
-  <div class="card">Card 2</div>
-  <div class="card">Card 3</div>
-  <div class="card">Card 4</div>
+  <div>Card 1</div>
+  <div>Card 2</div>
+  <div>Card 3</div>
+  <div>Card 4</div>
 </snice-masonry>
 ```
 
-### Different Gap Sizes
+### Gap Sizes
+
+Use the `gap` attribute with any CSS length value.
 
 ```html
-<!-- Tight spacing -->
 <snice-masonry columns="4" gap="0.5rem">
-  <div class="card">Item 1</div>
-  <div class="card">Item 2</div>
+  <div>Tight spacing</div>
+  <div>Between cards</div>
 </snice-masonry>
 
-<!-- Wide spacing -->
 <snice-masonry columns="2" gap="2rem">
-  <div class="card">Item 1</div>
-  <div class="card">Item 2</div>
+  <div>Wide spacing</div>
+  <div>Between cards</div>
 </snice-masonry>
 ```
 
@@ -78,91 +79,45 @@ When `columns` is set to `0`, the layout automatically calculates column count b
 
 ```html
 <snice-masonry columns="3" gap="0.75rem">
-  <img src="photo1.jpg" alt="Photo 1" style="width: 100%; border-radius: 8px;">
-  <img src="photo2.jpg" alt="Photo 2" style="width: 100%; border-radius: 8px;">
-  <img src="photo3.jpg" alt="Photo 3" style="width: 100%; border-radius: 8px;">
-  <img src="photo4.jpg" alt="Photo 4" style="width: 100%; border-radius: 8px;">
-  <img src="photo5.jpg" alt="Photo 5" style="width: 100%; border-radius: 8px;">
-</snice-masonry>
-```
-
-### Card Layout
-
-```html
-<style>
-  .masonry-card {
-    padding: 1rem;
-    background: white;
-    border: 1px solid #e5e7eb;
-    border-radius: 8px;
-  }
-</style>
-
-<snice-masonry columns="3" gap="1rem">
-  <div class="masonry-card">
-    <h3>Short Card</h3>
-    <p>Brief content.</p>
-  </div>
-  <div class="masonry-card">
-    <h3>Tall Card</h3>
-    <p>This card has more content to demonstrate variable heights in the masonry layout.</p>
-    <p>Additional paragraph for height.</p>
-  </div>
-  <div class="masonry-card">
-    <h3>Medium Card</h3>
-    <p>Some content here.</p>
-  </div>
-  <div class="masonry-card">
-    <h3>Another Card</h3>
-    <p>More content to fill the grid.</p>
-  </div>
+  <img src="photo1.jpg" alt="Landscape" style="width:100%;border-radius:8px">
+  <img src="photo2.jpg" alt="Portrait" style="width:100%;border-radius:8px">
+  <img src="photo3.jpg" alt="Abstract" style="width:100%;border-radius:8px">
+  <img src="photo4.jpg" alt="Nature" style="width:100%;border-radius:8px">
 </snice-masonry>
 ```
 
 ### Dynamic Content
 
 ```html
-<snice-masonry id="dynamic-masonry" columns="3" gap="1rem">
-</snice-masonry>
-
-<button onclick="addCard()">Add Card</button>
+<snice-masonry id="grid" columns="3" gap="1rem"></snice-masonry>
+<button id="addBtn">Add Card</button>
 
 <script type="module">
-  const masonry = document.getElementById('dynamic-masonry');
+  import 'snice/components/masonry/snice-masonry';
+
+  const masonry = document.getElementById('grid');
   let count = 0;
 
-  window.addCard = () => {
+  document.getElementById('addBtn').addEventListener('click', () => {
     count++;
     const card = document.createElement('div');
-    card.className = 'masonry-card';
     card.style.height = `${100 + Math.random() * 200}px`;
     card.textContent = `Card ${count}`;
     masonry.appendChild(card);
-  };
+  });
 </script>
 ```
 
-## Accessibility
+## Slots
 
-- **ARIA role**: Container has `role="list"` for screen reader context
-- **Semantic children**: Items can use `role="listitem"` for full list semantics
-- **Tab order**: Items maintain DOM order for keyboard navigation
+| Name | Description |
+|------|-------------|
+| (default) | Items to arrange in the masonry layout |
 
-## Browser Support
-
-- Modern browsers (Chrome, Firefox, Safari, Edge)
-- Requires Custom Elements v1 and Shadow DOM support
-- CSS `column-count` and `column-gap` are widely supported
-
-## Best Practices
-
-1. **Use variable heights**: Masonry works best when items have different heights
-2. **Set appropriate column count**: 3-4 columns work well for most layouts
-3. **Use auto columns for responsive**: Set `columns="0"` with `min-column-width` for adaptive layouts
-4. **Keep items lightweight**: Avoid heavy content that slows rendering
-5. **Add border-radius and shadows**: Visual cards look great in masonry layouts
-6. **Test with different content**: Ensure layout works with varying item sizes
-
-## How It Works
+## Properties
 
-The component uses CSS `column-count` and `column-gap` to create the masonry effect. Each slotted child receives `break-inside: avoid` to prevent items from splitting across columns. When `columns` is set to `0`, the component uses `column-width` instead of `column-count`, allowing the browser to auto-calculate the optimal number of columns based on available space.
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `columns` | `number` | `3` | Number of columns (0 for auto based on `minColumnWidth`) |
+| `gap` | `string` | `'1rem'` | Gap between items (any CSS length) |
+| `minColumnWidth` (attr: `min-column-width`) | `string` | `'250px'` | Minimum column width when `columns` is 0 |