@mhmo91/schmancy 0.8.6 → 0.9.3

package/ai/card.md

@@ -1,226 +1,53 @@
-# Schmancy Card - AI Reference
+# schmancy-card
 
-Material Design 3 card components with optimized performance and clean API.
+> Card container with luminous hover glow and spring press animation. Interactive cards get embedded `cursorGlow` directive.
 
+## Usage
 ```html
-<!-- Card Component -->
-<schmancy-card
-  type="elevated|filled|outlined"
-  elevation="0|1|2|3|4|5">
-  Card content
-</schmancy-card>
-
-<!-- Properties -->
-type: string          // "elevated", "filled", "outlined" (default: "elevated")
-elevation: number     // Shadow depth 0-5 (default: 0, overrides type defaults)
-
-<!-- Card Types -->
-"elevated"            // Surface with shadow, uses surface-low color
-"filled"              // Filled background, uses surface-highest color
-"outlined"            // Border outline, uses surface-default color
-
-<!-- Examples -->
-<!-- 1. Basic elevated card -->
-<schmancy-card>
-  <h3>Card Title</h3>
-  <p>Card content goes here</p>
+<schmancy-card type="elevated" interactive>
+  <div class="p-4">Card content</div>
 </schmancy-card>
+```
 
-<!-- 2. Complete card structure -->
-<schmancy-card type="filled" elevation="2">
-  <schmancy-card-media src="image.jpg" fit="cover" alt="Product"></schmancy-card-media>
-  <schmancy-card-content>
-    <span slot="headline">Product Name</span>
-    <span slot="subhead">$29.99</span>
-    Product description goes here...
-  </schmancy-card-content>
-  <schmancy-card-action>
-    <schmancy-button variant="filled">Add to Cart</schmancy-button>
-  </schmancy-card-action>
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `type` | `'elevated' \| 'filled' \| 'outlined'` | `'elevated'` | Visual style |
+| `interactive` | `boolean` | `false` | Enables click, cursorGlow, keyboard nav, ripple |
+| `disabled` | `boolean` | `false` | Disables interaction |
+| `dragged` | `boolean` | `false` | Elevated drag state with extra glow |
+| `href` | `string` | `undefined` | URL navigation on click |
+| `target` | `string` | `undefined` | Link target (e.g. `_blank`) |
+| `role` | `string` | `'article'` | ARIA role (auto-switches to `button`/`link` when interactive) |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `schmancy-click` | `{ value: type }` | Fired on interactive card click |
+
+## Physics
+- **cursorGlow** directive on interactive cards (radius: 200, intensity: 0.1)
+- Hover: luminous glow + lift (`translateY(-2px)` for elevated, `-1px` for others)
+- Active: spring compress `scale(0.98)` with 100ms transition
+- Dragged: enhanced glow + `translateY(-4px)`
+
+## Examples
+```html
+<!-- Elevated clickable card -->
+<schmancy-card type="elevated" interactive>
+  <div class="p-4">
+    <h3 class="text-surface-on font-medium">Title</h3>
+    <p class="text-surface-on-variant">Description</p>
+  </div>
 </schmancy-card>
 
-<!-- 3. Outlined card -->
+<!-- Outlined static card -->
 <schmancy-card type="outlined">
-  <schmancy-card-content>
-    <span slot="headline">Settings</span>
-    Configure your preferences here
-  </schmancy-card-content>
+  <div class="p-4">Static content</div>
 </schmancy-card>
-```
-
-## 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
-
-## Technical Details
-
-### CSS Host Styling
-The component uses `:host` selectors for all styling:
-- No wrapper elements - clean component boundary
-- CSS attribute selectors work with the properties
-- Automatic hover states for elevated and outlined types
-
-### 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
-
-/* 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
-Structured content area with headline and subhead slots.
-
-```html
-<schmancy-card-content>
-  <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
-<!-- 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 Action
-Action area for buttons, positioned at bottom.
-
-```html
-<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
+<!-- Link card -->
+<schmancy-card type="filled" interactive href="/details" target="_blank">
+  <div class="p-4">Opens in new tab</div>
+</schmancy-card>
 ```
-
-## Common Use Cases
-
-1. **Product Cards**: E-commerce product display
-   ```html
-   <schmancy-card type="elevated">
-     <schmancy-card-media src="product.jpg" fit="cover" alt="Product"></schmancy-card-media>
-     <schmancy-card-content>
-       <span slot="headline">Product Name</span>
-       <span slot="subhead">$29.99</span>
-       Premium quality product with excellent features...
-     </schmancy-card-content>
-     <schmancy-card-action>
-       <schmancy-button variant="filled">Add to Cart</schmancy-button>
-       <schmancy-button variant="text">Details</schmancy-button>
-     </schmancy-card-action>
-   </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>
-       <span slot="headline">Notification Settings</span>
-       <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 src="gallery.jpg" fit="cover" alt="Gallery"></schmancy-card-media>
-     <schmancy-card-content>
-       <span slot="subhead">Photo by Artist Name</span>
-       Beautiful landscape captured at sunset
-     </schmancy-card-content>
-   </schmancy-card>
-   ```
-
-5. **Article Cards**: Blog or news items
-   ```html
-   <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)

package/ai/charts.md

@@ -0,0 +1,93 @@
+# Schmancy Charts
+
+> Canvas-rendered area chart and horizontal pill chart. Theme-aware, lazy-animated, with auto peak highlighting.
+
+## schmancy-area-chart
+
+> Smooth Catmull-Rom spline area chart with peak markers and hover tooltips.
+
+```html
+<schmancy-area-chart
+  .data=${[
+    { label: '9 AM', value: 12.4 },
+    { label: '10 AM', value: 18.9 },
+    { label: '11 AM', value: 42.1, metadata: { users: 320 } },
+    { label: '12 PM', value: 56.7 },
+  ]}
+  value-prefix="EUR "
+  value-decimals="2"
+  peak-count="2"
+  height="240"
+></schmancy-area-chart>
+```
+
+### Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `data` | `ChartDataPoint[]` | `[]` | `{ label, value, metadata? }[]` |
+| `height` | number | `200` | Chart height in px |
+| `showGrid` | boolean | `true` | Background grid lines |
+| `showLabels` | boolean | `true` | X-axis labels |
+| `showTooltip` | boolean | `true` | Hover tooltip |
+| `peakCount` | number | `3` | Top-N points highlighted larger |
+| `animationDuration` | number | `800` | Entrance animation ms |
+| `animated` | boolean | `true` | Animate on first visible |
+| `valuePrefix` | string | `''` | Display prefix (e.g. `"EUR "`) |
+| `valueSuffix` | string | `''` | Display suffix (e.g. `"%"`) |
+| `valueDecimals` | number | `2` | Decimal places |
+| `theme` | `Partial<ChartTheme>` | `{}` | Override colors, stroke, radii |
+
+### ChartTheme
+| Key | Default | Description |
+|-----|---------|-------------|
+| `primaryColor` | `--schmancy-sys-color-primary` | Line + fill gradient color |
+| `gradientOpacity` | `[0.4, 0.05]` | Top/bottom fill opacity |
+| `strokeWidth` | `2` | Line thickness |
+| `pointRadius` | `4` | Normal point radius |
+| `peakRadius` | `6` | Peak point radius |
+
+## schmancy-pills
+
+> Horizontal bar chart with optional stacked segments, medal ranks, and peak/low styling.
+
+```html
+<schmancy-pills
+  .data=${[
+    { label: 'Mon', value: 1240, rank: 1 },
+    { label: 'Tue', value: 980 },
+    { label: 'Wed', value: 1830, rank: 2, segments: [
+      { label: 'Pizza', value: 1200 },
+      { label: 'Drinks', value: 630 }
+    ]},
+  ]}
+></schmancy-pills>
+```
+
+### Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `data` | `PillDataPoint[]` | `[]` | Rows with optional stacked `segments` |
+| `valuePrefix` / `valueSuffix` / `valueDecimals` | — | — | Value formatting (same as area chart) |
+| `showMedals` | boolean | `true` | Show 🥇🥈🥉 for rank 1/2/3 |
+
+### PillDataPoint
+```typescript
+{
+  label: string
+  value: number
+  segments?: { label, value, color }[]  // stacked
+  isPeak?: boolean   // highlighted
+  isLow?: boolean    // muted
+  rank?: 1 | 2 | 3   // medal
+  metadata?: Record<string, unknown>
+}
+```
+
+## Behavior
+- Both charts use an IntersectionObserver to defer animation until visible.
+- Responsive — resize triggers a re-render.
+- Dark/light aware via theme CSS variables.
+
+## When to Use
+- Area chart: time-series or comparative trends.
+- Pills: ranked categorical data (leaderboards, top days, distribution).

package/ai/checkbox.md

@@ -1,139 +1,36 @@
-# Schmancy Checkbox - AI Reference
+# schmancy-checkbox
 
-```js
-// Basic Checkbox
-<schmancy-checkbox
-  .value=${booleanValue}         // Boolean value (default: false)
-  .checked=${booleanValue}        // Alias for value - use either value or checked
-  ?disabled=${isDisabled}        // Whether checkbox is disabled
-  ?required=${isRequired}        // Whether checkbox is required
-  name="checkbox-name"           // Name attribute (auto-generated if not provided)
-  id="checkbox-id"               // ID attribute (auto-generated if not provided)
-  label="Checkbox Label"         // Optional label text
-  size="sm|md|lg"                // Size of checkbox (default: "md") - Note: currently not affecting rendering
-  @change=${handleChange}>       // Change event handler
-</schmancy-checkbox>
-
-// Checkbox with label attribute
-<schmancy-checkbox
-  label="Subscribe to newsletter"
-  .checked=${isSubscribed}
-  @change=${(e) => this.isSubscribed = e.detail.value}>
-</schmancy-checkbox>
-
-// Checkbox with slot content (when no label attribute)
-<schmancy-checkbox
-  name="terms"
-  .checked=${agreedToTerms}
-  required
-  @change=${(e) => this.agreedToTerms = e.detail.value}>
-  I accept the <a href="/terms">terms and conditions</a>
-</schmancy-checkbox>
-
-// Checkbox Properties
-value: boolean         // The checked state (true/false, default: false)
-checked: boolean       // Alias for value - getter/setter that maps to value
-name: string           // The name attribute (auto-generated random ID if not provided)
-id: string             // The id attribute (auto-generated random ID if not provided)
-disabled: boolean      // Whether the checkbox is disabled (default: false)
-required: boolean      // Whether the checkbox is required (default: false)
-label?: string         // Optional label text - if provided, shows text; otherwise uses slot
-size: 'sm'|'md'|'lg'   // Size of the checkbox (default: 'md')
-
-// Checkbox Events
-@change  // Fires when checked state changes, event detail: { value: boolean }
-         // Access new value via: e.detail.value (NOT e.detail.checked)
-
-// Important Notes:
-// - The component uses md-checkbox internally from Material Web Components
-// - Use property binding (.value or .checked) for the boolean state, not attribute
-// - The label property takes precedence over slot content
-// - Event detail contains 'value' property, not 'checked'
-
-// Examples
-
-// Basic usage with property binding
-<schmancy-checkbox
-  name="agree"
-  label="I agree to the terms and conditions"
-  .checked=${this.agreed}
-  required
-  @change=${(e) => {
-    console.log('Agreed:', e.detail.value);  // Use e.detail.value, not e.detail.checked
-    this.agreed = e.detail.value;
-  }}>
-</schmancy-checkbox>
+> Checkbox with label support and form association.
 
-// Using slot for custom HTML content
-<schmancy-checkbox
-  .checked=${this.acceptTerms}
-  @change=${(e) => this.acceptTerms = e.detail.value}>
-  I accept the <strong>terms</strong> and <a href="/privacy">privacy policy</a>
+## Usage
+```html
+<schmancy-checkbox label="I agree to terms" @change=${(e) => handle(e.detail.value)}>
 </schmancy-checkbox>
-
-// Typical checkbox group pattern
-<div class="flex flex-col gap-2">
-  <schmancy-checkbox
-    .checked=${this.preferences.notifications}
-    @change=${(e) => this.preferences.notifications = e.detail.value}
-    label="Email notifications">
-  </schmancy-checkbox>
-
-  <schmancy-checkbox
-    .checked=${this.preferences.newsletter}
-    @change=${(e) => this.preferences.newsletter = e.detail.value}
-    label="Weekly newsletter">
-  </schmancy-checkbox>
-
-  <schmancy-checkbox
-    .checked=${this.preferences.marketing}
-    @change=${(e) => this.preferences.marketing = e.detail.value}
-    label="Marketing emails">
-  </schmancy-checkbox>
-</div>
-
-// Common pattern with external label
-<div class="flex items-center gap-2">
-  <schmancy-checkbox
-    .checked=${this.isSelected}
-    @change=${(e) => this.isSelected = e.detail.value}>
-  </schmancy-checkbox>
-  <schmancy-typography type="body" token="md">
-    Custom styled label text
-  </schmancy-typography>
-</div>
-
-// Disabled states
-<schmancy-checkbox
-  label="This option is disabled"
-  disabled>
+```
+
+## Properties
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| value | boolean | `false` | Whether the checkbox is checked |
+| checked | boolean | `false` | Alias for value |
+| label | string | `undefined` | Label text (alternative to slot) |
+| name | string | auto | Form submission name |
+| disabled | boolean | `false` | Whether the checkbox is disabled |
+| required | boolean | `false` | Whether the checkbox is required |
+| size | `'xxs'\|'xs'\|'sm'\|'md'\|'lg'` | `'md'` | Checkbox size |
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| change | `{ value: boolean }` | When checked state changes |
+
+## Examples
+```html
+<!-- With label property -->
+<schmancy-checkbox label="Enable notifications" .value=${true}></schmancy-checkbox>
+
+<!-- With slotted label -->
+<schmancy-checkbox name="terms" required>
+  Accept <a href="/terms">terms and conditions</a>
 </schmancy-checkbox>
-
-<schmancy-checkbox
-  label="This option is checked and disabled"
-  .checked=${true}
-  disabled>
-</schmancy-checkbox>
-
-// In a form context
-<schmancy-form @submit=${handleSubmit}>
-  <schmancy-input name="email" label="Email" type="email" required></schmancy-input>
-
-  <schmancy-checkbox
-    name="subscribe"
-    .checked=${this.wantsNewsletter}
-    @change=${(e) => this.wantsNewsletter = e.detail.value}>
-    Send me newsletter updates
-  </schmancy-checkbox>
-
-  <schmancy-checkbox
-    name="terms"
-    required
-    .checked=${this.acceptedTerms}
-    @change=${(e) => this.acceptedTerms = e.detail.value}>
-    I accept the terms and conditions
-  </schmancy-checkbox>
-
-  <schmancy-button type="submit">Submit</schmancy-button>
-</schmancy-form>
-```
+```