# @federa/solanda-ui

> Minimalist Web Components UI library for Vue, Nuxt, React, and Angular

- **Version**: 1.5.0
- **License**: AGPL-3.0
- **Components**: 52 components (65 custom elements, including sub-elements like sl-popover-trigger, sl-dropdown-menu-item)
- **Framework**: Vanilla Web Components (works with Vue, React, Angular, Svelte, or plain HTML)
- **Bundle Size**: ~36 KB gzip (full), ~205 KB min
- **Dependencies**: Zero (Custom Elements v1 + Shadow DOM only)
- **TypeScript**: Full type definitions with JSDoc documentation
- **Repository**: [GitLab](https://gitlab.com/federa-social/libraries/solanda-ui.git) · [npm](https://www.npmjs.com/package/@federa/solanda-ui)
- **Website**: https://solanda.federa.social

---

## 🤖 AI Agent Quick Reference

### Installation
```bash
npm install @federa/solanda-ui
```

### Import Patterns
```js
// All components + CSS
import '@federa/solanda-ui'
import '@federa/solanda-ui/css'

// Individual components (tree-shaking)
import '@federa/solanda-ui/sl-button'
import '@federa/solanda-ui/sl-input'
import '@federa/solanda-ui/css'

// Themes
import '@federa/solanda-ui/css/themes/catppuccin'
```

### Framework Integration Notes
- **Vue/Nuxt**: Use `@update:value` event for v-model (manual binding required)
- **React**: Events receive `CustomEvent` with `e.detail.value`
- **Angular**: Requires `CUSTOM_ELEMENTS_SCHEMA` in module config
- **Svelte**: Use `on:event` syntax
- **Vanilla**: Works out of the box

### Key Patterns
- All components use `sl-` prefix (e.g., `<sl-button>`)
- CSS must be imported separately from components
- Components are self-registering via `customElements.define()`
- Shadow DOM: `mode: 'open'`
- All events are `bubbles: true, composed: true`

---

## Component Index

Each component has its own reference page with attributes, events, slots, methods, and CSS custom properties:

### 📝 Form Controls

- [sl-button](https://solanda.federa.social/components/button.md) — 6 variants, 5 sizes, icon support
- [sl-button-group](https://solanda.federa.social/components/button-group.md) — Radio/checkbox group of buttons
- [sl-input](https://solanda.federa.social/components/input.md) — All HTML input types, validation states
- [sl-input-group](https://solanda.federa.social/components/input-group.md) — Form controls with addons
- [sl-label](https://solanda.federa.social/components/label.md) — Form label
- [sl-checkbox](https://solanda.federa.social/components/checkbox.md) — With label and indeterminate state
- [sl-select](https://solanda.federa.social/components/select.md) — Dropdown with keyboard navigation
- [sl-switch](https://solanda.federa.social/components/switch.md) — Toggle switch
- [sl-textarea](https://solanda.federa.social/components/textarea.md) — Multiline text with auto-resize

### 🎨 Display

- [sl-alert](https://solanda.federa.social/components/alert.md) — Contextual feedback with 5 variants
- [sl-avatar](https://solanda.federa.social/components/avatar.md) — Image with fallback initials
- [sl-badge](https://solanda.federa.social/components/badge.md) — 7 variants, 3 sizes
- [sl-card](https://solanda.federa.social/components/card.md) — Header, body, actions slots
- [sl-icon](https://solanda.federa.social/components/icon.md) — SVG icon host
- [sl-skeleton](https://solanda.federa.social/components/skeleton.md) — Loading placeholder with shimmer
- [sl-spinner](https://solanda.federa.social/components/spinner.md) — Loading indicator, 4 sizes

### 🧭 Navigation

- [sl-breadcrumb](https://solanda.federa.social/components/breadcrumb.md) — Hierarchical navigation with separator
- [sl-pagination](https://solanda.federa.social/components/pagination.md) — Page navigation with ellipsis
- [sl-tab](https://solanda.federa.social/components/tab.md) — Individual tab item
- [sl-tab-content](https://solanda.federa.social/components/tab-content.md) — Tab panel content
- [sl-tabs](https://solanda.federa.social/components/tabs.md) — Tab list container

### 🪟 Overlays

- [sl-dialog](https://solanda.federa.social/components/dialog.md) — Modal with focus trap and keyboard dismiss
- [sl-dropdown-menu](https://solanda.federa.social/components/dropdown-menu.md) — Context/action menu
- [sl-offcanvas](https://solanda.federa.social/components/offcanvas.md) — Slide-in panel from any edge
- [sl-popover](https://solanda.federa.social/components/popover.md) — Click-triggered floating panel
- [sl-toast](https://solanda.federa.social/components/toast.md) — Programmatic notifications
- [sl-tooltip](https://solanda.federa.social/components/tooltip.md) — Hover tooltip with placement

### 📐 Layout

- [sl-accordion](https://solanda.federa.social/components/accordion.md) — Collapsible content sections
- [sl-feature-card](https://solanda.federa.social/components/feature-card.md) — Icon + title + description
- [sl-footer](https://solanda.federa.social/components/footer.md) — Page footer
- [sl-list-group](https://solanda.federa.social/components/list-group.md) — List container with variants
- [sl-section-header](https://solanda.federa.social/components/section-header.md) — Eyebrow + title + description
- [sidebar](https://solanda.federa.social/components/sidebar.md) — Page sidebar
- [sl-showcase-card](https://solanda.federa.social/components/showcase-card.md) — Demo container
- [sl-step-indicator](https://solanda.federa.social/components/step-indicator.md) — Progress steps
- [sl-topbar](https://solanda.federa.social/components/topbar.md) — Page top navigation bar

### 📄 Documentation Helpers

- [sl-doc-block](https://solanda.federa.social/components/doc-block.md) — Documentation content block

---

## Programmatic APIs

### Toast Notifications
```js
import { showToast } from '@federa/solanda-ui/sl-toast'

showToast({
  message: 'Operation completed!',
  variant: 'success',    // 'default' | 'success' | 'error' | 'warning' | 'info'
  duration: 3000,        // ms (0 to disable auto-dismiss)
  dismissible: true      // show close button
})
```

### Theme Manager
```js
import { themeManager } from '@federa/solanda-ui/theme'

// Initialize with defaults
const tm = themeManager.init({
  defaultTheme: 'system',       // 'light' | 'dark' | 'system'
  defaultPreset: 'solanda',     // 'solanda' | 'social-neutral' | 'catppuccin' | 'gruvbox' | 'tokyo-night' | 'nord'
  storageKey: 'solanda-ui-theme',
  autoApply: true
})

tm.getTheme()          // returns 'light' | 'dark' | 'system'
tm.getResolvedTheme()  // returns 'light' | 'dark'
tm.getPreset()         // returns current preset name
tm.setTheme('dark')    // apply a theme
tm.setPreset('gruvbox') // apply a preset
tm.toggleTheme()       // toggle between light and dark
```

---

## Theming

### Theme Presets

Six built-in presets, each with light and dark modes:

| Preset | Class | Description |
| --- | --- | --- |
| Solanda | `theme-solanda` | Warm terracotta + cool blues (default) |
| Social Neutral | `theme-social-neutral` | Clean professional teal/cyan |
| Catppuccin | `theme-catppuccin` | Vibrant purple/pink |
| Gruvbox | `theme-gruvbox` | Warm earth tones/orange |
| Tokyo Night | `theme-tokyo-night` | Cool blue/lavender |
| Nord | `theme-nord` | Cool arctic blues/greys |

### Semantic Color Variables

All components use HSL-based semantic tokens. Override these to customize:

```css
:root {
  --sl-hsl-background: H S% L%;
  --sl-hsl-foreground: H S% L%;
  --sl-hsl-primary: H S% L%;
  --sl-hsl-primary-foreground: H S% L%;
  --sl-hsl-secondary: H S% L%;
  --sl-hsl-muted: H S% L%;
  --sl-hsl-accent: H S% L%;
  --sl-hsl-destructive: H S% L%;
  --sl-hsl-border: H S% L%;
  --sl-hsl-input: H S% L%;
  --sl-hsl-ring: H S% L%;
  --sl-hsl-card: H S% L%;
  --sl-hsl-popover: H S% L%;
}
```

Usage in CSS: `background-color: hsl(var(--sl-hsl-primary));`

---

## Accessibility

All components follow WCAG 2.1 AA guidelines:

- **Keyboard Navigation**: Full keyboard support with Tab, Enter, Space, Arrow keys
- **ARIA Attributes**: Automatic role, aria-label, aria-checked, aria-hidden
- **Focus Management**: Focus trapping in dialogs, proper focus restoration
- **Screen Readers**: Semantic HTML with live regions for notifications
- **Color Contrast**: All color combinations meet 4.5:1 contrast ratio

---

## TypeScript Support

```ts
import type {
  SlButtonVariants,
  SlDialogSize,
  SlToastVariant,
  SlSwitchSize
} from '@federa/solanda-ui'

const buttonProps: SlButtonVariants = {
  variant: 'default',
  size: 'sm'
}
```

---

## Resources

- **Full reference**: [llms-full.txt](https://solanda.federa.social/llms-full.txt) — complete inline documentation
- **Component reference**: [solanda.federa.social/doc/](https://solanda.federa.social/doc/) — interactive examples
- **Custom Elements Manifest**: [custom-elements.json](https://solanda.federa.social/custom-elements.json)
- **npm**: [@federa/solanda-ui](https://www.npmjs.com/package/@federa/solanda-ui)
- **Repository**: [GitLab](https://gitlab.com/federa-social/libraries/solanda-ui.git)

---

**Built with ❤️ by [Federa](https://gitlab.com/federa-social)**