snice 4.8.0 → 4.10.0

package/docs/components/layout.md

@@ -0,0 +1,84 @@
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/layout.md instead)
+
+# Layout
+`<snice-layout>`
+
+Application layout with header navigation, main content area, and footer.
+
+## Basic Usage
+
+```typescript
+import 'snice/components/layout/snice-layout';
+```
+
+```html
+<snice-layout>
+  <div slot="brand"><h1>My App</h1></div>
+  <div slot="page">Page content</div>
+  <div slot="footer"><p>&copy; 2025 My Company</p></div>
+</snice-layout>
+```
+
+## Importing
+
+**ESM (bundler)**
+```typescript
+import 'snice/components/layout/snice-layout';
+```
+
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-layout.min.js"></script>
+```
+
+## Examples
+
+### Basic Layout
+
+Use slots to fill the brand, page, and footer areas.
+
+```html
+<snice-layout>
+  <div slot="brand">
+    <h1>Dashboard</h1>
+  </div>
+  <div slot="page">
+    <h2>Welcome</h2>
+    <p>Main content goes here.</p>
+  </div>
+  <div slot="footer">
+    <p>&copy; 2025 Acme Corp</p>
+  </div>
+</snice-layout>
+```
+
+### With Router Integration
+
+Use the `update()` method to sync navigation with the router.
+
+```html
+<snice-layout id="app-layout">
+  <img slot="brand" src="/logo.svg" alt="Logo" />
+  <div slot="page" id="page-content"></div>
+</snice-layout>
+```
+
+```javascript
+const layout = document.querySelector('#app-layout');
+layout.update(appContext, placards, currentRoute, routeParams);
+```
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| `brand` | Logo or brand content in the header |
+| `page` | Main page content area |
+| `footer` | Footer content |
+
+## Methods
+
+| Method | Arguments | Description |
+|--------|-----------|-------------|
+| `update()` | `appContext: AppContext, placards: Placard[], currentRoute: string, routeParams: RouteParams` | Updates navigation from router state |

package/docs/components/link-preview.md

@@ -1,161 +1,135 @@
-# Link Preview Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/link-preview.md instead)
 
-The link preview component displays social media-style link preview cards, similar to Open Graph or Twitter Card previews. It is purely visual -- all data is passed via properties (no fetching).
+# Link Preview
+`<snice-link-preview>`
 
-## Table of Contents
-- [Basic Usage](#basic-usage)
-- [Properties](#properties)
-- [Events](#events)
-- [Examples](#examples)
+Displays a rich preview card for a URL with image, title, description, and site info.
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/link-preview/snice-link-preview';
+```
+
 ```html
 <snice-link-preview
-  title="My Article"
-  description="A brief description of the article content."
-  image="https://example.com/og-image.jpg"
-  site-name="example.com"
-  url="https://example.com/article"
-></snice-link-preview>
+  url="https://example.com"
+  title="Example Website"
+  description="An example website for demonstration."
+  image="https://example.com/og-image.jpg">
+</snice-link-preview>
 ```
 
+## Importing
+
+**ESM (bundler)**
 ```typescript
 import 'snice/components/link-preview/snice-link-preview';
 ```
 
-## Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `url` | `string` | `''` | Target URL. Clicking the card opens this in a new tab. |
-| `title` | `string` | `''` | Title text. Truncated to 2 lines. |
-| `description` | `string` | `''` | Description text. Truncated to 3 lines. |
-| `image` | `string` | `''` | Image URL. Shows a placeholder icon when empty. |
-| `site-name` | `string` | `''` | Name of the source site. |
-| `favicon` | `string` | `''` | URL of the site favicon icon. |
-| `variant` | `'horizontal' \| 'vertical'` | `'vertical'` | Layout direction. Vertical shows image on top; horizontal shows image on left. |
-| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Controls padding, font sizes, and image dimensions. |
-
-## Events
-
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `@snice/link-click` | `{ url: string }` | Fired when the card is clicked, before opening the URL. |
+**CDN**
+```html
+<script src="snice-runtime.min.js"></script>
+<script src="snice-link-preview.min.js"></script>
+```
 
 ## Examples
 
-### Vertical Card (Default)
+### Vertical Card
+
+The default layout stacks the image above the content.
 
 ```html
 <snice-link-preview
+  url="https://snice.dev"
   title="Snice - Beautiful Decorators for Custom Elements"
-  description="Write clean, reactive web components with TypeScript decorators. No framework. No virtual DOM."
+  description="Write clean, reactive web components with TypeScript decorators."
   image="https://picsum.photos/600/300"
-  site-name="snice.dev"
-  url="https://snice.dev"
-></snice-link-preview>
+  site-name="snice.dev">
+</snice-link-preview>
 ```
 
 ### Horizontal Card
 
+Use `variant="horizontal"` to display the image beside the content.
+
 ```html
 <snice-link-preview
   variant="horizontal"
-  title="Getting Started Guide"
-  description="Learn to build elements step by step"
-  site-name="snice.dev"
   url="https://snice.dev/guide"
-></snice-link-preview>
+  title="Getting Started Guide"
+  description="Learn to build elements step by step."
+  site-name="snice.dev">
+</snice-link-preview>
 ```
 
-### Small Horizontal Cards
-
-```html
-<snice-link-preview
-  variant="horizontal"
-  size="small"
-  title="Quick Link"
-  description="A short description"
-  site-name="example.com"
-  url="https://example.com"
-></snice-link-preview>
-```
+### Sizes
 
-### Large Card
+Use the `size` attribute to adjust padding, font sizes, and image dimensions.
 
 ```html
-<snice-link-preview
-  size="large"
-  title="In-Depth Article Title"
-  description="A longer description that can span up to four lines in the large size variant, giving more room for content summaries."
-  image="https://picsum.photos/800/400"
-  site-name="blog.example.com"
-  favicon="https://example.com/favicon.ico"
-  url="https://blog.example.com/article"
-></snice-link-preview>
+<snice-link-preview size="small" url="https://example.com" title="Compact Card" description="A short summary."></snice-link-preview>
+<snice-link-preview size="large" url="https://example.com" title="Expanded Card" description="A longer description with more room for content." image="https://picsum.photos/800/400"></snice-link-preview>
 ```
 
 ### Without Image
 
+When no image is provided, a placeholder link icon is shown.
+
 ```html
 <snice-link-preview
+  url="https://example.com"
   title="Text-Only Preview"
   description="When no image is provided, a placeholder icon is shown."
-  site-name="example.com"
-  url="https://example.com"
-></snice-link-preview>
+  site-name="example.com">
+</snice-link-preview>
 ```
 
 ### With Favicon
 
 ```html
 <snice-link-preview
+  url="https://example.com/article"
   title="Article with Favicon"
   description="Shows the site favicon next to the site name."
   image="https://picsum.photos/600/300"
   site-name="example.com"
-  favicon="https://example.com/favicon.ico"
-  url="https://example.com/article"
-></snice-link-preview>
+  favicon="https://example.com/favicon.ico">
+</snice-link-preview>
 ```
 
-### Listening for Click Events
+### Click Event
 
 ```html
 <snice-link-preview
   id="preview"
   title="Clickable Preview"
-  description="Listen for link-click events."
-  url="https://example.com"
-></snice-link-preview>
+  description="Listen for click events."
+  url="https://example.com">
+</snice-link-preview>
 
 <script type="module">
-  const preview = document.getElementById('preview');
-  preview.addEventListener('@snice/link-click', (e) => {
+  document.getElementById('preview').addEventListener('@snice/link-click', (e) => {
     console.log('Link clicked:', e.detail.url);
   });
 </script>
 ```
 
-## Accessibility
-
-- **ARIA role**: Card has `role="article"` for screen reader context
-- **ARIA label**: Uses the title as the accessible label
-- **Keyboard navigation**: Card is focusable and activates with Enter or Space
-- **Focus ring**: Visible focus indicator for keyboard users
-- **Image alt**: Images use empty alt text (decorative) since the title provides context
-
-## Browser Support
+## Properties
 
-- Modern browsers (Chrome, Firefox, Safari, Edge)
-- Requires Custom Elements v1 and Shadow DOM support
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `url` | `string` | `''` | Target URL (opens on click) |
+| `title` | `string` | `''` | Preview title (clamped to 2 lines) |
+| `description` | `string` | `''` | Preview description (clamped to 3 lines) |
+| `image` | `string` | `''` | Preview image URL |
+| `siteName` (attr: `site-name`) | `string` | `''` | Site name in footer |
+| `favicon` | `string` | `''` | Favicon URL in footer |
+| `variant` | `'vertical' \| 'horizontal'` | `'vertical'` | Card layout direction |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Card size |
 
-## Best Practices
+## Events
 
-1. **Always set a title**: The title is the primary content of the preview card
-2. **Provide meaningful descriptions**: Keep descriptions concise but informative
-3. **Use appropriate images**: Wide aspect ratio images (1.91:1) work best for vertical cards
-4. **Set the URL**: Without a URL, clicking the card does nothing
-5. **Use horizontal for compact layouts**: The horizontal variant works well in sidebars or lists
-6. **Use small size for dense UIs**: Small cards work well when showing multiple previews
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `@snice/link-click` | `{ url: string }` | Fired when the card is clicked |

package/docs/components/link.md

@@ -1,100 +1,84 @@
-# Link Component
+[//]: # (AI: For a low-token version of this doc, use docs/ai/components/link.md instead)
 
-A customizable link component with multiple variants, external link handling, and accessibility features.
+# Link
+`<snice-link>`
 
-## Features
-
-- **Multiple Variants**: default, primary, secondary, muted
-- **External Link Handling**: Automatic `target="_blank"` and security attributes
-- **Hash Routing**: Built-in support for hash-based navigation
-- **Router Integration**: Emits events for custom router integration
-- **Accessibility**: Proper ARIA attributes and keyboard navigation
-- **Disabled State**: Visual and functional disabled state
-- **Customizable**: Full theme integration
+A customizable hyperlink component with variants, external link handling, and hash routing support.
 
 ## Basic Usage
 
+```typescript
+import 'snice/components/link/snice-link';
+```
+
 ```html
 <snice-link href="/about">About Us</snice-link>
 ```
 
-## Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `href` | `string` | `''` | Link URL |
-| `target` | `LinkTarget` | `'_self'` | Target attribute ('_self', '_blank', '_parent', '_top') |
-| `variant` | `LinkVariant` | `'default'` | Visual style variant |
-| `disabled` | `boolean` | `false` | Disable the link |
-| `external` | `boolean` | `false` | Treat as external link (auto _blank + security) |
-| `underline` | `boolean` | `false` | Show text underline |
-| `hash` | `boolean` | `false` | Automatically prepend # to href (for hash routing) |
-
-## Variants
+## Importing
 
-### Default
-```html
-<snice-link href="/page">Default link</snice-link>
+**ESM (bundler)**
+```typescript
+import 'snice/components/link/snice-link';
 ```
 
-### Primary
+**CDN**
 ```html
-<snice-link href="/page" variant="primary">Primary link</snice-link>
+<script src="snice-runtime.min.js"></script>
+<script src="snice-link.min.js"></script>
 ```
 
-### Secondary
-```html
-<snice-link href="/page" variant="secondary">Secondary link</snice-link>
-```
+## Examples
+
+### Variants
+
+Use the `variant` attribute to change the link's visual style.
 
-### Muted
 ```html
-<snice-link href="/page" variant="muted">Muted link</snice-link>
+<snice-link href="/page" variant="default">Default</snice-link>
+<snice-link href="/page" variant="primary">Primary</snice-link>
+<snice-link href="/page" variant="secondary">Secondary</snice-link>
+<snice-link href="/page" variant="muted">Muted</snice-link>
 ```
 
-## External Links
+### External Links
 
-External links automatically open in a new tab with security attributes:
+Set the `external` attribute to open in a new tab with security attributes and an arrow icon.
 
 ```html
-<snice-link href="https://example.com" external>
-  External Link
-</snice-link>
+<snice-link href="https://example.com" external>Visit Example</snice-link>
 ```
 
-This automatically adds:
-- `target="_blank"`
-- `rel="noopener noreferrer"`
-- External link icon (↗)
+### Underline
 
-## Underline
+Use the `underline` attribute to show text decoration.
 
 ```html
-<snice-link href="/page" underline>Underlined link</snice-link>
+<snice-link href="/docs" underline>Documentation</snice-link>
 ```
 
-## Disabled State
+### Disabled State
+
+Set the `disabled` attribute to prevent interaction.
 
 ```html
-<snice-link href="/page" disabled>Disabled link</snice-link>
+<snice-link href="/page" disabled>Unavailable</snice-link>
 ```
 
-## Hash Routing
+### Hash Routing
 
-For hash-based navigation (Single Page Applications):
+Set the `hash` attribute to auto-prepend `#` to href for single-page app routing.
 
 ```html
-<!-- Automatically prepends # to href -->
 <snice-link href="home" hash>Home</snice-link>
 <snice-link href="about" hash>About</snice-link>
 <snice-link href="contact" hash>Contact</snice-link>
-
 <!-- Renders as: <a href="#home">Home</a> -->
 ```
 
 ### Router Integration
 
-The `navigate` event allows decoupled router integration:
+Listen for the `navigate` event on hash links for custom routing.
 
 ```html
 <snice-link href="profile" hash id="profile-link">Profile</snice-link>
@@ -102,128 +86,60 @@ The `navigate` event allows decoupled router integration:
 <script>
   document.getElementById('profile-link').addEventListener('navigate', (e) => {
     console.log('Navigating to:', e.detail.href);
-
-    // Custom routing logic
-    myRouter.navigate(e.detail.href);
-
-    // Optionally prevent default navigation
-    // e.preventDefault();
-  });
-</script>
-```
-
-### Example Router Setup
-
-```html
-<nav>
-  <snice-link href="home" hash>Home</snice-link>
-  <snice-link href="products" hash>Products</snice-link>
-  <snice-link href="about" hash>About</snice-link>
-</nav>
-
-<script>
-  // Listen to all navigate events
-  document.addEventListener('navigate', (e) => {
-    const route = e.detail.href;
-
-    // Update view based on route
-    switch(route) {
-      case 'home':
-        showHomeView();
-        break;
-      case 'products':
-        showProductsView();
-        break;
-      case 'about':
-        showAboutView();
-        break;
-    }
+    // e.preventDefault() cancels default navigation
   });
 </script>
 ```
 
-## In Context
+### Inline Usage
 
-Links work naturally within text:
+Links display inline and work naturally within text.
 
 ```html
 <p>
-  This is a paragraph with an <snice-link href="/page">inline link</snice-link>
-  in the middle of the text.
+  Read our <snice-link href="/privacy" underline>privacy policy</snice-link>
+  for more details.
 </p>
 ```
 
-## Events
-
-| Event | Detail | Description |
-|-------|--------|-------------|
-| `click` | `MouseEvent` | Emitted when link is clicked (prevented if disabled) |
-| `navigate` | `{ href: string }` | Emitted on hash link click (bubbles, composed, cancelable) |
-
-## CSS Parts
-
-Use `::part()` to style internal elements:
-
-```css
-snice-link::part(link) {
-  font-weight: bold;
-}
+### Footer Links
 
-snice-link::part(external-icon) {
-  color: blue;
-}
+```html
+<footer>
+  <snice-link href="/privacy" variant="muted">Privacy</snice-link>
+  <snice-link href="/terms" variant="muted">Terms</snice-link>
+  <snice-link href="https://github.com" external variant="muted">GitHub</snice-link>
+</footer>
 ```
 
-## Theming
-
-The component uses these CSS custom properties:
+## Slots
 
-```css
---snice-color-primary
---snice-color-primary-dark
---snice-color-primary-darker
---snice-color-text
---snice-color-text-secondary
---snice-color-text-muted
---snice-color-text-disabled
---snice-transition-fast
-```
+| Name | Description |
+|------|-------------|
+| (default) | Link text content |
 
-## Accessibility
+## Properties
 
-- Proper `href` attribute for keyboard navigation
-- Correct `rel` attributes for external links
-- Disabled state prevents interaction
-- Screen reader friendly
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `href` | `string` | `''` | Link URL |
+| `target` | `'_self' \| '_blank' \| '_parent' \| '_top'` | `'_self'` | Link target |
+| `variant` | `'default' \| 'primary' \| 'secondary' \| 'muted'` | `'default'` | Visual style |
+| `disabled` | `boolean` | `false` | Disables the link |
+| `external` | `boolean` | `false` | Opens in new tab with `noopener noreferrer` |
+| `underline` | `boolean` | `false` | Shows text underline |
+| `hash` | `boolean` | `false` | Auto-prepends `#` to href |
 
-## Examples
+## Events
 
-### Navigation Menu
-```html
-<nav>
-  <snice-link href="/">Home</snice-link>
-  <snice-link href="/about">About</snice-link>
-  <snice-link href="/contact">Contact</snice-link>
-</nav>
-```
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `click` | `MouseEvent` | Fired on click (prevented when disabled) |
+| `navigate` | `{ href: string }` | Fired on hash link click, cancelable |
 
-### Footer Links
-```html
-<footer>
-  <snice-link href="/privacy" variant="muted">Privacy</snice-link>
-  <snice-link href="/terms" variant="muted">Terms</snice-link>
-  <snice-link href="https://twitter.com" external variant="muted">
-    Twitter
-  </snice-link>
-</footer>
-```
+## CSS Parts
 
-### Action Links
-```html
-<snice-link href="/download" variant="primary">
-  Download Now
-</snice-link>
-<snice-link href="/learn-more" variant="secondary">
-  Learn More
-</snice-link>
-```
+| Part | Description |
+|------|-------------|
+| `link` | The anchor element |
+| `external-icon` | The external link arrow icon |