@mhmo91/schmancy 0.4.53 → 0.4.55

package/ai/map.md

@@ -0,0 +1,232 @@
+# Schmancy Map Component
+
+The `schmancy-map` component provides an easy-to-use Google Maps integration with an intuitive API designed for both technical and non-technical users.
+
+## Installation
+
+```bash
+npm install @mhmo91/schmancy
+# or
+yarn add @mhmo91/schmancy
+```
+
+## Import
+
+```javascript
+import '@mhmo91/schmancy/map'
+```
+
+## API Reference
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `address` | `string` | `''` | Simple address string that automatically geocodes to display the location. Takes precedence over latitude/longitude if both are provided. |
+| `latitude` | `number` | `undefined` | Latitude coordinate for precise location. Used when address is not provided. |
+| `longitude` | `number` | `undefined` | Longitude coordinate for precise location. Used when address is not provided. |
+| `zoom` | `number` | `15` | Map zoom level. Higher numbers show more detail (1-20). |
+| `height` | `string` | `"400px"` | Height of the map with CSS unit (e.g., "400px", "50vh"). |
+| `marker` | `boolean` | `true` | Whether to show a marker at the location. |
+| `markerTitle` | `string` | `''` | Tooltip text for the location marker. |
+| `type` | `'roadmap' \| 'satellite' \| 'hybrid' \| 'terrain'` | `'roadmap'` | Map display type. |
+| `interactive` | `boolean` | `true` | Whether users can interact with the map (pan, zoom, click). |
+| `controls` | `boolean` | `true` | Whether to show map controls (zoom buttons, fullscreen, etc.). |
+| `apiKey` | `string` | `''` | Google Maps API key. Falls back to GOOGLE_MAPS_API_KEY environment variable. |
+
+## Basic Usage
+
+### Simple Address
+The easiest way to display a map - just provide an address:
+
+```html
+<schmancy-map address="Times Square, New York"></schmancy-map>
+```
+
+### Coordinates
+For precise positioning, use latitude and longitude:
+
+```html
+<schmancy-map 
+  latitude="40.758" 
+  longitude="-73.985" 
+  zoom="17">
+</schmancy-map>
+```
+
+### Custom Height
+Adjust the map size:
+
+```html
+<schmancy-map 
+  address="Central Park, New York" 
+  height="600px">
+</schmancy-map>
+```
+
+## Map Types
+
+### Satellite View
+```html
+<schmancy-map 
+  address="Grand Canyon" 
+  type="satellite" 
+  height="500px">
+</schmancy-map>
+```
+
+### Hybrid View
+Combines satellite imagery with labels:
+
+```html
+<schmancy-map 
+  address="Mount Everest" 
+  type="hybrid">
+</schmancy-map>
+```
+
+### Terrain View
+Shows topographical features:
+
+```html
+<schmancy-map 
+  address="Yellowstone National Park" 
+  type="terrain">
+</schmancy-map>
+```
+
+## Static Maps
+
+For display-only maps without user interaction:
+
+```html
+<schmancy-map 
+  address="Eiffel Tower, Paris" 
+  interactive="false" 
+  controls="false">
+</schmancy-map>
+```
+
+## Customization
+
+### Custom Marker
+```html
+<schmancy-map 
+  address="Statue of Liberty" 
+  markerTitle="Welcome to Liberty Island">
+</schmancy-map>
+```
+
+### No Marker
+```html
+<schmancy-map 
+  address="Pacific Ocean" 
+  marker="false">
+</schmancy-map>
+```
+
+### Different Zoom Levels
+```html
+<!-- City view -->
+<schmancy-map address="Tokyo" zoom="10"></schmancy-map>
+
+<!-- Street view -->
+<schmancy-map address="Tokyo Tower" zoom="18"></schmancy-map>
+```
+
+## API Key Setup
+
+### Environment Variable (Recommended)
+Set `GOOGLE_MAPS_API_KEY` in your environment:
+
+```bash
+GOOGLE_MAPS_API_KEY=your_api_key_here
+```
+
+### Direct Property
+```html
+<schmancy-map 
+  address="Sydney Opera House" 
+  api-key="your_api_key_here">
+</schmancy-map>
+```
+
+## Features
+
+### Automatic Geocoding
+- Converts human-readable addresses to coordinates
+- Handles various address formats
+- Provides error feedback for invalid addresses
+
+### Responsive Design
+- Adapts to container width
+- Configurable height with CSS units
+- Maintains aspect ratio on mobile
+
+### Loading States
+- Shows spinner while loading
+- Displays error messages for failed loads
+- Graceful fallback when maps can't load
+
+### Performance
+- Lazy loads Google Maps API
+- Caches script loading across components
+- Minimal bundle size impact
+
+## Error Handling
+
+The component handles various error scenarios:
+
+- **Invalid Address**: Shows error message with geocoding failure
+- **Missing API Key**: Clear error message about required API key
+- **Network Issues**: Graceful fallback with retry capability
+- **Invalid Coordinates**: Validation of latitude/longitude ranges
+
+## Accessibility
+
+- Proper ARIA labels for screen readers
+- Keyboard navigation support (when interactive)
+- High contrast error states
+- Semantic HTML structure
+
+## Browser Support
+
+- Modern browsers with ES2015+ support
+- Google Maps API compatibility
+- Progressive enhancement for older browsers
+
+## Examples in Real Applications
+
+### Store Locator
+```html
+<schmancy-map 
+  address="Apple Store, 5th Avenue, New York" 
+  zoom="16" 
+  marker-title="Apple Store - 5th Avenue">
+</schmancy-map>
+```
+
+### Event Location
+```html
+<schmancy-map 
+  address="Madison Square Garden, New York" 
+  height="300px" 
+  interactive="false">
+</schmancy-map>
+```
+
+### Property Listing
+```html
+<schmancy-map 
+  latitude="40.7831" 
+  longitude="-73.9712" 
+  zoom="15" 
+  marker-title="Beautiful Apartment">
+</schmancy-map>
+```
+
+## Best Practices
+
+1. **Use addresses for user-friendly input**: Most users understand addresses better than coordinates
+2. **Set appropriate zoom levels**: 10-12 for cities, 15-17 for neighborhoods, 18+ for buildings
+3. **Consider mobile users**: Use responsive heights like "50vh" for mobile-friendly maps
+4. **Provide meaningful marker titles**: Help users understand what the marker represents
+5. **Use static maps for display-only**: Disable interaction when the map is purely informational

package/ai/notification.md

@@ -1,79 +1,192 @@
 # Schmancy Notification - AI Reference
 
+## Core Notification Service
+
 ```js
-// Notification Service API
-import { $notification } from '@mhmo91/schmancy';
+import { $notify } from '@mhmo91/schmancy'
 
 // Display notification methods
-$notification.info(message?, options?) -> string    // Returns notification ID
-$notification.success(message?, options?) -> string
-$notification.warning(message?, options?) -> string
-$notification.error(message?, options?) -> string
+$notify.info(message?, options?) -> string    // Returns notification ID
+$notify.success(message?, options?) -> string
+$notify.warning(message?, options?) -> string
+$notify.error(message?, options?) -> string
 
 // Custom notification
-$notification.notify({
+$notify.show({
   message: string,
   type?: 'info'|'success'|'warning'|'error',
   title?: string,
-  duration?: number,      // milliseconds, default 1000 (1 second)
+  duration?: number,      // milliseconds, default 1000
   closable?: boolean,     // default true
   playSound?: boolean,    // default true
+  showProgress?: boolean, // show progress bar
   id?: string            // custom ID
-}) -> string             // Returns notification ID
+}) -> string
+
+// Dismiss notifications
+$notify.dismiss(id?)     // Dismisses specific notification or latest if no ID
+
+// Update notification content
+$notify.update(id, options)  // Update existing notification
+
+// Persistent notification
+$notify.persistent(message, options)  // Won't auto-dismiss (duration: 0)
+
+// Custom duration
+$notify.customDuration(message, duration, options)
+```
+
+## API Integration with notify()
+
+The `notify()` operator wraps observables with automatic notification lifecycle management.
+
+```js
+import { notify } from '@mhmo91/schmancy'
+
+// Basic usage - minimal configuration
+someApiCall().pipe(
+  notify({
+    loadingMessage: 'Loading data...',
+    successMessage: 'Data loaded!',
+    errorMessage: 'Failed to load'
+  })
+).subscribe()
+
+// With custom durations
+saveData().pipe(
+  notify({
+    loadingMessage: 'Saving...',
+    successMessage: 'Saved!',
+    successDuration: 5000,  // Success stays 5 seconds
+    errorMessage: 'Save failed',
+    errorDuration: 0        // Error is persistent
+  })
+).subscribe()
+
+// Full configuration
+uploadFile().pipe(
+  notify({
+    // Loading state
+    loadingMessage: 'Uploading file...',
+    loadingType: 'info',
+    
+    // Success state
+    successMessage: 'Upload complete!',
+    successType: 'success',
+    successDuration: 3000,
+    
+    // Error state
+    errorMessage: (err) => `Upload failed: ${err.message}`,
+    errorType: 'error',
+    errorDuration: 10000,
+    
+    // Options
+    autoDismissLoading: true
+  })
+).subscribe()
+
+// With progress tracking
+// Automatically detects { progress: number } or { loaded, total } in emissions
+fileUpload().pipe(
+  notify({
+    loadingMessage: 'Uploading...',  // Updates to "Uploading... (50%)"
+    successMessage: 'Upload complete!',
+    errorMessage: 'Upload failed'
+  })
+).subscribe()
+```
 
-// Notification Container Component
+### notify() Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `loadingMessage` | string | Message during loading |
+| `loadingType` | NotificationType | Type for loading notification |
+| `successMessage` | string | Message on success |
+| `successType` | NotificationType | Type for success notification |
+| `successDuration` | number | Duration for success (ms, 0 = persistent) |
+| `errorMessage` | string \| (err) => string | Message on error |
+| `errorType` | NotificationType | Type for error notification |
+| `errorDuration` | number | Duration for error (ms, 0 = persistent) |
+| `autoDismissLoading` | boolean | Auto-dismiss loading on complete |
+
+## Components
+
+### Notification Container
+
+```html
 <sch-notification-container
   position="top-right|top-left|bottom-right|bottom-left|top-center|bottom-center"
-  max-visible-notifications="2"     // Max number shown at once (default: 2)
-  play-sound="true|false"          // Enable/disable sounds (default: false)
-  audio-volume="0.1">               // Volume level 0-1 (default: 0.1)
+  max-visible-notifications="2"     
+  play-sound="true|false"          
+  audio-volume="0.1">
 </sch-notification-container>
+```
 
-// Individual Notification Component (used internally)
+### Individual Notification (used internally)
+
+```html
 <sch-notification
   title="Title"
   message="Message text"
   type="info|success|warning|error"
-  duration="5000"                   // Auto-close after ms (0 = no auto-close)
+  duration="5000"         
   closable="true"
   play-sound="true"
-  @close>                          // Fired when notification closes
+  show-progress="false"   
+  @close>
 </sch-notification>
+```
 
-// Examples
-// Basic usage
-$notification.success("Operation completed successfully");
+## Examples
 
-// Without message (just icon)
-$notification.success();
+```js
+// Basic notifications
+$notify.success("Operation completed")
+$notify.error("Failed to save", { duration: 5000 })
+$notify.info() // Just icon, no message
 
-// With options
-$notification.error("Failed to save changes", {
-  title: "Error",
-  duration: 10000,
-  closable: true
-});
+// Persistent notification
+const id = $notify.persistent("Processing...")
+// Later: $notify.dismiss(id)
 
-// Custom notification
-$notification.notify({
-  type: "info",
-  message: "Custom message",
-  title: "Information",
-  duration: 0, // won't auto-close
-  playSound: false
-});
-
-// Programmatic control
-const notificationId = $notification.info("Processing...", { duration: 0 });
-// Later, to remove it:
-const container = document.querySelector('sch-notification-container');
-container.removeNotification(notificationId);
-
-// Setup notification container
-// Add this once in your app layout:
+// API with loading state
+fetchData().pipe(
+  notify({
+    loadingMessage: 'Fetching...',
+    successMessage: 'Data loaded!',
+    errorMessage: 'Failed'
+  })
+).subscribe()
+
+// File upload with progress
+upload(file).pipe(
+  notify({
+    loadingMessage: 'Uploading file...',
+    successMessage: 'Upload complete!',
+    successDuration: 3000,
+    errorMessage: (err) => `Upload failed: ${err.message}`,
+    errorDuration: 0  // Persistent error
+  })
+).subscribe()
+```
+
+## Setup
+
+Add the notification container once in your app layout:
+
+```html
 <sch-notification-container 
   position="top-right"
   max-visible-notifications="3"
   play-sound="true">
 </sch-notification-container>
-```
+```
+
+## Progress Indication
+
+- Notifications automatically show a progress bar when `duration > 0` (countdown)
+- When using `notify()` operator, shows indeterminate progress during loading
+- Detects progress in observable emissions:
+  - `{ progress: 50 }` - Shows "Loading... (50%)"
+  - `{ loaded: 500, total: 1000 }` - Shows "Loading... (50%)"

package/dist/ai/map.md

@@ -0,0 +1,232 @@
+# Schmancy Map Component
+
+The `schmancy-map` component provides an easy-to-use Google Maps integration with an intuitive API designed for both technical and non-technical users.
+
+## Installation
+
+```bash
+npm install @mhmo91/schmancy
+# or
+yarn add @mhmo91/schmancy
+```
+
+## Import
+
+```javascript
+import '@mhmo91/schmancy/map'
+```
+
+## API Reference
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `address` | `string` | `''` | Simple address string that automatically geocodes to display the location. Takes precedence over latitude/longitude if both are provided. |
+| `latitude` | `number` | `undefined` | Latitude coordinate for precise location. Used when address is not provided. |
+| `longitude` | `number` | `undefined` | Longitude coordinate for precise location. Used when address is not provided. |
+| `zoom` | `number` | `15` | Map zoom level. Higher numbers show more detail (1-20). |
+| `height` | `string` | `"400px"` | Height of the map with CSS unit (e.g., "400px", "50vh"). |
+| `marker` | `boolean` | `true` | Whether to show a marker at the location. |
+| `markerTitle` | `string` | `''` | Tooltip text for the location marker. |
+| `type` | `'roadmap' \| 'satellite' \| 'hybrid' \| 'terrain'` | `'roadmap'` | Map display type. |
+| `interactive` | `boolean` | `true` | Whether users can interact with the map (pan, zoom, click). |
+| `controls` | `boolean` | `true` | Whether to show map controls (zoom buttons, fullscreen, etc.). |
+| `apiKey` | `string` | `''` | Google Maps API key. Falls back to GOOGLE_MAPS_API_KEY environment variable. |
+
+## Basic Usage
+
+### Simple Address
+The easiest way to display a map - just provide an address:
+
+```html
+<schmancy-map address="Times Square, New York"></schmancy-map>
+```
+
+### Coordinates
+For precise positioning, use latitude and longitude:
+
+```html
+<schmancy-map 
+  latitude="40.758" 
+  longitude="-73.985" 
+  zoom="17">
+</schmancy-map>
+```
+
+### Custom Height
+Adjust the map size:
+
+```html
+<schmancy-map 
+  address="Central Park, New York" 
+  height="600px">
+</schmancy-map>
+```
+
+## Map Types
+
+### Satellite View
+```html
+<schmancy-map 
+  address="Grand Canyon" 
+  type="satellite" 
+  height="500px">
+</schmancy-map>
+```
+
+### Hybrid View
+Combines satellite imagery with labels:
+
+```html
+<schmancy-map 
+  address="Mount Everest" 
+  type="hybrid">
+</schmancy-map>
+```
+
+### Terrain View
+Shows topographical features:
+
+```html
+<schmancy-map 
+  address="Yellowstone National Park" 
+  type="terrain">
+</schmancy-map>
+```
+
+## Static Maps
+
+For display-only maps without user interaction:
+
+```html
+<schmancy-map 
+  address="Eiffel Tower, Paris" 
+  interactive="false" 
+  controls="false">
+</schmancy-map>
+```
+
+## Customization
+
+### Custom Marker
+```html
+<schmancy-map 
+  address="Statue of Liberty" 
+  markerTitle="Welcome to Liberty Island">
+</schmancy-map>
+```
+
+### No Marker
+```html
+<schmancy-map 
+  address="Pacific Ocean" 
+  marker="false">
+</schmancy-map>
+```
+
+### Different Zoom Levels
+```html
+<!-- City view -->
+<schmancy-map address="Tokyo" zoom="10"></schmancy-map>
+
+<!-- Street view -->
+<schmancy-map address="Tokyo Tower" zoom="18"></schmancy-map>
+```
+
+## API Key Setup
+
+### Environment Variable (Recommended)
+Set `GOOGLE_MAPS_API_KEY` in your environment:
+
+```bash
+GOOGLE_MAPS_API_KEY=your_api_key_here
+```
+
+### Direct Property
+```html
+<schmancy-map 
+  address="Sydney Opera House" 
+  api-key="your_api_key_here">
+</schmancy-map>
+```
+
+## Features
+
+### Automatic Geocoding
+- Converts human-readable addresses to coordinates
+- Handles various address formats
+- Provides error feedback for invalid addresses
+
+### Responsive Design
+- Adapts to container width
+- Configurable height with CSS units
+- Maintains aspect ratio on mobile
+
+### Loading States
+- Shows spinner while loading
+- Displays error messages for failed loads
+- Graceful fallback when maps can't load
+
+### Performance
+- Lazy loads Google Maps API
+- Caches script loading across components
+- Minimal bundle size impact
+
+## Error Handling
+
+The component handles various error scenarios:
+
+- **Invalid Address**: Shows error message with geocoding failure
+- **Missing API Key**: Clear error message about required API key
+- **Network Issues**: Graceful fallback with retry capability
+- **Invalid Coordinates**: Validation of latitude/longitude ranges
+
+## Accessibility
+
+- Proper ARIA labels for screen readers
+- Keyboard navigation support (when interactive)
+- High contrast error states
+- Semantic HTML structure
+
+## Browser Support
+
+- Modern browsers with ES2015+ support
+- Google Maps API compatibility
+- Progressive enhancement for older browsers
+
+## Examples in Real Applications
+
+### Store Locator
+```html
+<schmancy-map 
+  address="Apple Store, 5th Avenue, New York" 
+  zoom="16" 
+  marker-title="Apple Store - 5th Avenue">
+</schmancy-map>
+```
+
+### Event Location
+```html
+<schmancy-map 
+  address="Madison Square Garden, New York" 
+  height="300px" 
+  interactive="false">
+</schmancy-map>
+```
+
+### Property Listing
+```html
+<schmancy-map 
+  latitude="40.7831" 
+  longitude="-73.9712" 
+  zoom="15" 
+  marker-title="Beautiful Apartment">
+</schmancy-map>
+```
+
+## Best Practices
+
+1. **Use addresses for user-friendly input**: Most users understand addresses better than coordinates
+2. **Set appropriate zoom levels**: 10-12 for cities, 15-17 for neighborhoods, 18+ for buildings
+3. **Consider mobile users**: Use responsive heights like "50vh" for mobile-friendly maps
+4. **Provide meaningful marker titles**: Help users understand what the marker represents
+5. **Use static maps for display-only**: Disable interaction when the map is purely informational