snice 4.9.0 → 4.10.0

package/docs/components/location.md

@@ -1,9 +1,16 @@
-# Location Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/location.md instead)
 
-Display location information with addresses, coordinates, maps, and custom icons.
+# Location
+`<snice-location>`
+
+Displays location information with addresses, coordinates, maps, and custom icons.
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/location/snice-location';
+```
+
 ```html
 <snice-location
   name="Central Park"
@@ -15,100 +22,27 @@ Display location information with addresses, coordinates, maps, and custom icons
 </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` | `'📍'` | Icon (URL, image file, emoji, or font ligature) |
-| `iconImage` | `string` | `''` | Icon image URL (deprecated, use `icon`) |
-| `mapUrl` | `string` | `''` | Custom map URL |
-| `clickable` | `boolean` | `false` | Make location clickable |
-
-## Slots
-
-| Slot Name | Description |
-|-----------|-------------|
-| `icon` | Custom icon content. Overrides `icon` and `iconImage` properties. |
-
-### Icon Slot Usage
-
-Use the `icon` slot for external CSS-based icon fonts:
-
-```html
-<snice-location name="Office" address="123 Main St">
-  <span slot="icon" class="material-symbols-outlined">business</span>
-</snice-location>
+## Importing
 
-<snice-location name="Restaurant" city="New York" clickable>
-  <i slot="icon" class="fa-solid fa-utensils"></i>
-</snice-location>
-```
-
-## 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}`);
-}
+**ESM (bundler)**
+```typescript
+import 'snice/components/location/snice-location';
 ```
 
-### `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);
-});
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-location.min.js"></script>
 ```
 
-**Detail:** `LocationData` object
-
 ## Examples
 
 ### Display Modes
 
+Use the `mode` attribute to control what information is shown.
+
 ```html
-<!-- Full mode (default) -->
+<!-- Full mode (default) - shows name, address, and coordinates -->
 <snice-location
   name="Empire State Building"
   address="350 5th Ave"
@@ -120,93 +54,77 @@ location.addEventListener('location-click', (e) => {
 </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>
+<snice-location name="Times Square" city="New York" mode="compact"></snice-location>
 
 <!-- Coordinates only -->
-<snice-location
-  latitude="40.7580"
-  longitude="-73.9855"
-  mode="coordinates">
-</snice-location>
+<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>
+<snice-location name="Brooklyn Bridge" city="New York" state="NY" mode="address"></snice-location>
 ```
 
 ### Custom Icons
 
+Use the `icon` attribute for emoji or the `icon` slot for external icon fonts.
+
 ```html
 <!-- Emoji icon -->
-<snice-location
-  name="Office"
-  address="123 Business Blvd"
-  icon="🏢">
-</snice-location>
+<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 name="Store" address="456 Shopping Ave" icon-image="/icons/store.svg"></snice-location>
+
+<!-- Icon slot (for CSS icon fonts) -->
+<snice-location name="Restaurant" city="New York">
+  <span slot="icon" class="material-symbols-outlined">restaurant</span>
 </snice-location>
 
 <!-- No icon -->
-<snice-location
-  name="Home"
-  address="789 Residential St"
-  show-icon="false">
-</snice-location>
+<snice-location name="Home" address="789 Elm St" show-icon="false"></snice-location>
 ```
 
-### Interactive Locations
+### Clickable Locations
+
+Set the `clickable` attribute to make the location interactive.
 
 ```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
 
+Set the `show-map` attribute to display an embedded Google Maps iframe.
+
 ```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>
 ```
 
+### Custom Map URL
+
+Use `map-url` to link to an alternative maps provider.
+
+```html
+<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>
+```
+
 ### Complete Address
 
 ```html
@@ -223,147 +141,10 @@ location.addEventListener('location-click', (e) => {
 </snice-location>
 ```
 
-### Restaurant Location
+### Programmatic Usage
 
-```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);
-});
+```typescript
+const location = document.querySelector('snice-location');
 
 // Get data
 const data = location.getData();
@@ -372,18 +153,50 @@ const address = location.getFullAddress();
 
 // Open in maps
 location.openMap();
+
+// Listen for clicks
+location.addEventListener('location-click', (e) => {
+  console.log('Clicked:', e.detail);
+});
 ```
 
-## Accessibility
+## Slots
+
+| Name | Description |
+|------|-------------|
+| `icon` | Custom icon content (overrides `icon` and `iconImage` properties) |
+
+## 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 or province |
+| `country` | `string` | `''` | Country name |
+| `zipCode` (attr: `zip-code`) | `string` | `''` | ZIP/postal code |
+| `latitude` | `number \| string` | `''` | Latitude coordinate |
+| `longitude` | `number \| string` | `''` | Longitude coordinate |
+| `showMap` (attr: `show-map`) | `boolean` | `false` | Show embedded map |
+| `showIcon` (attr: `show-icon`) | `boolean` | `true` | Show location icon |
+| `icon` | `string` | `'📍'` | Icon (emoji, URL, or font ligature) |
+| `iconImage` (attr: `icon-image`) | `string` | `''` | Icon image URL |
+| `mapUrl` (attr: `map-url`) | `string` | `''` | Custom map URL |
+| `clickable` | `boolean` | `false` | Make location clickable |
+
+## Events
 
-- 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
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `location-click` | `LocationData` | Fired when a clickable location is clicked |
 
-## Browser Support
+## Methods
 
-- 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
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `getData()` | -- | Returns complete LocationData object |
+| `getCoordinates()` | -- | Returns `{ latitude, longitude }` or null |
+| `getFullAddress()` | -- | Returns formatted address string |
+| `openMap()` | -- | Opens location in maps (new tab) |