@3ddv/software-division-components 1.0.0-alpha.3.9 → 1.0.1

package/README.md

@@ -1,103 +1,266 @@
-# Software Division Components
+# **Software Division Components**
 
-## Overview
+## **Overview**
 
-![Angular Badge](https://img.shields.io/badge/Angular-18.2.13-dd0031?logo=angular&style=for-the-badge)
-![PrimeNG Badge](https://img.shields.io/badge/PrimeNG-18.0.2-034efc?logo=primeng&style=for-the-badge)
+![Angular Badge](https://img.shields.io/badge/Angular-19.2.0-dd0031?logo=angular&style=for-the-badge)
 ![Storybook Badge](https://img.shields.io/badge/Storybook-8.4.5-ff4785?logo=storybook&style=for-the-badge)
 
-The Software Division Components library is a wrapper around the [PrimeNG](https://v18.primeng.org/installation) component library that provides extra functionality based on common needs within the Software Division department applications. It also uses [Angular](https://v18.angular.dev/) and [Storybook](https://storybook.js.org/).
+The Software Division Components library is a wrapper around the [SpartanNG](https://spartan.ng/documentation/introduction) 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](https://v18.angular.dev/) for application development and [Storybook](https://storybook.js.org/) for interactive component documentation and testing.
 
-## Installation
+## **Installation**
 
-To install the library, use npm:
+[Refer to the dedicated docs page](./docs/installation.md)
+
+## **Development**
+
+### Conventions
+
+[Refer to the dedicated docs page](./docs/conventions.md)
+
+### Development Workflows
+
+#### 1. Storybook Development (Recommended)
+
+Use Storybook for isolated component development and testing:
 
 ```bash
- npm install @3ddv/software-division-components
+pnpm storybook
 ```
 
-## Usage
+#### 2. Consumer App Integration Testing
 
-### Theming and styling
+Use the consumer app for integration testing of components in a real application context. Each component should have its own route for testing.
 
-This library is a wrapper to an already existing component library, so there are some styles which are already present in all the components. These styles are kept intact whenever the `backoffice` theme parameter is passed. 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. You can check that design [here](https://xd.adobe.com/view/0ea7033e-8fdf-4fcd-8215-546d1df20d37-5bf4/) and [here](https://xd.adobe.com/view/c640d5a1-b5d3-4379-8684-fb860f95f052-9313/grid).
+**Setup requires two terminals:**
 
-Styling components works as if you were styling a usual HTML element. Every component has a `styleClasses` input which accepts a single or several whitespace-separated CSS class/classes declared within the using application.
+**Terminal 1 - Build Library:**
 
-```css
-.my-class {
-  background-color: red;
-}
+```bash
+pnpm run build:watch
 ```
 
-```typescript
- <sdc-button
-  styleClasses='my-class'
- ></sdc-button>
+Watches for changes in the SDC library and rebuilds to the `dist/` folder.
 
+**Terminal 2 - Watch and Restart Consumer App:**
+
+```bash
+pnpm run start:watch
 ```
 
-Styles will pierce through the PrimeNG 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](https://v18.primeng.org/theming) or the individual webpage for styling each component [as in this example for the button component](https://v18.primeng.org/button).
+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](https://mmcbcn.atlassian.net/browse/TICKETING-598) 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
 
-#### Setting a theme
+#### Providing the library to the application
 
 ```ts
 import { ApplicationConfig } from '@angular/core';
-import { provideSdComponentsTheme } from '@3ddv/software-division-components';
+import { provideSdc } from '@3ddv/software-division-components';
 
 export const appConfig: ApplicationConfig = {
-  // this can be generic or backoffice
-  providers: [provideSdComponentsTheme({ theme: 'generic' })],
+  // this provides the consuming app with all necessary modules
+  // to make it work
+  providers: [provideSdc({ theme: 'generic' })],
 };
 ```
 
 #### Import from main entry
 
-```typescript
+```ts
 import { TableComponent, ButtonComponent } from '@3ddv/software-division-components';
 ```
 
 #### Import from secondary entry
 
-```typescript
+```ts
 import { ButtonComponent } from '@3ddv/software-division-components/generic/button';
 ```
 
-## **Reporting issues**
+### Theming and styling
 
-> **This is a temporary workflow to report issues until the usage of the library grows and we find ourselves in the need to scale this issue reporting system.**
+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](https://xd.adobe.com/view/0ea7033e-8fdf-4fcd-8215-546d1df20d37-5bf4/), [here](https://xd.adobe.com/view/c640d5a1-b5d3-4379-8684-fb860f95f052-9313/grid) and [here](https://xd.adobe.com/view/50a2d5c5-e2e1-413f-b7a5-8f3d61c88026-05f1/screen/65dee679-9942-4a63-b790-40e3b1fec39b/).
 
-To report an issue, please visit [the following ticket](https://mmcbcn.atlassian.net/browse/TICKETING-598) and open a Bug ticket with a clear description of the issue you are facing.
+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)[https://spartan.ng/components/button]. 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:
 
-## **Project summary**
+```css
+.my-class {
+  --p-button-primary-background: red;
+}
+```
 
-This project source folder contains multiple folders, the most important are the following:
+```html
+<sdc-button styleClasses="my-class"></sdc-button>
+```
 
-- **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`). There are some components in the Generic folder which can also be used in the backoffice, but please do so by passing the `backoffice` theme to the library provider. The `backoffice` parameter tells the system to not apply any styles to the components, keeping the design to the one PrimeNG already has by default.
+#### Specifity issues
 
-- **DVM**
-  This folder contains components that are exclusive to an application that uses DVM. There are a lot of components that are common both in style and functionality, and this module aims to reuse those as much as posible. Some examples of these components are the section navigator buttons or the minimap.
+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:
 
-- **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).
+```css
+#sdc-button.my-class {
+  --p-button-primary-background: red;
+}
+```
 
-- **Shared**
-  This folder contains initialization methods, directives and other methods to aid with the usage and debugging of the library.
+#### Encapsulation issues
 
-- **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.
+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)[https://angular.dev/guide/components/styling] 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:
+
+```css
+::ng-deep.my-class {
+  --p-button-primary-background: red;
+}
+```
+
+You also have the option with SCSS to nest:
+
+```css
+::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:
+
+```html
+<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](https://v18.primeng.org/theming) or the individual webpage for styling each component [as in this example for the button component](https://v18.primeng.org/button).
+
+### 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:
+
+```css
+@layer tailwind-base {
+  @tailwind base;
+  @tailwind components;
+}
 
-### Common @3ddv/software-division-components errors
+@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:
+
+```html
+<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:
+
+```ts
+import { ButtonProps } from '@3ddv/software-division-components';
 
-#### Error console `Invalid CSS class string found on ...`
+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;
+}
+```
 
-This indicates that the `stylesClasses` input that you provided to the component does not have a valid format. Please make sure
-to adhere to a valid format documented in the component.
+And the resulting HTML:
 
-## **How to collaborate**
+```html
+<sdc-button [props]="{props}" />
+```
+
+## **How to collaborate to the library as a developer**
 
 ### Semantic versioning
 
@@ -122,7 +285,7 @@ If the commit message does not adhere to the Conventional Commits format, Commit
 
 ### Development workflow steps
 
-- Make sure you have latest master remote changes on your local master branch
+- 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](https://www.conventionalcommits.org/en/v1.0.0/).
 
@@ -136,8 +299,6 @@ If the commit message does not adhere to the Conventional Commits format, Commit
 
 - Rinse and repeat.
 
-## **How to document your changes**
-
 ### 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.
@@ -146,7 +307,7 @@ We also declare the accessibility scope, parameter types and return types of any
 
 ```typescript
 /**
- * A customizable button component built on PrimeNG's Button component.
+ * 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.
@@ -177,12 +338,130 @@ export class ButtonComponent extends Button {
    */
   public handleClick(event: MouseEvent): void {
     // Implementation should document any steps that cannot be easily explained
-    // with variable names. Another scenario might be on documenting why things
+    // 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](https://v18.primeng.org/theming), 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:
+
+```ts
+// 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
+
+```ts
+import { sideButtonTokens } from './styles/side-button.tokens';
+....
+export class NeighboursComponent {
+  ...
+    protected readonly sideButtonStyle = sideButtonTokens;
+  ...
+}
+```
+
+Template example:
+
+```html
+<!-- [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:
+
+<div style="display: flex; align-items: center; gap: 20px;">
+  <div style="text-align: center;">
+    <p>Before Styling</p>
+    <img src="./projects/software-division-components/public/neighbours-before.png" alt="Before styling neighbours." width="300">
+  </div>
+  <div style="text-align: center;">
+    <p>After Styling</p>
+    <img src="./projects/software-division-components/public/neighbours-after.png" alt="After styling neighbours." width="300">
+  </div>
+</div>
+
+### 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:
@@ -255,7 +534,7 @@ export const Primary: Story = {
 };
 ```
 
-When this is done (or while you are doing developing the component) you can visualize it by booting up Storybook locally. Use this command:
+When this is done (or while you are developing the component) you can visualize it by booting up Storybook locally. Use this command:
 
 ```bash
 pnpm run storybook