@mhmo91/schmancy 0.8.6 → 0.9.3

package/ai/countries.md

@@ -1,271 +0,0 @@
-# Schmancy Countries Select - AI Reference
-
-## Quick Start
-
-```typescript
-import '@schmancy/index'  // For all Schmancy components
-// Or specific import: import '@schmancy/extra' // Countries are part of extra
-```
-
-## Component Overview
-
-A specialized country selection component with autocomplete, built on top of schmancy-autocomplete with a comprehensive list of countries including flags and dial codes.
-
-## API
-
-```typescript
-// Countries Select Component
-<schmancy-select-countries
-  value?="string"                    // Selected country code
-  label?="string"                    // Label text (default: "Country")
-  hint?="string"                     // Helper text (default: "Please select a country")
-  placeholder?="string"              // Placeholder (default: "Select a country")
-  name?="string"                     // Form field name
-  required?="boolean"                // Required field
-  @change=${handleChange}>           // Selection change event
-</schmancy-select-countries>
-
-// Component Properties
-value: string         // ISO country code (e.g., "US", "GB")
-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 country selection changes
-
-// Methods
-checkValidity() -> boolean      // Validate selection
-reportValidity() -> boolean     // Report validation state
-setCustomValidity(message) -> void  // Set custom error
-```
-
-## Examples
-
-### Basic Usage
-
-```typescript
-// Simple country selector
-<schmancy-select-countries 
-  @change=${(e) => console.log('Selected:', e.detail.value)}>
-</schmancy-select-countries>
-
-// With initial value
-<schmancy-select-countries 
-  value="US"
-  @change=${handleCountryChange}>
-</schmancy-select-countries>
-
-// Required field
-<schmancy-select-countries 
-  required
-  name="country"
-  label="Your Country"
-  hint="Required for shipping">
-</schmancy-select-countries>
-```
-
-### Form Integration
-
-```typescript
-// In a registration form
-<schmancy-form @submit=${handleSubmit}>
-  <schmancy-input 
-    label="Full Name" 
-    name="name" 
-    required>
-  </schmancy-input>
-  
-  <schmancy-select-countries 
-    name="country" 
-    required
-    @change=${updatePhoneFormat}>
-  </schmancy-select-countries>
-  
-  <schmancy-input 
-    label="Phone" 
-    name="phone" 
-    type="tel">
-  </schmancy-input>
-  
-  <schmancy-button type="submit" variant="filled">
-    Register
-  </schmancy-button>
-</schmancy-form>
-```
-
-### Real-World Examples
-
-```typescript
-// Address form with country
-class AddressForm extends LitElement {
-  @state() selectedCountry = '';
-  
-  render() {
-    return html`
-      <schmancy-surface class="p-6">
-        <schmancy-typography type="headline" token="sm" class="mb-4 block">
-          Shipping Address
-        </schmancy-typography>
-        
-        <schmancy-form @submit=${this.handleSubmit}>
-          <div class="grid gap-4">
-            <schmancy-input 
-              label="Street Address" 
-              name="street" 
-              required>
-            </schmancy-input>
-            
-            <div class="grid grid-cols-2 gap-4">
-              <schmancy-input 
-                label="City" 
-                name="city" 
-                required>
-              </schmancy-input>
-              
-              <schmancy-input 
-                label="Postal Code" 
-                name="postalCode" 
-                required>
-              </schmancy-input>
-            </div>
-            
-            <schmancy-select-countries 
-              name="country" 
-              required
-              value=${this.selectedCountry}
-              @change=${(e) => this.selectedCountry = e.detail.value}>
-            </schmancy-select-countries>
-            
-            ${this.selectedCountry === 'US' ? html`
-              <schmancy-select 
-                label="State" 
-                name="state" 
-                required>
-                <!-- State options -->
-              </schmancy-select>
-            ` : ''}
-          </div>
-          
-          <schmancy-button type="submit" variant="filled" class="mt-4">
-            Save Address
-          </schmancy-button>
-        </schmancy-form>
-      </schmancy-surface>
-    `
-  }
-}
-
-// Phone number with country code
-class PhoneInput extends LitElement {
-  @state() countryCode = '';
-  @state() dialCode = '';
-  
-  handleCountryChange(e) {
-    const country = countriesData.find(c => c.code === e.detail.value);
-    this.dialCode = country?.dial_code || '';
-  }
-  
-  render() {
-    return html`
-      <div class="space-y-4">
-        <schmancy-select-countries 
-          @change=${this.handleCountryChange}>
-        </schmancy-select-countries>
-        
-        <schmancy-input 
-          label="Phone Number"
-          .value=${this.dialCode}
-          placeholder="${this.dialCode} ">
-        </schmancy-input>
-      </div>
-    `
-  }
-}
-```
-
-## Country Data Structure
-
-Each country in the dataset includes:
-
-```typescript
-interface Country {
-  name: string;       // Full country name
-  code: string;       // ISO 3166-1 alpha-2 code
-  dial_code: string;  // International dialing code
-  flag: string;       // Flag emoji
-}
-
-// Example:
-{
-  name: "United States",
-  code: "US",
-  dial_code: "+1",
-  flag: "🇺🇸"
-}
-```
-
-## Features
-
-- **Comprehensive List**: All countries with ISO codes
-- **Flag Emojis**: Visual country identification
-- **Dial Codes**: International phone codes included
-- **Search**: Type to filter countries by name
-- **Keyboard Navigation**: Full keyboard support
-- **Form Integration**: Works with native forms
-- **Validation**: Built-in required field validation
-
-## Accessibility
-
-- Proper ARIA labels and roles
-- Keyboard navigation (arrow keys, enter, escape)
-- Screen reader announcements
-- High contrast mode support
-- Focus management
-
-## Best Practices
-
-1. **Default Selection**: Consider pre-selecting based on user's location
-2. **Validation**: Use required attribute for mandatory fields
-3. **Phone Integration**: Use dial_code for phone number inputs
-4. **Localization**: Country names are in English by default
-5. **Performance**: Virtual scrolling for large lists
-
-## Common Pitfalls
-
-- **Code vs Name**: Value is country code, not full name
-- **Case Sensitivity**: Country codes are uppercase
-- **Missing Countries**: Some territories may not be included
-- **Flag Display**: Emoji flags may not work on all systems
-
-## Related Components
-
-- **[Autocomplete](./autocomplete.md)**: Base component for country select
-- **[Form](./form.md)**: Form integration
-- **[Input](./input.md)**: Often used with phone inputs
-- **[Timezone](./timezone.md)**: Related location selector
-
-## TypeScript Interface
-
-```typescript
-interface SchmancySelectCountriesElement 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 CountryChangeEvent extends CustomEvent {
-  detail: {
-    value: string;  // Country code
-  };
-}
-```

package/ai/index.md

@@ -1,112 +0,0 @@
-# Schmancy Component Library - AI Reference
-
-This directory contains concise reference documentation for the Schmancy component library, formatted for AI assistance.
-
-## Components
-
-### Core Components
-- [Animated Text](./animated-text.md) - Animated text effects with word and letter animations
-- [Area](./area.md) - Routing and subscription API for application areas
-- [Autocomplete](./autocomplete.md) - Searchable input with dropdown suggestions
-- [Avatar](./avatar.md) - User profile images with fallback initials
-- [Badge](./badge.md) - Status indicators and notification counts
-- [Busy](./busy.md) - Loading states and progress indicators
-- [Button](./button.md) - Primary, secondary, and tertiary buttons with various states
-- [Card](./card.md) - Content containers with headers and actions
-- [Checkbox](./checkbox.md) - Checkable input with indeterminate state
-- [Chips](./chips.md) - Compact elements for input or selection
-- [Progress](./progress.md) - Linear progress indicator showing task completion
-
-### Layout & Navigation
-- [Content Drawer](./content-drawer.md) - Sliding panel system for navigation and overlays
-- [Date Range](./date-range.md) - Date range selector with presets
-- [Delay](./delay.md) - Delayed content rendering with animations
-- [Dialog](./dialog.md) - Modal dialog boxes for confirmations and custom content
-- [Divider](./divider.md) - Visual separators with animations
-- [Dropdown](./dropdown.md) - Floating dropdown menus
-- [Layout](./layout.md) - **⚠️ DEPRECATED** - Use Tailwind CSS utilities instead
-- [List](./list.md) - Interactive lists with selection support
-- [Menu](./menu.md) - Context and dropdown menus
-- [Nav Drawer](./nav-drawer.md) - Responsive navigation drawer system
-
-### Form Elements
-- [Form](./form.md) - Form containers with validation capabilities
-- [Input](./input.md) - Text input fields with various types and features
-- [Option](./option.md) - Option elements for selects and autocomplete
-- [Radio Group](./radio-group.md) - Single-selection radio button groups
-- [Select](./select.md) - Dropdown selection components
-- [Textarea](./textarea.md) - Multi-line text input
-
-### Feedback & Interaction
-- [Notification](./notification.md) - Toast notifications and alerts
-- [Sheet](./sheet.md) - Side panels and drawers
-- [Slider](./slider.md) - Carousel component for content
-- [Steps](./steps.md) - Multi-step process indicators
-- [Tabs](./tabs.md) - Tabbed interface components
-- [Tooltip](./tooltip.md) - Contextual help text
-
-### Utilities
-- [Icons](./icons.md) - Material Design icon system
-- [Store](./store.md) - State management system
-- [Surface](./surface.md) - Elevation and container system
-- [Table](./table.md) - Data table components
-- [Teleport](./teleport.md) - FLIP animations between DOM positions
-- [Theme](./theme.md) - Material Design 3 theming system
-- [Theme Button](./theme-button.md) - Theme switching button
-- [Tree](./tree.md) - Hierarchical tree view
-- [Typography](./typography.md) - Text styling system
-- [Typewriter](./typewriter.md) - Typing animation effects
-
-## Reference Format
-
-Each reference file follows a consistent pattern:
-
-```js
-// Component name and basic usage
-<component-name attribute="value" boolean-attribute>
-  Content or children
-</component-name>
-
-// Component variations and options
-<component-name 
-  option1="value"
-  option2>
-  <!-- Structure examples -->
-</component-name>
-
-// Component methods and events
-component.method() -> returnType
-@event // Event description with { detail: { properties } }
-
-// Examples of common usage patterns (numbered for clarity)
-// 1. Basic usage
-<component-name attribute="value">
-  Example content
-</component-name>
-
-// 2. Advanced configuration
-<component-name attribute="value" advanced-config="true">
-  Complex example
-</component-name>
-```
-
-Each component documentation also includes:
-
-- **Related Components**: Links to related components with relationship descriptions
-- **Technical Details**: Interfaces, types, CSS custom properties
-- **Common Use Cases**: Practical examples with explanations
-
-This format is designed to quickly convey:
-1. Component tag names and attributes
-2. Available options and variations
-3. Component methods and events
-4. Relationships to other components
-5. Practical usage patterns
-
-For detailed documentation guidelines, see [template.md](./template.md).
-
-## Library Structure
-
-The Schmancy library is organized into individual component directories under `/src`, each exporting its components through an `index.ts` file. The main library entry point is `/src/index.ts` which re-exports all components.
-
-Most components follow LitElement patterns with TypeScript typing and are designed to be used with a reactive rendering system like lit-html.

package/ai/navigation-bar-item.md

@@ -1,259 +0,0 @@
-# Navigation Bar Item Component
-
-## Overview
-The `<schmancy-navigation-bar-item>` component represents an individual navigation destination within a navigation bar. It follows Material Design 3 specifications with proper touch targets, ripple effects, and state management using RxJS observables.
-
-## Usage
-
-### Basic Example
-```html
-<schmancy-navigation-bar-item
-  icon="home"
-  label="Home"
-  active
-></schmancy-navigation-bar-item>
-```
-
-### With Badge
-```html
-<schmancy-navigation-bar-item
-  icon="notifications"
-  label="Alerts"
-  badge="5"
-></schmancy-navigation-bar-item>
-```
-
-### Custom Icon Slot
-```html
-<schmancy-navigation-bar-item label="Custom">
-  <span slot="icon">🏠</span>
-</schmancy-navigation-bar-item>
-```
-
-### With Custom Content
-```html
-<schmancy-navigation-bar-item>
-  <schmancy-icon slot="icon" size="24">favorite</schmancy-icon>
-  Custom Content
-</schmancy-navigation-bar-item>
-```
-
-## Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `icon` | `string` | `''` | Material Symbols Outlined icon name |
-| `label` | `string` | `''` | Label text for the navigation item |
-| `badge` | `string` | `''` | Badge content (number or short text) |
-| `active` | `boolean` | `false` | Whether this item is currently active/selected |
-| `disabled` | `boolean` | `false` | Whether this item is disabled |
-| `hideLabels` | `boolean` | `false` | Hide labels (controlled by parent navigation bar) |
-
-## Events
-
-### bar-item-click
-Fired when the item is clicked.
-
-```javascript
-item.addEventListener('bar-item-click', (event) => {
-  console.log('Icon:', event.detail.icon);
-  console.log('Label:', event.detail.label);
-  console.log('Active:', event.detail.active);
-});
-```
-
-### focus / blur
-Standard focus and blur events for accessibility.
-
-## Features
-
-### RxJS-Powered Interactions
-- **Click handling**: Uses RxJS observables for instant navigation events
-- **Ripple effects**: Immediate visual feedback on interaction
-- **Keyboard support**: Enter and Space keys properly handled
-- **State management**: BehaviorSubject for reactive active state updates
-
-### Full Clickable Area
-The entire navigation item is clickable, not just the icon area:
-- Better touch targets on mobile devices
-- Improved accessibility
-- More intuitive user experience
-- 48x48dp minimum touch target as per Material Design
-
-### Badge System
-Intelligent badge handling:
-- Numbers > 99 display as "99+"
-- Text badges limited to 3 characters
-- Zero values hide the badge
-- Proper ARIA labels for screen readers
-
-### Ripple Animation
-Material Design ripple effect:
-- Originates from click position
-- 600ms animation duration
-- GPU-accelerated CSS animations
-- Multiple concurrent ripples supported
-
-## Slots
-
-| Slot | Description |
-|------|-------------|
-| `icon` | Custom icon content to replace the default icon |
-| default | Custom content for the item |
-
-## Styling
-
-### State-based Styling
-The component automatically applies different styles based on state:
-
-```css
-/* Active state */
-schmancy-navigation-bar-item[active] {
-  /* Icon indicator background: secondary-container */
-  /* Text color: secondary-onContainer */
-}
-
-/* Inactive state */
-schmancy-navigation-bar-item:not([active]) {
-  /* Text color: surface-onVariant */
-  /* Hover background: surface-container-highest */
-}
-
-/* Disabled state */
-schmancy-navigation-bar-item[disabled] {
-  /* Opacity: 0.38 */
-  /* Pointer events disabled */
-}
-```
-
-### CSS Parts
-```css
-/* Style the button element */
-schmancy-navigation-bar-item::part(button) {
-  /* Custom button styles */
-}
-```
-
-## Methods
-
-### setActive(isActive: boolean)
-Programmatically set the active state of the item.
-
-```javascript
-// In Lit component - use property binding
-@state() isActive = true;
-
-render() {
-  return html`
-    <schmancy-navigation-bar-item ?active=${this.isActive}>
-    </schmancy-navigation-bar-item>
-  `;
-}
-```
-
-## Integration Example
-
-### Complete Navigation Setup
-```typescript
-@customElement('app-navigation')
-class AppNavigation extends LitElement {
-  @state() activeIndex = 0;
-
-  private navigationItems = [
-    { icon: 'home', label: 'Home', route: 'home' },
-    { icon: 'search', label: 'Search', route: 'search' },
-    { icon: 'favorite', label: 'Favorites', route: 'favorites', badge: '3' },
-    { icon: 'person', label: 'Profile', route: 'profile' }
-  ];
-
-  private handleItemClick = (e: CustomEvent, index: number) => {
-    this.activeIndex = index;
-    const route = this.navigationItems[index].route;
-
-    // Navigate to route
-    area.push({
-      component: route,
-      area: 'main'
-    });
-  }
-
-  render() {
-    return html`
-      ${this.navigationItems.map((item, index) => html`
-        <schmancy-navigation-bar-item
-          icon=${item.icon}
-          label=${item.label}
-          ?active=${this.activeIndex === index}
-          badge=${item.badge || ''}
-          @bar-item-click=${(e: CustomEvent) => this.handleItemClick(e, index)}
-        ></schmancy-navigation-bar-item>
-      `)}
-    `;
-  }
-}
-```
-
-## Accessibility
-
-### Keyboard Support
-- `Enter` / `Space` - Activate the item instantly
-- Full focus management with visual indicators
-- `aria-pressed` attribute reflects active state
-- `aria-label` for badge notifications
-
-### Screen Reader Support
-- Proper ARIA attributes
-- Semantic HTML structure
-- Badge announcements ("3 notifications")
-
-## Performance Optimization
-
-### RxJS Observables
-- Efficient event handling with proper cleanup
-- Instant navigation events for responsive interaction
-- Immediate ripple feedback for better UX
-- Memory-safe with `takeUntil(this.disconnecting)`
-
-### Rendering Optimization
-- Conditional rendering based on props
-- Efficient class mapping with TailwindElement
-- Shadow DOM for style encapsulation
-
-## Best Practices
-
-1. **Icons**: Always use Material Symbols Outlined for consistency
-2. **Labels**: Keep labels concise (1-2 words maximum)
-3. **Badges**: Use for important notifications only
-4. **Active State**: Let parent navigation bar manage active states
-5. **Disabled State**: Use sparingly, consider hiding instead
-6. **Custom Icons**: Use the icon slot for custom SVGs or emojis
-
-## Common Patterns
-
-### Dynamic Badges
-```javascript
-// In Lit component - use declarative binding
-@state() notificationCount = 0;
-
-render() {
-  return html`
-    <schmancy-navigation-bar-item
-      badge=${this.notificationCount > 0 ? String(this.notificationCount) : ''}
-    ></schmancy-navigation-bar-item>
-  `;
-}
-```
-
-### Conditional Rendering
-```javascript
-// Show/hide items based on user role
-const items = user.isAdmin
-  ? ['dashboard', 'users', 'settings']
-  : ['dashboard', 'settings'];
-```
-
-### Icon Switching
-```javascript
-// Change icon based on state
-const icon = isPlaying ? 'pause' : 'play_arrow';
-```