# Web Components Guidelines

These components are built as Vue custom elements and loaded via the single `dist-web-components/web-components.es.js` bundle.

## Design Principles

- Keep components small. Move non-trivial logic into composables/services.
- Avoid cross-dependencies on mini-apps. Shared utilities live under the web-component folder.
- Prefer explicit DOM events (`CustomEvent`) for communication between web components.
- Use `rc-` prefixed custom element names only.

## Structure

- `rc-<name>/` — one component per folder.
- `shared/` — shared types and utilities used across web components.
- `index.ts` — registers all web components.

## Styling

- Keep styles isolated per component.
- Prefer dedicated CSS files for large style blocks (use `<style src="...">`).
- Do not rely on Bootstrap or external styles; Shadow DOM components must be self-styled.

## Events & API

- Emit DOM `CustomEvent` with `bubbles: true` and `composed: true` when a parent component needs to react.
- For form integration, use form-associated custom elements and set form values with `ElementInternals`.
- Expose `open()` / `close()` methods on modal-like components using `defineExpose`.

## Build & Dev

- Build: `yarn build:web-components`
- Dev server: `yarn dev:web-components`
- Always rebuild the bundle when testing in REDCap pages.
- Run `npm run typecheck` during development to catch TypeScript errors early.
