@mhmo91/schmancy 0.4.8 → 0.4.10

package/ai/timezone.md

@@ -0,0 +1,275 @@
+# Schmancy Timezone Select - AI Reference
+
+## Quick Start
+
+```typescript
+import '@mhmo91/schmancy/extra/timezone'
+```
+
+## Component Overview
+
+A timezone selection component with autocomplete functionality, providing a comprehensive list of global timezones with UTC offsets and region information.
+
+## API
+
+```typescript
+// Timezone Select Component
+<schmancy-select-timezones
+  value?="string"                    // Selected timezone ID
+  label?="string"                    // Label text (default: "Timezone")
+  hint?="string"                     // Helper text (default: "Please select a timezone")
+  placeholder?="string"              // Placeholder (default: "Select a timezone")
+  name?="string"                     // Form field name
+  required?="boolean"                // Required field
+  @change=${handleChange}>           // Selection change event
+</schmancy-select-timezones>
+
+// Component Properties
+value: string         // Timezone identifier (e.g., "America/New_York")
+label: string        // Field label
+hint: string         // Helper text below field
+placeholder: string  // Placeholder text
+name: string         // Form field name
+required: boolean    // Required validation
+
+// Events
+@change  // Fires when timezone selection changes
+
+// Methods
+checkValidity() -> boolean      // Validate selection
+reportValidity() -> boolean     // Report validation state
+setCustomValidity(message) -> void  // Set custom error
+```
+
+## Examples
+
+### Basic Usage
+
+```typescript
+// Simple timezone selector
+<schmancy-select-timezones 
+  @change=${(e) => console.log('Selected:', e.detail.value)}>
+</schmancy-select-timezones>
+
+// With initial value
+<schmancy-select-timezones 
+  value="America/New_York"
+  @change=${handleTimezoneChange}>
+</schmancy-select-timezones>
+
+// Required field
+<schmancy-select-timezones 
+  required
+  name="timezone"
+  label="Your Timezone"
+  hint="Used for scheduling">
+</schmancy-select-timezones>
+```
+
+### Form Integration
+
+```typescript
+// User preferences form
+<schmancy-form @submit=${handleSavePreferences}>
+  <schmancy-select-timezones 
+    name="timezone" 
+    value=${this.userTimezone}
+    required>
+  </schmancy-select-timezones>
+  
+  <schmancy-select-countries 
+    name="country" 
+    value=${this.userCountry}>
+  </schmancy-select-countries>
+  
+  <schmancy-button type="submit" variant="filled">
+    Save Preferences
+  </schmancy-button>
+</schmancy-form>
+```
+
+### Real-World Examples
+
+```typescript
+// Meeting scheduler with timezone
+class MeetingScheduler extends LitElement {
+  @state() selectedTimezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  @state() meetingTime = '';
+  
+  render() {
+    return html`
+      <schmancy-surface class="p-6">
+        <schmancy-typography type="headline" token="sm" class="mb-4 block">
+          Schedule Meeting
+        </schmancy-typography>
+        
+        <schmancy-form @submit=${this.scheduleMeeting}>
+          <div class="space-y-4">
+            <schmancy-input 
+              type="datetime-local"
+              label="Meeting Time"
+              name="time"
+              required
+              @change=${(e) => this.meetingTime = e.detail.value}>
+            </schmancy-input>
+            
+            <schmancy-select-timezones 
+              name="timezone"
+              value=${this.selectedTimezone}
+              @change=${this.handleTimezoneChange}>
+            </schmancy-select-timezones>
+            
+            <div class="bg-surface-container p-3 rounded">
+              <schmancy-typography type="body" token="sm">
+                ${this.getLocalTimeDisplay()}
+              </schmancy-typography>
+            </div>
+          </div>
+          
+          <schmancy-button type="submit" variant="filled" class="mt-4">
+            Schedule
+          </schmancy-button>
+        </schmancy-form>
+      </schmancy-surface>
+    `
+  }
+  
+  getLocalTimeDisplay() {
+    if (!this.meetingTime || !this.selectedTimezone) return '';
+    // Convert to different timezones for display
+    const date = new Date(this.meetingTime);
+    return `Local time: ${date.toLocaleString('en-US', { 
+      timeZone: this.selectedTimezone 
+    })}`;
+  }
+}
+
+// User profile with auto-detection
+class UserProfile extends LitElement {
+  @state() detectedTimezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  
+  connectedCallback() {
+    super.connectedCallback();
+    // Auto-detect user's timezone
+    this.requestUpdate();
+  }
+  
+  render() {
+    return html`
+      <div class="space-y-4">
+        <schmancy-typography type="body" token="sm" class="text-surface-onVariant">
+          Detected timezone: ${this.detectedTimezone}
+        </schmancy-typography>
+        
+        <schmancy-select-timezones 
+          value=${this.detectedTimezone}
+          label="Confirm your timezone"
+          hint="We'll use this for notifications and scheduling"
+          @change=${this.updateTimezone}>
+        </schmancy-select-timezones>
+        
+        <schmancy-button 
+          variant="filled" 
+          @click=${this.saveProfile}>
+          Save Profile
+        </schmancy-button>
+      </div>
+    `
+  }
+}
+```
+
+## Timezone Data Structure
+
+Each timezone in the dataset includes:
+
+```typescript
+interface Timezone {
+  text: string;   // Display text with offset (e.g., "(UTC-05:00) Eastern Time")
+  value: string;  // Timezone ID (e.g., "America/New_York")
+  offset: string; // UTC offset (e.g., "-05:00")
+  abbr: string;   // Abbreviation (e.g., "EST")
+}
+
+// Example:
+{
+  text: "(UTC-05:00) Eastern Time (US & Canada)",
+  value: "America/New_York",
+  offset: "-05:00",
+  abbr: "EST"
+}
+```
+
+## Features
+
+- **Comprehensive List**: All global timezones with regions
+- **UTC Offsets**: Visual offset display for easy identification
+- **Search**: Filter by timezone name, city, or offset
+- **Auto-detection**: Can detect user's current timezone
+- **Daylight Saving**: Handles DST automatically
+- **Form Integration**: Works with native forms
+- **Grouped Display**: Timezones grouped by offset
+
+## Common Use Cases
+
+1. **User Preferences**: Setting user's default timezone
+2. **Event Scheduling**: Selecting timezone for meetings/events
+3. **Notifications**: Configuring notification delivery times
+4. **Reports**: Setting timezone for data analysis
+5. **International Apps**: Multi-timezone support
+
+## Accessibility
+
+- Proper ARIA labels and roles
+- Keyboard navigation support
+- Screen reader friendly
+- High contrast mode support
+- Clear visual indicators
+
+## Best Practices
+
+1. **Auto-Detection**: Pre-select user's detected timezone
+2. **Display Format**: Show both offset and name
+3. **Validation**: Use required for mandatory fields
+4. **Updates**: Handle timezone database updates
+5. **DST Handling**: Account for daylight saving changes
+
+## Common Pitfalls
+
+- **ID vs Display**: Value is timezone ID, not display text
+- **DST Changes**: Offsets may vary with daylight saving
+- **Browser Support**: Intl API availability varies
+- **Historical Data**: Past dates may have different offsets
+
+## Related Components
+
+- **[Autocomplete](./autocomplete.md)**: Base component
+- **[Countries](./countries.md)**: Often used together
+- **[Form](./form.md)**: Form integration
+- **[Date Range](./date-range.md)**: Date/time selection
+
+## TypeScript Interface
+
+```typescript
+interface SchmancySelectTimezonesElement extends HTMLElement {
+  value: string;
+  label: string;
+  hint: string;
+  placeholder: string;
+  name: string;
+  required: boolean;
+  checkValidity(): boolean;
+  reportValidity(): boolean;
+  setCustomValidity(message: string): void;
+}
+
+// Change event
+interface TimezoneChangeEvent extends CustomEvent {
+  detail: {
+    value: string;  // Timezone ID
+  };
+}
+
+// Utility functions
+const userTimezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+```

package/ai/typography.md

@@ -3,23 +3,27 @@
 ```js
 // Component Tag
 <schmancy-typography
-  type="display|headline|title|label|body"                // Typography scale type
-  token="lg|md|sm"                                        // Size token within type
-  class?="additional-tailwind-classes"                    // Additional styling
-  tag?="h1|h2|h3|h4|h5|h6|p|span|div"                   // HTML element (auto-determined by type/token)
-  @click=${handler}>                                      // Click handler
+  type="display|headline|title|subtitle|label|body"      // Typography scale type
+  token="xl|lg|md|sm|xs"                                 // Size token within type
+  align?="left|center|justify|right"                     // Text alignment
+  weight?="normal|medium|bold"                           // Font weight override
+  transform?="uppercase|lowercase|capitalize|normal"     // Text transformation
+  maxLines?="1|2|3|4|5|6"                               // Truncate with ellipsis
+  class?="additional-tailwind-classes"                   // Additional styling
+  @click=${handler}>                                     // Click handler
   <!-- Text content or HTML -->
 </schmancy-typography>
 
 // Import
 import '@mhmo91/schmancy/typography'
 
-// Typography Scale Reference
-// Display: lg (57/64), md (45/52), sm (36/44)
-// Headline: lg (32/40), md (28/36), sm (24/32)
-// Title: lg (22/28), md (16/24), sm (14/20)
-// Label: lg (14/20), md (12/16), sm (11/16)
-// Body: lg (16/24), md (14/20), sm (12/16)
+// Typography Scale Reference (size/line-height)
+// Display: xl (72/80), lg (57/64), md (45/52), sm (36/44), xs (28/36)
+// Headline: xl (36/44), lg (32/40), md (28/36), sm (24/32), xs (20/28)
+// Title: xl (28/36), lg (22/28), md (16/24), sm (14/20), xs (12/16)
+// Subtitle: xl (20/28), lg (18/24), md (16/20), sm (14/18), xs (12/16)
+// Label: xl (16/24), lg (14/20), md (12/16), sm (11/16), xs (10/14)
+// Body: xl (18/28), lg (16/24), md (14/20), sm (12/16), xs (10/14)
 
 // Examples
 // 1. Page heading (Display)
@@ -52,9 +56,9 @@ import '@mhmo91/schmancy/typography'
   Highlighted Section
 </schmancy-typography>
 
-// 7. Custom tag usage
-<schmancy-typography type="display" token="md" tag="h1">
-  Main Page Title
+// 7. Centered uppercase title
+<schmancy-typography type="title" token="lg" align="center" transform="uppercase">
+  Section Header
 </schmancy-typography>
 
 // 8. Clickable text
@@ -62,9 +66,9 @@ import '@mhmo91/schmancy/typography'
   Click me for more information
 </schmancy-typography>
 
-// 9. Mixed content with HTML
-<schmancy-typography type="body" token="lg">
-  This text contains <strong>bold</strong> and <em>italic</em> elements.
+// 9. Truncated text with ellipsis
+<schmancy-typography type="body" token="md" maxLines="2">
+  This is a long description that will be truncated after two lines with an ellipsis if it exceeds the available space...
 </schmancy-typography>
 
 // 10. Multiple typography in a card
@@ -91,40 +95,73 @@ import '@mhmo91/schmancy/typography'
 ## Technical Details
 
 ### Typography Scale System
-Material Design 3 typography scale with 5 scales, each with 3 sizes:
+Material Design 3 typography scale with 6 types, each with 5 sizes:
 
-**Display** - Largest text for big statements
+**Display** - Largest text for big statements (weight: 400)
+- `xl`: 72px/80px line-height
 - `lg`: 57px/64px line-height
 - `md`: 45px/52px line-height
 - `sm`: 36px/44px line-height
+- `xs`: 28px/36px line-height
 
-**Headline** - Section headers and important titles
+**Headline** - Section headers and important titles (weight: 400)
+- `xl`: 36px/44px line-height
 - `lg`: 32px/40px line-height
 - `md`: 28px/36px line-height
 - `sm`: 24px/32px line-height
-
-**Title** - Smaller titles and subtitles
-- `lg`: 22px/28px line-height
-- `md`: 16px/24px line-height
-- `sm`: 14px/20px line-height
-
-**Label** - UI labels and buttons
+- `xs`: 20px/28px line-height
+
+**Title** - Smaller titles and subtitles (weight: 400-500)
+- `xl`: 28px/36px line-height (weight: 500)
+- `lg`: 22px/28px line-height (weight: 400)
+- `md`: 16px/24px line-height (weight: 500)
+- `sm`: 14px/20px line-height (weight: 500)
+- `xs`: 12px/16px line-height (weight: 500)
+
+**Subtitle** - Secondary headings (weight: 400)
+- `xl`: 20px/28px line-height
+- `lg`: 18px/24px line-height
+- `md`: 16px/20px line-height
+- `sm`: 14px/18px line-height
+- `xs`: 12px/16px line-height
+
+**Label** - UI labels and buttons (weight: 500)
+- `xl`: 16px/24px line-height
 - `lg`: 14px/20px line-height
 - `md`: 12px/16px line-height
 - `sm`: 11px/16px line-height
+- `xs`: 10px/14px line-height
 
-**Body** - Main content text
+**Body** - Main content text (weight: 400)
+- `xl`: 18px/28px line-height
 - `lg`: 16px/24px line-height
 - `md`: 14px/20px line-height
 - `sm`: 12px/16px line-height
+- `xs`: 10px/14px line-height
+
+### Additional Properties
+
+**Text Alignment** (`align`)
+- `left`: Align text to the left
+- `center`: Center the text
+- `justify`: Justify text
+- `right`: Align text to the right
 
-### Automatic Tag Selection
-The component automatically selects appropriate HTML tags:
-- Display: `h1`, `h2`, `h3`
-- Headline: `h3`, `h4`, `h5`
-- Title: `h5`, `h6`, `p`
-- Label: `span`
-- Body: `p`
+**Font Weight** (`weight`)
+- `normal`: 400 weight
+- `medium`: 500 weight
+- `bold`: 700 weight
+
+**Text Transform** (`transform`)
+- `uppercase`: Convert to uppercase
+- `lowercase`: Convert to lowercase
+- `capitalize`: Capitalize first letter of each word
+- `normal`: No transformation
+
+**Line Clamping** (`maxLines`)
+- Truncates text after specified number of lines
+- Adds ellipsis (...) at the end
+- Values: 1-6 lines
 
 ### Theme Integration
 Typography automatically inherits colors from the theme:
@@ -132,14 +169,12 @@ Typography automatically inherits colors from the theme:
 - Respects surface container colors
 - Can be overridden with Tailwind classes
 
-### CSS Custom Properties
-The component uses Material Design 3 type scale tokens:
-```css
---schmancy-sys-typescale-[type]-[token]-size
---schmancy-sys-typescale-[type]-[token]-line-height
---schmancy-sys-typescale-[type]-[token]-weight
---schmancy-sys-typescale-[type]-[token]-letter-spacing
-```
+### Implementation Details
+- Uses Shadow DOM with encapsulated styles
+- All typography values are hardcoded in the component
+- Renders as a `<span>` element with `display: inherit`
+- Font family: system-ui, -apple-system, sans-serif
+- Letter spacing is set to 0 for all variants
 
 ## Common Use Cases
 

package/dist/ai/button.md

@@ -8,17 +8,20 @@
   type="button|reset|submit"                            // HTML button type (default: "button")
   href?="string"                                        // Makes button a link
   disabled?                                             // Disable state
-  ariaLabel?="string"                                   // Accessibility label
+  aria-label?="string"                                  // Accessibility label
   @click=${handler}>
   <!-- Content with optional prefix/suffix slots -->
 </schmancy-button>
 
 // Icon Button Component
 <schmancy-icon-button
-  variant="filled|filled tonal|outlined|standard"      // Visual style (default: "standard")
+  variant="elevated|filled|filled tonal|outlined|text"  // Visual style (default: "text")
   size="sm|md|lg"                                      // Button size (default: "md")
+  width="full|auto"                                     // Button width (default: "auto")
+  type="button|reset|submit"                            // HTML button type (default: "button")
+  href?="string"                                        // Makes button a link
   disabled?                                             // Disable state
-  ariaLabel="string">                                  // REQUIRED for accessibility
+  aria-label="string">                                  // Accessibility label
   icon_name
 </schmancy-icon-button>