@3ddv/software-division-components 1.0.2 → 1.1.0

package/README.backup.md

@@ -1,575 +0,0 @@
-# **Software Division Components**
-
-## **Overview**
-
-![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 [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**
-
-[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
-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:**
-
-```bash
-pnpm run build:watch
-```
-
-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
-```
-
-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
-
-#### Providing the library to the application
-
-```ts
-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
-
-```ts
-import { TableComponent, ButtonComponent } from '@3ddv/software-division-components';
-```
-
-#### Import from secondary entry
-
-```ts
-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](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/).
-
-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:
-
-```css
-.my-class {
-  --p-button-primary-background: red;
-}
-```
-
-```html
-<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:
-
-```css
-#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)[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;
-}
-
-@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';
-
-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:
-
-```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](https://semver.org/) for any further information.
-
-### 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](https://www.conventionalcommits.org/en/v1.0.0/) 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](https://www.conventionalcommits.org/en/v1.0.0/).
-
-- 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.
-
-```typescript
-/**
- * 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](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:
-
-```json
-  "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](https://storybook.js.org/) 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.
-
-```typescript
-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.
-
-```typescript
-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:
-
-```bash
-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.
-
-```typescript
-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.