@mhmo91/schmancy 0.4.2 → 0.4.4

package/ai/button.md

@@ -1,112 +1,150 @@
 # Schmancy Button - AI Reference
 
 ```js
-// Basic Button
+// Component Tags
 <schmancy-button
-  variant="elevated|filled|filled tonal|outlined|text"
-  width="full|auto"
-  type="button|submit|reset"
-  disabled?
-  href?
-  @click>
-  Button Text
+  variant="elevated|filled|filled tonal|outlined|text"  // Visual style (default: "text")
+  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"                                   // Accessibility label
+  @click=${handler}>
+  <!-- Content with optional prefix/suffix slots -->
 </schmancy-button>
 
-// Icon Button
+// Icon Button Component
 <schmancy-icon-button
-  variant="elevated|filled|filled tonal|outlined|text"
-  size="sm|md|lg"
-  width="full|auto"
-  type="button|submit|reset"
-  disabled?
-  href?
-  @click>
-  <!-- Icon content goes directly in the slot -->
-  <svg>...</svg> 
+  variant="filled|filled tonal|outlined|standard"      // Visual style (default: "standard")
+  size="sm|md|lg"                                      // Button size (default: "md")
+  disabled?                                             // Disable state
+  ariaLabel="string">                                  // REQUIRED for accessibility
+  icon_name
 </schmancy-icon-button>
 
-// Button with Icon
-<schmancy-button>
-  <schmancy-icon slot="prefix" icon="check"></schmancy-icon>
-  With Prefix Icon
-</schmancy-button>
-
-<schmancy-button>
-  With Suffix Icon
-  <schmancy-icon slot="suffix" icon="arrow-right"></schmancy-icon>
-</schmancy-button>
+// Component Methods
+button.focus(options?: FocusOptions) -> void
+button.blur() -> void
+button.click() -> void
 
-// Button Properties
-variant: string       // "elevated", "filled", "filled tonal", "outlined", "text" (default: "text")
-width: string         // "full", "auto" (default: "auto")
-type: string          // "button", "submit", "reset" (default: "button")
-disabled: boolean     // Whether the button is disabled
-href: string          // If provided, renders as an anchor (<a>) element
-ariaLabel: string     // Accessible label for the button
-
-// Icon Button Properties
-variant: string       // "elevated", "filled", "filled tonal", "outlined", "text" (default: "text")
-size: string          // "sm", "md", "lg" (default: "md")
-width: string         // "full", "auto" (default: "auto")
-type: string          // "button", "submit", "reset" (default: "button")
-disabled: boolean     // Whether the button is disabled
-href: string          // If provided, renders as an anchor (<a>) element
-ariaLabel: string     // Accessible label for the button
-
-// Button Methods
-focus(options?) -> void  // Sets focus on the button
-blur() -> void           // Removes focus from the button
-click() -> void          // Programmatically clicks the button
+// Slots
+default  // Button text content
+prefix   // Icon or content before text
+suffix   // Icon or content after text
 
 // Examples
-<schmancy-button variant="filled" @click=${() => console.log('clicked')}>
-  Filled Button
-</schmancy-button>
+// 1. Basic button with text
+<schmancy-button variant="filled">Save Changes</schmancy-button>
 
-<schmancy-button variant="outlined" disabled>
-  Disabled Button
+// 2. Button with icon
+<schmancy-button variant="outlined">
+  <schmancy-icon slot="prefix">add</schmancy-icon>
+  Add Item
 </schmancy-button>
 
-<schmancy-button variant="elevated">
-  Elevated Button
-</schmancy-button>
+// 3. Button as link
+<schmancy-button href="/learn-more" variant="text">Learn More</schmancy-button>
 
-<schmancy-button variant="text">
-  Text Button
-</schmancy-button>
+// 4. Full width button
+<schmancy-button width="full" variant="filled">Submit Form</schmancy-button>
 
-<schmancy-button variant="filled tonal">
-  Tonal Button
-</schmancy-button>
+// 5. Icon-only button
+<schmancy-icon-button variant="filled" ariaLabel="Settings">
+  settings
+</schmancy-icon-button>
 
-<schmancy-button href="https://example.com" variant="outlined">
-  Link Button
-</schmancy-button>
+// 6. Form submission buttons
+<schmancy-form @submit="${handleSubmit}">
+  <div class="flex gap-2 justify-end">
+    <schmancy-button type="button" variant="text">Cancel</schmancy-button>
+    <schmancy-button type="submit" variant="filled">Submit</schmancy-button>
+  </div>
+</schmancy-form>
 
-<schmancy-button width="full" variant="filled">
-  Full Width Button
+// 7. Loading state pattern
+<schmancy-button variant="filled" ?disabled="${isLoading}">
+  ${isLoading 
+    ? html`<schmancy-circular-progress slot="prefix" size="sm"></schmancy-circular-progress>`
+    : html`<schmancy-icon slot="prefix">send</schmancy-icon>`
+  }
+  ${isLoading ? 'Sending...' : 'Send Message'}
 </schmancy-button>
 
-<schmancy-icon-button variant="filled" size="md">
-  <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
-    <path d="M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7"></path>
-    <path d="M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z"></path>
-  </svg>
-</schmancy-icon-button>
-
-<schmancy-icon-button variant="text" size="sm">
-  <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
-    <circle cx="18" cy="6" r="3"></circle>
-    <circle cx="6" cy="18" r="3"></circle>
-    <line x1="13" y1="6" x2="6" y2="14"></line>
-  </svg>
-</schmancy-icon-button>
-
-// Form submission button
-<schmancy-form @submit=${handleSubmit}>
-  <schmancy-input name="email" type="email" required></schmancy-input>
-  <schmancy-button type="submit" variant="filled">
-    Submit Form
-  </schmancy-button>
-</schmancy-form>
-```
+// 8. Button group
+<div class="flex gap-2">
+  <schmancy-button variant="outlined">Edit</schmancy-button>
+  <schmancy-button variant="outlined">Delete</schmancy-button>
+  <schmancy-button variant="filled">Save</schmancy-button>
+</div>
+```
+
+## Related Components
+- **[Icon](./icon.md)**: Used for button icons in prefix/suffix slots
+- **[Card Action](./card.md)**: Container for button groups in cards
+- **[Dialog](./dialog.md)**: Common usage for action buttons
+- **[Form](./form.md)**: Form submission context
+- **[FAB](./fab.md)**: Floating action button alternative
+- **[Circular Progress](./circular-progress.md)**: Loading indicator for buttons
+
+## Technical Details
+
+### Variant Hierarchy
+Material Design 3 emphasis levels (highest to lowest):
+1. `filled` - Primary actions, highest emphasis
+2. `filled tonal` / `elevated` - Important secondary actions
+3. `outlined` - Medium emphasis with clear boundaries
+4. `text` - Low emphasis, tertiary actions
+
+### Icon Button Sizes
+- `sm`: 40×40px container, 18px icon
+- `md`: 48×48px container, 24px icon (default)
+- `lg`: 56×56px container, 28px icon
+
+### CSS Custom Properties
+```css
+/* Applied to button host element */
+--schmancy-button-width: auto | 100%;  /* Controls button width */
+```
+
+### Accessibility
+- Buttons automatically include ARIA attributes
+- Icon-only buttons MUST have `ariaLabel`
+- Focus management methods available
+- Keyboard navigation fully supported
+
+### State Management
+- `disabled` attribute prevents all interactions
+- Loading states should disable button to prevent double-submission
+- Visual feedback through variant system
+
+## Common Use Cases
+
+1. **Primary Action Button**
+   ```html
+   <schmancy-button variant="filled" type="submit">
+     Complete Purchase
+   </schmancy-button>
+   ```
+
+2. **Secondary Action with Icon**
+   ```html
+   <schmancy-button variant="outlined">
+     <schmancy-icon slot="prefix">upload</schmancy-icon>
+     Upload File
+   </schmancy-button>
+   ```
+
+3. **Navigation Link Button**
+   ```html
+   <schmancy-button href="/documentation" variant="text">
+     View Documentation
+     <schmancy-icon slot="suffix">arrow_forward</schmancy-icon>
+   </schmancy-button>
+   ```
+
+4. **Responsive Mobile-First Button**
+   ```html
+   <schmancy-button variant="filled" class="w-full sm:w-auto">
+     Get Started
+   </schmancy-button>
+   ```

package/ai/card.md

@@ -1,59 +1,50 @@
 # Schmancy Card - AI Reference
 
-```js
-// Card Component
+Material Design 3 card components with optimized performance and clean API.
+
+```html
+<!-- Card Component -->
 <schmancy-card
   type="elevated|filled|outlined"
   elevation="0|1|2|3|4|5">
   Card content
 </schmancy-card>
 
-// Properties
+<!-- Properties -->
 type: string          // "elevated", "filled", "outlined" (default: "elevated")
-elevation: number     // Shadow depth 0-5 (default: 0)
+elevation: number     // Shadow depth 0-5 (default: 0, overrides type defaults)
 
-// Card Types
+<!-- Card Types -->
 "elevated"            // Surface with shadow, uses surface-low color
 "filled"              // Filled background, uses surface-highest color
-"outlined"            // Border outline, uses surface color
+"outlined"            // Border outline, uses surface-default color
 
-// Examples
-// 1. Basic elevated card
+<!-- Examples -->
+<!-- 1. Basic elevated card -->
 <schmancy-card>
   <h3>Card Title</h3>
   <p>Card content goes here</p>
 </schmancy-card>
 
-// 2. Filled card with custom elevation
+<!-- 2. Complete card structure -->
 <schmancy-card type="filled" elevation="2">
-  <schmancy-card-media>
-    <img src="image.jpg" alt="Card image">
-  </schmancy-card-media>
+  <schmancy-card-media src="image.jpg" fit="cover" alt="Product"></schmancy-card-media>
   <schmancy-card-content>
-    <h3>Product Name</h3>
-    <p>Product description</p>
+    <span slot="headline">Product Name</span>
+    <span slot="subhead">$29.99</span>
+    Product description goes here...
   </schmancy-card-content>
-  <schmancy-card-actions>
-    <schmancy-button>Add to Cart</schmancy-button>
-  </schmancy-card-actions>
+  <schmancy-card-action>
+    <schmancy-button variant="filled">Add to Cart</schmancy-button>
+  </schmancy-card-action>
 </schmancy-card>
 
-// 3. Outlined card
+<!-- 3. Outlined card -->
 <schmancy-card type="outlined">
-  <div style="padding: 16px;">
-    <h4>Settings</h4>
-    <p>Configure your preferences</p>
-  </div>
-</schmancy-card>
-
-// 4. Interactive card with hover effect
-<schmancy-card elevation="1">
-  <a href="/details" style="text-decoration: none; color: inherit;">
-    <div style="padding: 16px;">
-      <h3>Click for Details</h3>
-      <p>This card has hover elevation changes</p>
-    </div>
-  </a>
+  <schmancy-card-content>
+    <span slot="headline">Settings</span>
+    Configure your preferences here
+  </schmancy-card-content>
 </schmancy-card>
 ```
 
@@ -93,26 +84,56 @@ type="outlined"  -> --schmancy-sys-color-surface-default
 ## Card Sub-components
 
 ### Card Content
+Structured content area with headline and subhead slots.
+
 ```html
 <schmancy-card-content>
-  <h3>Title</h3>
-  <p>Description text</p>
+  <span slot="headline">Main Title</span>
+  <span slot="subhead">Subtitle or metadata</span>
+  Body content goes here...
 </schmancy-card-content>
+
+<!-- Properties -->
+- Automatic padding and spacing
+- Headline uses surface-on color
+- Subhead and body use surface-onVariant color
 ```
 
 ### Card Media  
+Media container with object-fit control.
+
 ```html
-<schmancy-card-media>
+<!-- With src attribute -->
+<schmancy-card-media 
+  src="image.jpg" 
+  fit="contain|cover|fill|none|scale-down"
+  alt="Description">
+</schmancy-card-media>
+
+<!-- With slotted content -->
+<schmancy-card-media fit="cover">
   <img src="image.jpg" alt="Media">
 </schmancy-card-media>
+
+<!-- Properties -->
+src: string           // Image source URL
+fit: string           // Object fit mode (default: "contain")
+alt: string           // Alt text for accessibility
 ```
 
-### Card Actions
+### Card Action
+Action area for buttons, positioned at bottom.
+
 ```html
-<schmancy-card-actions>
-  <schmancy-button>Action 1</schmancy-button>
-  <schmancy-button variant="text">Action 2</schmancy-button>
-</schmancy-card-actions>
+<schmancy-card-action>
+  <schmancy-button variant="filled">Primary</schmancy-button>
+  <schmancy-button variant="text">Secondary</schmancy-button>
+</schmancy-card-action>
+
+<!-- Properties -->
+- Flex layout with right alignment
+- Automatic spacing between buttons
+- Padding on all sides
 ```
 
 ## Common Use Cases
@@ -120,18 +141,16 @@ type="outlined"  -> --schmancy-sys-color-surface-default
 1. **Product Cards**: E-commerce product display
    ```html
    <schmancy-card type="elevated">
-     <schmancy-card-media>
-       <img src="product.jpg" alt="Product">
-     </schmancy-card-media>
+     <schmancy-card-media src="product.jpg" fit="cover" alt="Product"></schmancy-card-media>
      <schmancy-card-content>
-       <h3>Product Name</h3>
-       <p class="price">$29.99</p>
-       <p class="description">Product description...</p>
+       <span slot="headline">Product Name</span>
+       <span slot="subhead">$29.99</span>
+       Premium quality product with excellent features...
      </schmancy-card-content>
-     <schmancy-card-actions>
+     <schmancy-card-action>
        <schmancy-button variant="filled">Add to Cart</schmancy-button>
        <schmancy-button variant="text">Details</schmancy-button>
-     </schmancy-card-actions>
+     </schmancy-card-action>
    </schmancy-card>
    ```
 
@@ -150,7 +169,7 @@ type="outlined"  -> --schmancy-sys-color-surface-default
    ```html
    <schmancy-card type="outlined">
      <schmancy-card-content>
-       <h4>Notification Settings</h4>
+       <span slot="headline">Notification Settings</span>
        <schmancy-form>
          <schmancy-checkbox>Email notifications</schmancy-checkbox>
          <schmancy-checkbox>Push notifications</schmancy-checkbox>
@@ -162,25 +181,46 @@ type="outlined"  -> --schmancy-sys-color-surface-default
 4. **Media Cards**: Image galleries
    ```html
    <schmancy-card elevation="2">
-     <schmancy-card-media aspect-ratio="16:9">
-       <img src="gallery-image.jpg" alt="Gallery">
-     </schmancy-card-media>
+     <schmancy-card-media src="gallery.jpg" fit="cover" alt="Gallery"></schmancy-card-media>
      <schmancy-card-content>
-       <p>Image caption or description</p>
+       <span slot="subhead">Photo by Artist Name</span>
+       Beautiful landscape captured at sunset
      </schmancy-card-content>
    </schmancy-card>
    ```
 
-5. **List Item Cards**: Clickable list items
+5. **Article Cards**: Blog or news items
    ```html
-   <schmancy-card type="elevated" elevation="1">
-     <a href="/user/123" style="display: flex; padding: 16px; align-items: center; text-decoration: none; color: inherit;">
-       <schmancy-avatar src="user.jpg"></schmancy-avatar>
-       <div style="margin-left: 16px; flex: 1;">
-         <h4>User Name</h4>
-         <p>user@example.com</p>
-       </div>
-       <schmancy-icon icon="chevron-right"></schmancy-icon>
-     </a>
+   <schmancy-card type="outlined">
+     <schmancy-card-content>
+       <schmancy-typography type="label" token="sm" class="text-primary-default block mb-2">
+         TECHNOLOGY
+       </schmancy-typography>
+       <span slot="headline">The Future of Web Development</span>
+       <span slot="subhead">5 min read • March 15, 2024</span>
+       Explore the latest trends in web development...
+     </schmancy-card-content>
+     <schmancy-card-action>
+       <schmancy-button variant="text">Read More</schmancy-button>
+       <schmancy-button variant="text">
+         <schmancy-icon>share</schmancy-icon>
+       </schmancy-button>
+     </schmancy-card-action>
    </schmancy-card>
-   ```
+   ```
+
+## Performance Notes
+
+All card components use :host styling for optimal performance:
+- No wrapper elements or runtime class manipulation
+- CSS-only hover states and transitions
+- Efficient use of CSS custom properties
+- Minimal JavaScript overhead
+
+## Migration Guide
+
+If upgrading from older versions:
+1. Replace `<schmancy-card-actions>` with `<schmancy-card-action>`
+2. Update card-content to use slots for headline/subhead
+3. Card-media now supports direct src attribute
+4. All components use :host styling (no wrapper divs)