name	opal-frontend-common-ui-lib-repo-guidelines
description	Repository structure, build/test commands, coding style, and contribution rules for opal-frontend-common-ui-lib. Use when navigating the repo, running or debugging builds/lint/tests, or following style conventions.

Opal Frontend Common UI Lib Repo Guidelines

Overview

Use these rules to keep work aligned with opal-frontend-common-ui-lib structure, tooling, and contribution expectations.

Project Structure & Module Organization

This repository hosts the Angular library opal-frontend-common. Source code lives under projects/opal-frontend-common, organized into feature folders such as components, services, pipes, and stores.
Shared styles are stored in projects/opal-frontend-common/styles.
projects/opal-frontend-common/public-api.ts governs which symbols are exported.
Build artifacts land in dist/opal-frontend-common; clean it before publishing changes.

Build, Test, and Development Commands

Use Yarn for all tasks.
yarn start serves the example harness via the Angular dev server for local smoke tests.
yarn watch rebuilds the library in development watch mode.
yarn build runs yarn clean, builds the production bundle, and copies README.md and LICENSE into dist/.
yarn test runs the Vitest-based unit test suite once (Angular 21 unit-test builder).
yarn test:coverage runs tests with coverage reporting via Vitest (output in coverage/).
yarn lint runs Prettier checks followed by Angular ESLint; apply yarn prettier:fix to reformat automatically.
yarn exports:check validates that source exports and tsconfig path aliases are synchronized.
yarn pack:check validates publish tarball shape and export target presence via npm pack --dry-run.
yarn pack:local builds and creates a root-level local .tgz package for consumer app testing.

Coding Style & Naming Conventions

Respect .editorconfig (UTF-8, spaces, 2-space indent).
Prettier enforces 120-character lines, single quotes, and semicolons.
Angular ESLint rules require component selectors to use the opal-lib- prefix (kebab-case) and directives to use opalLib (camelCase).
Keep the public surface curated through public-api.ts, and follow member ordering enforced by ESLint when adding class fields or methods.

Testing Guidelines

Author Vitest unit tests beside their subjects using the *.spec.ts suffix.
Run yarn test:coverage before raising PRs and review Vitest coverage reports to protect shared utilities, guards, and interceptors.
For complex features, add harness components within components/*/testing folders to exercise interactions end-to-end.

Design System References

Commit & Pull Request Guidelines

Use succinct, descriptive commit subjects (e.g., chore(deps): update angular-cli monorepo to v20.3.5, PO-2278).
Mirror that structure and include ticket IDs where applicable.
Keep commits focused and avoid bundling unrelated refactors.
PRs should summarize intent, document testing performed, flag breaking API changes, and attach screenshots or GIFs for UI tweaks.
Link Jira or GitHub issues and notify dependent teams if exports or selectors change.

Opal Frontend Common UI Lib Repo Guidelines

Overview

Use these rules to keep work aligned with opal-frontend-common-ui-lib structure, tooling, and contribution expectations.

Project Structure & Module Organization

This repository hosts the Angular library opal-frontend-common. Source code lives under projects/opal-frontend-common, organized into feature folders such as components, services, pipes, and stores.

Shared styles are stored in projects/opal-frontend-common/styles.

projects/opal-frontend-common/public-api.ts governs which symbols are exported.

Build artifacts land in dist/opal-frontend-common; clean it before publishing changes.

Build, Test, and Development Commands

Use Yarn for all tasks.

yarn start serves the example harness via the Angular dev server for local smoke tests.

yarn watch rebuilds the library in development watch mode.

yarn build runs yarn clean, builds the production bundle, and copies README.md and LICENSE into dist/.

yarn test runs the Vitest-based unit test suite once (Angular 21 unit-test builder).

yarn test:coverage runs tests with coverage reporting via Vitest (output in coverage/).

yarn lint runs Prettier checks followed by Angular ESLint; apply yarn prettier:fix to reformat automatically.

yarn exports:check validates that source exports and tsconfig path aliases are synchronized.

yarn pack:check validates publish tarball shape and export target presence via npm pack --dry-run.

yarn pack:local builds and creates a root-level local .tgz package for consumer app testing.

Coding Style & Naming Conventions

Respect .editorconfig (UTF-8, spaces, 2-space indent).

Prettier enforces 120-character lines, single quotes, and semicolons.

Angular ESLint rules require component selectors to use the opal-lib- prefix (kebab-case) and directives to use opalLib (camelCase).

Keep the public surface curated through public-api.ts, and follow member ordering enforced by ESLint when adding class fields or methods.

Testing Guidelines

Author Vitest unit tests beside their subjects using the *.spec.ts suffix.

Run yarn test:coverage before raising PRs and review Vitest coverage reports to protect shared utilities, guards, and interceptors.

For complex features, add harness components within components/*/testing folders to exercise interactions end-to-end.

Design System References

Commit & Pull Request Guidelines

Use succinct, descriptive commit subjects (e.g., chore(deps): update angular-cli monorepo to v20.3.5, PO-2278).

Mirror that structure and include ticket IDs where applicable.

Keep commits focused and avoid bundling unrelated refactors.

PRs should summarize intent, document testing performed, flag breaking API changes, and attach screenshots or GIFs for UI tweaks.

Link Jira or GitHub issues and notify dependent teams if exports or selectors change.

opal-frontend-common-ui-lib-repo-guidelines