@api-client/base-ui

The foundational web components and UI framework library for the API Cloud ecosystem.

This package provides the building blocks for creating consistent, accessible, and beautiful interfaces across all API Cloud applications, powered by Lit.

What's Included

• Material 3 Components: A comprehensive suite of base components implementing the Material Design 3 specifications.
• Ecosystem Base Components: Reusable, high-level components specifically tailored for the API Cloud ecosystem (e.g., code editors, navigation menus).
• Core UI Framework: Essential frontend logic, reactive data mixins, routing utilities, and global styling systems required to bootstrap new applications.

🛑 Important Note to Developers

This library is strictly for general-purpose UI and foundational frontend logic.

• DO NOT include any application-specific components, business logic, or domain models here.
• If a component relies on a specific API endpoint, database schema, or app-specific state, it belongs in the consuming application, not in base-ui.
• All components should be generic, reusable, and driven entirely by attributes, properties, and events.

Getting Started

Installation

npm install @api-client/base-ui

Usage

Import the components you need directly from the package:

import '@api-client/base-ui/elements/code-editor/CodeEditor.js'
import '@api-client/base-ui/md/buttons/button.js'

Developer Experience (DX)

We've optimized the local development environment for maximum speed and instant feedback.

Running the Dev Server Workspace

To start developing components locally, run the dev server:

npm run dev

This spins up @web/dev-server with native esbuild integration at http://localhost:8000/demo/.

• No Build Steps: TypeScript is compiled natively on-the-fly in memory.
• HMR: Any changes made to src/**/*.ts or demo/**/*.html will instantly reflect in the browser without needing a compilation watcher like tsc --watch.

Component Demos

Every component should have a corresponding demo page. When you create a new component, add an index.html file in the demo/ directory.

Because we use esbuild, you can import your TypeScript source files directly into your demo HTML:

<script type="module" src="./index.ts"></script>

Testing

Tests are written using @open-wc/testing and run via Web Test Runner (WTR) using Playwright Chromium. Tests also run on-the-fly without needing a build step.

To run the test suite once:

npm run test

To run tests in watch mode (ideal when actively writing a component):

npm run test:watch

Analyzing Custom Elements

This project uses @custom-elements-manifest/analyzer to automatically document all custom elements. This manifest is included in the production build for IDE integrations and downstream consumers.

To manually generate the manifest:

npm run build:ce

Production Build

To build the library for publishing, run:

npm run build

This command uses a strict tsconfig.build.json to ensure that only the src/ directory (and its generated custom-elements.json manifest) is compiled into the final build/ output, safely ignoring all tests and demos.