semmet-angular 0.42.0 → 0.43.0

package/README.en.md

@@ -1,318 +1,5 @@
 # semmet-angular
 
-**Accessible UI delivery dev kit in Angular.**
+The primary English documentation lives in [README.md](./README.md).
 
-Create accessible Angular components, interface blocks, and delivery scaffolds through the CLI.
-
-Semmet Angular helps teams generate, compose, test, verify, and package accessible Angular UI using the Angular CLI ecosystem.
-
-**Generate. Compose. Test. Verify. Package.**
-
-Read the broader product direction in [PRODUCT_VISION.md](./PRODUCT_VISION.md).
-
-Brazilian Portuguese documentation is available in [README.md](./README.md).
-
-`ng generate semmet-angular:accordion my-faq` scaffolds a standalone, signals-based Angular component — `.ts`/`.html`/`.css` — plus `.spec.ts` and `.e2e-spec.ts` smoke tests. The generated component implements a W3C ARIA Authoring Practices Guide pattern for real: correct roles and `aria-*` wiring, the keyboard/focus behavior the pattern requires (arrow-key navigation, focus traps, focus restoration...), and a consistent visual identity out of the box.
-
-## Usage
-
-```
-ng add semmet-angular
-ng generate semmet-angular:accordion my-faq
-ng generate semmet-angular:block section-card
-ng generate semmet-angular:ci
-ng generate semmet-angular:docker
-ng generate semmet-angular:deploy
-```
-
-`ng add semmet-angular` installs the package and configures the delivery workflow once for the target application, including Playwright e2e support, npm scripts, and `npm run verify`. Each generated component is dropped into your project exactly like `ng generate component` would (respecting your `angular.json` project, source root, and selector prefix), and has **zero runtime dependency** on this package — `semmet-angular` is only needed at generation time.
-
-## Layered Architecture
-
-Use isolated components when you need fine-grained control, or compositions when you want to accelerate accessible screens with validated structure.
-
-- **Components**: isolated components such as `button`, `card`, `accordion`, `table`, and `navbar`.
-- **Compositions / Blocks**: ready-made sections such as `section-card`, `section-faq`, `section-pricing`, `section-stats`, `section-table`, `section-form`, `section-tabs`, `section-list-group`, `section-alert`, `section-progress`, `section-carousel`, `header-navbar`, `footer-navigation`, and `command-list`.
-- **Delivery**: `ng add`, `ci`, `docker`, `deploy`, and `verify`.
-
-## Composition Commands
-
-Compositions/blocks generate standalone Angular sections using the matching Semmet components. Generated CSS stays local to the block and uses local spacing tokens to keep landing-page rhythm without injecting global styles into the application.
-
-| Command | Generates | Built from |
-|---|---|---|
-| `ng generate semmet-angular:block hero` | Semantic hero section | Section structure |
-| `ng generate semmet-angular:block section-card` | Card section | `card` |
-| `ng generate semmet-angular:block section-faq` | FAQ section | `accordion` |
-| `ng generate semmet-angular:block section-pricing` | Pricing section | `card` |
-| `ng generate semmet-angular:block section-stats` | Stats section | Section structure |
-| `ng generate semmet-angular:block section-table` | Table section | `table` |
-| `ng generate semmet-angular:block section-form` | Form section | `form` |
-| `ng generate semmet-angular:block section-tabs` | Tabs section | `tabs` |
-| `ng generate semmet-angular:block section-list-group` | Action list section | `list-group` |
-| `ng generate semmet-angular:block section-alert` | Alert section | `alert` |
-| `ng generate semmet-angular:block section-progress` | Progress section | `progress-bar` |
-| `ng generate semmet-angular:block section-carousel` | Carousel section | `carousel` |
-| `ng generate semmet-angular:block header-navbar` | Header navigation | `navbar` |
-| `ng generate semmet-angular:block footer-navigation` | Footer navigation | `navbar` |
-| `ng generate semmet-angular:block command-list` | Command list section | Section structure |
-
-## Generated tests
-
-Every component command generates test files next to the component:
-
-```
-my-faq.ts
-my-faq.html
-my-faq.css
-my-faq.spec.ts
-my-faq.e2e-spec.ts
-```
-
-The unit test uses Angular's `TestBed` to verify the component through its public selector. Interactive components also generate behavior-focused tests for their ARIA state, keyboard flow, value changes, focus management, and open/close behavior. The e2e test uses Playwright and becomes active as soon as the component is mounted in a route or host component. If the component has not been added to any rendered page yet, the generated e2e smoke test is skipped with a clear message instead of failing the whole suite.
-
-After running `ng add semmet-angular`, use:
-
-```
-npm test
-npm run e2e
-npm run e2e:ui
-```
-
-`npm run e2e` runs Playwright against the Angular dev server configured by `playwright.config.ts`; `npm run e2e:ui` opens Playwright's interactive UI.
-
-## GitHub Actions CI
-
-```bash
-ng generate semmet-angular:ci
-```
-
-This command generates `.github/workflows/ci.yml` using the package scripts that already exist in `package.json`. The workflow uses Node 24, detects the package manager by lockfile (`package-lock.json`, `pnpm-lock.yaml`, or `yarn.lock`), installs dependencies, and runs `verify` when available. If `verify` does not exist yet, it runs `build`, `test`, and `e2e` when those scripts exist.
-
-When the project uses Playwright, the CI also installs Chromium with `playwright install --with-deps chromium` and caches `~/.cache/ms-playwright` with `actions/cache`, reducing follow-up run times.
-
-By default, the command does not overwrite an existing workflow. Use `--force` when you want to replace `.github/workflows/ci.yml`.
-
-## Docker Packaging
-
-```bash
-ng generate semmet-angular:docker
-```
-
-This command generates `Dockerfile`, `.dockerignore`, and `nginx.conf` to package the Angular application as an image served by Nginx. The Dockerfile uses Node 24 in the build stage, detects the package manager by lockfile, runs the build, and copies the output configured in `angular.json` to `/usr/share/nginx/html`.
-
-The `nginx.conf` includes SPA fallback with `try_files ... /index.html`. By default, the command does not overwrite existing files; use `--force` to replace the current Docker configuration.
-
-## Guided Deploy
-
-```bash
-ng generate semmet-angular:deploy
-```
-
-The command asks which platform you want to target and generates the minimal configuration for that destination. You can also pass the platform directly:
-
-```bash
-ng generate semmet-angular:deploy --platform=vercel
-ng generate semmet-angular:deploy --platform=netlify
-ng generate semmet-angular:deploy --platform=firebase
-ng generate semmet-angular:deploy --platform=github-pages
-ng generate semmet-angular:deploy --platform=docker
-```
-
-Supported targets: Vercel (`vercel.json`), Netlify (`netlify.toml`), Firebase Hosting (`firebase.json` and `.firebaserc`), GitHub Pages (`.github/workflows/deploy.yml`), and Docker-based deployment (`compose.yml` and `deploy/docker.README.md`). The command detects the build output from `angular.json` when possible and does not overwrite existing files without `--force`.
-
-## Projected content containers
-
-Some generated components are containers: they own the ARIA wiring, keyboard behavior, focus management, and visual shell, while your app owns the content rendered inside them.
-
-`accordion`, `tabs`, `carousel`, `disclosure`, `card`, `button`, `badge`, `navbar`, `table`, and `button-group` use Angular's modern projection pattern with `ng-template`, signal queries, and `NgTemplateOutlet`. This means you can place real app components inside generated components without dynamic component factories.
-
-Example after generating `faq`:
-
-```
-import { Component, signal } from '@angular/core';
-import { Faq, FaqItem } from './faq/faq';
-import { ProfilePanel } from './profile-panel/profile-panel';
-import { SettingsPanel } from './settings-panel/settings-panel';
-
-@Component({
-  selector: 'app-root',
-  imports: [Faq, FaqItem, ProfilePanel, SettingsPanel],
-  templateUrl: './app.html',
-})
-export class App {
-  readonly userId = signal(123);
-
-  reload(): void {}
-}
-```
-
-```
-<app-faq>
-  <ng-template faqItem id="profile" title="Profile" [expanded]="true">
-    <app-profile-panel />
-  </ng-template>
-
-  <ng-template faqItem id="settings" title="Settings">
-    <app-settings-panel [userId]="userId()" (saved)="reload()" />
-  </ng-template>
-</app-faq>
-```
-
-The same pattern applies to `tabs`, `carousel`, and `disclosure`:
-
-```
-<app-settings-tabs>
-  <ng-template settingsTabsItem id="profile" label="Profile" [selected]="true">
-    <app-profile-panel />
-  </ng-template>
-</app-settings-tabs>
-
-<app-featured-carousel>
-  <ng-template featuredCarouselSlide id="intro" label="Introduction">
-    <app-intro-slide />
-  </ng-template>
-</app-featured-carousel>
-
-<app-details label="Show profile details" [(expanded)]="profileDetailsOpen">
-  <ng-template detailsContent>
-    <app-profile-details [userId]="userId()" />
-  </ng-template>
-</app-details>
-```
-
-By default, projected panel/slide content is preserved after its first render. Set `[preserveContent]="false"` on the generated container to destroy inactive content when it closes or becomes inactive.
-
-The smaller structural components keep their simple input APIs and add safe slots where the generated component still owns the accessible structure:
-
-```
-<app-product-card title="Accessible components">
-  <ng-template productCardMedia>
-    <img src="/assets/card.png" alt="Generated Angular component preview" />
-  </ng-template>
-
-  <ng-template productCardDescription>
-    Generate Angular components with ARIA, keyboard behavior and signals.
-  </ng-template>
-
-  <ng-template productCardActions>
-    <a href="/docs">Read docs</a>
-  </ng-template>
-</app-product-card>
-
-<app-save-button label="Save">
-  <ng-template saveButtonLeading>
-    <app-save-icon aria-hidden="true" />
-  </ng-template>
-</app-save-button>
-
-<app-status-badge accessibleLabel="Build passed">
-  <ng-template statusBadgeLabel>Passed</ng-template>
-</app-status-badge>
-
-<app-main-navbar brand="Acme">
-  <ng-template mainNavbarActions>
-    <a href="/account">Account</a>
-  </ng-template>
-</app-main-navbar>
-
-<app-results-table caption="Quarterly revenue" [rows]="results">
-  <ng-template resultsTableEmpty>No revenue results yet.</ng-template>
-</app-results-table>
-
-<app-view-switcher [items]="views">
-  <ng-template viewSwitcherItem let-item>
-    {{ item.label }}
-  </ng-template>
-</app-view-switcher>
-```
-
-## Components, Blocks, and Delivery (43)
-
-**Overlays & disclosure**
-
-| Command | Generates | Keyboard/focus behavior implemented |
-|---|---|---|
-| `ng generate semmet-angular:accordion <name>` | [Accordion](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/) | Click/Enter/Space toggle; Up/Down/Home/End moves focus between headers |
-| `ng generate semmet-angular:disclosure <name>` | [Disclosure](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/) | Click/Enter/Space toggle |
-| `ng generate semmet-angular:dialog <name>` | [Dialog (Modal)](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) | Focus moves in on open; Tab/Shift+Tab focus trap; Escape closes; focus returns to trigger on close |
-| `ng generate semmet-angular:alert-dialog <name>` | [Alert Dialog](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/) | Same focus trap as Dialog; initial focus on the least destructive action (Cancel) |
-| `ng generate semmet-angular:offcanvas <name>` | Offcanvas / Drawer | Modal dialog semantics; focus moves in; Tab/Shift+Tab focus trap; Escape/backdrop close; focus returns to trigger |
-| `ng generate semmet-angular:popover <name>` | Popover | Disclosure trigger with `aria-haspopup="dialog"`; Escape closes; outside click dismisses |
-| `ng generate semmet-angular:tooltip <name>` | [Tooltip](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/) | Shows on hover **and** focus (required for keyboard users); hides on blur/mouseleave/Escape |
-| `ng generate semmet-angular:menu-button <name>` | [Menu Button](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/) | Up/Down/Home/End/Escape inside the menu; closes on outside click; focus returns to the trigger |
-| `ng generate semmet-angular:button <name>` | Button | Native `<button>` with variant, size, disabled, busy, optional pressed state, and safe label/icon slots |
-| `ng generate semmet-angular:button-group <name>` | Button Group | Native grouped buttons with `role="group"`, optional `aria-pressed` toggle state, and safe item-label projection |
-| `ng generate semmet-angular:close-button <name>` | Close Button | Native icon button with required accessible label |
-
-**Navigation & structure**
-
-| Command | Generates | Keyboard/focus behavior implemented |
-|---|---|---|
-| `ng generate semmet-angular:tabs <name>` | [Tabs](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/) | Automatic activation; Left/Right/Home/End with roving `tabindex` |
-| `ng generate semmet-angular:breadcrumb <name>` | [Breadcrumb](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/) | Static — plain links + `aria-current="page"` |
-| `ng generate semmet-angular:navigation-menu <name>` | [Navigation Menu (Disclosure)](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/) | Click/Enter/Space toggles the submenu — deliberately avoids `role="menu"`, reserved for app-style menus |
-| `ng generate semmet-angular:navbar <name>` | Navbar | Semantic `nav`/list/link structure with responsive disclosure toggle, `aria-current`, and safe brand/action slots |
-| `ng generate semmet-angular:pagination <name>` | Pagination | Working page state; Previous/Next disable at the boundaries |
-| `ng generate semmet-angular:skip-link <name>` | [Skip Link](https://www.w3.org/WAI/WCAG21/Techniques/general/G1) | Hidden until focused, per the standard skip-link pattern |
-| `ng generate semmet-angular:landmarks <name>` | [Landmarks (Page Skeleton)](https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/) | Content-projected layout wrapper (`header`/`nav`/`main`/`aside`/`footer` slots) |
-| `ng generate semmet-angular:tree-view <name>` | [Tree View](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/) | Up/Down/Left/Right/Home/End/Enter with roving `tabindex` across visible nodes |
-| `ng generate semmet-angular:toolbar <name>` | [Toolbar](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/) | Left/Right/Home/End with roving `tabindex` |
-| `ng generate semmet-angular:card <name>` | Card | Semantic `<article>` with owned heading/description/action/media structure and safe projection slots |
-| `ng generate semmet-angular:list-group <name>` | List Group | Semantic list structure with action items, active state, optional badges, and disabled states |
-| `ng generate semmet-angular:table <name>` | [Table](https://www.w3.org/WAI/ARIA/apg/patterns/table/) | Caption + scoped headers, input rows, and safe caption/empty-state slots |
-
-**Forms & inputs**
-
-| Command | Generates | Keyboard/focus behavior implemented |
-|---|---|---|
-| `ng generate semmet-angular:form <name>` | Form | Native `<form>` with labeled controls, inline validation, and status messaging |
-| `ng generate semmet-angular:input <name>` | Input | Native `<input>` with label, hint, validation message wiring, and signal-backed value |
-| `ng generate semmet-angular:select <name>` | Select | Native `<select>` with label, hint, validation message wiring, and signal-backed value |
-| `ng generate semmet-angular:input-group <name>` | Input Group | Native `<input>` with prefix/suffix addons announced via `aria-describedby` and optional action button |
-| `ng generate semmet-angular:textarea <name>` | Textarea | Native `<textarea>` with label, hint, counter, validation message wiring, and signal-backed value |
-| `ng generate semmet-angular:checkbox <name>` | [Checkbox](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/) | Click/Enter/Space toggle |
-| `ng generate semmet-angular:radio-group <name>` | [Radio Group](https://www.w3.org/WAI/ARIA/apg/patterns/radio/) | Up/Down/Left/Right/Home/End move focus and selection together |
-| `ng generate semmet-angular:switch <name>` | [Switch](https://www.w3.org/WAI/ARIA/apg/patterns/switch/) | Native `<button>` — Click/Enter/Space toggle |
-| `ng generate semmet-angular:combobox <name>` | [Combobox](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) | Live filtering; Up/Down/Home/End/Enter/Escape via `aria-activedescendant` |
-| `ng generate semmet-angular:listbox <name>` | [Listbox](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/) | Up/Down/Home/End via `aria-activedescendant` |
-| `ng generate semmet-angular:slider <name>` | [Slider](https://www.w3.org/WAI/ARIA/apg/patterns/slider/) | Arrow keys/PageUp/PageDown/Home/End, plus pointer drag |
-| `ng generate semmet-angular:spinbutton <name>` | [Spinbutton](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/) | Up/Down/Home/End, plus increment/decrement buttons |
-| `ng generate semmet-angular:meter <name>` | [Meter](https://www.w3.org/TR/wai-aria-1.2/#meter) | Static — native `<meter>` bound to a signal |
-| `ng generate semmet-angular:progress-bar <name>` | [Progress Bar](https://www.w3.org/TR/wai-aria-1.2/#progressbar) | Native `<progress>` bound to a signal |
-
-**Feedback & media**
-
-| Command | Generates | Keyboard/focus behavior implemented |
-|---|---|---|
-| `ng generate semmet-angular:alert <name>` | [Alert](https://www.w3.org/WAI/ARIA/apg/patterns/alert/) | Dismissible assertive live region |
-| `ng generate semmet-angular:toast <name>` | Toast / Notification | Auto-dismisses after 5s (cleaned up via `DestroyRef`); dismissible early |
-| `ng generate semmet-angular:skeleton <name>` | Skeleton Loading | Composable loading placeholder for text, media, circles, cards, and custom blocks |
-| `ng generate semmet-angular:badge <name>` | Badge | Compact status label/counter with decorative mode, optional accessible label, and safe label projection |
-| `ng generate semmet-angular:spinner <name>` | Spinner | Loading status with `role="status"`, visually hidden label by default, and reduced-motion support |
-| `ng generate semmet-angular:carousel <name>` | [Carousel](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/) | Previous/Next controls; `aria-live="polite"` slide region |
-
-## What every generated component looks like
-
-- Standalone (implicit — no `standalone: true` needed, matches Angular's current default).
-- State via `signal()`/`computed()`, not plain class fields.
-- Templates use the built-in control flow (`@for`, `@if`), not `*ngFor`/`*ngIf`.
-- No `.component` suffix on file names or class names (`accordion.ts`, `export class Accordion`), matching the current `ng generate component` convention.
-- A unique per-instance id (`<name>-0`, `<name>-1`, ...) so multiple instances of the same generated component never collide on `id`/`aria-controls`/`aria-labelledby`.
-- A generated unit test (`.spec.ts`) and Playwright e2e smoke test (`.e2e-spec.ts`) so the component starts life with a test surface.
-
-## Visual identity
-
-Every generated component shares the same Material Design-informed look — clean surfaces, subtle elevation, a consistent radius/motion scale — using its own color palette (not Material's colors, to stay clear of any lookalike/plagiarism concern). The tokens are plain CSS custom properties declared on each component's `:host` (e.g. `--semmet-color-primary`, `--semmet-radius-md`, `--semmet-elevation-1`), so you can either use the defaults as-is or override the whole family from a global stylesheet without touching the generated files.
-
-## Options
-
-Every component command accepts the same three options (same as `ng generate component`):
-
-- `name` (required, positional) — component name.
-- `project` — target project; defaults to the current/default project.
-- `path` — target directory; defaults to the project's `src/app`.
-
-## License
-
-MIT
+Keep AI-agent guidance in [AI_USAGE_GUIDE.md](./AI_USAGE_GUIDE.md).