@3ddv/software-division-components 1.4.1 → 1.4.2

package/angular.json

@@ -0,0 +1,144 @@
+{
+  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
+  "version": 1,
+  "cli": {
+    "packageManager": "pnpm",
+    "analytics": false,
+    "cache": {
+      "enabled": false
+    }
+  },
+  "newProjectRoot": "projects",
+  "projects": {
+    "software-division-components": {
+      "projectType": "library",
+      "root": "projects/software-division-components/src",
+      "sourceRoot": "projects/software-division-components/src",
+      "prefix": "sdc",
+      "architect": {
+        "build": {
+          "builder": "@angular-devkit/build-angular:ng-packagr",
+          "configurations": {
+            "production": {
+              "project": "projects/software-division-components/ng-package.json",
+              "tsConfig": "projects/software-division-components/tsconfig.json"
+            },
+            "options": {
+              "project": "projects/software-division-components/ng-package.json",
+              "tsConfig": "projects/software-division-components/tsconfig.json"
+            }
+          }
+        },
+        "test": {
+          "builder": "@angular-devkit/build-angular:karma",
+          "options": {
+            "tsConfig": "projects/software-division-components/tsconfig.spec.json",
+            "polyfills": ["zone.js", "zone.js/testing"]
+          }
+        },
+        "storybook": {
+          "builder": "@storybook/angular:start-storybook",
+          "options": {
+            "configDir": "projects/software-division-components/.storybook",
+            "browserTarget": "software-division-components:build",
+            "compodoc": false,
+            "port": 6006,
+            "stylePreprocessorOptions": { "includePaths": ["projects/software-division-components/src"] },
+            "styles": ["./projects/software-division-components/styles.css"]
+          }
+        },
+        "build-storybook": {
+          "builder": "@storybook/angular:build-storybook",
+          "options": {
+            "configDir": "projects/software-division-components/.storybook",
+            "browserTarget": "software-division-components:build",
+            "compodoc": true,
+            "compodocArgs": ["-e", "json", "-d", "projects/software-division-components"],
+            "outputDir": "storybook-static",
+            "styles": ["./projects/software-division-components/styles.css"]
+          }
+        }
+      }
+    },
+    "consumer-app": {
+      "projectType": "application",
+      "schematics": {},
+      "root": "projects/consumer-app",
+      "sourceRoot": "projects/consumer-app/src",
+      "prefix": "app",
+      "architect": {
+        "build": {
+          "builder": "@angular-devkit/build-angular:application",
+          "options": {
+            "outputPath": "dist/consumer-app",
+            "index": "projects/consumer-app/src/index.html",
+            "browser": "projects/consumer-app/src/main.ts",
+            "polyfills": ["zone.js"],
+            "tsConfig": "projects/consumer-app/tsconfig.app.json",
+            "assets": [
+              {
+                "glob": "**/*",
+                "input": "projects/consumer-app/public"
+              }
+            ],
+            "styles": ["projects/consumer-app/src/styles.css"],
+            "scripts": []
+          },
+          "configurations": {
+            "production": {
+              "budgets": [
+                {
+                  "type": "initial",
+                  "maximumWarning": "500kB",
+                  "maximumError": "1MB"
+                },
+                {
+                  "type": "anyComponentStyle",
+                  "maximumWarning": "4kB",
+                  "maximumError": "8kB"
+                }
+              ],
+              "outputHashing": "all"
+            },
+            "development": {
+              "optimization": false,
+              "extractLicenses": false,
+              "sourceMap": true
+            }
+          },
+          "defaultConfiguration": "production"
+        },
+        "serve": {
+          "builder": "@angular-devkit/build-angular:dev-server",
+          "configurations": {
+            "production": {
+              "buildTarget": "consumer-app:build:production"
+            },
+            "development": {
+              "buildTarget": "consumer-app:build:development"
+            }
+          },
+          "defaultConfiguration": "development"
+        },
+        "extract-i18n": {
+          "builder": "@angular-devkit/build-angular:extract-i18n"
+        },
+        "test": {
+          "builder": "@angular-devkit/build-angular:karma",
+          "options": {
+            "polyfills": ["zone.js", "zone.js/testing"],
+            "tsConfig": "projects/consumer-app/tsconfig.spec.json",
+            "assets": [
+              {
+                "glob": "**/*",
+                "input": "projects/consumer-app/public"
+              }
+            ],
+            "styles": ["projects/consumer-app/src/styles.css"],
+            "scripts": []
+          }
+        }
+      }
+    }
+  }
+}

package/commitlint-config.ts

@@ -0,0 +1,7 @@
+import { type UserConfig } from '@commitlint/types';
+
+const config: UserConfig = {
+  extends: ['@commitlint/config-conventional'],
+};
+
+export default config;

package/components.json

@@ -0,0 +1,6 @@
+{
+  "componentsPath": "libs/ui",
+  "buildable": true,
+  "generateAs": "library",
+  "importAlias": "@software-division/components"
+}

package/docs/conventions.md

@@ -0,0 +1,151 @@
+[BACK TO THE TOP](../README.md)
+
+# Component Development Conventions
+
+This document outlines the conventions for developing new components within the Software Division Components (SDC) library.
+
+## General Conventions & API
+
+- **Selector and Variable Prefix**: All component selectors and component-specific CSS variables must use the `sdc-` prefix (e.g., `sdc-input`, `--sdc-input-field-border-color`).
+- **Root Element Class**: The component's selector must be added as a class to its root element. This allows for consistent global styling and targeting.
+
+### Component Inputs for Styling
+
+All components must provide two standard inputs for styling by consumers:
+
+- **`styleClass`**: An `input<string[]>` that accepts an array of predefined variant classes. These classes control component appearance, such as size, color, or shape (e.g., `['variant-primary', 'size-sm']`). The component must validate the provided classes and throw an error if an unknown variant is passed. This ensures consumers use the component's styling API correctly.
+
+- **`className`**: An `input<string>` that accepts additional CSS classes. These classes are applied directly to the component's root element, allowing for specific, one-off style overrides. This is the recommended way to apply custom styles for a single instance.
+
+## Styling and Theming
+
+Our styling approach is built upon CSS Custom Properties (Variables) to allow for flexible and easy theming by consumer applications. This provides a clear and predictable way to customize component appearance.
+
+### 1. Base Theme
+
+A base theme, `theme-sdc`, is defined in `projects/software-division-components/src/shared/themes/sdc.css`. It contains a comprehensive set of global CSS variables for colors, fonts, spacing, etc.
+
+```css
+/* sdc.css */
+:root .theme-sdc {
+  /* ... */
+  --color-primary: 29.01 100% 52.55%; /* #ff8c00 - Main Club brand color */
+  --text-base: 1rem; /* 16px - Body text, buttons */
+  --space-4: 1rem; /* 16px - Standard spacing unit */
+  /* ... */
+}
+```
+
+All new components should be styled using these global theme variables.
+
+### 2. Component Structure
+
+Each component must accept a `theme` input. This input's value is applied as a class to the component's root element, scoping the styles and ensuring the component correctly consumes the intended theme.
+
+**`input.component.ts`**:
+
+```typescript
+@Component({
+  selector: 'sdc-input',
+  // ...
+})
+export class InputComponent {
+  /**
+   * The current theme applied to the component.
+   */
+  public readonly theme = input<ThemeClass>('theme-sdc');
+
+  protected readonly computedClass = computed(() => {
+    // ...
+    return ['sdc-input', this.theme()].filter(Boolean).join(' ');
+  });
+}
+```
+
+**`input.component.html`**:
+
+```html
+<div [class]="computedClass()">
+  <!-- Component content -->
+</div>
+```
+
+### 3. Component-Specific Style Variables
+
+Each component should define its own set of local, component-specific CSS variables in its stylesheet (e.g., `input.component.css`). These variables should, by default, map to the global theme variables. This creates a dedicated styling "API" for each component.
+
+**`input.component.css`**:
+
+```css
+/* Base styles for sdc-input */
+.sdc-input {
+  --sdc-input-field-border-color: var(--color-neutral-300);
+  --sdc-input-field-text-size: var(--text-base);
+  --sdc-input-focus-ring-color: var(--color-primary);
+  /* ... other component-specific variables */
+}
+
+.sdc-input-field {
+  border-color: hsl(var(--sdc-input-field-border-color));
+  font-size: var(--sdc-input-field-text-size);
+  /* ... */
+}
+
+.sdc-input-field:focus-visible {
+  outline-color: hsl(var(--sdc-input-focus-ring-color));
+  /* ... */
+}
+```
+
+### 4. Overriding Styles in a Consumer App
+
+This architecture provides multiple levels for consumers to customize styles, from broad theme changes to specific instance tweaks.
+
+#### A. Global Theme Override
+
+To change a theme value globally (e.g., for a specific client or brand), the consumer application can override the global variable within the theme's scope. This is the most common way to apply brand colors.
+
+**`consumer-app/src/styles.css`**:
+
+```css
+/* Change the primary color for the entire sdc theme */
+:root .theme-sdc {
+  --color-primary: 120, 100%, 25%; /* Green */
+}
+```
+
+This will affect all components that use `--color-primary`, such as the focus ring of our `sdc-input`.
+
+#### B. Component-Type Override
+
+To change a style for all instances of a specific component type (e.g., all buttons), the consumer can target the component's class and override its local CSS variable. This is useful for adjustments that shouldn't affect other components.
+
+**`consumer-app/src/styles.css`**:
+
+```css
+/* Change the background for all sdc-button components */
+:root .theme-sdc.sdc-button {
+  --sdc-button-background: 60, 100%, 50%; /* Yellow */
+}
+```
+
+#### C. Specific Component Instance Override
+
+For fine-grained control over a single component instance, the consumer can pass a custom class via the `className` input and use a more specific CSS selector.
+
+**In the consumer's template:**
+
+```html
+<sdc-button className="submit-button">Submit</sdc-button>
+```
+
+**`consumer-app/src/styles.css`**:
+
+```css
+/* Change the background only for buttons with the 'submit-button' class */
+:root .theme-sdc.sdc-button.submit-button {
+  --sdc-button-background: 0, 100%, 50%; /* Red */
+}
+```
+
+This layered approach ensures that our components are both consistent with the design system and highly customizable to meet specific product requirements.

package/docs/installation.md

@@ -0,0 +1,131 @@
+[BACK TO THE TOP](../README.md)
+
+# Software Division Components (SDC) - Installation Guide
+
+## Prerequisites
+
+- **Angular**: 19.0.0+
+- **Node.js**: 18+
+- **Package Manager**: npm 8+ or pnpm 8+
+
+**Note**: Tailwind CSS is not required - SDC ships with pre-compiled CSS only.
+
+## Installation Steps
+
+### 1. Install the SDC Library
+
+```bash
+npm install @3ddv/software-division-components
+```
+
+### 2. Import Library Styles
+
+Add to your `src/styles.css`:
+
+```css
+@import '@3ddv/software-division-components/styles.css';
+```
+
+This imports all SDC component styles, Tailwind utilities, and theme configurations needed for proper component rendering.
+
+### 3. Import Components
+
+```typescript
+import { ButtonComponent } from '@3ddv/software-division-components';
+
+@Component({
+  imports: [ButtonComponent],
+  // ... other config
+})
+```
+
+Import specific components you need to use in your application. Each component is standalone and can be imported individually.
+
+## Using Tailwind CSS Alongside SDC (Optional)
+
+If you want to use Tailwind CSS in your app alongside SDC components:
+
+1. **Install Tailwind CSS**:
+
+```bash
+npm install -D tailwindcss postcss autoprefixer
+npx tailwindcss init
+```
+
+2. **Configure Tailwind** to include SDC components:
+
+```javascript
+// tailwind.config.js
+module.exports = {
+  content: ['./src/**/*.{html,ts}', './node_modules/@3ddv/software-division-components/**/*.{html,ts}'],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+};
+```
+
+3. **Version Compatibility**:
+
+- **SDC uses Tailwind CSS v4.1.11** for compilation
+- **Consumer apps can use Tailwind CSS v3.x or v4.x**
+- **No version conflicts** since SDC ships compiled CSS only
+
+## Troubleshooting
+
+### Common Issues
+
+**Error: "Module not found" for components**
+
+- **Solution**: Check that components are properly imported in your component's imports array
+- **Why**: Angular standalone components require explicit imports for tree-shaking
+
+**Error: Could not resolve dependency**
+
+```bash
+✘ [ERROR] Could not resolve "rxjs"
+
+    ../../libs/ticketing-598-software-division-components-npm/dist/fesm2022/3ddv-software-division-components.mjs:12:46:
+      12 │ import { Subject, fromEvent, startWith } from 'rxjs';
+         ╵                                               ~~~~~~
+
+  You can mark the path "rxjs" as external to exclude it from the bundle, which will remove this error and leave the unresolved path in the bundle.
+
+
+✘ [ERROR] Could not resolve "rxjs/operators"
+
+    ../../libs/ticketing-598-software-division-components-npm/dist/fesm2022/3ddv-software-division-components.mjs:13:31:
+      13 │ import { takeUntil, map } from 'rxjs/operators';
+         ╵                                ~~~~~~~~~~~~~~~~
+
+  You can mark the path "rxjs/operators" as external to exclude it from the bundle, which will remove this error and leave the unresolved path in the bundle.
+```
+
+- **Solution**: Declare the unresolved dependencies as external dependencies in angular.json
+
+```json
+...
+"builder": "@angular-devkit/build-angular:application",
+  "options": {
+    "externalDependencies": ["rxjs", "rxjs/operators"]
+  }
+...
+```
+
+- **Why**: This is required because the Application Builder (Angular 17+) uses esbuild, which needs explicit external dependency configuration.
+
+## Usage Examples
+
+### Basic Button Component
+
+```typescript
+import { ButtonComponent } from '@3ddv/software-division-components';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [ButtonComponent],
+  template: ` <sdc-button variant="primary">Click me</sdc-button> `,
+})
+export class ExampleComponent {}
+```