semmet-angular 0.44.0 → 0.46.0

package/README.md

@@ -2,6 +2,8 @@
 
 **Accessible Angular UI generation for Angular applications.**
 
+> **AI agents:** before generating or editing code with this library, read [AI_USAGE_GUIDE.md](./AI_USAGE_GUIDE.md). It has operational rules for Figma-to-code workflows, a Figma-pattern-to-command mapping table, and what is safe to change vs. accessibility-critical.
+
 Semmet Angular is a collection of Angular CLI schematics that generate accessible, editable application code: components, starter blocks, tests, and delivery scaffolds.
 
 The generated code belongs to the consuming project. There is no Semmet runtime UI package to import at runtime; `semmet-angular` is only needed when generating files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "semmet-angular",
-  "version": "0.44.0",
+  "version": "0.46.0",
   "description": "Accessible UI delivery dev kit in Angular: schematics that generate components, compositions, tests, and delivery scaffolds as native editable Angular code.",
   "publisher": "danilodevsilva",
   "license": "MIT",

package/src/accordion/files/__name@dasherize__/__name@dasherize__.css.template

@@ -1,39 +0,0 @@
-:host {
-  display: block;
-}
-
-h3 {
-  margin: 0;
-}
-
-button {
-  display: flex;
-  align-items: center;
-  width: 100%;
-  font: inherit;
-  color: inherit;
-  background: none;
-  border: none;
-  cursor: pointer;
-  text-align: left;
-}
-
-button:focus-visible {
-  outline: 2px solid currentColor;
-  outline-offset: 2px;
-}
-
-button::after {
-  content: '';
-  width: 0.5rem;
-  height: 0.5rem;
-  margin-left: auto;
-  flex-shrink: 0;
-  border-right: 2px solid currentColor;
-  border-bottom: 2px solid currentColor;
-  transform: rotate(45deg);
-}
-
-button[aria-expanded='true']::after {
-  transform: rotate(-135deg);
-}

package/src/accordion/files/__name@dasherize__/__name@dasherize__.e2e-spec.ts.template

@@ -4,37 +4,36 @@ test.describe('<%= classify(name) %>', () => {
   test('toggles mounted accordion panels and keeps disabled headers stable', async ({ page }) => {
     await page.goto('/');
 
-    const component = page.locator('<%= selector %>').first();
+    const component = page.locator('[<%= camelize(name) %>]').first();
     test.skip(
       (await component.count()) === 0,
-      'Mount <<%= selector %> /> in a route or host component to enable this generated e2e test.'
+      'Mount an element with [<%= camelize(name) %>] in a route or host component to enable this generated e2e test.'
     );
 
     await expect(component).toBeVisible();
 
-    const buttons = component.getByRole('button');
-    const enabledButton = buttons.filter({ hasText: /settings|details|show|open/i }).first();
-    const targetButton = (await enabledButton.count()) > 0 ? enabledButton : buttons.filter({ hasNotText: /billing/i }).nth(1);
-
+    const headers = component.locator('[<%= camelize(name) %>Header]');
     test.skip(
-      (await targetButton.count()) === 0,
-      'Mount at least two enabled accordion headers to enable the generated accordion interaction e2e test.'
+      (await headers.count()) < 2,
+      'Mount at least two accordion headers to enable the generated accordion interaction e2e test.'
     );
 
-    await expect(targetButton).toHaveAttribute('aria-controls', /.+/);
-    const controls = await targetButton.getAttribute('aria-controls');
+    const targetHeader = headers.nth(1);
+
+    await expect(targetHeader).toHaveAttribute('aria-controls', /.+/);
+    const controls = await targetHeader.getAttribute('aria-controls');
     const panel = page.locator(`#${controls}`);
 
-    await targetButton.click();
-    await expect(targetButton).toHaveAttribute('aria-expanded', 'true');
+    await targetHeader.click();
+    await expect(targetHeader).toHaveAttribute('aria-expanded', 'true');
     await expect(panel).toBeVisible();
 
-    await targetButton.click();
-    await expect(targetButton).toHaveAttribute('aria-expanded', 'false');
+    await targetHeader.click();
+    await expect(targetHeader).toHaveAttribute('aria-expanded', 'false');
 
-    const disabledButton = component.getByRole('button', { disabled: true }).first();
-    if ((await disabledButton.count()) > 0) {
-      await expect(disabledButton).toHaveAttribute('aria-expanded', 'false');
+    const disabledHeader = component.locator('[<%= camelize(name) %>Header][aria-disabled="true"]').first();
+    if ((await disabledHeader.count()) > 0) {
+      await expect(disabledHeader).toHaveAttribute('aria-expanded', 'false');
     }
   });
 });

package/src/accordion/files/__name@dasherize__/__name@dasherize__.html.template

@@ -1,43 +1,23 @@
 <!-- Semmet Angular: Accordion — https://www.w3.org/WAI/ARIA/apg/patterns/accordion/ -->
 <!--
 Usage from a parent component template:
-Import <%= classify(name) %> and <%= classify(name) %>Item in that parent component.
+Import <%= classify(name) %>, <%= classify(name) %>Header and <%= classify(name) %>Panel
+in that parent component. This directive set never owns markup: bring your own wrapper,
+heading level and panel content, in whatever structure the layout needs.
 
-<<%= selector %>>
-  <ng-template <%= camelize(name) %>Item id="profile" title="Profile" [expanded]="true">
+<div <%= camelize(name) %>>
+  <h3>
+    <button type="button" <%= camelize(name) %>Header value="profile" [expanded]="true">Profile</button>
+  </h3>
+  <div <%= camelize(name) %>Panel value="profile">
     <app-profile-panel />
-  </ng-template>
-
-  <ng-template <%= camelize(name) %>Item id="settings" title="Settings">
-    <app-settings-panel [userId]="userId()" (saved)="reload()" />
-  </ng-template>
-</<%= selector %>>
+  </div>
 
-Set [preserveContent]="false" on <<%= selector %>> to destroy panel content when closed.
--->
-@for (item of items(); track item.id(); let i = $index) {
   <h3>
-    <button
-      #headerButton
-      type="button"
-      [disabled]="item.disabled()"
-      [attr.aria-expanded]="isExpanded(item.id())"
-      [attr.aria-controls]="instanceId + '-panel-' + item.id()"
-      [id]="instanceId + '-header-' + item.id()"
-      (click)="toggle(item)"
-      (keydown)="navigateHeaders($event)"
-    >
-      {{ item.title() }}
-    </button>
+    <button type="button" <%= camelize(name) %>Header value="settings">Settings</button>
   </h3>
-  <div
-    [id]="instanceId + '-panel-' + item.id()"
-    role="region"
-    [attr.aria-labelledby]="instanceId + '-header-' + item.id()"
-    [hidden]="!isExpanded(item.id())"
-  >
-    @if (shouldRender(item.id())) {
-      <ng-container [ngTemplateOutlet]="item.templateRef" />
-    }
+  <div <%= camelize(name) %>Panel value="settings">
+    <app-settings-panel [userId]="userId()" (saved)="reload()" />
   </div>
-}
+</div>
+-->

package/src/accordion/files/__name@dasherize__/__name@dasherize__.spec.ts.template

@@ -1,31 +1,38 @@
 import { Component } from '@angular/core';
 import { ComponentFixture, TestBed } from '@angular/core/testing';
-import { <%= classify(name) %>, <%= classify(name) %>Item } from './<%= dasherize(name) %>';
+
+import {
+  <%= classify(name) %>,
+  <%= classify(name) %>Header,
+  <%= classify(name) %>Panel,
+} from './<%= dasherize(name) %>';
 
 @Component({
-  imports: [<%= classify(name) %>, <%= classify(name) %>Item],
+  imports: [<%= classify(name) %>, <%= classify(name) %>Header, <%= classify(name) %>Panel],
   template: `
-    <<%= selector %> [preserveContent]="preserveContent">
-      <ng-template <%= camelize(name) %>Item id="profile" title="Profile" [expanded]="true">
-        <p>Profile content</p>
-      </ng-template>
-
-      <ng-template <%= camelize(name) %>Item id="settings" title="Settings">
-        <p>Settings content</p>
-      </ng-template>
-
-      <ng-template <%= camelize(name) %>Item id="billing" title="Billing" disabled>
-        <p>Billing content</p>
-      </ng-template>
-    </<%= selector %>>
+    <div <%= camelize(name) %>>
+      @for (item of items; track item.id) {
+        <h3>
+          <button type="button" <%= camelize(name) %>Header [value]="item.id" [expanded]="item.expanded" [disabled]="item.disabled">
+            {{ item.title }}
+          </button>
+        </h3>
+        <div <%= camelize(name) %>Panel [value]="item.id">{{ item.title }} content</div>
+      }
+    </div>
   `,
 })
 class HostComponent {
-  preserveContent = true;
+  readonly items = [
+    { id: 'profile', title: 'Profile', expanded: true, disabled: false },
+    { id: 'settings', title: 'Settings', expanded: false, disabled: false },
+    { id: 'billing', title: 'Billing', expanded: false, disabled: true },
+  ];
 }
 
 describe('<%= classify(name) %>', () => {
   let fixture: ComponentFixture<HostComponent>;
+  let host: HTMLElement;
 
   beforeEach(async () => {
     await TestBed.configureTestingModule({
@@ -34,91 +41,74 @@ describe('<%= classify(name) %>', () => {
 
     fixture = TestBed.createComponent(HostComponent);
     fixture.detectChanges();
+    host = fixture.nativeElement as HTMLElement;
   });
 
-  function buttons(): HTMLButtonElement[] {
-    return Array.from(fixture.nativeElement.querySelectorAll('button'));
+  function headers(): HTMLButtonElement[] {
+    return Array.from(host.querySelectorAll('button'));
   }
 
   function panels(): HTMLElement[] {
-    return Array.from(fixture.nativeElement.querySelectorAll('[role="region"]'));
+    return Array.from(host.querySelectorAll('[role="region"]'));
   }
 
-  it('renders projected accordion items with ARIA relationships', () => {
-    const [profileButton, settingsButton] = buttons();
+  it('decorates consumer-owned markup with header/region ARIA relationships', () => {
+    const [profileHeader, settingsHeader] = headers();
     const [profilePanel, settingsPanel] = panels();
 
-    expect(profileButton.textContent?.trim()).toBe('Profile');
-    expect(profileButton.getAttribute('aria-expanded')).toBe('true');
-    expect(profileButton.getAttribute('aria-controls')).toBe(profilePanel.id);
-    expect(profilePanel.getAttribute('aria-labelledby')).toBe(profileButton.id);
+    expect(profileHeader.getAttribute('aria-expanded')).toBe('true');
+    expect(profileHeader.getAttribute('aria-controls')).toBe(profilePanel.id);
+    expect(profilePanel.getAttribute('aria-labelledby')).toBe(profileHeader.id);
     expect(profilePanel.hidden).toBe(false);
 
-    expect(settingsButton.textContent?.trim()).toBe('Settings');
-    expect(settingsButton.getAttribute('aria-expanded')).toBe('false');
-    expect(settingsButton.getAttribute('aria-controls')).toBe(settingsPanel.id);
+    expect(settingsHeader.getAttribute('aria-expanded')).toBe('false');
     expect(settingsPanel.hidden).toBe(true);
   });
 
-  it('toggles an enabled item with click', () => {
-    const [, settingsButton] = buttons();
+  it('toggles an enabled header with click and keeps panel content mounted', () => {
+    const [, settingsHeader] = headers();
     const [, settingsPanel] = panels();
 
-    settingsButton.click();
+    settingsHeader.click();
     fixture.detectChanges();
 
-    expect(settingsButton.getAttribute('aria-expanded')).toBe('true');
+    expect(settingsHeader.getAttribute('aria-expanded')).toBe('true');
     expect(settingsPanel.hidden).toBe(false);
     expect(settingsPanel.textContent).toContain('Settings content');
 
-    settingsButton.click();
+    settingsHeader.click();
     fixture.detectChanges();
 
-    expect(settingsButton.getAttribute('aria-expanded')).toBe('false');
+    expect(settingsHeader.getAttribute('aria-expanded')).toBe('false');
     expect(settingsPanel.hidden).toBe(true);
+    expect(settingsPanel.textContent).toContain('Settings content');
   });
 
-  it('does not toggle disabled items', () => {
-    const disabledButton = buttons()[2];
+  it('does not toggle disabled headers', () => {
+    const disabledHeader = headers()[2];
     const disabledPanel = panels()[2];
 
-    expect(disabledButton.disabled).toBe(true);
-    expect(disabledButton.getAttribute('aria-expanded')).toBe('false');
-
-    disabledButton.click();
+    disabledHeader.click();
     fixture.detectChanges();
 
-    expect(disabledButton.getAttribute('aria-expanded')).toBe('false');
+    expect(disabledHeader.getAttribute('aria-disabled')).toBe('true');
+    expect(disabledHeader.getAttribute('aria-expanded')).toBe('false');
     expect(disabledPanel.hidden).toBe(true);
   });
 
-  it('keeps closed content after first render when preserveContent is enabled', () => {
-    const [, settingsButton] = buttons();
-    const [, settingsPanel] = panels();
-
-    settingsButton.click();
-    fixture.detectChanges();
-    settingsButton.click();
-    fixture.detectChanges();
-
-    expect(settingsPanel.hidden).toBe(true);
-    expect(settingsPanel.textContent).toContain('Settings content');
-  });
-
   it('moves focus between headers with arrow, Home, and End keys', () => {
-    const [profileButton, settingsButton] = buttons();
+    const [profileHeader, settingsHeader] = headers();
 
-    profileButton.focus();
-    profileButton.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }));
+    profileHeader.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }));
     fixture.detectChanges();
-    expect(document.activeElement).toBe(settingsButton);
+    expect(document.activeElement).toBe(settingsHeader);
 
-    settingsButton.dispatchEvent(new KeyboardEvent('keydown', { key: 'End', bubbles: true }));
+    settingsHeader.dispatchEvent(new KeyboardEvent('keydown', { key: 'End', bubbles: true }));
     fixture.detectChanges();
-    expect(document.activeElement).toBe(settingsButton);
+    expect(document.activeElement).toBe(settingsHeader);
 
-    settingsButton.dispatchEvent(new KeyboardEvent('keydown', { key: 'Home', bubbles: true }));
+    settingsHeader.dispatchEvent(new KeyboardEvent('keydown', { key: 'Home', bubbles: true }));
     fixture.detectChanges();
-    expect(document.activeElement).toBe(profileButton);
+    expect(document.activeElement).toBe(profileHeader);
   });
 });

package/src/accordion/files/__name@dasherize__/__name@dasherize__.ts.template

@@ -1,106 +1,56 @@
-import { NgTemplateOutlet } from '@angular/common';
-import {
-  Component,
-  Directive,
-  ElementRef,
-  TemplateRef,
-  booleanAttribute,
-  computed,
-  contentChildren,
-  inject,
-  input,
-  signal,
-  viewChildren,
-} from '@angular/core';
-
-type <%= classify(name) %>ItemId = string | number;
+import { Directive, ElementRef, booleanAttribute, computed, contentChildren, inject, input, model } from '@angular/core';
+
+type <%= classify(name) %>Id = string;
 
 let nextId = 0;
-let nextItemId = 0;
 
 @Directive({
-  selector: 'ng-template[<%= camelize(name) %>Item]',
-})
-export class <%= classify(name) %>Item {
-  readonly templateRef = inject<TemplateRef<unknown>>(TemplateRef);
-
-  readonly id = input<<%= classify(name) %>ItemId>(`<%= dasherize(name) %>-item-${nextItemId++}`);
-  readonly title = input.required<string>();
-  readonly expanded = input(false, { transform: booleanAttribute });
-  readonly disabled = input(false, { transform: booleanAttribute });
-}
-
-@Component({
-  selector: '<%= selector %>',
-  imports: [NgTemplateOutlet],
-  templateUrl: './<%= dasherize(name) %>.html',
-  styleUrl: './<%= dasherize(name) %>.css',
+  selector: '[<%= camelize(name) %>]',
+  exportAs: '<%= camelize(name) %>',
 })
 export class <%= classify(name) %> {
-  private readonly headerButtons = viewChildren<ElementRef<HTMLButtonElement>>('headerButton');
-
-  protected readonly items = contentChildren(<%= classify(name) %>Item);
-  protected readonly instanceId = `<%= dasherize(name) %>-${nextId++}`;
-  readonly preserveContent = input(true, { transform: booleanAttribute });
+  private readonly instanceId = `<%= dasherize(name) %>-${nextId++}`;
+  private readonly headers = contentChildren(<%= classify(name) %>Header, { descendants: true });
 
-  private readonly renderedIds = signal<ReadonlySet<<%= classify(name) %>ItemId>>(new Set());
-  private readonly userExpandedIds = signal<ReadonlySet<<%= classify(name) %>ItemId> | null>(null);
+  readonly expandedIds = model<ReadonlySet<<%= classify(name) %>Id> | null>(null);
 
-  private readonly expandedIds = computed<ReadonlySet<<%= classify(name) %>ItemId>>(() => {
-    const userExpandedIds = this.userExpandedIds();
-    if (userExpandedIds) {
-      return userExpandedIds;
+  private readonly resolvedExpandedIds = computed<ReadonlySet<<%= classify(name) %>Id>>(() => {
+    const expandedIds = this.expandedIds();
+    if (expandedIds) {
+      return expandedIds;
     }
 
     return new Set(
-      this.items()
-        .filter((item) => item.expanded())
-        .map((item) => item.id()),
+      this.headers()
+        .filter((header) => header.expanded())
+        .map((header) => header.value()),
     );
   });
 
-  protected isExpanded(id: <%= classify(name) %>ItemId): boolean {
-    return this.expandedIds().has(id);
-  }
-
-  protected shouldRender(id: <%= classify(name) %>ItemId): boolean {
-    return this.isExpanded(id) || (this.preserveContent() && this.renderedIds().has(id));
+  isExpanded(value: <%= classify(name) %>Id): boolean {
+    return this.resolvedExpandedIds().has(value);
   }
 
-  protected toggle(item: <%= classify(name) %>Item): void {
-    if (item.disabled()) {
+  toggle(header: <%= classify(name) %>Header): void {
+    if (header.disabled()) {
       return;
     }
 
-    const id = item.id();
-    const next = new Set(this.expandedIds());
-    if (next.has(id)) {
-      this.markRendered(id);
-      next.delete(id);
+    const value = header.value();
+    const next = new Set(this.resolvedExpandedIds());
+    if (next.has(value)) {
+      next.delete(value);
     } else {
-      next.add(id);
-      this.markRendered(id);
+      next.add(value);
     }
-    this.userExpandedIds.set(next);
-  }
 
-  private markRendered(id: <%= classify(name) %>ItemId): void {
-    const renderedIds = this.renderedIds();
-    if (renderedIds.has(id)) {
-      return;
-    }
-
-    this.renderedIds.set(new Set(renderedIds).add(id));
+    this.expandedIds.set(next);
   }
 
   // Up/Down/Home/End move focus between headers — optional but APG-recommended keyboard support.
-  protected navigateHeaders(event: KeyboardEvent): void {
-    const buttons = this.headerButtons().filter((button) => !button.nativeElement.disabled);
-    if (buttons.length === 0) {
-      return;
-    }
-
-    const index = buttons.findIndex((button) => button.nativeElement === event.currentTarget);
+  navigate(current: <%= classify(name) %>Header, event: KeyboardEvent): void {
+    const headers = this.headers().filter((header) => !header.disabled());
+    const index = headers.indexOf(current);
     if (index === -1) {
       return;
     }
@@ -108,22 +58,78 @@ export class <%= classify(name) %> {
     let nextIndex: number;
     switch (event.key) {
       case 'ArrowDown':
-        nextIndex = (index + 1) % buttons.length;
+        nextIndex = (index + 1) % headers.length;
         break;
       case 'ArrowUp':
-        nextIndex = (index - 1 + buttons.length) % buttons.length;
+        nextIndex = (index - 1 + headers.length) % headers.length;
         break;
       case 'Home':
         nextIndex = 0;
         break;
       case 'End':
-        nextIndex = buttons.length - 1;
+        nextIndex = headers.length - 1;
         break;
       default:
         return;
     }
 
     event.preventDefault();
-    buttons[nextIndex].nativeElement.focus();
+    headers[nextIndex]?.focus();
+  }
+
+  headerDomId(value: <%= classify(name) %>Id): string {
+    return `${this.instanceId}-header-${value}`;
   }
+
+  panelDomId(value: <%= classify(name) %>Id): string {
+    return `${this.instanceId}-panel-${value}`;
+  }
+}
+
+@Directive({
+  selector: '[<%= camelize(name) %>Header]',
+  exportAs: '<%= camelize(name) %>Header',
+  host: {
+    '[id]': 'root.headerDomId(value())',
+    '[attr.aria-expanded]': 'open()',
+    '[attr.aria-controls]': 'root.panelDomId(value())',
+    '[attr.aria-disabled]': 'disabled() ? "true" : null',
+    '[attr.tabindex]': 'disabled() ? -1 : null',
+    '(click)': 'toggle()',
+    '(keydown)': 'root.navigate(this, $event)',
+  },
+})
+export class <%= classify(name) %>Header {
+  protected readonly root = inject(<%= classify(name) %>);
+  private readonly elementRef = inject<ElementRef<HTMLElement>>(ElementRef);
+
+  readonly value = input.required<<%= classify(name) %>Id>();
+  readonly expanded = input(false, { transform: booleanAttribute });
+  readonly disabled = input(false, { transform: booleanAttribute });
+  readonly open = computed(() => this.root.isExpanded(this.value()));
+
+  toggle(): void {
+    this.root.toggle(this);
+  }
+
+  focus(): void {
+    this.elementRef.nativeElement.focus();
+  }
+}
+
+@Directive({
+  selector: '[<%= camelize(name) %>Panel]',
+  exportAs: '<%= camelize(name) %>Panel',
+  host: {
+    role: 'region',
+    '[id]': 'root.panelDomId(value())',
+    '[attr.aria-labelledby]': 'root.headerDomId(value())',
+    '[hidden]': '!open()',
+  },
+})
+export class <%= classify(name) %>Panel {
+  protected readonly root = inject(<%= classify(name) %>);
+
+  readonly value = input.required<<%= classify(name) %>Id>();
+  readonly open = computed(() => this.root.isExpanded(this.value()));
 }

package/src/accordion/schema.json

@@ -3,7 +3,7 @@
   "$id": "SemmetAngularAccordion",
   "title": "Semmet Angular Accordion Options Schema",
   "type": "object",
-  "description": "Generates a standalone Angular Accordion component (signals-based state, keyboard support) following the W3C ARIA Authoring Practices Guide.",
+  "description": "Generates headless Angular Accordion directives (root, header, panel) with signals-based state and keyboard support, coordinated over consumer-owned markup, following the W3C ARIA Authoring Practices Guide.",
   "additionalProperties": false,
   "properties": {
     "name": {