DOCSEARCHbyAlgolia
Submit Docs

Fundamental Library for Angular

repository·main·Indexed 43 days ago

https://github.com/sap/fundamental-ngx

The official SAP-maintained Angular library for UI5 Web Components and the Fiori design system, providing over 1,000 components for Angular 22+.

Tokens
174.6K
Snippets
661
Records
1.1K
Agent score
55%

What's inside Fundamental NGX

  1. Overview of @fundamental-ngx/cdk capabilities

    main

    @fundamental-ngx/cdk is a set of utilities and Angular directives designed to help developers build custom UI components that follow common interaction patterns.

    Key features include:

    • DataSource abstractions: For managing data flow in components.
    • ControlValueAccessor helpers: To simplify integration with Angular Forms.
    • List utilities: For creating focusable and selectable lists.
    • Drag-and-drop directives: For implementing drag-and-drop functionality.
    • Other interaction patterns: Various utilities for common UI behaviors.

  2. Overview of Fundamental NGX packages

    main

    Fundamental NGX provides SAP Design System components for Angular through two main approaches:

    1. Native Angular components: Built using Fundamental Library Styles, these include core UI, platform-level composites, BTP, and CX patterns.
    2. Angular wrappers for UI5 Web Components: Provides type-safe Angular wrappers for @ui5/webcomponents, allowing use without CUSTOM_ELEMENTS_SCHEMA or NO_ERRORS_SCHEMA.

    Package Categories

    Core Libraries

    • @fundamental-ngx/core: Foundational UI components (buttons, forms, dialogs, tables, etc.).
    • @fundamental-ngx/platform: Higher-level composites with form integration and data binding.

    UI5 Web Components

    • @fundamental-ngx/ui5-webcomponents: Angular wrappers for standard UI5 Web Components.
    • @fundamental-ngx/ui5-webcomponents-fiori: Fiori-specific UI5 component wrappers.
    • @fundamental-ngx/ui5-webcomponents-ai: AI-specific UI5 component wrappers.

    Supporting Packages

    • @fundamental-ngx/cdk: Component Development Kit (DataSource patterns, ControlValueAccessor helpers, etc.).
    • @fundamental-ngx/i18n: Signal-based internationalization.
    • @fundamental-ngx/datetime-adapter: Date/time adapter using Day.js.
    • @fundamental-ngx/moment-adapter: Legacy Date/time adapter using Moment.js.

    Domain-Specific

    • @fundamental-ngx/btp: Business Technology Platform components.
    • @fundamental-ngx/cx: Customer Experience components.

    Developer Tooling

    • @fundamental-ngx/mcp: MCP server for AI coding assistants.
    • @fundamental-ngx/nx-plugin: NX generators and executors.

  3. New Components in v0.28.0-rc.x

    main

    The following components were introduced in the 0.28.0-rc release cycle:

    • Illustrated Message (@fundamental-ngx/core): Introduced in 0.28.0-rc.26.
    • Slider (@fundamental-ngx/platform): Introduced in 0.28.0-rc.23.
    • Select (@fundamental-ngx/platform): Introduced in 0.28.0-rc.17.
    • Text (@fundamental-ngx/core): Introduced in 0.28.0-rc.16.

  4. Use the i18n-manage Executor to manage translation keys

    main

    The i18n-manage executor is a CLI tool for managing translation keys across 37 language files in @fundamental-ngx/i18n. It works by reading .properties files and generating TypeScript files (translations_*.ts) for the build.

    Workflow Model:

    • Developers edit the English default file: libs/i18n/src/lib/translations/translations.properties.
    • Translation teams edit language-specific files (e.g., translations_de.properties).
    • The CLI synchronizes these sources into type-safe TypeScript files used by the application.
    nx run i18n:i18n-manage --command=<command> [options]

  5. Choose the correct library for your component

    main

    When adding a new component, select the appropriate library based on its purpose and required dependencies. Use the following mapping to determine the selector prefix and use case:

    LibrarySelector PrefixUse Case
    corefd-Standalone UI primitives (e.g., button, card, dialog, table)
    platformfdp-Higher-level composite components with form/data binding
    cdkfdk-Utility directives, services, or abstractions (no visible UI)
    btpfdb-Business Technology Platform-specific visual components
    cxfdx-Customer Experience-specific visual components

    Dependency Hierarchy:

    • cdk: Base layer (no dependencies).
    • core: May depend on cdk and i18n.
    • platform: May depend on core, cdk, and i18n.
    • btp / cx: May depend on core, platform, and cdk.

  6. How prerelease (rc) releases work

    main

    Prerelease (or rc) releases are created automatically after every merge into the main branch. The version is determined by conventional commits:

    • Current v1 stage behavior: BREAKING CHANGE increments the minor version; other changes increment the patch version.
    • Post-v1 behavior: BREAKING CHANGE increments the major version; other changes increment the minor or patch version.

    Example: If the latest release is 0.40.0 and you merge a fix commit, the next version is 0.40.1-rc.0. Subsequent merges increment the rc number (e.g., 0.40.1-rc.1) until a Stable release is triggered.

  8. How webc-generator works

    main

    The webc-generator is a code generator that produces Angular wrapper libraries from UI5 Web Components Custom Elements Manifests (CEM). It automates the creation of Angular components that wrap UI5 Web Components, mapping their properties, events, and slots to Angular-native primitives.

    Workflow:

    1. Input: Reads CEM JSON from @ui5/webcomponents, @ui5/webcomponents-fiori, or @ui5/webcomponents-ai.
    2. Processing: The executor.ts maps component metadata to:
      • input() signals for properties.
      • output() emitters for events.
      • Content-projection directives for slots.
    3. Output: Generates Angular component classes, type files, ng-package.json (for publishable sub-libraries), index.ts (public API barrel), shared CVA (Control Value Accessor) utilities, and theming service stubs.

    Important: The generated output is stored in libs/ui5-webcomponents* directories. These are auto-generated and must not be edited by hand.