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

package/README.md

@@ -2,20 +2,57 @@
 
 ## **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. It enhances PrimeNG 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.
+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**
 
-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
+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
- npm install @3ddv/software-division-components
+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.**
@@ -29,7 +66,7 @@ The source folder of this project contains multiple subfolders. Below are the mo
 - **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 PrimeNG design intact.
+  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**.
@@ -62,11 +99,38 @@ If the issue persists, refer to the documentation or check for any unintended mo
 
 ## **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 (PrimeNG), 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/).
+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 PrimeNG 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://primeng.org/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:
+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 {
@@ -90,7 +154,7 @@ If you are facing any specifity problems, each component also has an ID referenc
 
 #### 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 librareis, we bring the option to bypass View Encapsulation for a certain CSS class by declaring your classes with a pseudo-class selector:
+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:
 
@@ -137,11 +201,11 @@ Some components are composed of several underlying components, so a single `styl
 
 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 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).
+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 PrimeNG 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:
+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 {
@@ -152,13 +216,11 @@ Tailwind does reset most of the styles that any other third party app is applyin
 @tailwind utilities;
 ```
 
-TODO: DOCUMENT TAILWIND OPTION
-
 ### 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 PrimeNG, 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**.
+> 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:
 
@@ -198,33 +260,6 @@ And the resulting HTML:
 <sdc-button [props]="{props}" />
 ```
 
-### 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';
-```
-
 ## **How to collaborate to the library as a developer**
 
 ### Semantic versioning
@@ -250,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/).
 
@@ -272,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.
@@ -309,7 +344,7 @@ export class ButtonComponent extends Button {
 }
 ```
 
-### Internally overriding PrimeNG styles with component scope
+### 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.
 
@@ -382,11 +417,9 @@ For styling native HTML elements in our project, we adhere to the **Block-Elemen
 #### 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.**
@@ -414,7 +447,7 @@ Any further information regarding the BEM methodology can be found through the f
 
 ###### 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 with PrimeNG, Angular, and Storybook.
+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.
@@ -501,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