@lilydesignsystem/angular-menu-picker 0.0.0-stage → 0.1.0

package/menu-picker.component.ts

@@ -0,0 +1,325 @@
+import { NgTemplateOutlet } from "@angular/common";
+import {
+  ChangeDetectionStrategy,
+  Component,
+  Directive,
+  ElementRef,
+  TemplateRef,
+  computed,
+  contentChild,
+  effect,
+  input,
+  model,
+  signal,
+  viewChild,
+} from "@angular/core";
+// Only the trigger button composes a headless primitive. The panel is a disclosure of whatever the
+// app projects into it — links, buttons, forms — so it carries no ARIA menu roles (role="menu" would
+// promise a roving-focus menuitem widget that arbitrary content is not). See spec/index.md §3.
+import { IconButton } from "@lilydesignsystem/angular-headless";
+
+/** Context passed to a custom icon `<ng-template>` (the button icon). */
+export type ChildArgs = {
+  /** Is the panel open? */
+  open: boolean;
+};
+
+let uid = 0;
+/** Stable per-instance id prefix; SSR-safe (no Math.random / Date.now). */
+export function nextMenuPickerId(): string {
+  uid += 1;
+  return `menu-picker-${uid}`;
+}
+
+/** The selector for focusable things inside the panel. */
+export const FOCUSABLE =
+  'a[href], button:not([disabled]), input:not([disabled]):not([type="hidden"]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+/**
+ * Marker for the projected icon template. Gives consumers typed `let-` variables:
+ *
+ * ```html
+ * <lily-menu-picker label="Menu">
+ *   <ng-template lilyMenuPickerIcon let-args>{{ args.open ? "×" : "☰" }}</ng-template>
+ *   …the panel's content…
+ * </lily-menu-picker>
+ * ```
+ */
+@Directive({
+  selector: "ng-template[lilyMenuPickerIcon]",
+  standalone: true,
+})
+export class MenuPickerIcon {
+  static ngTemplateContextGuard(
+    _dir: MenuPickerIcon,
+    _ctx: unknown,
+  ): _ctx is ChildArgs & { $implicit: ChildArgs } {
+    return true;
+  }
+}
+
+/**
+ * MenuPicker — a headless dropdown control.
+ *
+ * A single-icon button (a bundled hamburger SVG) that opens a disclosure panel holding whatever
+ * the app projects into it. It applies nothing to the document and persists nothing. Give the
+ * element a template reference (`#menu`) to call `menu.close()` from the projected content.
+ * See `spec/index.md`.
+ */
+@Component({
+  selector: "lily-menu-picker",
+  standalone: true,
+  exportAs: "lilyMenuPicker",
+  imports: [NgTemplateOutlet, IconButton],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  host: {
+    "(document:click)": "onDocumentClick($event)",
+  },
+  template: `
+    <div
+      #rootEl
+      class="menu-picker {{ className() }}"
+      (focusout)="onRootFocusOut($event)"
+    >
+      <lily-icon-button
+        #buttonEl
+        [label]="label()"
+        baseClass="menu-picker-button"
+        [ariaExpanded]="open()"
+        [ariaControls]="panelId"
+        (click)="onButtonClick(); hoverButton.set(false)"
+        (mouseenter)="onTooltipButtonEnter()"
+        (mouseleave)="hoverButton.set(false)"
+        (focusin)="onTooltipButtonFocusIn()"
+        (focusout)="onTooltipButtonFocusOut()"
+        (keydown)="onButtonKeydown($event); onTooltipKeydown($event)"
+      >
+        @if (iconTemplate(); as tpl) {
+          <ng-container
+            [ngTemplateOutlet]="tpl"
+            [ngTemplateOutletContext]="childContext()"
+          />
+        } @else {
+          <svg
+            class="menu-picker-icon"
+            viewBox="0 0 16 16"
+            width="1.05rem"
+            height="1.05rem"
+            aria-hidden="true"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="1.6"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+          >
+            <path d="M1.5 3.5h13M1.5 8h13M1.5 12.5h13" />
+          </svg>
+        }
+      </lily-icon-button>
+
+      <!-- Purely visual: the same text is already the button's aria-label, so it is not wired
+           with aria-describedby (that would announce the name twice). -->
+      <div
+        class="menu-picker-tooltip"
+        role="tooltip"
+        [id]="tooltipId"
+        [attr.hidden]="tooltipVisible() ? null : ''"
+        (mouseenter)="hoverTooltip.set(true)"
+        (mouseleave)="hoverTooltip.set(false)"
+      >{{ label() }}</div>
+
+      <!-- A named group, not a menu: the content is the app's. The handlers are pure delegation
+           for whatever focusable content the app projects. -->
+      <div
+        #panelEl
+        class="menu-picker-panel"
+        [id]="panelId"
+        role="group"
+        [attr.aria-label]="label() || null"
+        [attr.hidden]="open() ? null : ''"
+        (keydown)="onPanelKeydown($event)"
+        (click)="onPanelClick($event)"
+      >
+        <ng-content />
+      </div>
+    </div>
+  `,
+})
+export class MenuPicker {
+  /** Accessible name for the button, the panel and the tooltip. */
+  readonly label = input.required<string>();
+  /** Is the panel open? Two-way bindable: `[(open)]`. */
+  readonly open = model<boolean>(false);
+  /**
+   * Close the panel when a link, button or `[role="menuitem"]` inside it is activated. Add
+   * `data-menu-picker-keep-open` to an element (or an ancestor) to opt it out. Default `true`.
+   */
+  readonly closeOnSelect = input<boolean>(true);
+  /** Extra CSS class on the root div. */
+  readonly className = input<string>("");
+
+  /** Projected icon template; replaces the default icon when supplied. */
+  protected readonly iconTemplate = contentChild(MenuPickerIcon, { read: TemplateRef });
+
+  private readonly rootRef =
+    viewChild.required<ElementRef<HTMLDivElement>>("rootEl");
+  // A template-ref-variable on a component tag resolves to the component INSTANCE, which is what
+  // is needed to call the headless component's own public `focus()` method.
+  private readonly buttonRef = viewChild.required<IconButton>("buttonEl");
+  private readonly panelRef =
+    viewChild.required<ElementRef<HTMLDivElement>>("panelEl");
+
+  private readonly baseId = nextMenuPickerId();
+  protected readonly panelId = `${this.baseId}-panel`;
+
+  // Tooltip: shown while the pointer is over the button or the tooltip itself (hoverable, WCAG
+  // 1.4.13) or while the button has keyboard focus; Escape dismisses it without moving focus;
+  // never shown while the popup is open, since the popup then explains the control.
+  protected readonly tooltipId = `${this.baseId}-tooltip`;
+  protected readonly hoverButton = signal(false);
+  protected readonly hoverTooltip = signal(false);
+  protected readonly focusButton = signal(false);
+  protected readonly dismissed = signal(false);
+  protected readonly tooltipVisible = computed(
+    () =>
+      !this.open() &&
+      !this.dismissed() &&
+      (this.hoverButton() || this.hoverTooltip() || this.focusButton()),
+  );
+
+  protected onTooltipButtonEnter(): void {
+    this.hoverButton.set(true);
+    this.dismissed.set(false);
+  }
+
+  protected onTooltipButtonFocusIn(): void {
+    // Keyboard focus only: a mouse click also focuses the button in Chromium, and the tooltip
+    // should not stick after a click.
+    try {
+      this.focusButton.set(
+        this.buttonRef().element?.matches(":focus-visible") ?? false,
+      );
+    } catch {
+      this.focusButton.set(true); // engine without :focus-visible — err towards showing
+    }
+  }
+
+  protected onTooltipButtonFocusOut(): void {
+    this.focusButton.set(false);
+    this.dismissed.set(false);
+  }
+
+  protected onTooltipKeydown(event: KeyboardEvent): void {
+    if (event.key === "Escape" && this.tooltipVisible()) this.dismissed.set(true);
+  }
+
+  // WCAG 1.4.13 "dismissable": while the tooltip is visible, Escape works wherever focus is. The
+  // listener exists only while visible; the effect cleanup removes it on hide and on destroy.
+  private readonly tooltipEscapeListener = effect((onCleanup) => {
+    if (!this.tooltipVisible() || typeof document === "undefined") return;
+    const onKey = (event: KeyboardEvent): void => {
+      if (event.key === "Escape") this.dismissed.set(true);
+    };
+    document.addEventListener("keydown", onKey);
+    onCleanup(() => document.removeEventListener("keydown", onKey));
+  });
+
+  protected readonly childContext = computed(() => {
+    const args: ChildArgs = { open: this.open() };
+    return { $implicit: args, ...args };
+  });
+
+  private focusables(): HTMLElement[] {
+    return Array.from(
+      this.panelRef().nativeElement.querySelectorAll<HTMLElement>(FOCUSABLE),
+    );
+  }
+
+  // ---------------------------------------------------------------
+  // Open / close
+  // ---------------------------------------------------------------
+
+  /** Open the panel, optionally focusing its first or last focusable element. */
+  openPanel(focus: "none" | "first" | "last" = "none"): void {
+    this.open.set(true);
+    if (focus === "none") return;
+    // Deferred so the `hidden` attribute is gone before focus is moved.
+    queueMicrotask(() => {
+      const all = this.focusables();
+      (focus === "last" ? all[all.length - 1] : all[0])?.focus({ preventScroll: true });
+    });
+  }
+
+  /** Close the panel; `refocus` returns focus to the trigger. */
+  closePanel(refocus = true): void {
+    if (!this.open()) return;
+    this.open.set(false);
+    if (refocus) queueMicrotask(() => this.buttonRef().focus({ preventScroll: true }));
+  }
+
+  /** Close the panel and return focus to the button. For the projected content to call. */
+  close(): void {
+    this.closePanel();
+  }
+
+  protected onButtonClick(): void {
+    if (this.open()) this.closePanel();
+    else this.openPanel();
+  }
+
+  protected onPanelClick(event: MouseEvent): void {
+    if (!this.closeOnSelect()) return;
+    const target = event.target as Element | null;
+    const hit = target?.closest?.('a[href], button, [role="menuitem"]');
+    if (!hit || !this.panelRef().nativeElement.contains(hit)) return;
+    if (hit.closest("[data-menu-picker-keep-open]")) return;
+    this.closePanel();
+  }
+
+  // ---------------------------------------------------------------
+  // Keyboard
+  // ---------------------------------------------------------------
+
+  protected onButtonKeydown(event: KeyboardEvent): void {
+    if (event.key === "Escape" && this.open()) {
+      event.preventDefault();
+      this.closePanel();
+    } else if (event.key === "ArrowDown") {
+      // Enter and Space already produce a click; the arrows open and move into the panel.
+      event.preventDefault();
+      if (!this.open()) this.openPanel("first");
+      else this.focusables()[0]?.focus({ preventScroll: true });
+    } else if (event.key === "ArrowUp") {
+      event.preventDefault();
+      if (!this.open()) this.openPanel("last");
+      else {
+        const all = this.focusables();
+        all[all.length - 1]?.focus({ preventScroll: true });
+      }
+    }
+  }
+
+  protected onPanelKeydown(event: KeyboardEvent): void {
+    if (event.key === "Escape") {
+      event.preventDefault();
+      this.closePanel();
+    } else if (event.key === "Tab") {
+      // Focus goes to the button FIRST, without cancelling the key, so the browser continues
+      // from the picker's position rather than from <body>.
+      this.buttonRef().focus?.({ preventScroll: true });
+      this.closePanel(false);
+    }
+  }
+
+  protected onRootFocusOut(event: FocusEvent): void {
+    const next = event.relatedTarget as Node | null;
+    if (next && this.rootRef().nativeElement.contains(next)) return;
+    this.closePanel(false);
+  }
+
+  protected onDocumentClick(event: Event): void {
+    if (!this.open()) return;
+    const t = event.target as Node | null;
+    if (t && !this.rootRef().nativeElement.contains(t)) this.closePanel(false);
+  }
+}

package/ng-package.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "./dist",
+  "lib": {
+    "entryFile": "index.ts"
+  },
+  "allowedNonPeerDependencies": [
+    "@lilydesignsystem/angular-headless"
+  ]
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@lilydesignsystem/angular-menu-picker",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "engines": {
+    "node": "=26"
+  },
+  "description": "Lily Design System Angular menu picker: an icon button (a hamburger icon) opening a dropdown of whatever the app provides. Headless, SSR-safe, no CSS.",
+  "dependencies": {
+    "@lilydesignsystem/angular-headless": "^0.2.0"
+  },
+  "peerDependencies": {
+    "@angular/core": ">=20.0.0 <23.0.0",
+    "@angular/common": ">=20.0.0 <23.0.0"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "cd .. && pnpm build",
+    "prepublishOnly": "cd .. && pnpm build"
+  },
+  "keywords": [
+    "lily",
+    "design",
+    "system",
+    "angular",
+    "menu",
+    "hamburger",
+    "dropdown",
+    "picker"
+  ],
+  "author": "Joel Parker Henderson <joel@joelparkerhenderson.com>",
+  "license": "MIT OR Apache-2.0 OR GPL-2.0-only OR GPL-3.0-only OR BSD-3-Clause",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LilyDesignSystem/lily-design-system-angular-helpers.git",
+    "directory": "lily-design-system-angular-menu-picker"
+  },
+  "homepage": "https://lilydesignsystem.com/",
+  "bugs": {
+    "url": "https://github.com/LilyDesignSystem/lily-design-system/issues"
+  }
+}

package/spec/index.md

@@ -0,0 +1,124 @@
+# MenuPicker (Angular) — spec
+
+**Package:** `@lilydesignsystem/angular-menu-picker` · **Canonical contract:** this file; the other seven catalogs port it.
+Topic summary: [spec/menu-picker](../../../spec/menu-picker/index.md).
+
+## 1. Goal
+
+An icon button — a typical **hamburger** (three horizontal lines) — that opens a dropdown panel holding **whatever the app
+provides**: links, buttons, a search form, a small list of settings. It owns the whole interaction: open/close, focus,
+keyboard, tooltip. It owns no content and no words: the panel's content and every accessible name come from the consumer.
+
+## 2. Non-goals
+
+- No default content, no English text, no routing, no data.
+- Not an ARIA menu: the panel is a named group of arbitrary content, so it has no `role="menu"` and no roving focus.
+- Not a site navigation bar (use `BreadcrumbNav`, `SectionNav`) and not a modal dialog (use `Dialog`).
+- No persistence.
+
+## 3. Architectural decisions
+
+- **A disclosure of arbitrary content, not a menu.** `role="menu"` promises a roving-focus `menuitem` widget; arbitrary app
+  content (links, inputs, headings) is not that, and the WAI-ARIA APG's disclosure pattern fits it exactly. The trigger carries
+  `aria-expanded` and `aria-controls`; the panel is a `role="group"` named by `label`.
+- **Only the trigger composes headless** (`IconButton`); the panel is self-built, as in `link-picker` and `share-picker`.
+- **The app provides the panel's content** through `children` (a template, slot, `ChildContent`, children …). It receives
+  `{ open, close }` so its own controls can close the panel.
+- **Closes on select by default.** Activating a link, a button or a `[role="menuitem"]` inside the panel closes it and returns
+  focus to the button. `closeOnSelect={false}` turns that off for the whole panel; an ancestor with
+  `data-menu-picker-keep-open` opts one element (or a region, e.g. a form) out.
+- **Focus is not moved on a click.** A disclosure must not steal focus on open; `ArrowDown`/`ArrowUp` on the button move into
+  the panel's first/last focusable element for keyboard users.
+
+## 4. Public API
+
+### 4.1 Props
+
+| Prop | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `label` | `string` | yes | Accessible name of the button **and** the panel; also the tooltip text. |
+| `[(open)]` | `boolean` (model) | no | Is the panel open? Default `false`. |
+| `closeOnSelect` | `boolean` | no | Close when a link/button/menuitem inside is activated. Default `true`. |
+| `(openChange)` | output `boolean` | no | Emitted whenever the open state changes (the `[(open)]` update). |
+| projected content | `<ng-content>` | no | The panel's content. Call `menu.close()` on a `#menu="lilyMenuPicker"` reference to close it. |
+| `<ng-template lilyMenuPickerIcon>` | context `{ open }` | no | Replaces the hamburger **icon** inside the button. |
+| `className` | `string` | no | Appended to the root class. |
+| `...rest` | | | Spread on the root. |
+
+### 4.2 DOM contract
+
+```html
+<div class="menu-picker {class}">
+  <button class="menu-picker-button" type="button" aria-label="{label}" aria-expanded="false" aria-controls="{id}-panel">
+    <svg class="menu-picker-icon" aria-hidden="true" viewBox="0 0 16 16" …three lines…/>
+  </button>
+  <div class="menu-picker-tooltip" role="tooltip" id="{id}-tooltip" hidden>{label}</div>
+  <div class="menu-picker-panel" id="{id}-panel" role="group" aria-label="{label}" hidden>
+    …whatever the app provides…
+  </div>
+</div>
+```
+
+### 4.3 Re-exports
+
+`MenuPicker`, `MenuPickerIcon`, `nextMenuPickerId`, `FOCUSABLE`, type `ChildArgs`.
+
+**Differences from the Svelte contract (idiom, not behaviour).** Angular renders the same DOM in a `<lily-menu-picker>` element; the bindable `open` is a `model()` (`[(open)]`), the content is projected, the icon override is a projected `<ng-template lilyMenuPickerIcon>`, `class` is the `className` input, `close()` is a public method reachable through `exportAs: "lilyMenuPicker"`, and ids come from a module counter.
+
+## 5. Behaviour
+
+### 5.1 Activation
+
+Click toggles the panel; focus stays on the button. Activating a link, button or menuitem inside the panel closes it (see
+§3) and returns focus to the button.
+
+### 5.2 Keyboard
+
+- Button: `Enter`/`Space` toggle; `ArrowDown` opens and focuses the panel's first focusable element (or moves into an open
+  panel); `ArrowUp` focuses the last; `Escape` closes an open panel.
+- Panel: `Escape` closes and returns focus to the button; `Tab` closes and moves on (focus goes to the button first so the
+  browser continues from the picker's position). Everything else is the app's content's own behaviour.
+- Clicking outside, or focus leaving the picker, closes the panel.
+
+### 5.3 Tooltip
+
+`<div class="menu-picker-tooltip" role="tooltip" hidden>` holds the button's `label`. Visible while the pointer is over the
+button or the tooltip (hoverable) or while the button has keyboard focus (`:focus-visible`); `Escape` dismisses it wherever
+focus is; never shown while the panel is open. Not linked with `aria-describedby` (it duplicates the name).
+
+## 6. Accessibility
+
+WCAG 2.2 AAA target. The button has an accessible name and `aria-expanded`/`aria-controls`; the icon is `aria-hidden`; the
+panel is a named group; focus stays visible; no motion. The content's own accessibility is the app's.
+
+## 7. Testing acceptance criteria
+
+1. Renders `div.menu-picker` containing `button.menu-picker-button`, a tooltip and a hidden `div.menu-picker-panel`.
+2. The button's accessible name is `label`; it has `aria-expanded="false"` and `aria-controls` pointing at the panel.
+3. The default icon is an `aria-hidden` SVG with class `menu-picker-icon`; `icon` replaces it.
+4. The panel is a `role="group"` named with `label`.
+5. The app's content renders inside the panel; with no content the panel is empty (nothing is invented).
+6. Click opens: panel visible, `aria-expanded="true"`, focus stays on the button.
+7. Click again closes.
+8. `ArrowDown` on the button opens and focuses the first focusable element in the panel; `ArrowUp` focuses the last.
+9. `Escape` closes and returns focus to the button.
+10. `Tab` closes without teleporting focus.
+11. Clicking outside closes.
+12. Focus moving out of the picker closes.
+13. Activating a link or button inside closes the panel and focuses the button; an element inside
+    `data-menu-picker-keep-open` does not close it; `closeOnSelect=false` never closes on select.
+14. The content receives `close()`, which closes the panel.
+15. `open` is bindable and `onOpenChange` fires once per actual change.
+16. The tooltip exists with `role="tooltip"`, holds `label`, and is hidden at rest.
+17. The tooltip shows on hover, hides on `Escape`, and never shows while the panel is open.
+18. The tooltip is not referenced by `aria-describedby`.
+19. `class` is appended to the root; rest props are spread on the root.
+20. Two instances get distinct ids.
+21. The package source contains no stylesheet, no inline `style` and no English default text.
+
+## 8. Tracking
+
+- Package: `@lilydesignsystem/angular-menu-picker`
+- Version: 0.1.0 (new, 2026-10-08)
+- Framework: Angular `>=20 <23` (signals, standalone, OnPush)
+- Test runner: vitest + TestBed

package/tsconfig.lib.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./out-tsc/lib",
+    "declaration": true,
+    "declarationMap": true,
+    "types": []
+  },
+  "angularCompilerOptions": {
+    "compilationMode": "partial"
+  },
+  "exclude": ["**/*.spec.ts", "node_modules", "dist"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.