@mhmo91/schmancy 0.2.194 → 0.2.196

package/ai/card.md

@@ -1,155 +1,186 @@
 # Schmancy Card - AI Reference
 
 ```js
-// Basic Card
-<schmancy-card>
-  <div>Card content goes here</div>
+// Card Component
+<schmancy-card
+  type="elevated|filled|outlined"
+  elevation="0|1|2|3|4|5">
+  Card content
 </schmancy-card>
 
-// Card with title and content
-<schmancy-card>
-  <schmancy-card-content>
-    <h2>Card Title</h2>
-    <p>Card description text goes here.</p>
-  </schmancy-card-content>
-</schmancy-card>
+// Properties
+type: string          // "elevated", "filled", "outlined" (default: "elevated")
+elevation: number     // Shadow depth 0-5 (default: 0)
 
-// Card with media
-<schmancy-card>
-  <schmancy-card-media
-    image="path/to/image.jpg"
-    alt="Image description"
-    height="200px">
-  </schmancy-card-media>
-  
-  <schmancy-card-content>
-    <h2>Card with Media</h2>
-    <p>Card content below the image.</p>
-  </schmancy-card-content>
-</schmancy-card>
+// Card Types
+"elevated"            // Surface with shadow, uses surface-low color
+"filled"              // Filled background, uses surface-highest color
+"outlined"            // Border outline, uses surface color
 
-// Card with actions
+// Examples
+// 1. Basic elevated card
 <schmancy-card>
-  <schmancy-card-content>
-    <h2>Card Title</h2>
-    <p>Card content with action buttons.</p>
-  </schmancy-card-content>
-  
-  <schmancy-card-actions>
-    <schmancy-button>Action 1</schmancy-button>
-    <schmancy-button>Action 2</schmancy-button>
-  </schmancy-card-actions>
+  <h3>Card Title</h3>
+  <p>Card content goes here</p>
 </schmancy-card>
 
-// Complete card with all components
-<schmancy-card>
-  <schmancy-card-media
-    image="path/to/image.jpg"
-    alt="Image description">
+// 2. Filled card with custom elevation
+<schmancy-card type="filled" elevation="2">
+  <schmancy-card-media>
+    <img src="image.jpg" alt="Card image">
   </schmancy-card-media>
-  
   <schmancy-card-content>
-    <h2>Card Title</h2>
-    <p>Card description text goes here. This can contain any content.</p>
+    <h3>Product Name</h3>
+    <p>Product description</p>
   </schmancy-card-content>
-  
   <schmancy-card-actions>
-    <schmancy-button kind="tertiary">Cancel</schmancy-button>
-    <schmancy-button kind="primary">Submit</schmancy-button>
+    <schmancy-button>Add to Cart</schmancy-button>
   </schmancy-card-actions>
 </schmancy-card>
 
-// Card Properties
-outlined: boolean        // Shows an outline instead of elevation
-elevation: number        // Shadow elevation level (1-5)
-interactive: boolean     // Enables hover and click effects
+// 3. Outlined card
+<schmancy-card type="outlined">
+  <div style="padding: 16px;">
+    <h4>Settings</h4>
+    <p>Configure your preferences</p>
+  </div>
+</schmancy-card>
 
-// Card Media Properties
-image: string           // URL of the image
-alt: string             // Alt text for the image
-height: string          // Height of the media area
-title: string           // Title to display over the media
+// 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>
+```
 
-// Card Actions Properties
-align: string           // Alignment of actions: "start", "end", "space-between", "center"
-direction: string       // Direction of actions: "row", "column"
+## Related Components
+- **[Surface](./surface.md)**: Base container component with more options
+- **[Card Content](./card.md#content)**: Structured content area
+- **[Card Media](./card.md#media)**: Media container for cards
+- **[Card Actions](./card.md#actions)**: Action button container
 
-// Examples
-// Basic card with content
-<schmancy-card>
-  <schmancy-card-content>
-    <h2>Welcome to Schmancy</h2>
-    <p>A modern component library for web applications.</p>
-  </schmancy-card-content>
-</schmancy-card>
+## Technical Details
 
-// Interactive card
-<schmancy-card 
-  interactive
-  @click=${handleCardClick}>
-  <schmancy-card-content>
-    <h3>Click Me</h3>
-    <p>This entire card is clickable.</p>
-  </schmancy-card-content>
-</schmancy-card>
+### CSS Host Styling
+The component uses `:host` selectors for all styling:
+- No wrapper elements - clean component boundary
+- Type and elevation properties reflect to HTML attributes
+- Automatic hover states for elevated and outlined types
 
-// Outlined card
-<schmancy-card outlined>
-  <schmancy-card-content>
-    <h3>Outlined Card</h3>
-    <p>This card has an outline instead of elevation.</p>
-  </schmancy-card-content>
-</schmancy-card>
+### Theme Integration
+```css
+/* Type-based colors */
+type="elevated"  -> --schmancy-sys-color-surface-low
+type="filled"    -> --schmancy-sys-color-surface-highest  
+type="outlined"  -> --schmancy-sys-color-surface-default
 
-// Product card
-<schmancy-card>
-  <schmancy-card-media
-    image="/products/headphones.jpg"
-    alt="Wireless Headphones"
-    height="180px">
-  </schmancy-card-media>
-  
-  <schmancy-card-content>
-    <h3>Wireless Headphones</h3>
-    <p>Premium sound quality with noise cancellation.</p>
-    <p><strong>$149.99</strong></p>
-  </schmancy-card-content>
-  
-  <schmancy-card-actions>
-    <schmancy-button kind="tertiary">Details</schmancy-button>
-    <schmancy-button kind="primary">Add to Cart</schmancy-button>
-  </schmancy-card-actions>
-</schmancy-card>
+/* Outline color */
+--schmancy-sys-color-outlineVariant
+
+/* Elevation shadows */
+--schmancy-sys-elevation-1 through --schmancy-sys-elevation-5
+```
+
+### Hover Behavior
+- Elevated cards: elevation 1 → 2 on hover
+- Filled cards: no elevation → 1 on hover
+- Outlined cards: no elevation → 1 on hover
+
+## Card Sub-components
+
+### Card Content
+```html
+<schmancy-card-content>
+  <h3>Title</h3>
+  <p>Description text</p>
+</schmancy-card-content>
+```
+
+### Card Media  
+```html
+<schmancy-card-media>
+  <img src="image.jpg" alt="Media">
+</schmancy-card-media>
+```
+
+### Card Actions
+```html
+<schmancy-card-actions>
+  <schmancy-button>Action 1</schmancy-button>
+  <schmancy-button variant="text">Action 2</schmancy-button>
+</schmancy-card-actions>
+```
+
+## Common Use Cases
+
+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-content>
+       <h3>Product Name</h3>
+       <p class="price">$29.99</p>
+       <p class="description">Product description...</p>
+     </schmancy-card-content>
+     <schmancy-card-actions>
+       <schmancy-button variant="filled">Add to Cart</schmancy-button>
+       <schmancy-button variant="text">Details</schmancy-button>
+     </schmancy-card-actions>
+   </schmancy-card>
+   ```
+
+2. **Info Cards**: Dashboard or stats display
+   ```html
+   <schmancy-card type="filled" elevation="0">
+     <div style="padding: 24px;">
+       <schmancy-icon icon="users" size="32"></schmancy-icon>
+       <h2>1,234</h2>
+       <p>Active Users</p>
+     </div>
+   </schmancy-card>
+   ```
+
+3. **Settings Cards**: Options or configuration
+   ```html
+   <schmancy-card type="outlined">
+     <schmancy-card-content>
+       <h4>Notification Settings</h4>
+       <schmancy-form>
+         <schmancy-checkbox>Email notifications</schmancy-checkbox>
+         <schmancy-checkbox>Push notifications</schmancy-checkbox>
+       </schmancy-form>
+     </schmancy-card-content>
+   </schmancy-card>
+   ```
+
+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-content>
+       <p>Image caption or description</p>
+     </schmancy-card-content>
+   </schmancy-card>
+   ```
 
-// Card grid layout
-<schmancy-grid
-  columns="1"
-  columns-md="2"
-  columns-lg="3"
-  gap="16px">
-  
-  ${products.map(product => html`
-    <schmancy-card>
-      <schmancy-card-media
-        image=${product.image}
-        alt=${product.name}>
-      </schmancy-card-media>
-      
-      <schmancy-card-content>
-        <h3>${product.name}</h3>
-        <p>${product.description}</p>
-        <p><strong>${product.price}</strong></p>
-      </schmancy-card-content>
-      
-      <schmancy-card-actions>
-        <schmancy-button @click=${() => viewProduct(product)}>
-          View
-        </schmancy-button>
-        <schmancy-button kind="primary" @click=${() => addToCart(product)}>
-          Add to Cart
-        </schmancy-button>
-      </schmancy-card-actions>
-    </schmancy-card>
-  `)}
-</schmancy-grid>
-```
+5. **List Item Cards**: Clickable list 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>
+   ```

package/ai/circular-progress.md

@@ -0,0 +1,91 @@
+# Schmancy Circular Progress - AI Reference
+
+```js
+// Circular Progress Component
+<schmancy-circular-progress
+  size="xs|sm|md|lg|xl|{custom}"
+  indeterminate?>
+</schmancy-circular-progress>
+
+// Properties
+size: string          // "xs", "sm", "md", "lg", "xl", or custom size (default: "md")
+indeterminate: boolean // Whether the progress is indeterminate (default: false)
+
+// Size values
+"xs" = 16px
+"sm" = 24px
+"md" = 32px
+"lg" = 48px
+"xl" = 64px
+
+// Examples
+// 1. Basic medium progress
+<schmancy-circular-progress></schmancy-circular-progress>
+
+// 2. Large indeterminate progress
+<schmancy-circular-progress 
+  size="lg"
+  indeterminate>
+</schmancy-circular-progress>
+
+// 3. Custom size
+<schmancy-circular-progress size="100">
+</schmancy-circular-progress>
+
+// 4. Small progress indicator
+<schmancy-circular-progress size="xs">
+</schmancy-circular-progress>
+```
+
+## Related Components
+- **[Busy](./busy.md)**: Parent component providing spinner functionality
+- **[Button](./button.md)**: Often used with buttons to show loading state
+
+## Technical Details
+
+### Implementation
+- Internally uses `<schmancy-spinner>` component
+- Size can be predefined string or custom CSS value
+- Numeric values are converted to pixels
+- Reflects indeterminate attribute to host element
+
+### CSS Custom Properties
+The component inherits spinner styling from the busy component.
+
+## Common Use Cases
+
+1. **Loading Buttons**: Show progress inside buttons
+   ```html
+   <schmancy-button disabled>
+     <schmancy-circular-progress size="sm"></schmancy-circular-progress>
+     Processing...
+   </schmancy-button>
+   ```
+
+2. **Page Loading**: Full-page loading indicator
+   ```html
+   <div class="loading-overlay">
+     <schmancy-circular-progress 
+       size="xl" 
+       indeterminate>
+     </schmancy-circular-progress>
+   </div>
+   ```
+
+3. **Inline Loading**: Small indicators in lists or tables
+   ```html
+   <td>
+     <schmancy-circular-progress size="xs"></schmancy-circular-progress>
+     Loading data...
+   </td>
+   ```
+
+4. **Card Loading State**: Centered in content areas
+   ```html
+   <schmancy-card>
+     <div class="centered">
+       <schmancy-circular-progress size="lg"></schmancy-circular-progress>
+       <p>Fetching results...</p>
+     </div>
+   </schmancy-card>
+   ```

package/ai/content-drawer.md

@@ -0,0 +1,190 @@
+# Content Drawer
+
+Sliding panel system for navigation, overlays, and responsive layouts.
+
+## Components
+
+```js
+// Main container that manages drawer behavior
+<schmancy-content-drawer
+  ?open="${boolean}"           // Controls drawer visibility
+  position="left|right|top|bottom"  // Drawer position (default: left)
+  variant="standard|modal|persistent"  // Behavior type
+  breakpoint="1024px"          // Responsive breakpoint
+  ?backdrop="${boolean}"       // Show backdrop when open
+>
+  <schmancy-content-drawer-main>
+    // Main content that shifts when drawer opens
+  </schmancy-content-drawer-main>
+  
+  <schmancy-content-drawer-sheet
+    width="256px"              // Width for left/right drawers
+    height="auto"              // Height for top/bottom drawers
+    offset="0"                 // Offset for nested drawers
+  >
+    // Drawer content
+  </schmancy-content-drawer-sheet>
+</schmancy-content-drawer>
+```
+
+## Context API
+
+```js
+import { contentDrawerContext } from '@schmancy/content-drawer'
+
+// Create drawer controller
+const drawer = contentDrawerContext.create('drawer-id')
+
+// Control methods
+drawer.open()
+drawer.close() 
+drawer.toggle()
+drawer.lock()      // Prevent closing
+drawer.unlock()
+drawer.setPersistent(boolean)
+
+// State access
+drawer.isOpen -> boolean
+drawer.state$ -> Observable<DrawerState>
+
+// Events
+@drawer-opened
+@drawer-closed
+@drawer-toggled -> { open: boolean }
+@before-open
+@before-close
+```
+
+## Examples
+
+### 1. Basic Navigation Drawer
+```html
+<schmancy-content-drawer ?open="${drawerOpen}">
+  <schmancy-content-drawer-main>
+    <button @click="${() => drawerOpen = !drawerOpen}">Menu</button>
+    <main>App content</main>
+  </schmancy-content-drawer-main>
+  
+  <schmancy-content-drawer-sheet width="280px">
+    <nav>
+      <a href="/home">Home</a>
+      <a href="/about">About</a>
+    </nav>
+  </schmancy-content-drawer-sheet>
+</schmancy-content-drawer>
+```
+
+### 2. Bottom Sheet
+```html
+<schmancy-content-drawer 
+  ?open="${sheetOpen}"
+  position="bottom"
+  @drawer-closed="${() => sheetOpen = false}"
+>
+  <schmancy-content-drawer-main>
+    <button @click="${() => sheetOpen = true}">Show Options</button>
+  </schmancy-content-drawer-main>
+  
+  <schmancy-content-drawer-sheet height="auto" max-height="50vh">
+    <div class="sheet-handle"></div>
+    <h3>Select Option</h3>
+    <schmancy-list>
+      <schmancy-list-item>Option 1</schmancy-list-item>
+      <schmancy-list-item>Option 2</schmancy-list-item>
+    </schmancy-list>
+  </schmancy-content-drawer-sheet>
+</schmancy-content-drawer>
+```
+
+### 3. Persistent Sidebar
+```js
+// Responsive persistent drawer
+const drawer = contentDrawerContext.create('sidebar')
+
+// Auto-persist on large screens
+const mediaQuery = window.matchMedia('(min-width: 1024px)')
+drawer.setPersistent(mediaQuery.matches)
+mediaQuery.addEventListener('change', e => drawer.setPersistent(e.matches))
+```
+
+```html
+<schmancy-content-drawer
+  .context="${drawer}"
+  variant="persistent"
+  breakpoint="1024px"
+>
+  <schmancy-content-drawer-main>
+    <schmancy-app-bar>
+      <schmancy-icon-button 
+        icon="menu"
+        @click="${() => drawer.toggle()}"
+      ></schmancy-icon-button>
+    </schmancy-app-bar>
+    <main>Dashboard content</main>
+  </schmancy-content-drawer-main>
+  
+  <schmancy-content-drawer-sheet width="240px">
+    <aside>Sidebar content</aside>
+  </schmancy-content-drawer-sheet>
+</schmancy-content-drawer>
+```
+
+### 4. Nested Drawers
+```js
+const mainDrawer = contentDrawerContext.create('main')
+const subDrawer = contentDrawerContext.create('sub')
+```
+
+```html
+<schmancy-content-drawer .context="${mainDrawer}">
+  <schmancy-content-drawer-main>
+    <!-- Nested drawer container -->
+    <schmancy-content-drawer .context="${subDrawer}">
+      <schmancy-content-drawer-main>
+        <button @click="${() => mainDrawer.open()}">Menu</button>
+      </schmancy-content-drawer-main>
+      
+      <!-- Sub drawer -->
+      <schmancy-content-drawer-sheet width="280px" offset="240px">
+        <button @click="${() => subDrawer.close()}">Back</button>
+        <div>Sub menu content</div>
+      </schmancy-content-drawer-sheet>
+    </schmancy-content-drawer>
+  </schmancy-content-drawer-main>
+  
+  <!-- Main drawer -->
+  <schmancy-content-drawer-sheet width="240px">
+    <button @click="${() => subDrawer.open()}">Open Submenu</button>
+    <div>Main menu content</div>
+  </schmancy-content-drawer-sheet>
+</schmancy-content-drawer>
+```
+
+## CSS Variables
+
+```css
+schmancy-content-drawer {
+  --drawer-width: 256px;
+  --drawer-background: var(--md-sys-color-surface);
+  --drawer-shadow: 0 8px 10px -5px rgba(0,0,0,0.2);
+  --drawer-transition-duration: 250ms;
+  --drawer-transition-timing: cubic-bezier(0.4, 0, 0.2, 1);
+  --backdrop-color: rgba(0, 0, 0, 0.5);
+  --drawer-z-index: 200;
+}
+```
+
+## Related Components
+
+- [Sheet](./sheet.md) - Simpler sheet component for modals
+- [Navigation Drawer](./nav-drawer.md) - Specialized navigation component
+- [Dialog](./dialog.md) - Modal dialogs
+- [Layout](./layout.md) - Layout utilities
+
+## Common Patterns
+
+**Command Palette**: Top drawer with search input
+**Help Panel**: Right drawer with contextual help
+**Mobile Menu**: Left drawer for navigation
+**Action Sheet**: Bottom drawer for mobile actions
+**Settings Panel**: Persistent right drawer