@molecule/app-danger-zone-angular 0.0.0-stage → 0.0.1-stage

package/README.md

@@ -1,3 +1,522 @@
-# Temporary Holding Version
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-11-15T09:11:28.356Z
+-->
 
-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.
+# @molecule/app-danger-zone-angular
+
+Angular destructive-action primitives — the counterpart of
+`@molecule/app-danger-zone-react`: the same props and the same DOM for the
+same input.
+
+Exports `<DangerZoneSection>` — Card with title/description/button for
+delete/reset/revoke — and `<ConfirmDialog>`, the standalone "Are you
+sure?" modal.
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+## Quick Start
+
+```ts
+import { Component } from '@angular/core'
+import { DangerZoneSection } from '@molecule/app-danger-zone-angular'
+
+@Component({
+  selector: 'app-account',
+  standalone: true,
+  imports: [DangerZoneSection],
+  template: `
+    <div
+      mol-danger-zone-section
+      title="Delete account"
+      description="This permanently removes your account and all data."
+      actionLabel="Delete account"
+      (click)="openConfirm()"
+    ></div>
+  `,
+})
+export class Account {}
+```
+
+## Type
+
+`feature`
+
+## Installation
+
+```bash
+npm install @molecule/app-danger-zone-angular @angular/common @angular/core @angular/platform-browser @molecule/app-angular @molecule/app-ui @molecule/app-ui-angular
+```
+
+## API
+
+### Interfaces
+
+#### `ConfirmDialogProps`
+
+Props accepted by {@link ConfirmDialog} — the same props
+`@molecule/app-danger-zone-react` accepts. Node-valued props (`title`,
+`description`) are projected content in Angular (an input cannot carry a
+node), so they are typed `unknown`; `children` is the element's default
+projection. Callbacks use React's names: the component's `close`/`confirm`
+outputs are the same contract.
+
+```typescript
+interface ConfirmDialogProps {
+  /** Whether the dialog is open. */
+  open: boolean
+  /** Called when the dialog should close (escape, backdrop, cancel). */
+  onClose?: (event?: unknown) => void
+  /** Title (nodes are `[slot=title]` content). */
+  title?: unknown
+  /** Body / warning text (nodes are `[slot=description]` content). */
+  description?: unknown
+  /** Confirm-button label (e.g. "Delete"). */
+  confirmLabel?: string
+  /** Cancel-button label. */
+  cancelLabel?: string
+  /** Called when the user confirms. */
+  onConfirm?: () => void | Promise<void>
+  /** Is the confirm action destructive? Defaults to true. */
+  destructive?: boolean
+  /** Extra body content between description and footer (default projection). */
+  children?: unknown
+  /** Disables both buttons; the caller owns the pending state. */
+  loading?: boolean
+}
+```
+
+#### `DangerZoneSectionProps`
+
+Props accepted by {@link DangerZoneSection} — the same props
+`@molecule/app-danger-zone-react` accepts. Node props (`title`,
+`description`, `actionLabel`, `children`) are projected content in Angular
+(an input cannot carry a node), so they are typed `unknown`: pass them in
+the host template (`[slot=title]`, `[slot=description]`,
+`[slot=actionLabel]` and default content), not as values.
+
+```typescript
+interface DangerZoneSectionProps {
+  /** Section title (string/number renders as text; nodes are `[slot=title]` content). */
+  title?: unknown
+  /** Explanation of the destructive action (nodes are `[slot=description]` content). */
+  description?: unknown
+  /** Label on the action button (nodes are `[slot=actionLabel]` content). */
+  actionLabel?: unknown
+  /** Called when the button is clicked; receives the DOM click event. */
+  onAction?: (event: MouseEvent) => void
+  /** When true, the button disables and shows a loading label. */
+  loading?: boolean
+  /** When true, the button is disabled without loading. */
+  disabled?: boolean
+  /** Additional content between description and button (e.g. a confirm-text input), projected as the element's default content. */
+  children?: unknown
+  /** Extra classes on the Card (the host element). */
+  className?: string
+  /** `data-mol-id` for AI-agent selectors. */
+  dataMolId?: string
+}
+```
+
+### Classes
+
+#### `DangerZoneSection`
+
+DangerZoneSection component.
+
+Card-wrapped section for destructive actions — delete account, reset data,
+revoke access. Uses the error/danger accent color and puts the action on
+the right. The host IS the Card's `<div>`
+(`div[mol-danger-zone-section]`), matching React's root exactly; the Card
+classes (`cm.card({ variant: 'elevated' })` + `cm.cardPadding('md')`, the
+UI Card's defaults) are applied through the host class binding.
+
+The node props are projected slots: `title` renders inside the `<h3>`,
+`description` inside the `<p>`, `actionLabel` inside the action `<button>`,
+and `children` bare between the header and the button row (React renders
+`{children}` with no wrapper). String inputs render as text instead — the
+same values React renders. The action label's capture wrapper detaches
+while `loading` is true: React shows the `…` glyph instead of the label.
+
+```typescript
+@Component({
+  selector: 'div[mol-danger-zone-section]',
+  standalone: true,
+  imports: [Button],
+  inputs: [
+    'title',
+    'description',
+    'actionLabel',
+    'loading',
+    'disabled',
+    'className',
+    'dataMolId',
+    'onAction',
+  ],
+  host: {
+    '[class]': 'classes()',
+    '[attr.data-mol-id]': 'dataMolId ?? null',
+  },
+  template: `<div [class]="cm().stack(3)">
+    <header [class]="cm().stack(1)">
+      <h3 [class]="titleClasses()">
+        {{ titleText() }}<ng-content select="[slot=title]"></ng-content>
+      </h3>
+      <p [class]="cm().textSize('sm')">
+        {{ descriptionText() }}<ng-content select="[slot=description]"></ng-content>
+      </p>
+    </header>
+    <ng-content></ng-content>
+    <div [class]="cm().flex({ justify: 'end' })">
+      <button
+        mol-button
+        [variant]="'solid'"
+        [color]="'error'"
+        [disabled]="isDisabled()"
+        (click)="handleAction($event)"
+      >
+        {{ loading ? '…' : actionLabelText()
+        }}<span #labelSlot><ng-content select="[slot=actionLabel]"></ng-content></span>
+      </button>
+    </div>
+  </div>`,
+})
+export class DangerZoneSection implements AfterViewInit, DoCheck {
+  /** Section title (string/number renders as text; nodes are `[slot=title]` content). */
+  title?: unknown
+  /** Explanation of the destructive action (string/number as text; nodes are `[slot=description]` content). */
+  description?: unknown
+  /** Label on the action button (string/number as text; nodes are `[slot=actionLabel]` content). */
+  actionLabel?: unknown
+  /** When true, the button disables and shows a loading label. */
+  loading?: boolean
+  /** When true, the button is disabled without loading. */
+  disabled?: boolean
+  /** Extra classes on the Card. */
+  className?: string
+  /** `data-mol-id` for AI-agent selectors. */
+  dataMolId?: string
+  /** Called when the button is clicked; receives the DOM click event (React's `onAction`). */
+  onAction?: (event: MouseEvent) => void
+
+  /** The action label's capture wrapper (moved out of the DOM once read). */
+  @ViewChild('labelSlot') labelSlot?: ElementRef<HTMLSpanElement>
+
+  /** Whether the action label slot holds projected content (read once). */
+  private hasLabelSlot = false
+
+  /** The capture wrapper's parent (the action `<button>`), remembered across detaches. */
+  private labelParent?: Node
+
+  /** The projected label nodes while they render bare (React's `{actionLabel}`). */
+  private labelNodes: Node[] = []
+
+  /** Marks the wrapper's position in the button while the projected nodes render bare. */
+  private labelAnchor?: Comment
+
+  /** The wrapper sync for the action label's capture wrapper. */
+  private readonly sync = new SlotWrapper(inject(ElementRef), inject(Renderer2))
+
+  /** Creates the position anchor comment the DOM normalizer strips. */
+  private readonly renderer = inject(Renderer2)
+
+  /**
+   * The current class map.
+   * @returns The UIClassMap.
+   */
+  cm(): UIClassMap {
+    return getClassMap()
+  }
+
+  /**
+   * Computes the Card's class list (`cm.card({ variant: 'elevated' })` +
+   * `cm.cardPadding('md')` — the UI Card's defaults — plus `className`).
+   * @returns The class string.
+   */
+  classes(): string {
+    return this.cm().cn(
+      this.cm().card({ variant: 'elevated' }),
+      this.cm().cardPadding('md'),
+      this.className,
+    )
+  }
+
+  /**
+   * Computes the title's class (`cm.textSize('base')` + `cm.fontWeight('semibold')`).
+   * @returns The class string.
+   */
+  titleClasses(): string {
+    return this.cm().cn(this.cm().textSize('base'), this.cm().fontWeight('semibold'))
+  }
+
+  /**
+   * The title input's text (React's `{title}` for a text child: strings and
+   * numbers render; a node arrives as `[slot=title]` content instead).
+   * @returns The text, or `''` for a node title.
+   */
+  titleText(): string {
+    return typeof this.title === 'string' || typeof this.title === 'number'
+      ? String(this.title)
+      : ''
+  }
+
+  /**
+   * The description input's text (React's `{description}` for a text child).
+   * @returns The text, or `''` for a node description.
+   */
+  descriptionText(): string {
+    return typeof this.description === 'string' || typeof this.description === 'number'
+      ? String(this.description)
+      : ''
+  }
+
+  /**
+   * The action label input's text (React's `{actionLabel}` for a text child).
+   * @returns The text, or `''` for a node label.
+   */
+  actionLabelText(): string {
+    return typeof this.actionLabel === 'string' || typeof this.actionLabel === 'number'
+      ? String(this.actionLabel)
+      : ''
+  }
+
+  /**
+   * The button's disabled state (React's `disabled || loading`; an absent
+   * boolean input must not show a disabled button).
+   * @returns Whether the button is disabled.
+   */
+  isDisabled(): boolean {
+    return this.disabled === true || this.loading === true
+  }
+
+  /** Runs the click handler the way React forwards the DOM event. */
+  handleAction(event: MouseEvent): void {
+    this.onAction?.(event)
+  }
+
+  /**
+   * Reads the label slot's presence (view queries resolve only at view init)
+   * and syncs the capture wrapper against React's DOM.
+   */
+  ngAfterViewInit(): void {
+    const label = this.labelSlot?.nativeElement
+    if (label) {
+      this.labelParent = label.parentElement ?? undefined
+      this.hasLabelSlot = hasNodes(label)
+    }
+    this.syncLabels()
+  }
+
+  /**
+   * Re-syncs the wrapper when `loading` changes.
+   */
+  ngDoCheck(): void {
+    this.syncLabels()
+  }
+
+  /**
+   * Applies React's label branch: the projected label renders only while
+   * there is one and the button is not loading (`{loading ? '…' : actionLabel}`),
+   * and it renders BARE — the capture wrapper never shows in the DOM.
+   */
+  private syncLabels(): void {
+    const span = this.labelSlot?.nativeElement
+    const parent = this.labelParent
+    if (!span || !parent) return
+    if (this.hasLabelSlot && this.loading !== true) {
+      this.unwrapLabel(span, parent)
+    } else {
+      this.wrapLabel(span, parent)
+    }
+  }
+
+  /**
+   * Moves the projected nodes out of the capture wrapper to its position and
+   * detaches the empty wrapper (React renders the label with no element).
+   *
+   * @param span - The capture wrapper.
+   * @param parent - The wrapper's parent (the action `<button>`).
+   */
+  private unwrapLabel(span: HTMLSpanElement, parent: Node): void {
+    const anchor = this.labelAnchor ?? this.createLabelAnchor(parent, span)
+    this.labelNodes = Array.from(span.childNodes)
+    for (const node of this.labelNodes) parent.insertBefore(node, anchor)
+    if (span.isConnected) parent.removeChild(span)
+  }
+
+  /**
+   * Creates the position anchor comment and inserts it where the wrapper sits.
+   *
+   * @param parent - The wrapper's parent (the action `<button>`).
+   * @param span - The capture wrapper the anchor replaces.
+   * @returns The created anchor comment.
+   */
+  private createLabelAnchor(parent: Node, span: Node): Comment {
+    const anchor: Comment = this.renderer.createComment('slot')
+    this.labelAnchor = anchor
+    parent.insertBefore(anchor, span)
+    return anchor
+  }
+
+  /**
+   * Puts the projected nodes back inside the capture wrapper (hidden, as
+   * React hides the label while loading) and keeps the wrapper out of the DOM.
+   *
+   * @param span - The capture wrapper.
+   * @param parent - The wrapper's parent (the action `<button>`).
+   */
+  private wrapLabel(span: HTMLSpanElement, parent: Node): void {
+    for (const node of this.labelNodes) span.appendChild(node)
+    this.labelNodes = []
+    if (!span.isConnected && this.labelAnchor?.isConnected) {
+      parent.insertBefore(span, this.labelAnchor)
+    }
+    this.sync.sync(span, false, parent)
+  }
+}
+```
+
+#### `ConfirmDialog`
+
+ConfirmDialog component.
+
+Composed from `Modal` and `Button` exactly as React composes them; the
+dialog's own title/description/children are projected content (`[slot=title]`,
+`[slot=description]`, default). The host is unwrapped (`data-parity-unwrap`,
+React's `Modal` root is a fragment/portal).
+
+```typescript
+@Component({
+  selector: 'mol-confirm-dialog',
+  standalone: true,
+  imports: [Button, Modal],
+  inputs: ['open', 'title', 'description', 'confirmLabel', 'cancelLabel', 'destructive', 'loading'],
+  outputs: ['close', 'confirm'],
+  host: {
+    'data-parity-unwrap': '',
+    style: 'display: contents',
+  },
+  template: `<mol-modal [open]="open" (close)="close.emit($event)"
+    ><div [class]="cm().stack(3)">
+      <h2 [class]="cm().cn(cm().textSize('lg'), cm().fontWeight('bold'))">
+        <ng-content select="[slot=title]"></ng-content>
+      </h2>
+      <p [class]="cm().textSize('sm')"><ng-content select="[slot=description]"></ng-content></p>
+      <ng-content></ng-content>
+      <div [class]="cm().flex({ justify: 'end', gap: 'sm' })">
+        <button mol-button [variant]="'ghost'" [disabled]="!!loading" (click)="close.emit($event)">
+          {{ cancelText() }}</button
+        ><button
+          mol-button
+          [variant]="'solid'"
+          [color]="destructive === false ? 'primary' : 'error'"
+          [disabled]="!!loading"
+          (click)="confirm.emit()"
+        >
+          {{ confirmText() }}
+        </button>
+      </div>
+    </div></mol-modal
+  >`,
+})
+export class ConfirmDialog {
+  /** Whether the dialog is open. */
+  open = false
+  /** Title (node-valued prop). */
+  title?: unknown
+  /** Body / warning text (node-valued prop). */
+  description?: unknown
+  /** Confirm-button label. */
+  confirmLabel?: string
+  /** Cancel-button label. */
+  cancelLabel?: string
+  /** Whether the confirm action is destructive (default true). */
+  destructive = true
+  /** Disables both buttons (the caller owns the pending state). */
+  loading?: boolean
+
+  /** Fires when the dialog should close (escape, backdrop, cancel). */
+  @Output() readonly close = new EventEmitter<unknown>()
+  /** Fires when the user confirms. */
+  @Output() readonly confirm = new EventEmitter<void>()
+
+  /**
+   * Reactive translation, read in the injection context. Its `t` reads the
+   * locale, so the view re-renders the text on a locale switch (the static `t`
+   * does not).
+   */
+  private readonly i18n = useTranslation()
+
+  /**
+   * The current class map.
+   * @returns The UIClassMap.
+   */
+  cm(): UIClassMap {
+    return getClassMap()
+  }
+
+  /**
+   * The cancel button's label.
+   * @returns The label text.
+   */
+  cancelText(): string {
+    return this.cancelLabel ?? this.i18n.t('confirm.cancel', {}, { defaultValue: 'Cancel' })
+  }
+
+  /**
+   * The confirm button's label (React shows an ellipsis while loading).
+   * @returns The label text.
+   */
+  confirmText(): string {
+    return this.loading
+      ? '…'
+      : (this.confirmLabel ?? this.i18n.t('confirm.confirm', {}, { defaultValue: 'Confirm' }))
+  }
+}
+```
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@angular/common` ^22.0.0
+- `@angular/core` ^22.0.0
+- `@angular/platform-browser` ^22.0.0
+- `@molecule/app-angular` ^3.5.0
+- `@molecule/app-ui` ^1.0.1
+- `@molecule/app-ui-angular` ^1.1.0
+
+### Runtime Dependencies
+
+- `@angular/common`
+- `@angular/core`
+- `@angular/platform-browser`
+- `@molecule/app-angular`
+- `@molecule/app-ui`
+- `@molecule/app-ui-angular`
+
+- Requires a bonded ClassMap (the Card classes, `cm.card` +
+  `cm.cardPadding('md')`) — rendering throws otherwise.
+- Node props are projected content: `title`, `description` and
+  `actionLabel` are selected by `[slot=title]` / `[slot=description]` /
+  `[slot=actionLabel]`, everything else lands bare between the header and
+  the button row as the default projection. String inputs render as text.
+- `<ConfirmDialog>` does NOT track `onConfirm`'s promise and does NOT
+  close itself on confirm: set `loading` yourself while the action runs,
+  then call `onClose()` when it settles — otherwise users can double-fire
+  the destructive action or be left staring at an open dialog.
+  Cancel/Confirm fall back to the `confirm.*` i18n keys (companion bond:
+  `@molecule/app-locales-danger-zone`); pass `confirmLabel`/`cancelLabel`
+  for action-specific wording ("Delete", "Revoke"). `destructive`
+  (default true) only switches the confirm button color.
+
+## Translations
+
+Translation strings are provided by `@molecule/app-locales-danger-zone`.

package/dist/confirm-dialog.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ConfirmDialog — re-exported from the framework bundle.
+ *
+ * The Angular port lives in `@molecule/app-ui-angular` (like React's, which
+ * lives in `@molecule/app-ui-react` after its 2026-09-24 promotion), so
+ * every Angular app can confirm destructive actions without installing this
+ * feature package. This re-export keeps
+ * `@molecule/app-danger-zone-angular`'s public API aligned with
+ * `@molecule/app-danger-zone-react`; prefer importing it from
+ * `@molecule/app-ui-angular` directly.
+ *
+ * Contract (unchanged): the dialog does NOT track `onConfirm`'s promise and
+ * does NOT close itself on confirm — set `loading` yourself while the action
+ * runs, then call `onClose()` when it settles. Cancel/Confirm fall back to
+ * the `confirm.*` i18n keys (companion bond:
+ * `@molecule/app-locales-danger-zone`); pass `confirmLabel`/`cancelLabel`
+ * for action-specific wording. `destructive` (default true) only switches
+ * the confirm button color.
+ *
+ * @module
+ */
+export { ConfirmDialog } from '@molecule/app-ui-angular';
+//# sourceMappingURL=confirm-dialog.d.ts.map

package/dist/confirm-dialog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirm-dialog.d.ts","sourceRoot":"","sources":["../src/confirm-dialog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA"}

package/dist/confirm-dialog.js

@@ -0,0 +1,23 @@
+/**
+ * ConfirmDialog — re-exported from the framework bundle.
+ *
+ * The Angular port lives in `@molecule/app-ui-angular` (like React's, which
+ * lives in `@molecule/app-ui-react` after its 2026-09-24 promotion), so
+ * every Angular app can confirm destructive actions without installing this
+ * feature package. This re-export keeps
+ * `@molecule/app-danger-zone-angular`'s public API aligned with
+ * `@molecule/app-danger-zone-react`; prefer importing it from
+ * `@molecule/app-ui-angular` directly.
+ *
+ * Contract (unchanged): the dialog does NOT track `onConfirm`'s promise and
+ * does NOT close itself on confirm — set `loading` yourself while the action
+ * runs, then call `onClose()` when it settles. Cancel/Confirm fall back to
+ * the `confirm.*` i18n keys (companion bond:
+ * `@molecule/app-locales-danger-zone`); pass `confirmLabel`/`cancelLabel`
+ * for action-specific wording. `destructive` (default true) only switches
+ * the confirm button color.
+ *
+ * @module
+ */
+export { ConfirmDialog } from '@molecule/app-ui-angular';
+//# sourceMappingURL=confirm-dialog.js.map

package/dist/confirm-dialog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirm-dialog.js","sourceRoot":"","sources":["../src/confirm-dialog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA"}