@mhmo91/schmancy 0.2.193 → 0.2.194

package/ai/typography.md

@@ -0,0 +1,170 @@
+# Schmancy Typography - AI Reference
+
+```js
+// Basic Typography
+<schmancy-typography
+  variant="h1|h2|h3|h4|h5|h6|subtitle1|subtitle2|body1|body2|button|caption|overline"
+  color="primary|secondary|tertiary|error|text-primary|text-secondary|text-disabled"
+  align="left|center|right|justify"
+  weight="thin|light|regular|medium|bold"
+  transform="none|uppercase|lowercase|capitalize"
+  truncate?
+  no-wrap?
+  gutter-bottom?>
+  Text content goes here
+</schmancy-typography>
+
+// Typography heading variants
+<schmancy-typography variant="h1">Heading 1</schmancy-typography>
+<schmancy-typography variant="h2">Heading 2</schmancy-typography>
+<schmancy-typography variant="h3">Heading 3</schmancy-typography>
+<schmancy-typography variant="h4">Heading 4</schmancy-typography>
+<schmancy-typography variant="h5">Heading 5</schmancy-typography>
+<schmancy-typography variant="h6">Heading 6</schmancy-typography>
+
+// Typography body variants
+<schmancy-typography variant="subtitle1">Subtitle 1</schmancy-typography>
+<schmancy-typography variant="subtitle2">Subtitle 2</schmancy-typography>
+<schmancy-typography variant="body1">Body 1 text</schmancy-typography>
+<schmancy-typography variant="body2">Body 2 text</schmancy-typography>
+<schmancy-typography variant="button">Button text</schmancy-typography>
+<schmancy-typography variant="caption">Caption text</schmancy-typography>
+<schmancy-typography variant="overline">Overline text</schmancy-typography>
+
+// Typography Properties
+variant: string        // Text style variant
+color: string          // Text color
+align: string          // Text alignment
+weight: string         // Font weight
+transform: string      // Text transformation
+truncate: boolean      // Truncate overflow with ellipsis
+noWrap: boolean        // Prevent text wrapping
+gutterBottom: boolean  // Add margin at the bottom
+italic: boolean        // Italic style
+underline: boolean     // Underline text
+lineHeight: string     // Line height
+letterSpacing: string  // Letter spacing
+fontFamily: string     // Font family
+size: string           // Custom font size (overrides variant)
+responsive: boolean    // Apply responsive sizing
+
+// Examples
+// Basic usage
+<schmancy-typography variant="h2" color="primary">
+  Welcome to Our Application
+</schmancy-typography>
+
+<schmancy-typography variant="body1">
+  This is a paragraph of text that demonstrates the body1 typography variant.
+  It's commonly used for the main content text on a page.
+</schmancy-typography>
+
+// Styled text
+<schmancy-typography
+  variant="subtitle1"
+  weight="bold"
+  color="secondary"
+  transform="uppercase">
+  Important Notice
+</schmancy-typography>
+
+// Truncated text
+<schmancy-typography
+  variant="body2"
+  truncate
+  style="max-width: 200px;">
+  This is a very long text that will be truncated with an ellipsis when it exceeds the container width.
+</schmancy-typography>
+
+// Responsive headings
+<schmancy-typography
+  variant="h1"
+  responsive
+  align="center"
+  gutter-bottom>
+  Responsive Heading
+</schmancy-typography>
+
+// Text with custom styling
+<schmancy-typography
+  variant="body1"
+  italic
+  letter-spacing="0.5px"
+  line-height="1.8">
+  This text has custom letter spacing and line height, with italic styling.
+</schmancy-typography>
+
+// Text with different weights
+<div>
+  <schmancy-typography variant="body1" weight="thin">
+    This text has thin weight.
+  </schmancy-typography>
+  
+  <schmancy-typography variant="body1" weight="light">
+    This text has light weight.
+  </schmancy-typography>
+  
+  <schmancy-typography variant="body1" weight="regular">
+    This text has regular weight.
+  </schmancy-typography>
+  
+  <schmancy-typography variant="body1" weight="medium">
+    This text has medium weight.
+  </schmancy-typography>
+  
+  <schmancy-typography variant="body1" weight="bold">
+    This text has bold weight.
+  </schmancy-typography>
+</div>
+
+// Typography in a card
+<schmancy-card>
+  <schmancy-card-content>
+    <schmancy-typography variant="h4" gutter-bottom>
+      Card Title
+    </schmancy-typography>
+    
+    <schmancy-typography variant="body2" color="text-secondary" gutter-bottom>
+      Posted on January 1, 2023
+    </schmancy-typography>
+    
+    <schmancy-typography variant="body1">
+      This is the main content of the card. It uses the body1 typography variant
+      which is suitable for longer text content.
+    </schmancy-typography>
+  </schmancy-card-content>
+  
+  <schmancy-card-actions>
+    <schmancy-button>
+      <schmancy-typography variant="button">
+        Read More
+      </schmancy-typography>
+    </schmancy-button>
+  </schmancy-card-actions>
+</schmancy-card>
+
+// Error message
+<schmancy-typography
+  variant="body2"
+  color="error"
+  gutter-bottom>
+  The username or password you entered is incorrect.
+</schmancy-typography>
+
+// Caption with custom size
+<schmancy-typography
+  variant="caption"
+  color="text-secondary"
+  size="10px">
+  * Terms and conditions apply
+</schmancy-typography>
+
+// Paragraph with custom font family
+<schmancy-typography
+  variant="body1"
+  font-family="'Georgia', serif"
+  line-height="1.7">
+  This paragraph uses a serif font for a more traditional typographic style.
+  Custom font families can be specified when needed for special sections.
+</schmancy-typography>
+```

package/dist/ai/area.md

@@ -0,0 +1,125 @@
+# Schmancy Area - AI Reference
+
+```js
+// Area Router Component
+<schmancy-area
+  name="root"
+  default="home-component">
+</schmancy-area>
+
+// Area Service
+import { area } from '@schmancy/area';
+
+// Navigation methods
+area.push({
+  component: UserProfileComponent,  // Component constructor, string tag name, or element instance
+  area: 'root',                     // Target area name
+  state?: { view: 'profile' },      // Optional state object
+  params?: { id: '123' },           // Optional parameters
+  historyStrategy: 'push'           // 'push', 'replace', 'pop', 'silent'
+});
+
+area.pop('sidebar');                // Remove an area
+
+// Subscription methods
+area.on(areaName, skipCurrent?) -> Observable<ActiveRoute>
+area.all(skipCurrent?) -> Observable<Map<string, ActiveRoute>>
+area.getState<T>(areaName) -> Observable<T>
+area.params<T>(areaName) -> Observable<T>
+area.param<T>(areaName, key) -> Observable<T>
+
+// Event name format for DOM event listeners
+schmancy-area-${areaName}-changed
+
+// Examples
+// 1. Basic navigation
+area.push({
+  component: 'home-page',
+  area: 'main',
+  historyStrategy: 'push'
+});
+
+// 2. Navigation with params
+area.push({
+  component: ProductDetailComponent,
+  area: 'main',
+  params: { productId: '12345' },
+  historyStrategy: 'push'
+});
+
+// 3. Subscribe to an area
+area.on('main').subscribe(route => {
+  console.log(`Component: ${route.component}, Params: ${route.params}`);
+});
+
+// 4. Get and react to a specific param
+area.param<string>('product', 'productId').subscribe(id => {
+  fetchProductDetails(id);
+});
+
+// 5. DOM event listening (non-RxJS approach)
+window.addEventListener('schmancy-area-main-changed', event => {
+  const { component, params } = event.detail;
+  updateUI(component, params);
+});
+```
+
+## Related Components
+- **[Teleport](./teleport.md)**: Can be used with Area for advanced component transportation
+- **[Store](./store.md)**: Complements Area for more complex state management
+- **[Layout](./layout.md)**: Often used as a container for areas
+
+## Technical Details
+
+### ActiveRoute Interface
+```typescript
+interface ActiveRoute {
+  component: string;        // Component tag name
+  area: string;             // Area name
+  state?: Record<string, unknown>;  // Optional state
+  params?: Record<string, unknown>; // Optional parameters
+}
+```
+
+### RouteAction Interface
+```typescript
+interface RouteAction {
+  component: CustomElementConstructor | string | HTMLElement;
+  area: string;
+  state?: Record<string, unknown>;
+  params?: Record<string, unknown>;
+  historyStrategy?: 'push' | 'replace' | 'pop' | 'silent';
+  clearQueryParams?: string[] | null;
+}
+```
+
+### Common Use Cases
+
+1. **Single Page Applications**: Define multiple areas for different sections of your app
+   ```html
+   <schmancy-area name="main"></schmancy-area>
+   <schmancy-area name="sidebar"></schmancy-area>
+   <schmancy-area name="modal"></schmancy-area>
+   ```
+
+2. **Typed Params and State**: Use TypeScript generics for type safety
+   ```typescript
+   interface UserParams { id: string; tab?: string; }
+   area.params<UserParams>('user').subscribe(params => {
+     fetchUser(params.id);
+     setActiveTab(params.tab || 'profile');
+   });
+   ```
+
+3. **Navigation Guards**: Implement navigation guards with RxJS operators
+   ```typescript
+   area.on('protected').pipe(
+     switchMap(route => {
+       if (!isAuthenticated()) {
+         area.push({ component: 'login-page', area: 'main' });
+         return EMPTY;
+       }
+       return of(route);
+     })
+   ).subscribe(handleProtectedRoute);
+   ```

package/dist/ai/autocomplete.md

@@ -0,0 +1,135 @@
+# Schmancy Autocomplete - AI Reference
+
+```js
+// Basic Autocomplete (Single-Select)
+<schmancy-autocomplete
+  label="Select an option"
+  placeholder="Type to search..."
+  value="selected-value"
+  size="sm|md|lg"
+  required?
+  maxHeight="300px"
+  @change=${handleChange}>
+  
+  <schmancy-option value="option1" label="Option 1"></schmancy-option>
+  <schmancy-option value="option2" label="Option 2"></schmancy-option>
+  <schmancy-option value="option3" label="Option 3"></schmancy-option>
+</schmancy-autocomplete>
+
+// Multi-Select Autocomplete
+<schmancy-autocomplete
+  label="Select multiple options"
+  placeholder="Type to search..."
+  multi
+  .values=${['option1', 'option3']} // Array of selected values (preferred for multi-select)
+  @change=${handleMultiChange}>
+  
+  <schmancy-option value="option1" label="Option 1"></schmancy-option>
+  <schmancy-option value="option2" label="Option 2"></schmancy-option>
+  <schmancy-option value="option3" label="Option 3"></schmancy-option>
+</schmancy-autocomplete>
+
+// Autocomplete with Custom Trigger
+<schmancy-autocomplete>
+  <button slot="trigger">Open Options</button>
+  
+  <schmancy-option value="option1" label="Option 1"></schmancy-option>
+  <schmancy-option value="option2" label="Option 2"></schmancy-option>
+</schmancy-autocomplete>
+
+// Autocomplete Properties
+value: string         // Selected value for single-select, comma-separated string for multi-select (legacy API)
+values: string[]      // Array of selected values for multi-select (preferred API for multi-select)
+multi: boolean        // Enable multi-select mode
+label: string         // Input label
+placeholder: string   // Input placeholder
+required: boolean     // Mark as required for validation
+size: string          // Input size: "sm", "md", "lg"
+maxHeight: string     // Maximum height of dropdown
+debounceMs: number    // Debounce delay in milliseconds for filtering
+autocomplete: string  // Value for input's autocomplete attribute
+description: string   // Description for screen readers
+
+// Autocomplete Events
+@change   // Fires when selection changes with { detail: { value, values? } }
+
+// Autocomplete Methods
+checkValidity() -> boolean    // Check if the input is valid
+reportValidity() -> boolean   // Show validation state and return validity
+
+// Examples
+// Basic usage
+<schmancy-autocomplete
+  label="Country"
+  placeholder="Select country"
+  @change=${(e) => selectedCountry = e.detail.value}>
+  
+  <schmancy-option value="us" label="United States"></schmancy-option>
+  <schmancy-option value="ca" label="Canada"></schmancy-option>
+  <schmancy-option value="mx" label="Mexico"></schmancy-option>
+  <schmancy-option value="fr" label="France"></schmancy-option>
+  <schmancy-option value="de" label="Germany"></schmancy-option>
+</schmancy-autocomplete>
+
+// Multi-select with preferred API
+<schmancy-autocomplete
+  label="Programming Languages"
+  placeholder="Select languages"
+  multi
+  .values=${selectedLanguages}
+  @change=${(e) => {
+    selectedLanguages = e.detail.values; // Use the new values array property
+  }}>
+  
+  <schmancy-option value="js" label="JavaScript"></schmancy-option>
+  <schmancy-option value="ts" label="TypeScript"></schmancy-option>
+  <schmancy-option value="py" label="Python"></schmancy-option>
+  <schmancy-option value="java" label="Java"></schmancy-option>
+  <schmancy-option value="go" label="Go"></schmancy-option>
+</schmancy-autocomplete>
+
+// Handling the change event
+handleChange(e) {
+  if (e.target.multi) {
+    const selectedValues = e.detail.values; // Array of values (preferred)
+    const legacyValue = e.detail.value;     // Comma-separated string (legacy)
+    console.log('Selected:', selectedValues);
+  } else {
+    const selectedValue = e.detail.value;   // Single value
+    console.log('Selected:', selectedValue);
+  }
+}
+
+// Dynamic options from data
+<schmancy-autocomplete
+  label="Select Item"
+  .value=${selectedItem}>
+  
+  ${items.map(item => html`
+    <schmancy-option
+      value=${item.id}
+      label=${item.name}>
+    </schmancy-option>
+  `)}
+</schmancy-autocomplete>
+
+// In a form
+<schmancy-form @submit=${handleSubmit}>
+  <schmancy-input
+    name="name"
+    label="Name"
+    required>
+  </schmancy-input>
+  
+  <schmancy-autocomplete
+    name="department"
+    label="Department"
+    required>
+    <schmancy-option value="hr" label="Human Resources"></schmancy-option>
+    <schmancy-option value="eng" label="Engineering"></schmancy-option>
+    <schmancy-option value="fin" label="Finance"></schmancy-option>
+  </schmancy-autocomplete>
+  
+  <schmancy-button type="submit">Submit</schmancy-button>
+</schmancy-form>
+```

package/dist/ai/avatar.md

@@ -0,0 +1,178 @@
+# Schmancy Avatar - AI Reference
+
+```js
+// Basic Avatar
+<schmancy-avatar
+  src="path/to/image.jpg"
+  alt="User Name"
+  size="x-small|small|medium|large|x-large">
+</schmancy-avatar>
+
+// Avatar with name initials
+<schmancy-avatar
+  name="John Doe"
+  size="medium">
+</schmancy-avatar>
+
+// Avatar with icon
+<schmancy-avatar
+  icon="user"
+  size="medium">
+</schmancy-avatar>
+
+// Avatar with custom size and color
+<schmancy-avatar
+  name="John Doe"
+  size="48px"
+  background-color="#6200ee"
+  color="white">
+</schmancy-avatar>
+
+// Avatar with shape
+<schmancy-avatar
+  src="path/to/image.jpg"
+  shape="circle|square|rounded">
+</schmancy-avatar>
+
+// Avatar Properties
+src: string             // Image URL
+alt: string             // Alt text for the image
+name: string            // Name for generating initials
+icon: string            // Icon name to display (if no src or name)
+size: string            // Size: "x-small" (24px), "small" (32px), "medium" (40px), "large" (48px), "x-large" (56px), or custom size
+shape: string           // Shape: "circle" (default), "square", "rounded"
+backgroundColor: string // Background color for name and icon avatars
+color: string           // Text/icon color
+bordered: boolean       // Show border
+badgeContent: string    // Content for the badge
+badgeColor: string      // Color for the badge
+fallback: string        // Fallback content if image fails to load
+clickable: boolean      // Make avatar clickable with hover effect
+
+// Avatar Events
+@click              // Fires when avatar is clicked
+@error              // Fires when image fails to load
+
+// Examples
+// Basic image avatar
+<schmancy-avatar
+  src="https://example.com/avatar.jpg"
+  alt="Jane Smith"
+  size="medium">
+</schmancy-avatar>
+
+// Name initials avatar
+<schmancy-avatar
+  name="John Doe"
+  size="large">
+</schmancy-avatar>
+
+// Icon avatar
+<schmancy-avatar
+  icon="user"
+  size="medium"
+  background-color="var(--color-primary)"
+  color="white">
+</schmancy-avatar>
+
+// Avatar with badge
+<schmancy-avatar
+  src="https://example.com/avatar.jpg"
+  badge-content="3"
+  badge-color="error">
+</schmancy-avatar>
+
+// Avatar with status indicator
+<div style="position: relative;">
+  <schmancy-avatar
+    name="Jane Smith"
+    size="large">
+  </schmancy-avatar>
+  
+  <schmancy-badge
+    dot
+    variant="success"
+    style="position: absolute; bottom: 0; right: 0; border: 2px solid white;">
+  </schmancy-badge>
+</div>
+
+// Avatar group
+<div style="display: flex;">
+  <schmancy-avatar
+    src="https://example.com/avatar1.jpg"
+    size="medium"
+    style="margin-right: -8px; border: 2px solid white;">
+  </schmancy-avatar>
+  
+  <schmancy-avatar
+    src="https://example.com/avatar2.jpg"
+    size="medium"
+    style="margin-right: -8px; border: 2px solid white;">
+  </schmancy-avatar>
+  
+  <schmancy-avatar
+    src="https://example.com/avatar3.jpg"
+    size="medium"
+    style="margin-right: -8px; border: 2px solid white;">
+  </schmancy-avatar>
+  
+  <schmancy-avatar
+    name="+5"
+    size="medium"
+    background-color="#e0e0e0"
+    color="#757575"
+    style="border: 2px solid white;">
+  </schmancy-avatar>
+</div>
+
+// Clickable avatar for profile
+<schmancy-avatar
+  src="https://example.com/avatar.jpg"
+  size="large"
+  clickable
+  @click=${openProfile}>
+</schmancy-avatar>
+
+// Avatar with fallback
+<schmancy-avatar
+  src="https://example.com/avatar.jpg"
+  name="John Doe"
+  fallback="JD"
+  @error=${handleImageError}>
+</schmancy-avatar>
+
+// Square avatar
+<schmancy-avatar
+  src="https://example.com/avatar.jpg"
+  shape="square"
+  size="large">
+</schmancy-avatar>
+
+// Avatar in a list item
+<schmancy-list-item>
+  <schmancy-avatar
+    slot="start"
+    src="https://example.com/avatar.jpg"
+    size="medium">
+  </schmancy-avatar>
+  
+  <div slot="main">
+    <div>John Doe</div>
+    <div>Software Engineer</div>
+  </div>
+</schmancy-list-item>
+
+// Avatar in a chat message
+<div style="display: flex; margin-bottom: 16px;">
+  <schmancy-avatar
+    src="https://example.com/avatar.jpg"
+    size="small"
+    style="margin-right: 8px;">
+  </schmancy-avatar>
+  
+  <div>
+    <div><strong>Jane Smith</strong> <span style="color: #757575;">12:34 PM</span></div>
+    <div>Hello! How are you doing today?</div>
+  </div>
+</div>
+```