@api-client/api-now-ui

A dedicated UI component library specifically designed to build the API Now application.

🎯 Purpose and Scope

This library strictly contains UIs that go directly into the API Now app.

• API Now Specific: Components here are tightly coupled to the API Now domain, business logic, and API data models. They are not intended to be agnostic.
• No Base Elements: Any general-purpose, primitive, or reusable design system element (buttons, inputs, dropdowns, abstract layouts, etc.) MUST NOT be created here. They must be built in the @api-client/base-ui library instead and imported into this workspace.
• No HTTP Client Specific UIs: Any UI components specific to making generic HTTP requests or dedicated to standard API client behaviors should be placed in @api-client/http-client-ui.

🛠️ Developer Experience (DX) & Workflow

We prioritize a smooth, consistent, and fast developer experience. Please adhere to the following standards when contributing to this library:

1. JSDoc Standards

Document properties and events only at the declaration site, never in the class header. We rely on the Custom Elements Manifest analyzer to pick these up.

• @attribute: Document the reflected HTML attribute (if any).
• @fires: Document custom events and the exact structure of their detail object.
• @slot: Document available shadow DOM slots and their purposes.
• @csspart / @cssproperty: Document style hooks (CSS Shadow Parts and Custom Properties).

2. Demo Pages (demo/)

Demos are critical for validating components in isolation before integrating them into the app.

• Bootstrap: Extend and use the shared DemoPage class to bootstrap your demo environments consistently.
• States: Render each distinct component state (e.g., empty, loading, error, populated) separately for clarity and visual regression testing.
• Imports: In demo TypeScript files, imports must reference the compiled output via /.tmp/demo/ for the build process, while internal src/ references remain direct.

3. Testing Protocol

We use @open-wc/testing to ensure component reliability. Every new feature or fix must include tests.

• Framework: Use @open-wc/testing coupled tightly with the Assert API (e.g., assert.isTrue(...), not expect(...)).
• Async Updates: Always await element.updateComplete after triggering property changes or user events before making assertions.
• Accessibility (a11y): Every component test suite must include an accessibility audit (await assert.isAccessible(element)).
• Test Runner: Execute tests using the Web Test Runner:

  npm run test
  # Or specifically:
  npx wtr [file-path] --playwright --browsers chromium

4. Code Generation & Scaffolding

If you need to scaffold a new Lit/MD3 component with internals, styles, and tests quickly, you can use the built-in workflow template guidelines (e.g., checking ui-templates.md for the standard element structure).

5. Local Development Server

Start the local development server (with live reloading capabilities) using:

npm run dev

This will run @web/dev-server serving the demo/ directory.

Happy coding!