ng-comps 0.2.0 → 1.0.1

package/.editorconfig

@@ -0,0 +1,17 @@
+# Editor configuration, see https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.ts]
+quote_type = single
+ij_typescript_use_double_quotes = false
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false

package/.github/copilot-instructions.md

@@ -0,0 +1,55 @@
+
+You are an expert in TypeScript, Angular, and scalable web application development. You write functional, maintainable, performant, and accessible code following Angular and TypeScript best practices.
+
+## TypeScript Best Practices
+
+- Use strict type checking
+- Prefer type inference when the type is obvious
+- Avoid the `any` type; use `unknown` when type is uncertain
+
+## Angular Best Practices
+
+- Always use standalone components over NgModules
+- Must NOT set `standalone: true` inside Angular decorators. It's the default in Angular v20+.
+- Use signals for state management
+- Implement lazy loading for feature routes
+- Do NOT use the `@HostBinding` and `@HostListener` decorators. Put host bindings inside the `host` object of the `@Component` or `@Directive` decorator instead
+- Use `NgOptimizedImage` for all static images.
+  - `NgOptimizedImage` does not work for inline base64 images.
+
+## Accessibility Requirements
+
+- It MUST pass all AXE checks.
+- It MUST follow all WCAG AA minimums, including focus management, color contrast, and ARIA attributes.
+
+### Components
+
+- Keep components small and focused on a single responsibility
+- Use `input()` and `output()` functions instead of decorators
+- Use `computed()` for derived state
+- Set `changeDetection: ChangeDetectionStrategy.OnPush` in `@Component` decorator
+- Prefer inline templates for small components
+- Prefer Reactive forms instead of Template-driven ones
+- Do NOT use `ngClass`, use `class` bindings instead
+- Do NOT use `ngStyle`, use `style` bindings instead
+- When using external templates/styles, use paths relative to the component TS file.
+
+## State Management
+
+- Use signals for local component state
+- Use `computed()` for derived state
+- Keep state transformations pure and predictable
+- Do NOT use `mutate` on signals, use `update` or `set` instead
+
+## Templates
+
+- Keep templates simple and avoid complex logic
+- Use native control flow (`@if`, `@for`, `@switch`) instead of `*ngIf`, `*ngFor`, `*ngSwitch`
+- Use the async pipe to handle observables
+- Do not assume globals like (`new Date()`) are available.
+
+## Services
+
+- Design services around a single responsibility
+- Use the `providedIn: 'root'` option for singleton services
+- Use the `inject()` function instead of constructor injection

package/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - master
+      - 'codex/**'
+  pull_request:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install
+        run: npm ci
+
+      - name: Validate Library
+        run: npm run ci

package/.prettierrc

@@ -0,0 +1,12 @@
+{
+  "printWidth": 100,
+  "singleQuote": true,
+  "overrides": [
+    {
+      "files": "*.html",
+      "options": {
+        "parser": "angular"
+      }
+    }
+  ]
+}

package/.storybook/main.ts

@@ -0,0 +1,21 @@
+import type { StorybookConfig } from '@storybook/angular';
+
+const config: StorybookConfig = {
+  "stories": [
+    "../src/**/*.mdx",
+    "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"
+  ],
+  "addons": [
+    "@storybook/addon-a11y",
+    "@storybook/addon-docs"
+  ],
+  "framework": "@storybook/angular",
+  "previewHead": (head) => `
+    ${head}
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Manrope:wght@400;500;600;700&family=Sora:wght@500;700&display=swap">
+    <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
+  `,
+};
+export default config;

package/.storybook/preview.ts

@@ -0,0 +1,27 @@
+import { setCompodocJson } from '@storybook/addon-docs/angular';
+import type { Preview } from '@storybook/angular';
+import { applicationConfig } from '@storybook/angular';
+import { provideAnimations } from '@angular/platform-browser/animations';
+import { importProvidersFrom } from '@angular/core';
+import { MatIconModule } from '@angular/material/icon';
+import docJson from '../documentation.json';
+
+setCompodocJson(docJson);
+
+const preview: Preview = {
+  decorators: [
+    applicationConfig({
+      providers: [provideAnimations(), importProvidersFrom(MatIconModule)],
+    }),
+  ],
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+  },
+};
+
+export default preview;

package/.storybook/tsconfig.doc.json

@@ -0,0 +1,10 @@
+// This tsconfig is used by Compodoc to generate the documentation for the project.
+// If Compodoc is not used, this file can be deleted.
+{
+  "extends": "./tsconfig.json",
+  // Exclude all files that are not needed for documentation generation.
+  "exclude": ["../src/test.ts", "../src/**/*.spec.ts", "../src/**/*.stories.ts"],
+  // Please make sure to include all files from which Compodoc should generate documentation.
+  "include": ["../src/**/*"],
+  "files": ["./typings.d.ts"]
+}

package/.storybook/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../tsconfig.app.json",
+  "compilerOptions": {
+    "types": ["node"],
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true
+  },
+  "exclude": ["../src/test.ts", "../src/**/*.spec.ts"],
+  "include": [
+    "../src/**/*.stories.*",
+    "../src/app/components/**/*.ts",
+    "./preview.ts"
+  ],
+  "files": ["./typings.d.ts"]
+}

package/.storybook/typings.d.ts

@@ -0,0 +1,4 @@
+declare module '*.md' {
+  const content: string;
+  export default content;
+}

package/.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=827846
+  "recommendations": ["angular.ng-template"]
+}

package/.vscode/launch.json

@@ -0,0 +1,20 @@
+{
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "ng serve",
+      "type": "chrome",
+      "request": "launch",
+      "preLaunchTask": "npm: start",
+      "url": "http://localhost:4200/"
+    },
+    {
+      "name": "ng test",
+      "type": "chrome",
+      "request": "launch",
+      "preLaunchTask": "npm: test",
+      "url": "http://localhost:9876/debug.html"
+    }
+  ]
+}

package/.vscode/mcp.json

@@ -0,0 +1,9 @@
+{
+  // For more information, visit: https://angular.dev/ai/mcp
+  "servers": {
+    "angular-cli": {
+      "command": "npx",
+      "args": ["-y", "@angular/cli", "mcp"]
+    }
+  }
+}

package/.vscode/tasks.json

@@ -0,0 +1,42 @@
+{
+  // For more information, visit: https://go.microsoft.com/fwlink/?LinkId=733558
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "type": "npm",
+      "script": "start",
+      "isBackground": true,
+      "problemMatcher": {
+        "owner": "typescript",
+        "pattern": "$tsc",
+        "background": {
+          "activeOnStart": true,
+          "beginsPattern": {
+            "regexp": "Changes detected"
+          },
+          "endsPattern": {
+            "regexp": "bundle generation (complete|failed)"
+          }
+        }
+      }
+    },
+    {
+      "type": "npm",
+      "script": "test",
+      "isBackground": true,
+      "problemMatcher": {
+        "owner": "typescript",
+        "pattern": "$tsc",
+        "background": {
+          "activeOnStart": true,
+          "beginsPattern": {
+            "regexp": "Changes detected"
+          },
+          "endsPattern": {
+            "regexp": "bundle generation (complete|failed)"
+          }
+        }
+      }
+    }
+  ]
+}

package/ACCESSIBILITY.md

@@ -0,0 +1,127 @@
+# Accessibility Contract for ng-comps v1
+
+## Positioning
+
+`ng-comps` v1 is built to make accessible implementation the default path for Angular teams using Angular Material under a branded component layer.
+
+Repository goals:
+
+- implement against WCAG 2.2 AA at component level
+- keep contractual evidence aligned to EN 301 549 v3.2.1 / WCAG 2.1 AA until the next EN revision is formally published
+- document known limits so procurement claims stay technically defensible
+
+The library can support accessibility conformance. It cannot guarantee application-level conformance on its own.
+
+## Public Contract
+
+Consumers must follow these rules:
+
+1. Every interactive component must expose an accessible name through visible text, `label`, `ariaLabel`, or `ariaLabelledby`.
+2. Placeholders are supplementary hints, never the only label.
+3. Icon-only actions must provide an explicit accessible label.
+4. Focus must remain visible. Consumers must not remove outlines without an equivalent replacement.
+5. Dialogs, menus, selects, datepickers, and sidenavs must use the provided accessible APIs and patterns.
+6. Table row interactions must be explicit buttons or links inside cells. Whole-row click targets are not part of the default contract.
+7. Theme overrides must preserve contrast and focus ring visibility.
+
+## What the Library Now Enforces
+
+- shared accessible-name contract on interactive form controls
+- `ControlValueAccessor` support for core form inputs
+- `aria-describedby` wiring for hints, counters, and errors
+- `aria-invalid` reflection for explicit and form-driven errors
+- visible global `:focus-visible` styling
+- safer dialog opening through `MfDialogService`
+- explicit row actions in `MfTableComponent`
+- snackbar politeness and announcement support
+- tooltip directive support on the real host element via `mfTooltip`
+
+## Component Notes
+
+### Buttons and triggers
+
+- `MfButtonComponent` supports icon-only mode, but icon-only usage requires `ariaLabel` or `ariaLabelledby`.
+- `MfMenuComponent` exposes a labelled trigger and relies on Angular Material keyboard navigation for menu items.
+
+### Form controls
+
+- `MfInputComponent`
+- `MfTextareaComponent`
+- `MfSelectComponent`
+- `MfAutocompleteComponent`
+- `MfDatepickerComponent`
+- `MfCheckboxComponent`
+- `MfRadioButtonComponent`
+- `MfSlideToggleComponent`
+
+These components support Angular forms integration, descriptive relationships, and explicit error announcements.
+
+### Overlays
+
+- `MfDialogService` applies safe defaults for role, autofocus, restore focus, and panel class.
+- `MfDialogComponent` requires a visible title or explicit accessible name.
+- `MfDatepickerComponent`, `MfSelectComponent`, and `MfAutocompleteComponent` inherit keyboard interaction from Angular Material and are documented with keyboard contract stories in Storybook.
+
+### Data and status
+
+- `MfTableComponent` uses explicit action controls instead of clickable rows.
+- `MfProgressBarComponent` and `MfProgressSpinnerComponent` require accessible labels for informative usage.
+- `MfBadgeComponent` distinguishes decorative usage from informative usage through `description`.
+- `MfAvatarComponent` distinguishes decorative usage from informative usage through `decorative`.
+
+## Automated Validation in This Repo
+
+Local commands:
+
+```bash
+npm run build:lib
+npm run test:ci
+npm run build-storybook
+npm run ci
+```
+
+Automated coverage currently includes:
+
+- unit tests
+- DOM-level accessibility checks with `axe-core`
+- regression checks for accessibility-oriented API defaults
+- Storybook static build for documentation and contract stories
+
+## Manual Validation Matrix
+
+This repository still requires manual validation before any formal claim:
+
+- keyboard-only navigation
+- 200% zoom
+- reflow equivalent to 320 CSS px width
+- NVDA on Windows
+- VoiceOver on macOS
+- visible focus review
+- contrast review after any token override
+
+## Known Limitations
+
+- Application conformance still depends on consumer content, routing, state changes, and custom wrappers.
+- If consumers override tokens or Angular Material theme values, they must re-run contrast checks.
+- `MfTooltipComponent` is retained for compatibility, but the preferred API in v1 is the `mfTooltip` directive on the host element.
+- Repeated row actions in tables should provide contextual `rowActionAriaLabel` values for best screen reader output.
+- Screen reader verification remains mandatory for procurement-grade evidence.
+
+## VPAT-Oriented Evidence Base
+
+This repository now includes:
+
+- component-level accessibility defaults
+- automated checks that run in CI
+- Storybook contract stories for critical interaction patterns
+- explicit documentation of correct usage, anti-patterns, and limitations
+
+That is a usable base for a VPAT process, but not a completed VPAT by itself.
+
+## Normative References
+
+- W3C WCAG overview: https://www.w3.org/WAI/standards-guidelines/wcag/
+- EN 301 549 working repository: https://labs.etsi.org/rep/HF/en301549
+- ETSI download/status entry referenced in procurement notes: https://portal.etsi.org/webapp/ewp/copy_file.asp?wki_id=64282
+
+As verified on 2026-03-27, W3C states that EN 301 549 currently uses WCAG 2.1 and encourages use of WCAG 2.2, while the EN 301 549 working repository describes the v4.1.0 draft as being in formal approval flow rather than a published replacement.

package/README.md

@@ -1,62 +1,79 @@
-# ng-comps
-
-Libreria de componentes UI para Angular con enfoque en:
-
-- paquete NPM liviano
-- tree-shaking real
-- peers de Angular (sin duplicar framework en cada instalacion)
-
-## Instalacion (consumidor)
-
-```bash
-npm i ng-comps
-```
-
-Importa solo lo que usas:
-
-```ts
-import { MfButtonComponent } from 'ng-comps';
-```
-
-Si quieres usar los tokens/estilos base:
-
-```css
-@import 'ng-comps/theme/tokens.css';
-@import 'ng-comps/styles.css';
-```
-
-## Publicacion optimizada a NPM
-
-Este repo publica desde `dist/ng-comps`, no desde la raiz. De esta forma no se suben historias, tests ni archivos de desarrollo.
-
-1. Construir la libreria APF:
-
-```bash
-npm run build:lib
-```
-
-2. Generar `package.json` optimizado para distribucion:
-
-```bash
-npm run prepare:package
-```
-
-3. Verificar contenido del paquete antes de publicar:
-
-```bash
-npm run release:dry-run
-```
-
-4. Publicar:
-
-```bash
-npm run publish:npm
-```
-
-## Estrategia de optimizacion aplicada
-
-- `sideEffects: false` para maximizar tree-shaking
-- `peerDependencies` para Angular y RxJS (evita bundles duplicados)
-- `dependencies` minimas (`tslib`)
-- `exports` explicitos para entrypoint y estilos
-- publicacion desde carpeta de build (`dist/ng-comps`)
+# ng-comps
+
+Angular UI library built on top of Angular Material with a public accessibility contract.
+
+## Installation
+
+```bash
+npm i ng-comps
+```
+
+Import only what you use:
+
+```ts
+import { MfButtonComponent } from 'ng-comps';
+```
+
+Load the shared tokens and base styles in your global stylesheet:
+
+```css
+@import 'ng-comps/theme/tokens.css';
+@import 'ng-comps/styles.css';
+```
+
+## Accessibility Contract
+
+`ng-comps` v1 is designed to support:
+
+- WCAG 2.2 AA implementation targets in the component layer
+- EN 301 549 evidence mapping when the library is used as documented
+- Contractual reporting against EN 301 549 v3.2.1 / WCAG 2.1 AA until the next EN update is formally published
+
+The library is accessible by default only when consumers keep the semantic contract intact:
+
+- interactive components must have an accessible name
+- visible labels are preferred over placeholders
+- overlays must be opened through the provided accessible APIs
+- row actions in tables must be explicit and focusable
+- custom theming must preserve contrast and visible focus states
+
+Read the full contract, QA matrix, limitations, and VPAT-oriented notes in [ACCESSIBILITY.md](./ACCESSIBILITY.md).
+
+## Development
+
+```bash
+npm run build:lib
+npm run test:ci
+npm run build-storybook
+npm run ci
+```
+
+`npm run ci` executes the local gate used by CI:
+
+- library build
+- unit and accessibility tests
+- Storybook static build
+
+## Storybook
+
+Storybook is the primary documentation surface for component usage and accessibility contracts.
+
+- component API stories live in `src/stories`
+- accessibility contract stories cover keyboard, focus, overlays, and explicit actions
+- anti-patterns are documented as examples of what not to ship
+
+## Publishing
+
+This repository publishes from `dist/ng-comps`, not from the workspace root.
+
+```bash
+npm run build:lib
+npm run prepare:package
+npm run release:dry-run
+npm run publish:npm
+```
+
+## Important Limitation
+
+Using `ng-comps` does not make an application automatically conformant with WCAG or EN 301 549.
+Final conformance still depends on product copy, content, workflows, application state management, custom wrappers, and consumer integration decisions.

package/angular.json

@@ -0,0 +1,105 @@
+{
+  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
+  "version": 1,
+  "cli": {
+    "packageManager": "npm",
+    "analytics": "186cd70a-0821-4a2c-a822-a3d7739f41eb"
+  },
+  "newProjectRoot": "projects",
+  "projects": {
+    "ng-comps": {
+      "projectType": "application",
+      "schematics": {},
+      "root": "",
+      "sourceRoot": "src",
+      "prefix": "app",
+      "architect": {
+        "build": {
+          "builder": "@angular/build:application",
+          "options": {
+            "browser": "src/main.ts",
+            "tsConfig": "tsconfig.app.json",
+            "assets": [
+              {
+                "glob": "**/*",
+                "input": "public"
+              }
+            ],
+            "styles": [
+              "src/theme/material-theme.scss",
+              "src/styles.css"
+            ]
+          },
+          "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/build:dev-server",
+          "configurations": {
+            "production": {
+              "buildTarget": "ng-comps:build:production"
+            },
+            "development": {
+              "buildTarget": "ng-comps:build:development"
+            }
+          },
+          "defaultConfiguration": "development"
+        },
+        "test": {
+          "builder": "@angular/build:unit-test"
+        },
+        "storybook": {
+          "builder": "@storybook/angular:start-storybook",
+          "options": {
+            "configDir": ".storybook",
+            "browserTarget": "ng-comps:build",
+            "compodoc": true,
+            "compodocArgs": [
+              "-e",
+              "json",
+              "-d",
+              "."
+            ],
+            "port": 6006
+          }
+        },
+        "build-storybook": {
+          "builder": "@storybook/angular:build-storybook",
+          "options": {
+            "configDir": ".storybook",
+            "browserTarget": "ng-comps:build",
+            "compodoc": true,
+            "compodocArgs": [
+              "-e",
+              "json",
+              "-d",
+              "."
+            ],
+            "outputDir": "storybook-static"
+          }
+        }
+      }
+    }
+  }
+}