@mhmo91/schmancy 0.8.6 → 0.9.3

package/ai/map.md

@@ -1,234 +1,55 @@
-# Schmancy Map Component
+# schmancy-map
 
-The `schmancy-map` component provides an easy-to-use Google Maps integration with an intuitive API designed for both technical and non-technical users.
+> Google Maps component. Accepts address string (auto-geocoded) or exact lat/lng. Singleton-loaded Maps SDK.
 
-## Installation
-
-```bash
-npm install @mhmo91/schmancy
-# or
-yarn add @mhmo91/schmancy
-```
-
-## Import
+## Usage
+```html
+<!-- By address -->
+<schmancy-map
+  address="Times Square, New York"
+  api-key="YOUR_GOOGLE_MAPS_KEY"
+></schmancy-map>
 
-```javascript
-import '@schmancy/index'  // For all Schmancy components
-// Or specific import: import '@schmancy/map'
+<!-- By coordinates -->
+<schmancy-map
+  .latitude=${40.758}
+  .longitude=${-73.985}
+  .zoom=${15}
+  type="satellite"
+  api-key="YOUR_GOOGLE_MAPS_KEY"
+></schmancy-map>
 ```
 
-## API Reference
-
-
+## Properties
 | 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>
+| `address` | string | — | Location for geocoding (e.g. `"Eiffel Tower, Paris"`) |
+| `latitude` | number | — | Precise latitude (takes precedence over address) |
+| `longitude` | number | — | Precise longitude |
+| `zoom` | number | default Maps default | Map zoom level |
+| `type` | `'roadmap' \| 'satellite' \| 'hybrid' \| 'terrain'` | `'roadmap'` | Map style |
+| `height` | string | — | Custom height (e.g. `'400px'`, `'60vh'`) |
+| `apiKey` | string | **required** | Google Maps API key |
+
+## Behavior
+- The first `schmancy-map` instance triggers a singleton script load of `maps.googleapis.com/maps/api/js` with the `places` library.
+- Subsequent instances reuse the same loader — no duplicate network requests.
+- If `address` is provided without coordinates, the built-in `Geocoder` resolves it before rendering.
+- Errors (invalid key, unauthorized domain, geocode failure) render a fallback message inside the host.
+
+## Setup
+1. Acquire a Google Maps JavaScript API key from Google Cloud Console.
+2. Enable the **Maps JavaScript API** and **Geocoding API**.
+3. Add your domain to the authorized list.
+
+## Example
+```html
+<schmancy-surface type="subtle" rounded="all">
+  <schmancy-map
+    address="1600 Amphitheatre Parkway, Mountain View, CA"
+    height="320px"
+    type="hybrid"
+    .apiKey=${import.meta.env.VITE_GOOGLE_MAPS_KEY}
+  ></schmancy-map>
+</schmancy-surface>
 ```
-
-### 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/menu.md

@@ -1,148 +1,39 @@
-# Schmancy Menu - AI Reference
+# schmancy-menu
 
-## Overview
+> Context menu that opens a dialog with menu items positioned at the click location.
 
-The menu component provides context menus and dropdown menus using the `$dialog` service for positioning. Menus are portaled to `document.body` for proper z-index handling and work correctly in complex layouts (tables, virtualizers, overflow containers).
-
-## Architecture
-
-- **Positioning**: Uses `$dialog.component()` with mouse event position
-- **Portal Pattern**: Menu items are temporarily moved to dialog at `document.body` level
-- **Fixed Positioning**: Menus stay fixed to viewport and don't scroll with content
-- **Auto-close**: Menus close on item click or when clicking outside
-
-## Basic Usage
-
-```js
-// Basic Menu
+## Usage
+```html
 <schmancy-menu>
-  <schmancy-menu-item @click=${() => console.log('Item 1')}>Item 1</schmancy-menu-item>
-  <schmancy-menu-item @click=${() => console.log('Item 2')}>Item 2</schmancy-menu-item>
-  <schmancy-menu-item @click=${() => console.log('Item 3')}>Item 3</schmancy-menu-item>
+  <schmancy-button slot="trigger">Actions</schmancy-button>
+  <schmancy-menu-item @click=${() => edit()}>Edit</schmancy-menu-item>
+  <schmancy-menu-item @click=${() => remove()}>Delete</schmancy-menu-item>
 </schmancy-menu>
+```
 
-// Menu with icons
-<schmancy-menu>
-  <schmancy-menu-item @click=${handleCopy}>
-    <schmancy-icon slot="leading">content_copy</schmancy-icon>
-    Copy
-  </schmancy-menu-item>
+## Slots
+| Slot | Description |
+|------|-------------|
+| trigger | Button that opens the menu (clicks open dialog) |
+| button | Legacy alias for trigger |
+| default | Menu items or custom content |
 
-  <schmancy-menu-item @click=${handleCut}>
-    <schmancy-icon slot="leading">content_cut</schmancy-icon>
-    Cut
-  </schmancy-menu-item>
+## schmancy-menu-item
+Auto-dismisses the dialog when clicked. Renders as a `schmancy-list-item` internally.
 
-  <schmancy-menu-item @click=${handlePaste}>
-    <schmancy-icon slot="leading">content_paste</schmancy-icon>
-    Paste
-  </schmancy-menu-item>
-</schmancy-menu>
-
-// Menu with custom trigger button
+## Examples
+```html
+<!-- With icon button trigger -->
 <schmancy-menu>
-  <schmancy-button slot="button" variant="filled">
-    Actions
-  </schmancy-button>
-  <schmancy-menu-item @click=${() => console.log('Edit')}>
-    Edit
-  </schmancy-menu-item>
-  <schmancy-menu-item @click=${() => console.log('Delete')}>
-    Delete
-  </schmancy-menu-item>
+  <schmancy-icon-button slot="trigger">more_vert</schmancy-icon-button>
+  <schmancy-menu-item @click=${() => duplicate()}>Duplicate</schmancy-menu-item>
+  <schmancy-menu-item @click=${() => archive()}>Archive</schmancy-menu-item>
 </schmancy-menu>
 
-// Default icon button trigger (no button slot provided)
+<!-- Default trigger (three-dot icon button) -->
 <schmancy-menu>
-  <schmancy-menu-item @click=${handleAction1}>Action 1</schmancy-menu-item>
-  <schmancy-menu-item @click=${handleAction2}>Action 2</schmancy-menu-item>
+  <schmancy-menu-item @click=${() => share()}>Share</schmancy-menu-item>
 </schmancy-menu>
 ```
 
-## API Reference
-
-### Menu Component
-
-**Slots:**
-- `button` - Custom trigger button (defaults to icon button with more_vert if not provided)
-- `default` - Menu items (use schmancy-menu-item components)
-
-**Positioning:**
-- Automatically positioned using $dialog service
-- Fixed to viewport (doesn't scroll with content)
-- Portaled to document.body for proper stacking
-- Works in complex layouts (tables, virtualizers, etc.)
-
-### Menu Item Component
-
-**Slots:**
-- `leading` - Icon or content before the text
-- `trailing` - Icon or content after the text
-- `default` - Main content
-
-**Events:**
-- `schmancy-menu-item-click` - Fired when clicked (bubbles up, auto-closes menu)
-
-## Real-World Examples
-
-### Menu in Table Header (sorting)
-```js
-<schmancy-menu>
-  <schmancy-icon-button slot="button" size="sm">
-    ${sortDirection === 'asc' ? 'arrow_upward' : 'arrow_downward'}
-  </schmancy-icon-button>
-  ${sortOptions.map(opt => html`
-    <schmancy-menu-item @click=${() => handleSort(opt.value)}>
-      ${opt.active ? html`<schmancy-icon slot="start">check</schmancy-icon>` : ''}
-      ${opt.label}
-      ${opt.active ? html`<schmancy-icon slot="end">${direction}</schmancy-icon>` : ''}
-    </schmancy-menu-item>
-  `)}
-</schmancy-menu>
-```
-
-### Menu in Virtualized List/Table
-Works correctly in lit-virtualizer, overflow containers, and complex layouts:
-```js
-<lit-virtualizer .items=${items} .renderItem=${item => html`
-  <div class="table-row">
-    <span>${item.name}</span>
-    <schmancy-menu>
-      <schmancy-menu-item @click=${() => edit(item)}>Edit</schmancy-menu-item>
-      <schmancy-menu-item @click=${() => delete(item)}>Delete</schmancy-menu-item>
-    </schmancy-menu>
-  </div>
-`}></lit-virtualizer>
-```
-
-### Menu in Cards
-```js
-<schmancy-surface type="container" class="p-6">
-  <div class="flex justify-between items-start">
-    <h3>Card Title</h3>
-    <schmancy-menu>
-      <schmancy-menu-item @click=${handleShare}>
-        <schmancy-icon slot="leading">share</schmancy-icon>
-        Share
-      </schmancy-menu-item>
-      <schmancy-menu-item @click=${handleEdit}>
-        <schmancy-icon slot="leading">edit</schmancy-icon>
-        Edit
-      </schmancy-menu-item>
-      <schmancy-menu-item @click=${handleDelete}>
-        <schmancy-icon slot="leading">delete</schmancy-icon>
-        Delete
-      </schmancy-menu-item>
-    </schmancy-menu>
-  </div>
-</schmancy-surface>
-```
-
-## Implementation Notes
-
-- Menu items are temporarily moved to dialog container when opened
-- Items are moved back to original location when menu closes
-- All event handlers remain functional during the move
-- Menu positioning is handled by $dialog service using floating-ui
-- No need to manage z-index or positioning manually
-```
+Uses `$dialog.component()` internally. Menu items auto-dismiss the dialog. Custom components in the default slot must call `$dialog.dismiss()` manually.

package/ai/mixins.md

@@ -0,0 +1,201 @@
+# $LitElement — Base Class Foundation
+
+> **Every Schmancy component extends `$LitElement`. No exceptions.**
+> It wires RxJS cleanup, Tailwind, cross-shadow discovery, and a few quality-of-life helpers into every element — so you never write that plumbing yourself.
+
+## The minimal component
+
+```typescript
+import { $LitElement } from '@mhmo91/schmancy/mixins'
+import { customElement } from 'lit/decorators.js'
+import { css, html } from 'lit'
+
+@customElement('my-card')
+class MyCard extends $LitElement(css`
+  :host { display: block; }
+`) {
+  render() {
+    return html`<slot></slot>`
+  }
+}
+```
+
+That's it. You now get the five things below for free.
+
+## What `$LitElement` gives you
+
+### 1. `disconnecting` — automatic RxJS cleanup
+```typescript
+connectedCallback() {
+  super.connectedCallback()
+
+  userContext.$.pipe(
+    takeUntil(this.disconnecting),
+  ).subscribe(user => this.user = user)
+}
+```
+
+`disconnecting` is a `Subject<void>` that emits once when the element is detached from the DOM. Paired with `takeUntil`, it makes the entire Schmancy codebase manual-unsubscribe-free.
+
+**This is the single most-used line in a Schmancy app.** If you see an RxJS pipe without `takeUntil(this.disconnecting)` — it's a leak.
+
+### 2. `classMap(obj)` — space-splitting enhanced
+```typescript
+render() {
+  return html`
+    <div class=${this.classMap({
+      'flex items-center gap-2': true,
+      'bg-primary-default': this.active,
+      'opacity-50 pointer-events-none': this.disabled,
+    })}>
+      …
+    </div>
+  `
+}
+```
+
+Unlike standard Lit `classMap`, keys can be **space-separated** ("flex items-center gap-2"). Combined with Tailwind, you write natural class strings instead of one-class-per-key.
+
+**Hard rule:** `class=${this.classMap(...)}` must be the *sole* expression in `class=`. You cannot mix it with string interpolation (` class="foo ${this.classMap(...)}"`) — Lit will fail silently.
+
+### 3. `styleMap(obj)` — inline styles (passthrough)
+```typescript
+render() {
+  return html`
+    <div style=${this.styleMap({
+      width: `${this.size}px`,
+      opacity: this.visible ? 1 : 0,
+    })}></div>
+  `
+}
+```
+
+Direct passthrough to Lit's `styleMap` directive, exposed as a method so you don't have to import it in every component.
+
+### 4. `discover<T>(tag)` — cross-shadow component lookup
+```typescript
+connectedCallback() {
+  super.connectedCallback()
+
+  this.discover<SchmancyDialog>('schmancy-dialog').pipe(
+    takeUntil(this.disconnecting),
+  ).subscribe(dialog => dialog?.setDefaultAction('confirm'))
+}
+```
+
+Broadcasts a `{tag}-where-are-you` event. Any mounted `$LitElement` with that tag responds with itself. Works **across shadow DOM boundaries** — zero traversal.
+
+### 5. Auto-response to discovery events
+Every `$LitElement` automatically answers `{its-tag}-where-are-you` by dispatching `{its-tag}-here-i-am` with `{ detail: { component: this } }`. You opt in by extending — opt out by not.
+
+## Tailwind support
+
+Styles you import are pre-processed through the Schmancy Tailwind pipeline. Tailwind utility classes work in both the host and slotted content. All theme CSS variables (`--schmancy-sys-color-primary-default`, etc.) resolve inside the component's shadow root.
+
+```typescript
+// Works out of the box
+render() {
+  return html`<div class="flex items-center gap-2 text-primary-default">…</div>`
+}
+```
+
+## Extending with SCSS
+
+For complex styling, import a `.scss?inline` file and pass it to `$LitElement`:
+
+```typescript
+import style from './my-card.scss?inline'
+
+@customElement('my-card')
+class MyCard extends $LitElement(style) {
+  // SCSS features: nesting, mixins, @layer
+}
+```
+
+Simple components use template-literal CSS; complex ones use SCSS.
+
+## Standard component shape
+
+This is the skeleton 90% of Schmancy components follow:
+
+```typescript
+import { $LitElement } from '@mhmo91/schmancy/mixins'
+import { css, html } from 'lit'
+import { customElement, property, state } from 'lit/decorators.js'
+import { Subject, takeUntil } from 'rxjs'
+
+@customElement('my-component')
+export class MyComponent extends $LitElement(css`
+  :host { display: block; }
+`) {
+  // 1. Public API — reflected / typed
+  @property({ type: String, reflect: true }) variant: 'a' | 'b' = 'a'
+  @property({ type: Boolean, reflect: true }) disabled = false
+
+  // 2. Internal state
+  @state() private _open = false
+
+  // 3. Private RxJS subjects (if needed)
+  private _value$ = new Subject<string>()
+
+  // 4. Lifecycle
+  connectedCallback() {
+    super.connectedCallback()
+    this._value$.pipe(
+      debounceTime(150),
+      takeUntil(this.disconnecting),
+    ).subscribe(v => this.handleValue(v))
+  }
+
+  // 5. Rendering
+  render() {
+    return html`
+      <div class=${this.classMap({
+        'flex items-center': true,
+        'opacity-50': this.disabled,
+      })}>
+        <slot></slot>
+      </div>
+    `
+  }
+
+  // 6. Public imperative API (if any)
+  public open() { this._open = true }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'my-component': MyComponent
+  }
+}
+```
+
+Guarantees from this shape:
+- Every subscription dies with the element.
+- Tailwind + theme tokens work.
+- Component is discoverable from anywhere via `discover('my-component')`.
+- Declared in the global tag map for TypeScript.
+
+## Why not `LitElement` directly?
+
+You can, but you'll re-implement:
+- Manual unsubscribe handling in `disconnectedCallback` for every `Observable`.
+- `classMap` space-splitting.
+- Tailwind variable wiring.
+- Cross-shadow discovery.
+
+`$LitElement` is 200 lines of common-denominator plumbing that keeps apps consistent. Using it is the convention; not using it is the outlier.
+
+## Rules
+
+1. **Every custom element extends `$LitElement(style?)`.**
+2. **Every RxJS subscription ends with `.pipe(takeUntil(this.disconnecting))`** — or you have a leak.
+3. **Call `super.connectedCallback()` and `super.disconnectedCallback()`** when you override them.
+4. **Don't mix `classMap` with string interpolation** in the same attribute.
+5. **Prefer `ref(createRef())` over `querySelector`** for your own shadow tree.
+6. **Register in `HTMLElementTagNameMap`** for TypeScript autocompletion.
+
+## See also
+- [store](./store.md) — contexts pair with `takeUntil(this.disconnecting)` for auto-cleaning subscriptions.
+- [area](./area.md) — route components all extend `$LitElement`.
+- [discovery](./discovery.md) — the discovery events `$LitElement` handles automatically.