@gntik-ai/blocks 0.6.0 → 0.8.0

package/src/forms/CredentialDisclosureDialog/CredentialDisclosureDialog.tsx

@@ -1,6 +1,5 @@
 import {
   Button,
-  CopyButton,
   Dialog,
   DialogContent,
   DialogHeader,
@@ -9,13 +8,15 @@ import {
   DialogBody,
   DialogFooter,
   DialogClose,
-  LiveAnnouncer,
-  SecretField,
-  CodeBlock,
   Alert,
   useI18n,
 } from '@gntik-ai/ui';
-import { useRef, useState, type ReactNode } from 'react';
+import { useEffectEvent, useId, useLayoutEffect, useRef, useState, type ReactNode } from 'react';
+import { SecretCopy } from './SecretCopy';
+import { usableFocusTarget } from './focus';
+import type { CredentialSecret } from './types';
+
+export type { CredentialSecret } from './types';
 
 export interface CredentialDisclosure {
   variant: 'stored' | 'fresh';
@@ -26,9 +27,21 @@ export interface CredentialDisclosure {
 }
 
 export interface CredentialDisclosureDialogProps {
+  /** Additional masked values; ids must be unique, non-empty and not "secret". */
+  additionalSecrets?: readonly CredentialSecret[];
+  /** Mask a fresh primary secret; read at the start of each session. */
+  maskFresh?: boolean;
+  /** Redacted content below the secrets; clear secret-bearing content on close. */
+  revealContent?: ReactNode;
+  /** Presentation fixed for each non-null opening. Defaults to a modal dialog. */
+  presentation?: 'dialog' | 'inline';
+  /** Called after copying with the secret id (primary: "secret"), never its value. */
+  onCopy?: (id: string) => void;
+  /** Label-only success announcement override, used only in multi-secret mode. */
+  copiedAnnouncementFor?: (label: string) => string;
   /** Set only after a successful response. Leave null while pending or on failure. */
   disclosure: CredentialDisclosure | null;
-  /** Clear disclosure to null on dismissal, dropping the secret in the consumer. */
+  /** Clear disclosure, additionalSecrets and secret-bearing revealContent on dismissal. */
   onClose: () => void;
   /** Resolve the current row action at close time, including after list reloads. */
   resolveReturnFocus?: () => HTMLElement | null;
@@ -51,9 +64,10 @@ export interface CredentialDisclosureDialogProps {
 }
 
 /**
- * Discloses an existing credential only after a successful response. Consumers keep disclosure
- * null while pending or on failure, and clear it on close. No pending/error state or internal
- * secret retention. A fresh secret requires a new successful response to be shown again.
+ * Render only successful responses. Keep disclosure null while pending or on failure.
+ * On close, clear disclosure, additionalSecrets and any secret-bearing revealContent.
+ * No pending/error state or internal secret retention. Retained dismissed sessions stay closed;
+ * a changed credential/value or a null-to-value opening starts a new session.
  */
 export function CredentialDisclosureDialog(props: CredentialDisclosureDialogProps) {
   if (!props.disclosure) return null;
@@ -61,108 +75,182 @@ export function CredentialDisclosureDialog(props: CredentialDisclosureDialogProp
 }
 
 type OpeningProps = CredentialDisclosureDialogProps & { disclosure: CredentialDisclosure };
+type FocusScope = {
+  onRootRef: (node: HTMLElement | null) => void;
+  onTargetRef: (node: HTMLElement | null) => void;
+  onPopupRef: (node: HTMLDivElement | null) => void;
+  containsFocus: () => boolean;
+  initialFocus: () => HTMLElement | false | null;
+};
 
 function DisclosureOpening(props: OpeningProps) {
-  // Keep the original opener across credential/value changes; the old popup is not an opener.
   const [opener] = useState(() => (typeof document === 'undefined' ? null : document.activeElement));
+  const [presentation] = useState(props.presentation ?? 'dialog');
+  const root = useRef<HTMLElement>(null);
+  const target = useRef<HTMLElement>(null);
+  const active = useRef<Element | null>(opener);
+  const started = useRef(false);
+  const activeWasInside = useRef(false);
+  const returnFocus = () => {
+    const current = props.resolveReturnFocus?.();
+    if (usableFocusTarget(current)) return current;
+    const fallback = props.fallbackFocus?.();
+    if (usableFocusTarget(fallback)) return fallback;
+    return usableFocusTarget(opener) ? opener : false;
+  };
+  const restore = useEffectEvent(() => {
+    if (root.current?.contains(document.activeElement)) {
+      const element = returnFocus();
+      if (element) element.focus();
+    }
+  });
+  useLayoutEffect(() => {
+    const track = () => {
+      if (document.activeElement !== document.body) {
+        active.current = document.activeElement;
+        activeWasInside.current = root.current?.contains(document.activeElement) ?? false;
+      }
+    };
+    document.addEventListener('focusin', track);
+    return () => {
+      document.removeEventListener('focusin', track);
+      restore();
+    };
+  }, [presentation]);
+  useLayoutEffect(() => {
+    // A surviving focused control wins, including one outside the disclosure.
+    if (activeWasInside.current && active.current && !active.current.isConnected) target.current?.focus();
+  });
+  const seen = new Set(['secret', '']);
+  const additionalSecrets = (props.additionalSecrets ?? []).filter(({ id }) => {
+    if (seen.has(id)) return false;
+    seen.add(id);
+    return true;
+  });
   const { variant, credentialId, secret } = props.disclosure;
-  // A new credential/value is a new session: reveal and announcement state cannot carry over.
-  // React keys are never rendered as DOM attributes.
-  return <DisclosureSession key={JSON.stringify([variant, credentialId, secret])} {...props} opener={opener} />;
+  return (
+    <DisclosureSession
+      key={JSON.stringify([variant, credentialId, secret, ...additionalSecrets.map(({ id, value }) => [id, value])])}
+      {...props}
+      presentation={presentation}
+      additionalSecrets={additionalSecrets}
+      onRootRef={(node) => {
+        root.current = node;
+      }}
+      onTargetRef={(node) => {
+        target.current = node;
+      }}
+      onPopupRef={(node) => {
+        root.current = node;
+        target.current = node;
+      }}
+      containsFocus={() => root.current?.contains(document.activeElement) ?? false}
+      initialFocus={() => {
+        const shouldFocus = !started.current || (activeWasInside.current && !active.current?.isConnected);
+        started.current = true;
+        return shouldFocus ? root.current : false;
+      }}
+      returnFocus={returnFocus}
+    />
+  );
 }
 
-function DisclosureSession({
-  disclosure,
-  onClose,
-  resolveReturnFocus,
-  fallbackFocus,
-  opener,
-  ...labels
-}: OpeningProps & { opener: Element | null }) {
+function DisclosureSession(props: OpeningProps & FocusScope & { returnFocus: () => HTMLElement | false }) {
   const { t } = useI18n();
+  const {
+    disclosure,
+    onRootRef,
+    onTargetRef,
+    onPopupRef,
+    initialFocus,
+    containsFocus,
+    presentation,
+    additionalSecrets = [],
+  } = props;
   const [open, setOpen] = useState(true);
-  const popup = useRef<HTMLDivElement>(null);
+  const [maskFresh] = useState(props.maskFresh ?? false);
   const dismissed = useRef(false);
-  const returnFocus = () => {
-    const target = resolveReturnFocus?.();
-    if (usableFocusTarget(target)) return target;
-    const fallback = fallbackFocus?.();
-    if (usableFocusTarget(fallback)) return fallback;
-    return usableFocusTarget(opener) ? opener : false;
+  const headingId = useId();
+  const close = () => {
+    if (dismissed.current) return;
+    dismissed.current = true;
+    if (presentation === 'inline' && containsFocus()) {
+      const element = props.returnFocus();
+      if (element) element.focus();
+    }
+    setOpen(false);
+    props.onClose();
   };
-  const closeLabel = labels.closeLabel ?? t('credentialDisclosure.close');
-  const secretLabel = labels.secretLabel ?? t('credentialDisclosure.secret');
+  const closeLabel = props.closeLabel ?? t('credentialDisclosure.close');
+  const title = props.title ?? t('credentialDisclosure.title');
+  const description = props.description ?? t('credentialDisclosure.description');
+  const secretLabel = props.secretLabel ?? t('credentialDisclosure.secret');
+  const warning =
+    disclosure.variant === 'fresh' ? (
+      <Alert
+        role={presentation === 'inline' ? 'note' : 'alert'}
+        tone="warning"
+        title={props.warningTitle ?? t('credentialDisclosure.warningTitle')}
+        description={props.warningText ?? t('credentialDisclosure.warningText')}
+      />
+    ) : null;
+  const body = (
+    <>
+      <dl className="grid grid-cols-2 gap-2 text-sm">
+        <dt className="text-muted-foreground">{props.credentialIdLabel ?? t('credentialDisclosure.credentialId')}</dt>
+        <dd className="break-all font-mono">{disclosure.credentialId}</dd>
+        <dt className="text-muted-foreground">{props.expiryLabel ?? t('credentialDisclosure.expiry')}</dt>
+        <dd>{disclosure.expiresAt}</dd>
+      </dl>
+      <SecretCopy
+        secret={{ id: 'secret', label: secretLabel, value: disclosure.secret }}
+        options={props}
+        grouped={additionalSecrets.length > 0}
+        masked={disclosure.variant === 'stored' || maskFresh}
+        warning={warning}
+      />
+      {additionalSecrets.map((secret) => (
+        <SecretCopy key={secret.id} secret={secret} options={props} grouped />
+      ))}
+      {props.revealContent != null && <div data-kit-redact>{props.revealContent}</div>}
+    </>
+  );
+  if (presentation === 'inline') {
+    if (!open) return null;
+    return (
+      <section ref={onRootRef} aria-labelledby={headingId} className="grid gap-4">
+        <h2 id={headingId} tabIndex={-1} ref={onTargetRef}>
+          {title}
+        </h2>
+        <p>{description}</p>
+        {body}
+        <Button variant="secondary" onClick={close}>
+          {closeLabel}
+        </Button>
+      </section>
+    );
+  }
   return (
     <Dialog
       open={open}
       onOpenChange={(next) => {
-        if (!next && !dismissed.current) {
-          dismissed.current = true;
-          setOpen(false);
-          onClose();
-        }
+        if (!next) close();
       }}
     >
       <DialogContent
-        ref={popup}
-        initialFocus={popup}
-        finalFocus={returnFocus}
+        ref={onPopupRef}
+        initialFocus={initialFocus}
+        finalFocus={() => (dismissed.current ? props.returnFocus() : false)}
         showClose={false}
         closeLabel={closeLabel}
       >
         {open && (
           <>
             <DialogHeader>
-              <DialogTitle>{labels.title ?? t('credentialDisclosure.title')}</DialogTitle>
-              <DialogDescription>{labels.description ?? t('credentialDisclosure.description')}</DialogDescription>
+              <DialogTitle>{title}</DialogTitle>
+              <DialogDescription>{description}</DialogDescription>
             </DialogHeader>
-            <DialogBody className="grid gap-4">
-              <dl className="grid grid-cols-2 gap-2 text-sm">
-                <dt className="text-muted-foreground">
-                  {labels.credentialIdLabel ?? t('credentialDisclosure.credentialId')}
-                </dt>
-                <dd className="break-all font-mono">{disclosure.credentialId}</dd>
-                <dt className="text-muted-foreground">{labels.expiryLabel ?? t('credentialDisclosure.expiry')}</dt>
-                <dd>{disclosure.expiresAt}</dd>
-              </dl>
-              <LiveAnnouncer>
-                {disclosure.variant === 'stored' ? (
-                  <SecretField
-                    value={disclosure.secret}
-                    copyable={false}
-                    aria-label={secretLabel}
-                    showLabel={labels.showLabel ?? t('credentialDisclosure.show')}
-                    hideLabel={labels.hideLabel ?? t('credentialDisclosure.hide')}
-                  />
-                ) : (
-                  <>
-                    <Alert
-                      role="alert"
-                      tone="warning"
-                      title={labels.warningTitle ?? t('credentialDisclosure.warningTitle')}
-                      description={labels.warningText ?? t('credentialDisclosure.warningText')}
-                    />
-                    <CodeBlock
-                      code={disclosure.secret}
-                      copyable={false}
-                      label={secretLabel}
-                      wrapToggle={false}
-                      defaultWrap
-                    />
-                  </>
-                )}
-                <CopyButton
-                  value={() => disclosure.secret}
-                  display="label"
-                  label={labels.copyLabel ?? t('credentialDisclosure.copy')}
-                  copiedLabel={labels.copiedLabel ?? t('credentialDisclosure.copied')}
-                  announcement={labels.successAnnouncement ?? t('credentialDisclosure.success')}
-                  failureLabel={labels.failureAnnouncement ?? t('credentialDisclosure.failure')}
-                  failureAnnouncement={labels.failureAnnouncement ?? t('credentialDisclosure.failure')}
-                  failurePoliteness="polite"
-                />
-              </LiveAnnouncer>
-            </DialogBody>
+            <DialogBody className="grid gap-4">{body}</DialogBody>
             <DialogFooter>
               <DialogClose render={<Button variant="secondary" />}>{closeLabel}</DialogClose>
             </DialogFooter>
@@ -172,22 +260,3 @@ function DisclosureSession({
     </Dialog>
   );
 }
-
-/** Programmatic focus permits negative tabIndex, but never hidden, inert or disabled targets. */
-function usableFocusTarget(element: Element | null | undefined): element is HTMLElement {
-  if (!(element instanceof HTMLElement) || !element.isConnected || element === document.body) return false;
-  if (element.matches(':disabled, [disabled], [aria-disabled="true"], input[type="hidden"]')) return false;
-  for (let ancestor: HTMLElement | null = element; ancestor; ancestor = ancestor.parentElement) {
-    if (ancestor.hidden || ancestor.hasAttribute('inert') || ancestor.getAttribute('aria-disabled') === 'true')
-      return false;
-    const style = getComputedStyle(ancestor);
-    if (
-      style.display === 'none' ||
-      style.visibility === 'hidden' ||
-      style.visibility === 'collapse' ||
-      style.contentVisibility === 'hidden'
-    )
-      return false;
-  }
-  return element.tabIndex >= 0 || element.hasAttribute('tabindex') || element.isContentEditable;
-}

package/src/forms/CredentialDisclosureDialog/IssueOnClick.test.tsx

@@ -0,0 +1,56 @@
+import { act, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import IssueOnClick from './examples/IssueOnClick';
+import { freshDisclosure } from './fixtures';
+import type { CredentialDisclosure } from './CredentialDisclosureDialog';
+
+it.each(['cancel', 'supersede'] as const)('ignores a deferred issuance after %s', async (action) => {
+  const user = userEvent.setup();
+  const results: ((value: CredentialDisclosure) => void)[] = [];
+  const signals: AbortSignal[] = [];
+  const request = vi.fn((signal: AbortSignal) => {
+    signals.push(signal);
+    return new Promise<CredentialDisclosure>((resolve) => results.push(resolve));
+  });
+  render(<IssueOnClick request={request} />);
+  await user.click(screen.getByRole('button', { name: 'Issue credential' }));
+  await user.click(screen.getByRole('button', { name: action === 'cancel' ? 'Cancel request' : 'Supersede request' }));
+  expect(signals[0]!.aborted).toBe(true);
+  await act(async () => results[0]!(freshDisclosure));
+  expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+  expect(document.body.textContent).not.toContain(freshDisclosure.secret);
+  if (action === 'supersede') {
+    await act(async () => results[1]!({ ...freshDisclosure, secret: 'synthetic_current_response' }));
+    expect(await screen.findByRole('dialog')).toBeInTheDocument();
+    await user.click(screen.getByRole('button', { name: 'Show secret' }));
+    expect(screen.getByRole('textbox')).toHaveValue('synthetic_current_response');
+  }
+});
+
+it('cancels the pending request on unmount before its deferred response settles', async () => {
+  const user = userEvent.setup();
+  const onAbort = vi.fn();
+  let settle!: (value: CredentialDisclosure) => void;
+  const request = vi.fn((signal: AbortSignal) => {
+    signal.addEventListener('abort', onAbort);
+    return new Promise<CredentialDisclosure>((resolve) => {
+      settle = resolve;
+    });
+  });
+  const { unmount } = render(<IssueOnClick request={request} />);
+  await user.click(screen.getByRole('button', { name: 'Issue credential' }));
+  expect(onAbort).not.toHaveBeenCalled();
+  unmount();
+  expect(onAbort).toHaveBeenCalledOnce();
+  expect(request.mock.calls[0]![0].aborted).toBe(true);
+  await act(async () => settle(freshDisclosure));
+});
+
+it('keeps disclosure null on failure and shows only a caller-owned error', async () => {
+  const user = userEvent.setup();
+  render(<IssueOnClick request={() => Promise.reject(new Error('409 DB_SHARED_MODE synthetic_not_for_display'))} />);
+  await user.click(screen.getByRole('button', { name: 'Issue credential' }));
+  expect(await screen.findByRole('alert')).toHaveTextContent('No credential was disclosed.');
+  expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+  expect(document.body.textContent).not.toContain('DB_SHARED_MODE');
+});

package/src/forms/CredentialDisclosureDialog/SecretCopy.tsx

@@ -0,0 +1,83 @@
+import { CodeBlock, CopyButton, LiveAnnouncer, SecretField, useI18n } from '@gntik-ai/ui';
+import { useState, type ReactNode } from 'react';
+import type { CredentialSecret } from './types';
+
+interface SecretCopyOptions {
+  showLabel?: string;
+  hideLabel?: string;
+  copyLabel?: string;
+  copiedLabel?: string;
+  successAnnouncement?: string;
+  failureAnnouncement?: string;
+  onCopy?: (id: string) => void;
+  copiedAnnouncementFor?: (label: string) => string;
+}
+
+/** Each secret owns feedback so simultaneous settlements cannot overwrite each other. */
+export function SecretCopy({
+  secret,
+  options,
+  grouped = false,
+  masked = true,
+  warning,
+}: {
+  secret: CredentialSecret;
+  options: SecretCopyOptions;
+  grouped?: boolean;
+  masked?: boolean;
+  warning?: ReactNode;
+}) {
+  const { t } = useI18n();
+  const [pending, setPending] = useState(false);
+  const copied = options.copiedLabel ?? t('credentialDisclosure.copied');
+  const content = (
+    <LiveAnnouncer>
+      {warning}
+      <div data-kit-redact>
+        {masked ? (
+          <SecretField
+            value={secret.value}
+            copyable={false}
+            aria-label={secret.label}
+            showLabel={options.showLabel ?? t('credentialDisclosure.show')}
+            hideLabel={options.hideLabel ?? t('credentialDisclosure.hide')}
+          />
+        ) : (
+          <CodeBlock code={secret.value} copyable={false} label={secret.label} wrapToggle={false} defaultWrap />
+        )}
+      </div>
+      <CopyButton
+        value={() => {
+          if (grouped) setPending(true);
+          return secret.value;
+        }}
+        loading={grouped && pending}
+        display="label"
+        label={options.copyLabel ?? t('credentialDisclosure.copy')}
+        copiedLabel={copied}
+        announcement={
+          grouped
+            ? (options.copiedAnnouncementFor?.(secret.label) ?? `${secret.label}: ${copied}`)
+            : (options.successAnnouncement ?? t('credentialDisclosure.success'))
+        }
+        failureLabel={options.failureAnnouncement ?? t('credentialDisclosure.failure')}
+        failureAnnouncement={options.failureAnnouncement ?? t('credentialDisclosure.failure')}
+        failurePoliteness="polite"
+        onCopy={() => {
+          if (grouped) setPending(false);
+          options.onCopy?.(secret.id);
+        }}
+        onCopyError={() => {
+          if (grouped) setPending(false);
+        }}
+      />
+    </LiveAnnouncer>
+  );
+  return grouped ? (
+    <div role="group" aria-label={secret.label}>
+      {content}
+    </div>
+  ) : (
+    content
+  );
+}

package/src/forms/CredentialDisclosureDialog/block.meta.ts

@@ -5,6 +5,6 @@ export const meta: BlockMeta = {
   family: 'forms',
   status: 'beta',
   description:
-    'Controlled disclosure for an existing credential. Set disclosure ({variant: stored | fresh, credentialId, expiresAt: caller-formatted ReactNode, secret}) only after a successful response; null renders nothing while pending or on failure. Clear disclosure to null in onClose to drop the secret; a fresh secret requires a new successful response before showing it again. No pending/error state or internal secret retention. Stored values start masked; each null-to-value opening or changed credentialId/secret resets masking and copy feedback. Fresh values use a non-copyable CodeBlock with a kit CopyButton and a replacement warning. Optional English defaults through en/es i18n for title, description, credentialIdLabel, expiryLabel, secretLabel, showLabel, hideLabel, copyLabel, copiedLabel, successAnnouncement, failureAnnouncement, warningTitle, warningText and closeLabel. Copy results are announced politely, including manual-selection fallback. Popup initial focus and focus trapping use Base UI; at close, resolveReturnFocus() is validated for connection, visibility, enabled state and focusability, then fallbackFocus(), then the original opener. Synthetic fixtures only; the default Stored preview is masked and the Fresh preview starts closed.',
+    'Controlled disclosure for an existing credential. Set disclosure ({variant: stored | fresh, credentialId, expiresAt: caller-formatted ReactNode, secret}) only after a successful response; null renders nothing while pending or on failure. Clear disclosure, additionalSecrets and secret-bearing revealContent in onClose to drop every secret; a fresh secret requires a new successful response before showing it again. No pending/error state or internal secret retention. Stored values start masked; each null-to-value opening or changed credentialId/secret resets masking and copy feedback. Fresh values use a non-copyable CodeBlock with a kit CopyButton and a replacement warning, or a masked SecretField when maskFresh is set at session start. Optional additionalSecrets ({id, label, value}) are always masked and use independent toggles and serialized copy actions; ids must be non-empty, unique and not secret, with the first duplicate winning. Multi-secret groups announce label plus copiedLabel, or copiedAnnouncementFor(label); onCopy(id) never receives a value. Every secret and the optional revealContent slot have data-kit-redact. The session key includes additional ids and values. presentation is dialog by default or inline, fixed until the next opening: inline is a named section, never traps focus or handles Escape, and its warning is a non-live note. Surviving focus stays; removing the focused slot or session control focuses the popup or inline heading. Focused inline unmounts return focus through the same resolvers. Dismissed retained props stay hidden; clear and re-set or change a session value to reopen. Optional English defaults through en/es i18n for title, description, credentialIdLabel, expiryLabel, secretLabel, showLabel, hideLabel, copyLabel, copiedLabel, successAnnouncement, failureAnnouncement, warningTitle, warningText and closeLabel. Copy results are announced politely, including manual-selection fallback. Popup initial focus and focus trapping use Base UI; at close, resolveReturnFocus() is validated for connection, visibility, enabled state and focusability, then fallbackFocus(), then the original opener. Synthetic fixtures only; the default Stored preview is masked and the Fresh preview starts closed.',
   uses: ['Dialog', 'SecretField', 'CodeBlock', 'CopyButton', 'Alert', 'LiveAnnouncer', 'Button'],
 };

package/src/forms/CredentialDisclosureDialog/examples/Inline.tsx

@@ -0,0 +1,19 @@
+import { useState } from 'react';
+import { CredentialDisclosureDialog } from '../CredentialDisclosureDialog';
+import { freshDisclosure } from '../fixtures';
+
+export default function Inline() {
+  const [open, setOpen] = useState(true);
+  if (!open) return null;
+  return (
+    <CredentialDisclosureDialog
+      disclosure={freshDisclosure}
+      presentation="inline"
+      maskFresh
+      onClose={() => setOpen(false)}
+      title="Connection credentials"
+      secretLabel="DSN"
+      additionalSecrets={[{ id: 'password', label: 'Password', value: 'synthetic_password_for_demo_only' }]}
+    />
+  );
+}

package/src/forms/CredentialDisclosureDialog/examples/IssueOnClick.tsx

@@ -0,0 +1,87 @@
+import { Alert, Button } from '@gntik-ai/ui';
+import { useEffect, useRef, useState } from 'react';
+import { CredentialDisclosureDialog, type CredentialDisclosure } from '../CredentialDisclosureDialog';
+import { freshDisclosure } from '../fixtures';
+
+const syntheticRequest = async () => ({ ...freshDisclosure });
+
+/** Page recipe: the caller owns issuance, cancellation and errors. Fixtures are synthetic. */
+export default function IssueOnClick({
+  request = syntheticRequest,
+}: {
+  request?: (signal: AbortSignal) => Promise<CredentialDisclosure>;
+}) {
+  const [disclosure, setDisclosure] = useState<CredentialDisclosure | null>(null);
+  const [pending, setPending] = useState(false);
+  const [failed, setFailed] = useState(false);
+  const current = useRef<AbortController | null>(null);
+  const trigger = useRef<HTMLButtonElement>(null);
+  useEffect(
+    () => () => {
+      current.current?.abort();
+    },
+    [],
+  );
+  const issue = async () => {
+    current.current?.abort();
+    const controller = new AbortController();
+    current.current = controller;
+    setDisclosure(null);
+    setFailed(false);
+    setPending(true);
+    try {
+      const response = await request(controller.signal);
+      if (!controller.signal.aborted) setDisclosure(response);
+    } catch {
+      if (!controller.signal.aborted) setFailed(true);
+    } finally {
+      if (!controller.signal.aborted) {
+        current.current = null;
+        setPending(false);
+      }
+    }
+  };
+  return (
+    <>
+      <h1>Issue a credential</h1>
+      <div className="flex flex-wrap gap-2">
+        <Button
+          ref={trigger}
+          loading={pending}
+          onClick={() => {
+            void issue();
+          }}
+        >
+          Issue credential
+        </Button>
+        {pending && (
+          <>
+            <Button
+              onClick={() => {
+                current.current?.abort();
+                current.current = null;
+                setPending(false);
+              }}
+            >
+              Cancel request
+            </Button>
+            <Button
+              onClick={() => {
+                void issue();
+              }}
+            >
+              Supersede request
+            </Button>
+          </>
+        )}
+      </div>
+      {failed && <Alert tone="destructive" title="Request failed" description="No credential was disclosed." />}
+      <CredentialDisclosureDialog
+        disclosure={disclosure}
+        maskFresh
+        onClose={() => setDisclosure(null)}
+        resolveReturnFocus={() => trigger.current}
+      />
+    </>
+  );
+}

package/src/forms/CredentialDisclosureDialog/examples/MultiSecret.tsx

@@ -0,0 +1,29 @@
+import { CodeBlock } from '@gntik-ai/ui';
+import { useState } from 'react';
+import { CredentialDisclosureDialog } from '../CredentialDisclosureDialog';
+import { freshDisclosure } from '../fixtures';
+
+/** All values and snippets are synthetic; closing unmounts every secret-bearing prop. */
+export default function MultiSecret() {
+  const [open, setOpen] = useState(true);
+  if (!open) return null;
+  return (
+    <CredentialDisclosureDialog
+      disclosure={freshDisclosure}
+      maskFresh
+      onClose={() => setOpen(false)}
+      secretLabel="Access key"
+      additionalSecrets={[
+        { id: 'dsn', label: 'DSN', value: 'synthetic_dsn_for_demo_only' },
+        { id: 'password', label: 'Password', value: 'synthetic_password_for_demo_only' },
+      ]}
+      revealContent={
+        <CodeBlock
+          copyable={false}
+          label="Integration examples"
+          code={`fetch('/example', { headers: { Authorization: '${freshDisclosure.secret}' } })\ncurl -H 'Authorization: ${freshDisclosure.secret}' /example`}
+        />
+      }
+    />
+  );
+}

package/src/forms/CredentialDisclosureDialog/focus.ts

@@ -0,0 +1,18 @@
+/** Programmatic focus permits negative tabIndex, but never hidden, inert or disabled targets. */
+export function usableFocusTarget(element: Element | null | undefined): element is HTMLElement {
+  if (!(element instanceof HTMLElement) || !element.isConnected || element === document.body) return false;
+  if (element.matches(':disabled, [disabled], [aria-disabled="true"], input[type="hidden"]')) return false;
+  for (let ancestor: HTMLElement | null = element; ancestor; ancestor = ancestor.parentElement) {
+    if (ancestor.hidden || ancestor.hasAttribute('inert') || ancestor.getAttribute('aria-disabled') === 'true')
+      return false;
+    const style = getComputedStyle(ancestor);
+    if (
+      style.display === 'none' ||
+      style.visibility === 'hidden' ||
+      style.visibility === 'collapse' ||
+      style.contentVisibility === 'hidden'
+    )
+      return false;
+  }
+  return element.tabIndex >= 0 || element.hasAttribute('tabindex') || element.isContentEditable;
+}

package/src/forms/CredentialDisclosureDialog/types.ts

@@ -0,0 +1,5 @@
+export interface CredentialSecret {
+  id: string;
+  label: string;
+  value: string;
+}