# Hearth UI

> A themeable Vue and web-component system for self-hosted dashboards, public pages, and authentication screens. Start here, then read only the component references needed for the task.

This index covers 35 public components from repository source. The current package.json version is 0.2.0; the working tree may contain unreleased changes. Check the installed version and matching source/tag before assuming a feature is in a published release.

## Agent workflow

1. Identify the host framework and choose native Vue components or web components. Do not create another implementation of an existing Hearth component.
2. Pick a page frame first: [HPublicShell](docs/components/public-shell/llms.txt), [HAuthPage](docs/components/auth-page/llms.txt), or [HDashboardShell](docs/components/dashboard-shell/llms.txt).
3. Read [HTheme](docs/components/theme/llms.txt) before changing tokens, palettes, density, or scoped theme islands.
4. Follow the relevant component links below for props, defaults, events, slots, examples, and constraints. Do not invent props, tags, or event payload shapes.
5. Keep authentication, authorization, routing, network requests, persistence, and business logic in the consuming application.
6. If changing this repository, regenerate these files with `npm run docs:generate` and verify them with `npm run docs:check`.

## Installation and entry points

- Package name: `@samishal1998/hearth-ui`. [GitHub releases](https://github.com/samishal1998/hearth-ui/releases) provide npm-compatible tarballs; do not assume an npm registry publication. For current unreleased source, build this checkout.
- Vue: import named components from the package and load `@samishal1998/hearth-ui/styles.css`. Use the host's Vue 3.5+ runtime.
- Web components: import `registerElements` from `@samishal1998/hearth-ui/elements`, load `@samishal1998/hearth-ui/themes.css`, and call `registerElements()`.
- Auto-registration: `@samishal1998/hearth-ui/elements/auto`. A custom prefix is supported through `registerElements('my-app')`.
- Raw browser: serve the extracted package contents, link `dist/themes.css`, and load `dist/elements/auto.js` as a module. Keep the shared chunks alongside the entry files. No Node globals or host Vue global are needed.
- Native Vue supports SSR. Web components render when connected in the browser; declarative shadow-DOM hydration is not provided.

## Shared integration rules

- Vue prop names use camelCase; HTML attributes use kebab-case. Array/object values are DOM properties, never JSON strings in attributes.
- Boolean attributes use presence/absence. Set `element.disabled = false`, not `disabled="false"`.
- Vue-emitted events become custom events with argument arrays: `const [value] = event.detail`. Listen on the element itself; do not assume bubbling. Native `click` is still a normal DOM event.
- Native Vue models use `v-model` (or a named model when documented). Update consumer-owned state for callbacks such as `favorite-change`, `close`, and navigation.
- Native slots use `slot="name"`; Vue uses `#name`. There are no web-component scoped slots.
- Fields need names to participate in form submission. Custom fields bridge to their owning native form through ElementInternals. Multi-selection uses repeated values: `new FormData(form).getAll(name)`.
- Keep form and field hosts in the same DOM tree. Configure initial properties before connection if they should become reset defaults. Do not attach unrelated slotted fields to an internal auth form.
- `formDisabled` and `control-sync` are internal adapter plumbing. Do not configure or subscribe to them in application code.
- Palettes in this source: `sunset`, `ocean`, `forest`, `dusk`, `rose`. Sunset is the default. Modes: dark, light, system. Density: comfortable, compact.
- Prefer `--h-*` tokens for consistent changes; use documented CSS parts for targeted web-component styling. Do not reach into shadow roots to patch implementation DOM.
- Use visible labels, meaningful state text, and native keyboard behavior. Validate custom palettes and your composed application; component tests are not an application-wide accessibility certification.

## Quick component selection

- Short fixed choice: HSelect. Searchable choice: HCombobox. Array-typed searchable choices: HMultiSelect. One visible choice among alternatives: HRadioGroup.
- Selection/agreement: HCheckbox. On/off setting: HSwitch. Free text: HInput/HTextarea. Bounded numeric adjustment: HRange.
- Revealing panels: HTabs. Expandable sections: HAccordion. Route navigation: HNavigationMenu/HSidebar/HBreadcrumbs.
- Known/unknown work progress: HProgress. Loading shapes: HSkeleton. Empty/no-results state: HEmptyState. Feedback: HAlert. Compact state label: HBadge.
- Generic content: HCard. Application launchers: HAppCard. Metrics: HStatCard.

## Layouts

- [HAuthPage](docs/components/auth-page/llms.txt): The full split-screen welcome/login page. It emits credentials; your application owns authentication.
- [HBreadcrumbs](docs/components/breadcrumbs/llms.txt): A wrapping breadcrumb trail with an accessible current page.
- [HDashboardShell](docs/components/dashboard-shell/llms.txt): A complete dashboard frame with desktop sidebar, native mobile navigation dialog, account controls, and content area.
- [HNavigationMenu](docs/components/navigation-menu/llms.txt): A navigation disclosure menu with native links, nested groups, outside-click dismissal, and Escape support.
- [HPageHeader](docs/components/page-header/llms.txt): A plain page introduction or the signature atmospheric dashboard hero.
- [HPublicShell](docs/components/public-shell/llms.txt): A public landing-page frame: brand, a few links, an account action, and a quiet footer.
- [HSidebar](docs/components/sidebar/llms.txt): A standalone, collapsible sidebar with grouped navigation and optional custom header/footer.

## Controls

- [HAccordion](docs/components/accordion/llms.txt): Native details/summary disclosures with single or multiple expansion.
- [HButton](docs/components/button/llms.txt): Native button or link behavior, clear focus, icon-only labels, and restrained press feedback.
- [HButtonBar](docs/components/button-bar/llms.txt): Group actions without changing native button focus or submission behavior.
- [HCheckbox](docs/components/checkbox/llms.txt): A native checkbox with a mixed-state option and optional description.
- [HCombobox](docs/components/combobox/llms.txt): Searchable single or multi-select with selected chips, disabled options, keyboard navigation, and repeated form values.
- [HInput](docs/components/input/llms.txt): A labeled input with help/error text and native validation. Web components participate in their owning form.
- [HMultiSelect](docs/components/multi-select/llms.txt): An array-typed multi-select combobox using the same searchable selection engine as HCombobox.
- [HPagination](docs/components/pagination/llms.txt): Bounded page navigation with current-page semantics and ellipses for long lists.
- [HRadioGroup](docs/components/radio-group/llms.txt): One native radio group per component, with descriptions, disabled choices, and arrow/Home/End keyboard control.
- [HRange](docs/components/range/llms.txt): A native numeric slider with a visible value and optional unit.
- [HSelect](docs/components/select/llms.txt): A native select with labeled options, not a recreated browser picker.
- [HSwitch](docs/components/switch/llms.txt): A keyboard-operable switch backed by a real checkbox, with form participation in custom-element mode.
- [HTabs](docs/components/tabs/llms.txt): Tabs with roving focus, arrow/Home/End keys, and properly associated panels.
- [HTextarea](docs/components/textarea/llms.txt): A labeled multiline field with native constraints and form reset support.

## Surfaces

- [HAppCard](docs/components/app-card/llms.txt): A launchable application card with source, status, and optional owner controls. Favorite state belongs to your app.
- [HCard](docs/components/card/llms.txt): The common surface: restrained depth, a readable heading, and generous space for your content.
- [HSeparator](docs/components/separator/llms.txt): A structural divider, optionally labeled or exposed as an accessible separator.
- [HStatCard](docs/components/stat-card/llms.txt): A quiet overview metric with tabular numbers, an icon, and a supporting label.

## Feedback

- [HAlert](docs/components/alert/llms.txt): Inline feedback for success, information, and problems. Errors announce as alerts; other tones use status.
- [HBadge](docs/components/badge/llms.txt): A compact label with optional status dot. Color always accompanies text.
- [HDialog](docs/components/dialog/llms.txt): A native modal dialog with focus containment, Escape dismissal, and focus return. Keep it inside your theme island.
- [HEmptyState](docs/components/empty-state/llms.txt): An inviting first-run or no-results state, with room for a useful next action.
- [HProgress](docs/components/progress/llms.txt): Native determinate or indeterminate progress, with percentage text and semantic colors.
- [HSkeleton](docs/components/skeleton/llms.txt): Text, rectangle, and circular loading placeholders with reduced-motion support.

## Foundation

- [HAvatar](docs/components/avatar/llms.txt): An image avatar with initials fallback and an optional decorative mode.
- [HBrand](docs/components/brand/llms.txt): A text wordmark with the signature accent. Use your own name, optional logo, and tagline.
- [HIcon](docs/components/icon/llms.txt): A small, consistent supporting icon set. Decorative by default; put the accessible label on its control.
- [HTheme](docs/components/theme/llms.txt): A scoped theme island. CSS variables flow through Vue trees, native slots, and shadow roots.

## Project references

- [Repository](https://github.com/samishal1998/hearth-ui): source and contribution workflows.
- [README](https://github.com/samishal1998/hearth-ui/blob/main/README.md): package setup and host integration.
- [Live catalog](https://samishal1998.github.io/hearth-ui/#components): interactive examples.
- [Theme studio](https://samishal1998.github.io/hearth-ui/#themes): visual token configuration.
- [Shared source types](https://github.com/samishal1998/hearth-ui/blob/main/src/themes.ts): types and theme helpers.

All local component links resolve in this repository and under the static site's base path. Source links point to main; use a matching tag when working with an older release.

---
Generated by `npm run docs:generate`. Update source/catalog/recipes instead of editing generated references.