npm package: @glaux-group/civetta-components
Description: Reusable Web Components for the Glaux Group design system, built with Stencil.
Latest version: 0.0.10

[![npm version](https://img.shields.io/npm/v/@glaux-group/civetta-components?style=flat-square)](https://www.npmjs.com/package/@glaux-group/civetta-components)
[![license](https://img.shields.io/npm/l/@glaux-group/civetta-components?style=flat-square)](https://github.com/wenish/glaux-group-design-system/blob/main/LICENSE)
[![Built With Stencil](https://img.shields.io/badge/-Built%20With%20Stencil-16161d.svg?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPCEtLSBHZW5lcmF0b3I6IEFkb2JlIElsbHVzdHJhdG9yIDE5LjIuMSwgU1ZHIEV4cG9ydCBQbHVnLUluIC4gU1ZHIFZlcnNpb246IDYuMDAgQnVpbGQgMCkgIC0tPgo8c3ZnIHZlcnNpb249IjEuMSIgaWQ9IkxheWVyXzEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHg9IjBweCIgeT0iMHB4IgoJIHZpZXdCb3g9IjAgMCA1MTIgNTEyIiBzdHlsZT0iZW5hYmxlLWJhY2tncm91bmQ6bmV3IDAgMCA1MTIgNTEyOyIgeG1sOnNwYWNlPSJwcmVzZXJ2ZSI%2BCjxzdHlsZSB0eXBlPSJ0ZXh0L2NzcyI%2BCgkuc3Qwe2ZpbGw6I0ZGRkZGRjt9Cjwvc3R5bGU%2BCjxwYXRoIGNsYXNzPSJzdDAiIGQ9Ik00MjQuNywzNzMuOWMwLDM3LjYtNTUuMSw2OC42LTkyLjcsNjguNkgxODAuNGMtMzcuOSwwLTkyLjctMzAuNy05Mi43LTY4LjZ2LTMuNmgzMzYuOVYzNzMuOXoiLz4KPHBhdGggY2xhc3M9InN0MCIgZD0iTTQyNC43LDI5Mi4xSDE4MC40Yy0zNy42LDAtOTIuNy0zMS05Mi43LTY4LjZ2LTMuNkgzMzJjMzcuNiwwLDkyLjcsMzEsOTIuNyw2OC42VjI5Mi4xeiIvPgo8cGF0aCBjbGFzcz0ic3QwIiBkPSJNNDI0LjcsMTQxLjdIODcuN3YtMy42YzAtMzcuNiw1NC44LTY4LjYsOTIuNy02OC42SDMzMmMzNy45LDAsOTIuNywzMC43LDkyLjcsNjguNlYxNDEuN3oiLz4KPC9zdmc%2BCg%3D%3D&colorA=16161d&style=flat-square)](https://stenciljs.com)

# Civetta Components

Reusable Web Components for the Glaux Group design system.

`@glaux-group/civetta-components` is a Stencil-based component library published as standards-based custom elements. It is designed for teams that want a single UI package that works in plain HTML, React, Vue, Angular, or any other framework that can render custom elements.

## Why use this package

- Framework-agnostic custom elements with the `glx-` prefix
- Multiple distribution options for different integration needs
- Encapsulated component styling shipped with the package
- Storybook-backed development workflow for contributors
- Published TypeScript definitions for better editor support

## Component catalog

The current library includes components across the following groups:

- Actions: `glx-button-primary`, `glx-button-secondary`, `glx-button-ghost`, `glx-button-danger`, `glx-button-icon`
- Feedback and overlays: `glx-alert`, `glx-badge`, `glx-spinner`, `glx-tooltip`, `glx-modal`, `glx-modal-sidebar-chat`
- Navigation and layout: `glx-accordion`, `glx-breadcrumbs`, `glx-footer-simple`, `glx-header`, `glx-header-dropdown`, `glx-pagination`, `glx-tabs`
- Forms: `glx-input-checkbox`, `glx-input-number`, `glx-input-radio`, `glx-input-search`, `glx-input-select-single`, `glx-input-text`, `glx-input-textarea`, `glx-input-toggle`
- Content and data display: `glx-card`, `glx-chat-ml`, `glx-table`

For the authoritative API surface, inspect the published custom element definitions or the generated `custom-elements.json` file in the repository.

## Installation

```bash
npm install @glaux-group/civetta-components
```

## Usage

### Recommended: register components with the loader

For most applications, register the library once near your app entry point and then use the custom elements anywhere in your markup.

```ts
import { defineCustomElements } from '@glaux-group/civetta-components/loader';

defineCustomElements();
```

After registration, use the components directly:

```html
<glx-button-primary>Save changes</glx-button-primary>
<glx-alert variant="info">Update available</glx-alert>
```

This approach uses Stencil's lazy-loading runtime so the browser only loads the component code it needs.

### Direct browser usage via CDN

If you want to use the package without a bundler, load the published ESM entry from a CDN:

```html
<script type="module" src="https://unpkg.com/@glaux-group/civetta-components"></script>

<glx-button-primary>Save changes</glx-button-primary>
```

If you want to pin a specific version, point directly to the published file:

```html
<script
  type="module"
  src="https://unpkg.com/@glaux-group/civetta-components@<version>/dist/civetta-components/civetta-components.esm.js"
></script>
```

### Pre-bundled entry

The package also ships a single bundled ESM entry and a matching CSS file for integrations that prefer a single import instead of Stencil's chunked runtime output.

```ts
import '@glaux-group/civetta-components/bundle';
import '@glaux-group/civetta-components/bundle.css';
```

This is useful when your build or deployment setup prefers a monolithic asset rather than lazy-loaded chunks.

## Framework notes

- React, Vue, Angular, and vanilla JavaScript can all consume the package because the output is based on native custom elements.
- Register the components once on the client before first render.
- Framework-specific wrapper components are not included in this package.
- If your app uses a strict Content Security Policy, the Stencil loader also exposes `setNonce()`.

## Package contents

The npm package publishes the following relevant entry points:

- Root entry: `@glaux-group/civetta-components` for shared utilities and generated types
- Loader entry: `@glaux-group/civetta-components/loader`
- Bundle entry: `@glaux-group/civetta-components/bundle`
- Bundle stylesheet: `@glaux-group/civetta-components/bundle.css`
- Individual component modules via package subpath exports

To render components in an application, use the loader or bundle entry. Importing the root package alone does not register custom elements.

## Contributing

### Prerequisites

- Node.js
- npm

### Local setup

```bash
npm ci
npm start
```

`npm start` runs the Stencil dev build in watch mode and serves the demo app for local development.

### Useful commands

| Command | Purpose |
| --- | --- |
| `npm start` | Run Stencil in watch mode with a local dev server |
| `npm run build` | Build the distributable package and generate the bundled ESM + CSS output |
| `npm test` | Run unit and end-to-end tests |
| `npm run test.watch` | Run tests in watch mode |
| `npm run storybook` | Build the components and start Storybook locally |
| `npm run storybook:build` | Create a static Storybook build |
| `npm run preview` | Preview the static Storybook output |
| `npm run generate` | Scaffold a new Stencil component |

### Development workflow

1. Create or update the component under `src/components`.
2. Add or update the matching Storybook story in the same component directory.
3. Run `npm test` for behavioral changes.
4. Run `npm run build` before opening a PR to verify the published outputs still compile.

### Project structure

- `src/components`: component source code and local stories
- `src/global`: shared global styles
- `src/stories`: documentation pages used by Storybook
- `scripts/build-single-file.mjs`: bundle generation script for the single-file ESM output
- `loader`: generated loader entry exposed to consumers

### Contribution expectations

- Keep public APIs consistent with the `glx-` naming scheme.
- Prefer changes that remain framework-agnostic.
- Update stories and documentation whenever behavior or props change.
- Keep changes focused and avoid unrelated refactors in the same PR.

## Publishing

This package is published as `@glaux-group/civetta-components`.

To bump the package version before publishing, use one of the following:

```bash
npm version patch
npm version minor
npm version major
```

`npm version` updates `package.json` and, by default, also creates a Git commit and tag. If you only want to change the version locally without creating a tag yet, use:

```bash
npm version patch --no-git-tag-version
```

Typical release flow:

```bash
npm version patch
npm run build
npm pack --dry-run
npm publish --access public
```

If you are not logged in to npm yet:

```bash
npm login
```

## License

MIT