snice 3.1.0 → 3.3.0

package/docs/components/link.md

@@ -0,0 +1,229 @@
+# Link Component
+
+A customizable link component with multiple variants, external link handling, and accessibility features.
+
+## Features
+
+- **Multiple Variants**: default, primary, secondary, muted
+- **External Link Handling**: Automatic `target="_blank"` and security attributes
+- **Hash Routing**: Built-in support for hash-based navigation
+- **Router Integration**: Emits events for custom router integration
+- **Accessibility**: Proper ARIA attributes and keyboard navigation
+- **Disabled State**: Visual and functional disabled state
+- **Customizable**: Full theme integration
+
+## Basic Usage
+
+```html
+<snice-link href="/about">About Us</snice-link>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `href` | `string` | `''` | Link URL |
+| `target` | `LinkTarget` | `'_self'` | Target attribute ('_self', '_blank', '_parent', '_top') |
+| `variant` | `LinkVariant` | `'default'` | Visual style variant |
+| `disabled` | `boolean` | `false` | Disable the link |
+| `external` | `boolean` | `false` | Treat as external link (auto _blank + security) |
+| `underline` | `boolean` | `false` | Show text underline |
+| `hash` | `boolean` | `false` | Automatically prepend # to href (for hash routing) |
+
+## Variants
+
+### Default
+```html
+<snice-link href="/page">Default link</snice-link>
+```
+
+### Primary
+```html
+<snice-link href="/page" variant="primary">Primary link</snice-link>
+```
+
+### Secondary
+```html
+<snice-link href="/page" variant="secondary">Secondary link</snice-link>
+```
+
+### Muted
+```html
+<snice-link href="/page" variant="muted">Muted link</snice-link>
+```
+
+## External Links
+
+External links automatically open in a new tab with security attributes:
+
+```html
+<snice-link href="https://example.com" external>
+  External Link
+</snice-link>
+```
+
+This automatically adds:
+- `target="_blank"`
+- `rel="noopener noreferrer"`
+- External link icon (↗)
+
+## Underline
+
+```html
+<snice-link href="/page" underline>Underlined link</snice-link>
+```
+
+## Disabled State
+
+```html
+<snice-link href="/page" disabled>Disabled link</snice-link>
+```
+
+## Hash Routing
+
+For hash-based navigation (Single Page Applications):
+
+```html
+<!-- Automatically prepends # to href -->
+<snice-link href="home" hash>Home</snice-link>
+<snice-link href="about" hash>About</snice-link>
+<snice-link href="contact" hash>Contact</snice-link>
+
+<!-- Renders as: <a href="#home">Home</a> -->
+```
+
+### Router Integration
+
+The `navigate` event allows decoupled router integration:
+
+```html
+<snice-link href="profile" hash id="profile-link">Profile</snice-link>
+
+<script>
+  document.getElementById('profile-link').addEventListener('navigate', (e) => {
+    console.log('Navigating to:', e.detail.href);
+
+    // Custom routing logic
+    myRouter.navigate(e.detail.href);
+
+    // Optionally prevent default navigation
+    // e.preventDefault();
+  });
+</script>
+```
+
+### Example Router Setup
+
+```html
+<nav>
+  <snice-link href="home" hash>Home</snice-link>
+  <snice-link href="products" hash>Products</snice-link>
+  <snice-link href="about" hash>About</snice-link>
+</nav>
+
+<script>
+  // Listen to all navigate events
+  document.addEventListener('navigate', (e) => {
+    const route = e.detail.href;
+
+    // Update view based on route
+    switch(route) {
+      case 'home':
+        showHomeView();
+        break;
+      case 'products':
+        showProductsView();
+        break;
+      case 'about':
+        showAboutView();
+        break;
+    }
+  });
+</script>
+```
+
+## In Context
+
+Links work naturally within text:
+
+```html
+<p>
+  This is a paragraph with an <snice-link href="/page">inline link</snice-link>
+  in the middle of the text.
+</p>
+```
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `click` | `MouseEvent` | Emitted when link is clicked (prevented if disabled) |
+| `navigate` | `{ href: string }` | Emitted on hash link click (bubbles, composed, cancelable) |
+
+## CSS Parts
+
+Use `::part()` to style internal elements:
+
+```css
+snice-link::part(link) {
+  font-weight: bold;
+}
+
+snice-link::part(external-icon) {
+  color: blue;
+}
+```
+
+## Theming
+
+The component uses these CSS custom properties:
+
+```css
+--snice-color-primary
+--snice-color-primary-dark
+--snice-color-primary-darker
+--snice-color-text
+--snice-color-text-secondary
+--snice-color-text-muted
+--snice-color-text-disabled
+--snice-transition-fast
+```
+
+## Accessibility
+
+- Proper `href` attribute for keyboard navigation
+- Correct `rel` attributes for external links
+- Disabled state prevents interaction
+- Screen reader friendly
+
+## Examples
+
+### Navigation Menu
+```html
+<nav>
+  <snice-link href="/">Home</snice-link>
+  <snice-link href="/about">About</snice-link>
+  <snice-link href="/contact">Contact</snice-link>
+</nav>
+```
+
+### Footer Links
+```html
+<footer>
+  <snice-link href="/privacy" variant="muted">Privacy</snice-link>
+  <snice-link href="/terms" variant="muted">Terms</snice-link>
+  <snice-link href="https://twitter.com" external variant="muted">
+    Twitter
+  </snice-link>
+</footer>
+```
+
+### Action Links
+```html
+<snice-link href="/download" variant="primary">
+  Download Now
+</snice-link>
+<snice-link href="/learn-more" variant="secondary">
+  Learn More
+</snice-link>
+```

package/docs/components/list.md

@@ -0,0 +1,65 @@
+# List Component
+
+Display a list of items with optional selection, icons, and descriptions.
+
+## Basic Usage
+
+```html
+<snice-list id="list"></snice-list>
+<script>
+  document.getElementById('list').items = [
+    { id: '1', label: 'Item 1', icon: '📄' },
+    { id: '2', label: 'Item 2', icon: '📄' }
+  ];
+</script>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `items` | `ListItem[]` | `[]` | Array of items |
+| `selectionMode` | `'single' \| 'multiple' \| 'none'` | `'none'` | Selection mode |
+| `selectedItems` | `string[]` | `[]` | Selected item IDs |
+| `hoverable` | `boolean` | `true` | Hover effects |
+| `dividers` | `boolean` | `false` | Show dividers |
+| `dense` | `boolean` | `false` | Compact spacing |
+
+## ListItem Interface
+
+```typescript
+interface ListItem {
+  id: string;
+  label: string;
+  description?: string;
+  icon?: string;
+  iconImage?: string;
+  disabled?: boolean;
+  selected?: boolean;
+  data?: any;
+}
+```
+
+## Methods
+
+- `selectItem(id: string)` - Select item
+- `deselectItem(id: string)` - Deselect item
+- `toggleSelection(id: string)` - Toggle selection
+- `getSelectedItems(): ListItem[]` - Get selected items
+
+## Events
+
+- `@snice/list-item-select` - Item selected (detail: { item, selected, list })
+
+## Examples
+
+```html
+<!-- With dividers -->
+<snice-list dividers></snice-list>
+
+<!-- Single selection -->
+<snice-list selection-mode="single"></snice-list>
+
+<!-- Dense -->
+<snice-list dense></snice-list>
+```

package/docs/components/location.md

@@ -0,0 +1,369 @@
+# Location Component
+
+Display location information with addresses, coordinates, maps, and custom icons.
+
+## Basic Usage
+
+```html
+<snice-location
+  name="Central Park"
+  address="Central Park"
+  city="New York"
+  state="NY"
+  latitude="40.7829"
+  longitude="-73.9654">
+</snice-location>
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `mode` | `'full' \| 'compact' \| 'coordinates' \| 'address'` | `'full'` | Display mode |
+| `name` | `string` | `''` | Location name |
+| `address` | `string` | `''` | Street address |
+| `city` | `string` | `''` | City name |
+| `state` | `string` | `''` | State/province |
+| `country` | `string` | `''` | Country name |
+| `zipCode` | `string` | `''` | ZIP/postal code |
+| `latitude` | `number \| string` | `''` | Latitude coordinate |
+| `longitude` | `number \| string` | `''` | Longitude coordinate |
+| `showMap` | `boolean` | `false` | Show embedded map |
+| `showIcon` | `boolean` | `true` | Show location icon |
+| `icon` | `string` | `'📍'` | Text/emoji icon |
+| `iconImage` | `string` | `''` | Icon image URL |
+| `mapUrl` | `string` | `''` | Custom map URL |
+| `clickable` | `boolean` | `false` | Make location clickable |
+
+## Methods
+
+### `getData(): LocationData`
+Get complete location data object.
+
+```javascript
+const data = location.getData();
+console.log(data.name, data.latitude, data.longitude);
+```
+
+### `getCoordinates(): { latitude: number; longitude: number } | null`
+Get coordinate pair or null if invalid.
+
+```javascript
+const coords = location.getCoordinates();
+if (coords) {
+  console.log(`${coords.latitude}, ${coords.longitude}`);
+}
+```
+
+### `getFullAddress(): string`
+Get formatted full address string.
+
+```javascript
+const address = location.getFullAddress();
+// "123 Main St, New York, NY, 10001, USA"
+```
+
+### `openMap(): void`
+Open location in maps application (new tab).
+
+```javascript
+location.openMap();
+```
+
+## Events
+
+### `location-click`
+Dispatched when clickable location is clicked.
+
+```javascript
+location.addEventListener('location-click', (e) => {
+  console.log('Location clicked:', e.detail);
+});
+```
+
+**Detail:** `LocationData` object
+
+## Examples
+
+### Display Modes
+
+```html
+<!-- Full mode (default) -->
+<snice-location
+  name="Empire State Building"
+  address="350 5th Ave"
+  city="New York"
+  state="NY"
+  latitude="40.7484"
+  longitude="-73.9857"
+  mode="full">
+</snice-location>
+
+<!-- Compact mode -->
+<snice-location
+  name="Times Square"
+  address="Times Square"
+  city="New York"
+  latitude="40.7580"
+  longitude="-73.9855"
+  mode="compact">
+</snice-location>
+
+<!-- Coordinates only -->
+<snice-location
+  latitude="40.7580"
+  longitude="-73.9855"
+  mode="coordinates">
+</snice-location>
+
+<!-- Address only -->
+<snice-location
+  name="Brooklyn Bridge"
+  address="Brooklyn Bridge"
+  city="New York"
+  state="NY"
+  mode="address">
+</snice-location>
+```
+
+### Custom Icons
+
+```html
+<!-- Emoji icon -->
+<snice-location
+  name="Office"
+  address="123 Business Blvd"
+  icon="🏢">
+</snice-location>
+
+<!-- Image icon -->
+<snice-location
+  name="Store"
+  address="456 Shopping Ave"
+  icon-image="/icons/store.svg">
+</snice-location>
+
+<!-- No icon -->
+<snice-location
+  name="Home"
+  address="789 Residential St"
+  show-icon="false">
+</snice-location>
+```
+
+### Interactive Locations
+
+```html
+<!-- Clickable location -->
+<snice-location
+  name="Golden Gate Bridge"
+  latitude="37.8199"
+  longitude="-122.4783"
+  clickable>
+</snice-location>
+
+<!-- Custom map URL -->
+<snice-location
+  name="Custom Location"
+  latitude="34.0522"
+  longitude="-118.2437"
+  clickable
+  map-url="https://www.openstreetmap.org/?mlat=34.0522&mlon=-118.2437">
+</snice-location>
+```
+
+### Embedded Maps
+
+```html
+<!-- Show embedded map -->
+<snice-location
+  name="Statue of Liberty"
+  address="Liberty Island"
+  city="New York"
+  state="NY"
+  latitude="40.6892"
+  longitude="-74.0445"
+  show-map>
+</snice-location>
+```
+
+### Complete Address
+
+```html
+<snice-location
+  name="White House"
+  address="1600 Pennsylvania Avenue NW"
+  city="Washington"
+  state="DC"
+  zip-code="20500"
+  country="USA"
+  latitude="38.8977"
+  longitude="-77.0365"
+  clickable>
+</snice-location>
+```
+
+### Restaurant Location
+
+```html
+<snice-location
+  name="Blue Hill"
+  address="75 Washington Pl"
+  city="New York"
+  state="NY"
+  zip-code="10011"
+  latitude="40.7308"
+  longitude="-73.9973"
+  icon="🍽️"
+  clickable>
+</snice-location>
+```
+
+### Park Location
+
+```html
+<snice-location
+  name="Millennium Park"
+  address="201 E Randolph St"
+  city="Chicago"
+  state="IL"
+  latitude="41.8826"
+  longitude="-87.6226"
+  icon="🌳"
+  mode="full"
+  clickable>
+</snice-location>
+```
+
+### Airport Location
+
+```html
+<snice-location
+  name="LAX"
+  address="1 World Way"
+  city="Los Angeles"
+  state="CA"
+  zip-code="90045"
+  latitude="33.9416"
+  longitude="-118.4085"
+  icon="✈️"
+  clickable>
+</snice-location>
+```
+
+### Hospital Location
+
+```html
+<snice-location
+  name="Mayo Clinic"
+  address="200 First St SW"
+  city="Rochester"
+  state="MN"
+  zip-code="55905"
+  latitude="44.0225"
+  longitude="-92.4666"
+  icon="🏥"
+  show-map>
+</snice-location>
+```
+
+### University Location
+
+```html
+<snice-location
+  name="MIT"
+  address="77 Massachusetts Ave"
+  city="Cambridge"
+  state="MA"
+  zip-code="02139"
+  latitude="42.3601"
+  longitude="-71.0942"
+  icon="🎓"
+  mode="compact"
+  clickable>
+</snice-location>
+```
+
+### Hotel Location
+
+```html
+<snice-location
+  name="The Plaza Hotel"
+  address="768 5th Ave"
+  city="New York"
+  state="NY"
+  zip-code="10019"
+  latitude="40.7643"
+  longitude="-73.9747"
+  icon="🏨"
+  clickable>
+</snice-location>
+```
+
+### Museum Location
+
+```html
+<snice-location
+  name="The Met"
+  address="1000 5th Ave"
+  city="New York"
+  state="NY"
+  zip-code="10028"
+  latitude="40.7794"
+  longitude="-73.9632"
+  icon="🏛️"
+  show-map>
+</snice-location>
+```
+
+### Stadium Location
+
+```html
+<snice-location
+  name="Yankee Stadium"
+  address="1 E 161st St"
+  city="Bronx"
+  state="NY"
+  zip-code="10451"
+  latitude="40.8296"
+  longitude="-73.9262"
+  icon="⚾"
+  clickable>
+</snice-location>
+```
+
+## Programmatic Usage
+
+```javascript
+const location = document.createElement('snice-location');
+location.name = 'Central Park';
+location.latitude = 40.7829;
+location.longitude = -73.9654;
+location.clickable = true;
+
+location.addEventListener('location-click', (e) => {
+  console.log('Clicked:', e.detail);
+});
+
+// Get data
+const data = location.getData();
+const coords = location.getCoordinates();
+const address = location.getFullAddress();
+
+// Open in maps
+location.openMap();
+```
+
+## Accessibility
+
+- Use descriptive `name` attributes for screen readers
+- Clickable locations are keyboard accessible
+- Icons should be decorative; location name provides context
+- Map iframes include proper loading attributes
+
+## Browser Support
+
+- Modern browsers with Custom Elements v1 support
+- Embedded maps require internet connection
+- Default map provider is Google Maps
+- Custom map URLs can use alternative providers