@cobranza-apps/ui

Shared Angular component library & Minimal Yet Warm design system for the Cobranza App Company Back-office.

Table of Contents

• Overview
• Target Consumers
• Installation
• Quick Start
• Development Commands
• Component Inventory
• Design Tokens (Theme)
• Related Libraries
• Integration Notes (Shell ↔ MFE)
• Documentation
• Contributing & AI Agent Onboarding
• License

Overview

@cobranza-apps/ui is the shared visual foundation for the Company Back-office Shell and every MFE. It provides a single source of truth for the Minimal Yet Warm design system and removes duplicated UI effort.

What this library provides:

• Layout primitives — ModuleHeader and ModuleContainer for the floating workspace.
• Theme — Full Minimal Yet Warm design tokens (CSS variables + utility classes + optional SCSS mixins).
• Basic components — CbaButton, CbaCard, CbaBadge, CbaEmptyState, CbaSkeleton, CbaModal.
• Form controls — Thin wrappers around Bootstrap / ng-bootstrap inputs, selects, and datepickers.
• Icons — Font Awesome Free (solid + regular) via @fortawesome/angular-fontawesome.
• Spanish-only defaults — Library-owned UI copy (status text, aria-labels) is Spanish by default; no i18n framework. Override via inputs/projection.
• Directives — Lightweight helpers (e.g., autofocus, click-outside) when needed.

What this library is NOT:

• No business logic or domain entities.
• No BFF communication or backend calls.
• No advanced data tables (future dedicated component).
• No drag-and-drop (owned by the Shell).
• No workspace state or persistence (owned by the Shell).
• No mobile / responsive layouts (desktop-only for now).

Target Consumers

• Shell developers — host MFEs using ModuleHeader and ModuleContainer, import the encapsulated theme.
• MFE developers — import the theme and use basic components (CbaButton, CbaCard, etc.).
• End users — Back-office operators using the Shell-hosted interface (desktop-only).

Installation

npm install @cobranza-apps/ui

Install peer dependencies separately (jQuery is never required). Exact versions are declared in package.json; use these major ranges:

| Package | Purpose | | --- | --- | | @angular/core, @angular/common, @angular/forms | Angular runtime (v22, standalone) | | bootstrap | CSS-only framework (never jQuery) | | @ng-bootstrap/ng-bootstrap | Forms & overlays (v21) | | @fortawesome/angular-fontawesome | Icon rendering | | @fortawesome/free-solid-svg-icons, @fortawesome/free-regular-svg-icons | Icon packs (solid + regular) |

Install the major ranges declared in package.json peerDependencies: @angular/core@^22, @angular/common@^22, @angular/forms@^22, bootstrap@^5, @ng-bootstrap/ng-bootstrap@^21, plus the latest compatible @fortawesome/angular-fontawesome and icon packs.

Quick Start

1. Import the theme in your global styles file:

/* global-styles.scss */
@use '@cobranza-apps/ui/theme';

The theme is published as SCSS via the ./theme package subpath (see package.json exports). @use '@cobranza-apps/ui/theme' is the supported global import. Loading the theme emits the --cba-* variables on :root and the opt-in .cba-* utility classes.

2. Import components in your Angular standalone component or module:

import { ModuleHeaderComponent, ModuleContainerComponent, CbaButtonComponent } from '@cobranza-apps/ui';

3. Minimal module template — compose the workspace chrome around your MFE content:

<!-- my-module.component.html -->
<cba-module-container [size]="'50%'">
  <cba-module-header
    [title]="'Clientes'"
    [status]="'loaded'"
    (collapseToggle)="onCollapse($event)"
    (sizeToggle)="onSize($event)"
  />
  <div class="my-module-body">
    <!-- MFE / business content here -->
  </div>

  <!-- optional footer -->
  <cba-module-footer status="loaded">Listo</cba-module-footer>
</cba-module-container>

Minimal quick start with ModuleContainer + ModuleHeader + optional ModuleFooter.

For usage patterns and examples, see ./docs/USAGE.md.

Spanish-only UI defaults

Library-owned default on-screen strings — module footer status text, header action aria-labels/tooltips, modal close label, datepicker toggle label — are Spanish and centralized in CBA_UI_MESSAGES (exported from @cobranza-apps/ui). The platform is not multi-language: there is no i18n framework and no locale switching. Override defaults via component inputs (e.g., statusText) or content projection, never via a locale switcher.

Development Commands

| Command | Description | | --- | --- | | npm run build | Build the library via ng-packagr → outputs to dist/ | | npm test | Run Jest unit tests (--passWithNoTests) | | npm run lint | Lint src/**/*.ts with ESLint (angular-eslint) | | npm run format | Format source files with Prettier (TS, SCSS, CSS, JSON, MD) |

Regression test suite — src/theme/*.spec.ts guards theme integrity: token values, WCAG AA contrast, surface lightness gaps, preview HTML/CSS structure, and Consumer Guide section presence. Shared helpers live in src/components/testing/. Run all with npm test; run one with npm test -- src/theme/<name>.spec.ts.

Config files reference:

| File | Purpose | | --- | --- | | ng-package.json | ng-packagr entry point (src/public-api.ts) and output (dist/) | | tsconfig.json | Base TypeScript config (extended by lib and spec configs) | | tsconfig.lib.json | Library build config — partial compilation, declarations | | tsconfig.spec.json | Jest test config — CommonJS module, Jest types | | jest.config.js | Jest config with jest-preset-angular CJS preset | | setup-jest.ts | Angular Zone.js test environment bootstrap | | eslint.config.js | Flat ESLint config (angular-eslint recommended) | | .prettierrc.json | Prettier rules (100 char width, single quotes, LF) |

Component Inventory

| Component | Description | | --- | --- | | ModuleHeaderComponent | Shell-injected header above each MFE module (title, size, collapse, fullscreen, status). | | ModuleContainerComponent | Wraps ModuleHeader + MFE content; handles size, collapse, fullscreen, padding, scroll (with opt-in scroll chaining). | | CbaButton | Variants: primary, secondary, ghost, danger, success; sizes sm/md; loading; icon support; truncate (ellipsis label), iconOnly (square icon button), block (full-width). | | CbaCard | Optional header & footer; no forced hover elevation. | | CbaBadge | Semantic colours; solid/outline styles. | | CbaEmptyState | Slots: icon, title, description, primary action. | | CbaSkeleton | Variants: text, avatar, card, table-row, generic. | | CbaModal | Thin wrapper around ng-bootstrap modal. | | CbaDropdown | Thin wrapper around ng-bootstrap dropdown with themed menu surface. | | CbaPopover | Thin wrapper around ng-bootstrap popover with themed window surface. | | CbaTypeahead | Thin wrapper around ng-bootstrap typeahead with themed input and popup surface. | | CbaAccordion | Thin wrapper around ng-bootstrap accordion with themed surface and passthrough inputs/outputs. | | CbaModuleFooterComponent | Optional plain footer bar for a module; status text aligned with ModuleHeaderStatus plus a default projection slot. | | Form controls | Thin wrappers around ng-bootstrap/Bootstrap inputs, selects, datepickers. |

Full Input/Output contracts are in JSDoc and the project brief.

Design Tokens (Theme)

Design tokens are published as SCSS via @cobranza-apps/ui/theme and use the --cba- prefix:

• Backgrounds: primary, secondary, tertiary, elevated, overlay
• Text: primary, secondary, muted, inverse
• Borders: subtle, default, strong (three deliberately distinct levels)
• Accents: primary, success, warning, danger, info
• Interactive states: hover, active, focus-ring
• Selected state: selected-bg, selected-border, selected-text, selected-hover (selected ≠ active ≠ focus)
• Form states: invalid border/text, valid border/text, disabled bg/text
• Layout constants: header height, footer height, module header min-height
• Radius: sm (6px), md (10px), lg (14px)
• Shadows: module, elevated (applied only when not fullscreen; border is primary separator)
• Spacing scale: 4px–32px (--cba-space-1 through --cba-space-8)

Typography: Inter (system-ui fallback), base 14px, line-height 1.5, headings weight 500–600. Six-step typography scale (display / heading-lg / heading-md / body / small / caption) exposed as --cba-font-size-* + --cba-line-height-* tokens with .cba-text-* utility classes.

Utility classes (examples):

• .cba-bg-primary, .cba-bg-secondary, .cba-bg-tertiary
• .cba-text-primary, .cba-text-secondary, .cba-text-muted

For the full token reference, see brief.md §5 and the SCSS source files under src/theme/.

For a quick reference, see ./docs/THEME.md (surface hierarchy, border roles, selected state, form state matrix, typography scale, radius/shadow rules). For Shell/MFE integration patterns (selected state usage, table/nav patterns, semantic status), see ./docs/CONSUMER_GUIDE.md.

Related Libraries

| Library | Role | | --- | --- | | @cobranza-apps/ui | Visual components + theme (this library) | | @cobranza-apps/entities | Shared domain models (already on npm) | | @cobranza-apps/mfe-events | Typed event contracts Shell ↔ MFE (not yet published) |

Integration Notes (Shell ↔ MFE)

• The Shell uses ModuleHeader and ModuleContainer to host each remote MFE.
• Each MFE imports the theme and may use basic components.
• Resize / collapse / fullscreen state:
  • Shell → MFE via component @Input() bindings.
  • MFE → Shell via custom events defined in @cobranza-apps/mfe-events.
• This library emits only pure UI events from ModuleHeader (collapseToggle, sizeToggle, remove, fullscreenToggle). It never dispatches workspace or routing events.
• Drag-and-drop is not part of this library — it is owned by the Shell and mfe-events.
• Surface hierarchy and token usage are shared contracts — Shell, Lib, and MFE each own specific surfaces (canvas / panel / elevated / inset). Follow the Consumer Guide for the token compliance mandate, exact token mappings for buttons, surfaces, text, and chrome.

Documentation

• ./docs/INDEX.md — Index of all library documentation pages.
• ./docs/USAGE.md — Patterns and examples for consuming the library.
• ./docs/THEME.md — Theme import, tokens, and utility classes.
• ./docs/CONSUMER_GUIDE.md — Shell & MFE integration rules: token compliance mandate, theme load (once), surface ownership map, button color guide, surface decision tree, text color rules, bar/chrome guide, checklists, anti-patterns, quick verify.
• ./docs/CBA_MODULE_HEADER.md — ModuleHeader selector, API, status values, fullscreen & drag notes.
• ./docs/CBA_MODULE_CONTAINER.md — ModuleContainer selector, API, size/collapse/fullscreen/padding behaviour, scroll & chrome notes.
• ./docs/CBA_BUTTON.md — CbaButton selector, API, variant mapping, size options, loading/disabled behaviour.
• ./docs/CBA_CARD.md — CbaCard selector, content projection slots, layout examples.
• ./docs/CBA_BADGE.md — CbaBadge selector, API, variant colours, solid vs outline.
• ./docs/CBA_EMPTY_STATE.md — CbaEmptyState selector, content projection slots, usage example.
• ./docs/CBA_SKELETON.md — CbaSkeleton selector, API, variant descriptions, usage examples.
• ./docs/CBA_MODAL.md — CbaModal selector, API, CbaModalService + options, sizes, dismiss reasons, theming.
• ./docs/CBA_INPUT.md — CbaInput selector, API, control types, ControlValueAccessor, label/hint/error, theming.
• ./docs/CBA_SELECT.md — CbaSelect selector, API, projected options, ControlValueAccessor, theming.
• ./docs/CBA_DATEPICKER.md — CbaDatepicker selector, API, ng-bootstrap NgbInputDateadapter notes, aria toggle label, theming.
• ./docs/CBA_DROPDOWN.md — CbaDropdown selector, API, projection slots, theming, ng-bootstrap behavior notes.
• ./docs/CBA_POPOVER.md — CbaPopover selector, API, projection slots, theming, ng-bootstrap behavior notes.
• ./docs/CBA_TYPEAHEAD.md — CbaTypeahead selector, API, search function, formatters, theming, ng-bootstrap behavior notes.
• ./docs/CBA_ACCORDION.md — CbaAccordion selector, API, projection API, theming, ng-bootstrap behavior notes.
• ./docs/CBA_MODULE_FOOTER.md — CbaModuleFooter selector, API, status text mapping, usage examples, theming notes.
• Internal architecture: ./docs/CBA_FORM_FIELD.md — shared CbaField layout + CbaControlValueAccessor used by Input/Select/Datepicker. Not part of the public API.
• Project brief — Source of truth for scope, design tokens, and component contracts.
• Product info — Product goals, target consumers, UX focus.
• Architecture — Build strategy, folder layout, integration patterns.
• Tech stack — Exact versions, dependencies, tooling constraints.
• JSDoc on every public @Input(), @Output(), and component class.
• ./docs/theme-preview.html — Live theme preview: minimizable sidebar, Shell mockup, 7 module examples (100%/50%, expanded/collapsed), 31 color-token swatches, button state matrix, labels & pills, icon list, text-on-surfaces, typography scale, border scale, selected states, form states, semantic status badges. Regenerate with npm run build:preview.
• ./CHANGELOG.md — Notable changes per release (Keep a Changelog format).

Contributing & AI Agent Onboarding

Review AGENTS.md and the project info files under .agent/project-info/ before making changes.

License

License: Proprietary — © . See LICENSE.

TODO: Confirm license terms with the maintainer. This is a placeholder until a LICENSE file is added.