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

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.

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

defineCustomElements();

After registration, use the components directly:

<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:

<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:

<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.

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

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:

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:

npm version patch --no-git-tag-version

Typical release flow:

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

If you are not logged in to npm yet:

npm login

License

MIT