@mhmo91/schmancy 0.2.193 → 0.2.194

package/ai/surface.md

@@ -0,0 +1,221 @@
+# Schmancy Surface - AI Reference
+
+```js
+// Basic Surface
+<schmancy-surface
+  elevation="0|1|2|3|4|5"
+  rounded="none|sm|md|lg|xl|full"
+  padding="none|xs|sm|md|lg|xl">
+  Surface content goes here
+</schmancy-surface>
+
+// Surface with color
+<schmancy-surface
+  color="primary|secondary|tertiary|surface|background|error"
+  theme="light|dark">
+  Colored surface content
+</schmancy-surface>
+
+// Interactive surface
+<schmancy-surface
+  interactive
+  @click=${handleClick}>
+  Click me!
+</schmancy-surface>
+
+// Surface with border
+<schmancy-surface
+  bordered
+  border-color="primary|secondary|tertiary|divider|error"
+  border-width="thin|medium|thick"
+  border-style="solid|dashed|dotted">
+  Surface with border
+</schmancy-surface>
+
+// Surface with dimensions
+<schmancy-surface
+  width="300px"
+  height="200px"
+  min-width="200px"
+  max-width="500px"
+  min-height="100px"
+  max-height="300px">
+  Fixed size surface
+</schmancy-surface>
+
+// Surface Properties
+elevation: number|string  // Shadow elevation (0-5)
+rounded: string           // Border radius: "none", "sm", "md", "lg", "xl", "full"
+padding: string           // Padding: "none", "xs", "sm", "md", "lg", "xl"
+margin: string            // Margin: "none", "xs", "sm", "md", "lg", "xl"
+color: string             // Background color (theme color or CSS value)
+theme: string             // Theme: "light", "dark"
+interactive: boolean      // Enable hover and active states
+bordered: boolean         // Show border
+borderColor: string       // Border color
+borderWidth: string       // Border width: "thin", "medium", "thick"
+borderStyle: string       // Border style: "solid", "dashed", "dotted"
+width: string             // Width
+height: string            // Height
+minWidth: string          // Minimum width
+maxWidth: string          // Maximum width
+minHeight: string         // Minimum height
+maxHeight: string         // Maximum height
+fullWidth: boolean        // Take full width of parent
+fullHeight: boolean       // Take full height of parent
+
+// Surface Context
+// For theme-aware surfaces and consistent styling
+import { SurfaceContext } from 'schmancy/surface';
+
+const surfaceContext = new SurfaceContext({
+  elevation: 1,
+  rounded: 'md',
+  padding: 'md',
+  theme: 'light'
+});
+
+// Examples
+// Basic card-like surface
+<schmancy-surface
+  elevation="2"
+  rounded="lg"
+  padding="lg">
+  <h3>Card Title</h3>
+  <p>This is a basic card surface with elevation, rounded corners, and padding.</p>
+</schmancy-surface>
+
+// Interactive card
+<schmancy-surface
+  elevation="1"
+  rounded="md"
+  padding="md"
+  interactive
+  @click=${navigateToDetails}>
+  <div style="display: flex; align-items: center; gap: 16px;">
+    <schmancy-avatar
+      src="path/to/avatar.jpg"
+      size="large">
+    </schmancy-avatar>
+    
+    <div>
+      <h3>John Doe</h3>
+      <p>Software Engineer</p>
+    </div>
+    
+    <schmancy-icon
+      icon="chevron-right"
+      style="margin-left: auto;">
+    </schmancy-icon>
+  </div>
+</schmancy-surface>
+
+// Alert surfaces
+<schmancy-surface
+  color="primary"
+  rounded="md"
+  padding="md"
+  bordered
+  border-color="primary"
+  style="--surface-color-opacity: 0.1;">
+  <div style="display: flex; align-items: center; gap: 16px;">
+    <schmancy-icon icon="info" color="primary"></schmancy-icon>
+    <div>
+      <h4>Information</h4>
+      <p>This is an informational message.</p>
+    </div>
+  </div>
+</schmancy-surface>
+
+<schmancy-surface
+  color="error"
+  rounded="md"
+  padding="md"
+  bordered
+  border-color="error"
+  style="--surface-color-opacity: 0.1;">
+  <div style="display: flex; align-items: center; gap: 16px;">
+    <schmancy-icon icon="alert-triangle" color="error"></schmancy-icon>
+    <div>
+      <h4>Error</h4>
+      <p>Something went wrong. Please try again.</p>
+    </div>
+  </div>
+</schmancy-surface>
+
+// Surface grid layout
+<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px;">
+  <schmancy-surface
+    elevation="1"
+    rounded="md"
+    padding="md">
+    <h3>Card 1</h3>
+    <p>Content for card 1.</p>
+  </schmancy-surface>
+  
+  <schmancy-surface
+    elevation="1"
+    rounded="md"
+    padding="md">
+    <h3>Card 2</h3>
+    <p>Content for card 2.</p>
+  </schmancy-surface>
+  
+  <schmancy-surface
+    elevation="1"
+    rounded="md"
+    padding="md">
+    <h3>Card 3</h3>
+    <p>Content for card 3.</p>
+  </schmancy-surface>
+</div>
+
+// Dashboard panel
+<schmancy-surface
+  elevation="2"
+  rounded="lg"
+  padding="lg"
+  height="300px">
+  <div style="display: flex; flex-direction: column; height: 100%;">
+    <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 16px;">
+      <h3>Sales Overview</h3>
+      <schmancy-dropdown>
+        <schmancy-button slot="trigger" variant="tertiary" size="small">
+          <span>This Week</span>
+          <schmancy-icon slot="suffix" icon="chevron-down"></schmancy-icon>
+        </schmancy-button>
+        
+        <schmancy-menu slot="content">
+          <schmancy-menu-item value="day">Today</schmancy-menu-item>
+          <schmancy-menu-item value="week">This Week</schmancy-menu-item>
+          <schmancy-menu-item value="month">This Month</schmancy-menu-item>
+          <schmancy-menu-item value="year">This Year</schmancy-menu-item>
+        </schmancy-menu>
+      </schmancy-dropdown>
+    </div>
+    
+    <div style="flex: 1; display: flex; align-items: center; justify-content: center;">
+      <!-- Chart or content would go here -->
+      <p>Chart placeholder</p>
+    </div>
+  </div>
+</schmancy-surface>
+
+// Using surface context
+<div .context=${surfaceContext}>
+  <schmancy-surface>
+    <h3>First Panel</h3>
+    <p>This surface inherits settings from the context.</p>
+  </schmancy-surface>
+  
+  <schmancy-surface>
+    <h3>Second Panel</h3>
+    <p>This surface also inherits settings from the context.</p>
+  </schmancy-surface>
+  
+  <schmancy-surface elevation="3" rounded="xl">
+    <h3>Custom Panel</h3>
+    <p>This surface overrides some context settings.</p>
+  </schmancy-surface>
+</div>
+```

package/ai/table.md

@@ -0,0 +1,236 @@
+# Schmancy Table - AI Reference
+
+```js
+// Basic Table
+<schmancy-table>
+  <thead>
+    <tr>
+      <th>Name</th>
+      <th>Email</th>
+      <th>Role</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>John Doe</td>
+      <td>john@example.com</td>
+      <td>Admin</td>
+    </tr>
+    <tr>
+      <td>Jane Smith</td>
+      <td>jane@example.com</td>
+      <td>User</td>
+    </tr>
+  </tbody>
+</schmancy-table>
+
+// Table with custom row component
+<schmancy-table>
+  <thead>
+    <tr>
+      <th>Name</th>
+      <th>Email</th>
+      <th>Role</th>
+      <th>Actions</th>
+    </tr>
+  </thead>
+  <tbody>
+    <schmancy-row
+      .data=${{ name: 'John Doe', email: 'john@example.com', role: 'Admin' }}
+      @click=${handleRowClick}>
+      <td>${data.name}</td>
+      <td>${data.email}</td>
+      <td>${data.role}</td>
+      <td>
+        <schmancy-button kind="tertiary" size="small">Edit</schmancy-button>
+        <schmancy-button kind="danger" size="small">Delete</schmancy-button>
+      </td>
+    </schmancy-row>
+    <!-- More rows -->
+  </tbody>
+</schmancy-table>
+
+// Table Properties
+striped: boolean          // Apply alternating row colors
+bordered: boolean         // Add borders to cells
+compact: boolean          // Reduce cell padding
+hover: boolean            // Highlight rows on hover
+responsive: boolean       // Make table horizontally scrollable on small screens
+sortable: boolean         // Enable column sorting
+selectable: boolean       // Enable row selection
+loading: boolean          // Show loading state
+
+// Row Properties
+selected: boolean         // Whether the row is selected
+data: object              // Data object for the row
+
+// Table Events
+@sort      // Fires when a sortable column is clicked, with { detail: { column, direction } }
+@selection // Fires when row selection changes, with { detail: { selected } }
+
+// Examples
+// Basic responsive table
+<schmancy-table
+  responsive
+  striped
+  hover>
+  <thead>
+    <tr>
+      <th>ID</th>
+      <th>Name</th>
+      <th>Email</th>
+      <th>Created</th>
+      <th>Status</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>1</td>
+      <td>John Doe</td>
+      <td>john@example.com</td>
+      <td>2023-04-12</td>
+      <td>
+        <schmancy-badge variant="success">Active</schmancy-badge>
+      </td>
+    </tr>
+    <tr>
+      <td>2</td>
+      <td>Jane Smith</td>
+      <td>jane@example.com</td>
+      <td>2023-04-15</td>
+      <td>
+        <schmancy-badge variant="warning">Pending</schmancy-badge>
+      </td>
+    </tr>
+  </tbody>
+</schmancy-table>
+
+// Sortable table
+<schmancy-table
+  sortable
+  @sort=${(e) => sortData(e.detail.column, e.detail.direction)}>
+  <thead>
+    <tr>
+      <th data-sort="id">ID</th>
+      <th data-sort="name">Name</th>
+      <th data-sort="email">Email</th>
+      <th data-sort="created">Created</th>
+      <th>Actions</th>
+    </tr>
+  </thead>
+  <tbody>
+    ${sortedData.map(item => html`
+      <tr>
+        <td>${item.id}</td>
+        <td>${item.name}</td>
+        <td>${item.email}</td>
+        <td>${formatDate(item.created)}</td>
+        <td>
+          <schmancy-icon-button
+            icon="edit"
+            variant="tertiary"
+            @click=${() => editItem(item)}>
+          </schmancy-icon-button>
+          <schmancy-icon-button
+            icon="delete"
+            variant="danger"
+            @click=${() => deleteItem(item)}>
+          </schmancy-icon-button>
+        </td>
+      </tr>
+    `)}
+  </tbody>
+</schmancy-table>
+
+// Selectable table
+<schmancy-table
+  selectable
+  @selection=${(e) => handleSelectedRows(e.detail.selected)}>
+  <thead>
+    <tr>
+      <th>
+        <schmancy-checkbox
+          .checked=${allSelected}
+          .indeterminate=${someSelected && !allSelected}
+          @change=${toggleAllSelection}>
+        </schmancy-checkbox>
+      </th>
+      <th>Name</th>
+      <th>Email</th>
+      <th>Role</th>
+    </tr>
+  </thead>
+  <tbody>
+    ${data.map(item => html`
+      <schmancy-row
+        .data=${item}
+        .selected=${selectedRows.includes(item.id)}>
+        <td>
+          <schmancy-checkbox
+            .checked=${selectedRows.includes(item.id)}
+            @change=${(e) => toggleRowSelection(item.id, e.target.checked)}>
+          </schmancy-checkbox>
+        </td>
+        <td>${item.name}</td>
+        <td>${item.email}</td>
+        <td>${item.role}</td>
+      </schmancy-row>
+    `)}
+  </tbody>
+</schmancy-table>
+
+// Loading state
+<schmancy-table loading>
+  <thead>
+    <tr>
+      <th>Name</th>
+      <th>Email</th>
+      <th>Role</th>
+    </tr>
+  </thead>
+  <tbody>
+    <!-- Content will be dimmed and a loading indicator shown -->
+  </tbody>
+</schmancy-table>
+
+// Pagination (with external component)
+<div>
+  <schmancy-table>
+    <!-- Table content -->
+  </schmancy-table>
+  
+  <div style="display: flex; justify-content: space-between; margin-top: 16px;">
+    <div>
+      Showing ${startIndex + 1} to ${Math.min(endIndex, totalItems)} of ${totalItems} items
+    </div>
+    
+    <div>
+      <schmancy-button
+        variant="tertiary"
+        size="small"
+        ?disabled=${page === 1}
+        @click=${() => setPage(page - 1)}>
+        Previous
+      </schmancy-button>
+      
+      <!-- Page numbers -->
+      ${generatePageNumbers(page, totalPages).map(p => html`
+        <schmancy-button
+          variant=${p === page ? "primary" : "tertiary"}
+          size="small"
+          @click=${() => setPage(p)}>
+          ${p}
+        </schmancy-button>
+      `)}
+      
+      <schmancy-button
+        variant="tertiary"
+        size="small"
+        ?disabled=${page === totalPages}
+        @click=${() => setPage(page + 1)}>
+        Next
+      </schmancy-button>
+    </div>
+  </div>
+</div>
+```

package/ai/tabs.md

@@ -0,0 +1,71 @@
+# Schmancy Tabs - AI Reference
+
+```js
+// Basic Tabs
+<schmancy-tabs value="tab1">
+  <schmancy-tab value="tab1" label="Tab 1"></schmancy-tab>
+  <schmancy-tab value="tab2" label="Tab 2"></schmancy-tab>
+  <schmancy-tab value="tab3" label="Tab 3"></schmancy-tab>
+  
+  <div slot="panel" data-tab="tab1">Content for Tab 1</div>
+  <div slot="panel" data-tab="tab2">Content for Tab 2</div>
+  <div slot="panel" data-tab="tab3">Content for Tab 3</div>
+</schmancy-tabs>
+
+// Tabs with Scrolling
+<schmancy-tabs value="tab1" scrollable>
+  <!-- Tab definitions -->
+</schmancy-tabs>
+
+// Tabs Groups (for complex tab structures)
+<schmancy-tabs-group value="tab1" @change=${handleTabChange}>
+  <schmancy-tab value="tab1" label="Tab 1"></schmancy-tab>
+  <schmancy-tab value="tab2" label="Tab 2"></schmancy-tab>
+  <schmancy-tab value="tab3" label="Tab 3"></schmancy-tab>
+  
+  <div data-tab="tab1">Content for Tab 1</div>
+  <div data-tab="tab2">Content for Tab 2</div>
+  <div data-tab="tab3">Content for Tab 3</div>
+</schmancy-tabs-group>
+
+// Tabs with Icons
+<schmancy-tabs value="tab1">
+  <schmancy-tab value="tab1">
+    <schmancy-icon icon="home"></schmancy-icon>
+    <span>Home</span>
+  </schmancy-tab>
+  <schmancy-tab value="tab2">
+    <schmancy-icon icon="settings"></schmancy-icon>
+    <span>Settings</span>
+  </schmancy-tab>
+</schmancy-tabs>
+
+// Tab Attributes
+value="tab-id" // Unique identifier for the tab
+label="Tab Label" // Text label (optional if using custom content)
+disabled? // Disabled state
+icon="icon-name" // Icon to display (alternative to using schmancy-icon in content)
+
+// Tab Methods and Events
+tabs.select(value) -> void // Programmatically select a tab
+@change // Fires when tab selection changes with { detail: { value } }
+
+// Examples
+// Basic usage
+<schmancy-tabs value="tab1" @change=${(e) => console.log('Selected tab:', e.detail.value)}>
+  <schmancy-tab value="tab1" label="Info"></schmancy-tab>
+  <schmancy-tab value="tab2" label="Settings"></schmancy-tab>
+  
+  <div slot="panel" data-tab="tab1">Information content here</div>
+  <div slot="panel" data-tab="tab2">Settings content here</div>
+</schmancy-tabs>
+
+// Dynamic tabs from data
+${tabData.map(tab => html`
+  <schmancy-tab value=${tab.id} label=${tab.label}></schmancy-tab>
+`)}
+
+${tabData.map(tab => html`
+  <div slot="panel" data-tab=${tab.id}>${tab.content}</div>
+`)}
+```

package/ai/template.md

@@ -0,0 +1,144 @@
+# Schmancy AI Documentation Guidelines
+
+This document provides a template and guidelines for creating consistent AI-friendly documentation for Schmancy components.
+
+## Documentation Format
+
+Each component's documentation should follow this structure:
+
+1. **Component Title**: `# Schmancy [Component] - AI Reference`
+2. **Code Block**: Main syntax reference with component usage patterns
+3. **Related Components**: List of related components with links and relationship descriptions
+4. **Technical Details**: Interfaces, types, CSS custom properties, etc.
+5. **Common Use Cases**: Practical examples with explanations
+
+## Code Block Template
+
+```js
+// Component Tag
+<schmancy-[component]
+  [primary-attribute]="value"
+  [boolean-attribute]?
+  @[event-name]=${handler}>
+  <!-- Content/children if applicable -->
+</schmancy-[component]>
+
+// Component Variations (if applicable)
+<schmancy-[component] 
+  variant="[variant]"
+  size="small|medium|large">
+</schmancy-[component]>
+
+// Component Methods
+component.method() -> returnType
+component.property = value
+
+// Event details
+@event-name // { detail: { relevantData } }
+
+// Examples (always number examples for clarity)
+// 1. Basic example
+<schmancy-[component] [primary-attribute]="value">
+  Content
+</schmancy-[component]>
+
+// 2. Advanced example
+<schmancy-[component]
+  [attribute]="value"
+  @[event]=${() => handleEvent()}>
+  <!-- Structured content -->
+</schmancy-[component]>
+```
+
+## Related Components Section
+
+Always include a "Related Components" section that links to other relevant components:
+
+```markdown
+## Related Components
+- **[Related-1](./related-1.md)**: Brief description of relationship
+- **[Related-2](./related-2.md)**: Brief description of relationship
+- **[Related-3](./related-3.md)**: Brief description of relationship
+```
+
+## Technical Details Section
+
+Include relevant technical information:
+
+```markdown
+## Technical Details
+
+### Interfaces
+```typescript
+interface ComponentProps {
+  property: type;
+  optionalProperty?: type;
+}
+```
+
+### CSS Custom Properties (if applicable)
+```css
+--schmancy-component-color: /* Controls the component color */
+--schmancy-component-spacing: /* Controls internal spacing */
+```
+```
+
+## Common Use Cases Section
+
+Provide 2-4 practical use cases with code examples:
+
+```markdown
+### Common Use Cases
+
+1. **Use Case 1**: Brief description
+   ```html
+   <schmancy-[component] specific-attribute="value"></schmancy-[component]>
+   ```
+
+2. **Use Case 2**: Brief description
+   ```html
+   <schmancy-[component] with="specific-configuration"></schmancy-[component]>
+   ```
+```
+
+## Style Guide
+
+1. **Code Examples**:
+   - Number all examples sequentially (e.g., `// 1. Basic example`)
+   - Include descriptive comments
+   - Ensure examples are realistic and complete
+
+2. **Component Descriptions**:
+   - Focus on functionality and API usage
+   - Avoid marketing language
+   - Provide context for when and why to use the component
+
+3. **Cross-Referencing**:
+   - Always link to related components
+   - Explain the relationship (e.g., "Used within", "Alternative to", "Extends")
+
+4. **Formatting**:
+   - Use backticks for inline code references
+   - Use proper markdown headers for sections
+   - Use TypeScript for type definitions
+
+## Component Categories
+
+Organize components according to these categories for better cross-referencing:
+
+1. **Core Infrastructure**: Area, Store, Teleport, RxJS Utils
+2. **Layout Components**: Layout, Surface, Card, Divider
+3. **Navigation & Structure**: Tabs, Menu, Nav-Drawer, Content-Drawer, Sheet, Dialog
+4. **Form Controls**: Form, Input, Textarea, Select, Autocomplete, Checkbox, Radio-Group, Option
+5. **Interactive Elements**: Button, Dropdown, Chips, List, Tree, Table
+6. **Feedback & Status**: Notification, Tooltip, Badge, Busy, Avatar
+7. **Typography & Visual**: Typography, Icons, Animated-Text, Typewriter
+8. **Utilities**: Directives, Theme, Theme-Button, Utils, Types, Delay, Date-Range, Steps
+
+## Examples
+
+See these files for examples of well-formatted component documentation:
+- [area.md](./area.md): Complex service component
+- [form.md](./form.md): Container component
+- [input.md](./input.md): Form field component
+- [store.md](./store.md): State management