Software Division Components

Overview

The Software Division Components library is a wrapper around the SpartanNG component library. It enhances SpartanNG components by providing additional functionality tailored to the common requirements of applications developed within the Software Division department. It also uses Angular for application development and Storybook for interactive component documentation and testing.

Migrate from v1 to v2

The v2 introduces multiple entrypoints to ensure tree-shaking and other optimizations to reduce bundle size. Here is a detailed guide for migrating from v1 to v2

Installation

Refer to the dedicated docs page

Host global CSS: The app must own one Tailwind v4 pipeline in its root stylesheet. Import @angular/cdk/overlay-prebuilt.css, @spartan-ng/brain/hlm-tailwind-preset.css, and add @source paths that cover both your app and @3ddv/software-division-components (published builds often need fesm2022/**/*.mjs in addition to HTML/TS). The library’s styles.css does not @import 'tailwindcss' on purpose; duplicating Tailwind there breaks Spartan utilities and theming. A worked example lives in Group Sales src/styles.css; full steps are in the installation guide.

Development

Conventions

Refer to the dedicated docs page

Development Workflows

1. Storybook Development (Recommended)

Use Storybook for isolated component development and testing:

pnpm storybook

2. Consumer App Integration Testing

Use the consumer app for integration testing of components in a real application context. Each component should have its own route for testing.

Setup requires two terminals:

Terminal 1 - Build Library:

pnpm run build:watch

Watches for changes in the SDC library and rebuilds to the dist/ folder.

Terminal 2 - Watch and Restart Consumer App:

pnpm run start:watch

Watches the dist/ folder and automatically restarts the consumer app when library changes are detected.

Note: The consumer app uses file:dist to link the SDC library locally, allowing real-time testing of library changes.

Note: This workflow was implemented because we couldn't find a better way to automatically update the library dependencies in the dev server. The current approach ensures fresh dependencies are loaded with each restart.

Reporting issues

Note: This is a temporary workflow for reporting issues. As the usage of the library increases, we will reassess and scale the issue reporting system accordingly.

To report an issue, please visit the following ticket and create a Bug ticket. Ensure that your report includes a clear and detailed description of the issue you are encountering..

Project summary

The source folder of this project contains multiple subfolders. Below are the most important ones:

• Backoffice This folder contains components that are exclusive to the backoffice setting, such as tables or sidebars. These components do not receive any styling from the theme class passed on initialization (be it generic or backoffice).

  Some components from the Generic folder can also be used in the backoffice, but in such cases, the backoffice theme must be passed to the library provider. This ensures that no additional styles are applied, keeping the default SpartanNG design intact.

• DVM This folder includes components specific to applications that use DVM. Many of these components share both style and functionality, and this module is designed to maximize reusability. Examples include the section navigator buttons and the minimap.

• Generic This folder contains components which can be used in any setting. The appearance of these components relies heavily on the parameter that is passed to the library provider (generic or backoffice).

• Shared This folder contains initialization methods, directives and shared utilities, which are exposed to the library API, like methods to aid with the usage of the library or debugging of the library.

• Utils This folder contains internal tools which can also be shared across the library, but this is more directed to functions used by the developer to streamline processes and reuse common logic.

Common library errors

❌ Error: Invalid CSS class string found on ...

This indicates that the stylesClasses input that you provided to the component does not have a valid format.

✅ Solution: Ensure that the value assigned to styleClasses follows the correct format as documented in the respective component's guidelines.

If the issue persists, refer to the documentation or check for any unintended modifications in the styleClasses input.

Any future errors will be documented here

How to use the library from the consuming application

Importing the library

Providing the library to the application

import { ApplicationConfig } from '@angular/core';
import { provideSdc } from '@3ddv/software-division-components';

export const appConfig: ApplicationConfig = {
  // this provides the consuming app with all necessary modules
  // to make it work
  providers: [provideSdc({ theme: 'generic' })],
};

Import from main entry

import { TableComponent, ButtonComponent } from '@3ddv/software-division-components';

Import from secondary entry

import { ButtonComponent } from '@3ddv/software-division-components/generic/button';

Theming and styling

This library is a wrapper to an already existing component library (SpartanNG), which means that there are some styles that are already present in all the exported components. These styles are kept intact whenever the backoffice theme parameter is passed to the provideSdc method. You also have the option of passing the generic parameter, which in turn makes the component align to the design that several ticketing applications share. If no parameter is passed, the generic is assigned as a fallback option. You can check that design here, here and here.

Styling components consist of passing down CSS classes that consist of SpartanNG variables. Go by as if you were styling a common HTML element. Every component has a styleClasses input which accepts a single or several whitespace-separated CSS class/classes declared within the using application. To see the variables that each component has, please check the official PrimeNG documentation per each component. Here you can see an example for the button component. The column Variable includes every single class that you can use within the your CSS classes which you will later pass into the library button to style it. The result looks as follows:

.my-class {
  --p-button-primary-background: red;
}

<sdc-button styleClasses="my-class"></sdc-button>

Specifity issues

If you are facing any specifity problems, each component also has an ID reference so you can later add them on your styles composition, giving advantage to the specifity algorithm to prioritize your styles:

#sdc-button.my-class {
  --p-button-primary-background: red;
}

Encapsulation issues

Most of the time you will be declaring your styles with a CSS file declared within the component scope (my-component.component.css) and later import it with styleUrl or stylesUrl in your component. In that scenario, you will be dealing with the default component View Encapsulation setting, which does not allow a parent component to apply styles to the child component. This brings a problem when it comes to passing down CSS classes to the library components. Following similar practices from other component librariess, we bring the option to bypass View Encapsulation for a certain CSS class by declaring your classes with a pseudo-class selector:

Depending on the Encapsulation option that you are using in your component, some styles will not apply. In that scenario, declare the style as follows:

::ng-deep.my-class {
  --p-button-primary-background: red;
}

You also have the option with SCSS to nest:

::ng-deep {
  &.my-class-1 {
    --p-button-primary-background: red;
  }
  &.my-class-2 {
    --p-button-primary-background: green;
  }

  &.my-class-3 {
    --p-button-primary-background: blue;
  }
}

Or declare the style in your root stylesheet to avoid any view encapsulation to affect your custom styles. (not recommended)

Several styleClasses inputs

Some components are composed of several underlying components, so a single styleClass input will not be enough. For those scenarios, some components require the styleClasses paramater to be composed of an object, with each key targetting different parts of the component:

<sdc-neighbours
  [currentSection]="..."
  [sectionsMmcToTdc]="..."
  [neigboursData]="..."
  [styleClasses]=`{
    sideButtonsClass: 'mock-side-button',
    middleDivClass: 'mock-middle-div'
  }`
></sdc-neighbours>

With this method, we are able to apply certain styles for the buttons on the sides ( with sideButtonsClass) and a different one for the div on the middle of the component template (with middleDivClass).

Styles will pierce through the SpartanNG layer and directly style the underlying HTML element. If you are facing any problem styling any component, please check the official PrimeNG documentation on theming or the individual webpage for styling each component as in this example for the button component.

What if I'm using Tailwind in my application?

Tailwind does reset most of the styles that any other third party app is applying, so SpartanNG styles will be overriden. In that scenario, the component library exposes several layers to scope this overriding as much as posible. If you are using Tailwind, declare the Tailwind reset as follows in your root stylesheet:

@layer tailwind-base {
  @tailwind base;
  @tailwind components;
}

@tailwind utilities;

Passing inputs to components that have a lot of props

Besides all the documented inputs that components have, some components also have the option to pass all components in an object to end up with a more concise template markup, instead of using individual bindings.

The components that provide this functionality are usually the ones that have a more direct representation within SpartanNG, as this is intended to solve the polution that the library creates due to it having so many inputs. An example would be the ButtonComponent.

This is the old markup:

<sdc-button
  type="button"
  label="Hover to trigger"
  ariaLabel="Hover to trigger"
  tooltip="You triggered the tooltip"
  tooltipPos="right"
  severity="primary"
  styleClasses="tooltip-padding" />

And this is the example with the configuration object:

import { ButtonProps } from '@3ddv/software-division-components';

class MyComponent {
  // You can of course declare, this where it better suits your use case
  protected props = {
    type: 'button',
    label: 'Hover to trigger',
    ariaLabel: 'Hover to trigger',
    severity: 'primary',
    tooltip: 'You triggered the tooltip',
    tooltipPos: 'right',
    styleClasses: 'tooltip-padding',
  } satisfies ButtonProps;
}

And the resulting HTML:

<sdc-button [props]="{props}" />

How to collaborate to the library as a developer

Semantic versioning

This project follows semantic versioning. We release patch versions for critical bugfixes, minor versions for new features or non-essential changes, and major versions for any breaking changes. When we make breaking changes, we also introduce deprecation warnings in a minor version so that our developer colleagues learn about the upcoming changes and get to know to not work on top of that deprecated code.

Refer to the official manifesto for any further information.

Releasing a new version

Refer to the dedicated release guide for detailed instructions on how to publish a new version of the library to npm.

Conventional commits

For managing our commit history and versioning, we follow the Conventional Commits specification. This structured format for commit messages enables us to handle our release process, making it clear when a commit introduces new features, fixes bugs, or includes breaking changes.

Refer to the official documentation for any further information.

Commit hooks

To ensure commit messages follow this format, Husky and Commitlint are used:

• Husky sets up a Git hook that runs on every commit.
• Commitlint checks the commit message during the commit-msg hook.

If the commit message does not adhere to the Conventional Commits format, Commitlint rejects the commit and displays an error with details on what needs to be fixed.

Development workflow steps

• Make sure you have the latest master remote changes on your local master branch

• If no release branch is created, create one checking which version is the next one to be developed on, if there is an ongoing release branch , create a branch following the official Conventional Commits guidelines.

• Make sure to develop on small commits which also follow the Conventional Commits guidelines.

• When you are done developing in your branch, create a pull request to the desired branch and await for any approval you might need.

Code that lands in the master branch must be compatible with the latest stable release, able to compile and functional. It may contain additional features, but no breaking changes unless a new major version bump is released. We should be able to release a new minor version from the tip of master branch at any time.

• Merge the branch, navigate to the destination branch and pull the changes from the remote branch.

• Rinse and repeat.

Documenting component files

When documenting your code changes, we use JSDoc to ensure that all JavaScript functions and components are described comprehensively. This helps maintain clarity and understandability throughout the codebase.

We also declare the accessibility scope, parameter types and return types of any function declared.

/**
 * A customizable button component built on SpartanNg Button component.
 *
 * This component supports various configurations, such as tooltips, badge values,
 * and theme styles. It uses the `ThemeProviderDirective` to apply theming dynamically.
 *
 * @class ButtonComponent
 * @extends {Button}
 */
@Component({
  standalone: true,
  selector: 'sdc-button',
  styleUrls: ['./button.component.css'],
  templateUrl: './button.component.html',
})
export class ButtonComponent extends Button {
  /**
   * Tooltip text for the button.
   */
  public tooltip = input<string>('');

  /**
   * Handles the click event for the button with debounce logic.
   *
   * This method prevents multiple rapid clicks by disabling the button
   * for the specified debounce time. If `debounceTime` is set to 0,
   * the button remains interactive without debounce behavior.
   *
   * @param event - The click event triggered by the user.
   */
  public handleClick(event: MouseEvent): void {
    // Implementation should document any steps that cannot be easily explained
    // with variable names. Another scenario on why you would add comments includes documenting why things
    // are done the way they are done (there might be some framework or language limitation).
  }
}

Internally overriding SpartanNG styles with component scope

First of all, we would like to clarify that this is a different feature from the previously mentioned styleClasses feature. Style classes are thought of as a styling interface for the users of the library. This feature is to be used for developers working on component development and wanting to override any styles of PrimeNG components, so custom components adhere to the styling required.

In some cases, specially if we are developing a component placed within the generic scope, we will need to override any required native styles from PrimeNG to be able to adhere to the design provided by our design team.

PrimeNG provides us with a tool called Design Tokens, which consists of a CSS-in-JS solution that composes a nested object which targets several styles of each component. Here is an example corresponding to the Neighbours component:

// Import types from PrimeNG module
import { ButtonDesignTokens } from '@primeng/themes/types/button';

// Create an export an object which will later by used in neighbours.components.ts
export const sideButtonTokens = {
  root: {
    primary: {
      // Overwrite the theme  variables with PrimeNG existing variables
      // Button text
      color: '',
      borderColor: '{zinc.50}',
      hoverColor: '',
      activeColor: '',
      // Button background
      background: '{zinc.50}',
      hoverBackground: '{zinc.50}',
      activeBackground: '{zinc.50}',
      // Button border
      activeBorderColor: '{zinc.50}',
      hoverBorderColor: '{zinc.50}',
    },
  },
} satisfies ButtonDesignTokens;

And we pass in the styles within the component template

import { sideButtonTokens } from './styles/side-button.tokens';
....
export class NeighboursComponent {
  ...
    protected readonly sideButtonStyle = sideButtonTokens;
  ...
}

Template example:

<!-- [dt] is a default input which is present in all components to declare PrimeNG design tokens -->
<sdc-button [dt]="sideButtonStyle" />

This way, we accomplished adhering to the styling that this component needed, which brings this result:

Styling native HTML elements

For styling native HTML elements in our project, we adhere to the Block-Element-Modifier (BEM) methodology. This ensures that our styles remain modular, maintainable, and predictable.

Guidelines for Using BEM

• Use BEM for anything that is not a design token.

  • Design tokens (e.g., colors, typography, spacing) should be handled via variables, custom properties, or a design system, not through BEM class names.

• Use design tokens for everything that involves styling a native PrimeNG component.

  • PrimeNG components already use design tokens, so we must align with them instead of defining custom BEM classes.

• Native HTML elements must always be styled using BEM classes.

  • Avoid styling elements directly by tag selectors (e.g., button {} or input {}), as this can lead to specificity conflicts and unintended side effects.

• Structure your class names properly:

  • Use meaningful blocks that represent standalone components.
  • Define elements as child parts of blocks.
  • Use modifiers to indicate variations in style or behavior.

By following this approach, we ensure that:

• Styles are reusable and scoped properly.
• We avoid unnecessary global overrides.
• We maintain consistency across the project.
• PrimeNG components remain compatible with design tokens.

Any further information regarding the BEM methodology can be found through the following links:

• https://css-tricks.com/bem-101/
• https://getbem.com/introduction/
• https://stackoverflow.com/questions/36703546/what-is-bem-methodology
• https://gauravmahlawat.github.io/online-bem-generator.html#google_vignette

Why are we not internally using Tailwind or SCSS?

Why no Tailwind?

We are not internally using Tailwind because this project has the intention of having a long lifespan, we do not want to introduce an extra dependency that could cause compatibility issues among PrimeNG, Angular, and Storybook. Since our project already relies on component libraries that define their own styles and classes, Tailwind’s utility-based approach could lead to conflicts and unnecessary complexity. For all we know, Tailwind is more likely to not be that popular in the near future than native CSS :).

However, we have included in the roadmap the ability to pass Tailwind classes within the styleClasses prop, present in most components so you can use Tailwind from your consuming application.

Why no SCSS?

We are not using SCSS because modern CSS now provides most of SCSS’s features natively. With CSS evolving rapidly (e.g., CSS variables, nesting, container queries, @layer, @scope, and :has()), there is little need for a preprocessor like SCSS. Additionally, relying on native CSS ensures:

• Better browser compatibility.
• No build-step dependencies.
• Future-proof styling that aligns with upcoming CSS standards.

Properly exporting a newly added component

Whenever a newly added component is added, do not forget to add a secondary entrypoint to be able to uniquely import that component in the consuming app:

  "exports": {
    ".": {
      "types": "./index.d.ts",
      "default": "./esm2022/3ddv-software-division-components.mjs"
    },
    "./generic/button": {
      "types": "./generic/button/index.d.ts",
      "default": "./esm2022/generic/button/index.mjs"
    },
    "./backoffice/table": {
      "types": "./backoffice/table/index.d.ts",
      "default": "./esm2022/backoffice/table/index.mjs"
    }
  },

Documenting and testing visual appeareance

The project uses Storybook as a means to document and test the visual appearance of the components throughout various states and parameters combinations. Storybook also aids in receiving visual feedback of the component while developing, without relying on an external application to be able to visualize the component changes. For any further information related to Storybook that is not exclusive to this project, please refer to the official documentation.

How to use Storybook

Storybook requires a separate file to be declared along the component. When you create a new component or modify the API of any exiting component, it is very likely you will either have to create or modify this file. This contains these relevant variables.

• Meta: This contains metadata about the component. Title declares the folder where Storybook will place the component, following a structure of FolderName/ComponentName. Component requires the real component constructor. argTypes declares the controls and its parameters used within Storybook page to modify the component in real time.

const meta: Meta<ButtonComponent> = {
  title: 'Generic/Button',
  component: ButtonComponent,
  id: 'Button',
  argTypes: {
    label: {
      control: 'text',
      description: 'Label of the button',
      table: {
        type: { summary: 'string' },
      },
    },
    // other properties ...
  },
};

• Story : Each story represents a combination of parameters that output a different version of the component. Each story represents a combination of parameters that might be useful in common usage. All stories can be navigated and debugged separately.

export const Primary: Story = {
  args: {
    label: 'Primary Button',
    type: 'button',
    disabled: false,
    loading: false,
    severity: 'primary',
    rounded: true,
    raised: true,
    outlined: false,
    link: false,
    ariaLabel: 'Primary button',
    size: 'large',
  },
};

When this is done (or while you are developing the component) you can visualize it by booting up Storybook locally. Use this command:

pnpm run storybook

and Storybook will serve a static page to interact with your components.

How Storybook component binding works

Define Inputs:

Inputs are exposed as arguments (args) in a story. These arguments can be controlled through Storybook's UI (via the "Controls" panel). Binding Inputs:

The args object is passed to the component via the props property. The args keys must match the @Input property names of the component.

export const WithGridlines: Story = {
  args: {
    value: [
      { id: 1, name: 'Item A' },
      { id: 2, name: 'Item B' },
    ], // Binds to @Input() value
    columnData: [
      { field: 'id', header: 'ID' },
      { field: 'name', header: 'Name' },
    ], // Binds to @Input() columnData
    showGridlines: true, // Binds to @Input() showGridlines
  },
};

This will render the TableComponent with value, columnData, and showGridlines set.In the context of Storybook:

Inputs (@Input) are controlled via args and Controls. Outputs (@Output) are linked to Storybook Actions, allowing you to observe and debug emitted events.