@gntik-ai/blocks 0.0.0-stage → 0.6.0

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

@@ -0,0 +1,10 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Create API key dialog',
+  family: 'forms',
+  status: 'stable',
+  description:
+    'Two-step dialog: name, scopes and expiry, then the secret shown once in a copyable CodeBlock with a warning.',
+  uses: ['Dialog', 'Field', 'Input', 'CheckboxGroup', 'Checkbox', 'Select', 'CodeBlock', 'Alert', 'Button'],
+};

package/src/forms/CreateApiKeyDialog/fixtures.ts

@@ -0,0 +1,31 @@
+export interface ApiKeyScope {
+  value: string;
+  label: string;
+  description?: string;
+}
+
+export interface ApiKeyExpiry {
+  value: string;
+  label: string;
+}
+
+export const apiKeyScopes: ApiKeyScope[] = [
+  { value: 'projects:read', label: 'projects:read', description: 'List and read projects and deployments.' },
+  { value: 'projects:write', label: 'projects:write', description: 'Create, update and deploy projects.' },
+  { value: 'members:read', label: 'members:read', description: 'Read workspace members and roles.' },
+  { value: 'billing:read', label: 'billing:read', description: 'Read invoices and usage.' },
+];
+
+export const apiKeyExpiries: ApiKeyExpiry[] = [
+  { value: '30d', label: '30 days' },
+  { value: '90d', label: '90 days' },
+  { value: '1y', label: '1 year' },
+  { value: 'never', label: 'No expiry' },
+];
+
+/** Demo secret generator (the real secret comes from your API). */
+export function generateDemoSecret(prefix = 'sk_live_') {
+  const bytes = new Uint8Array(24);
+  globalThis.crypto.getRandomValues(bytes);
+  return prefix + Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}

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

@@ -0,0 +1,339 @@
+import { act, render, screen, waitFor, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { useState } from 'react';
+import { expectNoAxeViolations } from '../../test/a11y';
+import {
+  CredentialDisclosureDialog,
+  type CredentialDisclosure,
+  type CredentialDisclosureDialogProps,
+} from './CredentialDisclosureDialog';
+
+const stored: CredentialDisclosure = {
+  variant: 'stored',
+  credentialId: 'cred_demo_01',
+  expiresAt: 'January 1, 2030',
+  secret: 'synthetic_secret_for_tests_only',
+};
+
+function RequestHarness({ request }: { request: () => Promise<CredentialDisclosure> }) {
+  const [disclosure, setDisclosure] = useState<CredentialDisclosure | null>(null);
+  return (
+    <>
+      <button
+        onClick={() => {
+          void request()
+            .then(setDisclosure)
+            .catch(() => {});
+        }}
+      >
+        Request
+      </button>
+      <CredentialDisclosureDialog disclosure={disclosure} onClose={() => setDisclosure(null)} />
+    </>
+  );
+}
+
+it('renders nothing until a successful response, including pending and rejected requests', async () => {
+  const user = userEvent.setup();
+  let resolve!: (value: CredentialDisclosure) => void;
+  let reject!: (reason: Error) => void;
+  const pending = new Promise<CredentialDisclosure>((yes, no) => {
+    resolve = yes;
+    reject = no;
+  });
+  const { rerender } = render(<RequestHarness request={() => pending} />);
+  expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+  expect(document.body.innerHTML).not.toContain(stored.secret);
+  await user.click(screen.getByRole('button', { name: 'Request' }));
+  expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+  await act(async () => reject(new Error('Synthetic rejection')));
+  expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+  expect(document.body.innerHTML).not.toContain(stored.secret);
+  const success = new Promise<CredentialDisclosure>((yes) => {
+    resolve = yes;
+  });
+  rerender(<RequestHarness request={() => success} />);
+  await user.click(screen.getByRole('button', { name: 'Request' }));
+  await act(async () => resolve(stored));
+  expect(await screen.findByRole('dialog')).toBeInTheDocument();
+  expect(document.body.innerHTML).not.toContain(stored.secret);
+});
+
+const labels = {
+  title: 'Credential value',
+  description: 'Keep this value safe.',
+  credentialIdLabel: 'Identifier',
+  expiryLabel: 'Valid until',
+  secretLabel: 'Secret value',
+  showLabel: 'Reveal value',
+  hideLabel: 'Mask value',
+  copyLabel: 'Copy value',
+  copiedLabel: 'Saved',
+  successAnnouncement: 'Value saved safely',
+  failureAnnouncement: 'Select and copy manually.',
+  closeLabel: 'Dismiss',
+};
+
+it('renders caller labels, copies the real stored value, and resets masking and feedback on reopening or replacement', async () => {
+  const user = userEvent.setup();
+  const writeText = vi.fn().mockResolvedValue(undefined);
+  Object.defineProperty(navigator, 'clipboard', { value: { writeText }, configurable: true });
+  const onClose = vi.fn();
+  const { rerender } = render(<CredentialDisclosureDialog disclosure={stored} onClose={onClose} {...labels} />);
+  const dialog = await screen.findByRole('dialog', { name: labels.title });
+  expect(dialog).toHaveAccessibleDescription(labels.description);
+  const dl = dialog.querySelector('dl');
+  expect(dl).toHaveTextContent('Identifier');
+  expect(dl).toHaveTextContent(stored.credentialId);
+  expect(dl).toHaveTextContent('Valid until');
+  expect(dl).toHaveTextContent('January 1, 2030');
+  expect(document.body.innerHTML).not.toContain(stored.secret);
+  await user.click(screen.getByRole('button', { name: labels.showLabel }));
+  expect(screen.getByRole('button', { name: labels.hideLabel })).toHaveAttribute('aria-pressed', 'true');
+  expect(screen.getByRole('textbox', { name: labels.secretLabel })).toHaveValue(stored.secret);
+  await user.click(screen.getByRole('button', { name: labels.copyLabel }));
+  expect(writeText).toHaveBeenCalledWith(stored.secret);
+  expect(screen.getByRole('status')).toHaveTextContent(labels.successAnnouncement);
+  expect(screen.getByRole('button', { name: labels.copiedLabel })).toBeInTheDocument();
+  await user.click(screen.getByRole('button', { name: labels.closeLabel }));
+  expect(onClose).toHaveBeenCalledTimes(1);
+  expect(document.body.innerHTML).not.toContain(stored.secret);
+  rerender(<CredentialDisclosureDialog disclosure={null} onClose={onClose} {...labels} />);
+  rerender(<CredentialDisclosureDialog disclosure={stored} onClose={onClose} {...labels} />);
+  await screen.findByRole('dialog');
+  expect(screen.getByRole('button', { name: labels.showLabel })).toHaveAttribute('aria-pressed', 'false');
+  expect(screen.getByRole('status')).toBeEmptyDOMElement();
+  await user.click(screen.getByRole('button', { name: labels.showLabel }));
+  await user.click(screen.getByRole('button', { name: labels.copyLabel }));
+  rerender(
+    <CredentialDisclosureDialog
+      disclosure={{ ...stored, secret: 'synthetic_replacement_value' }}
+      onClose={onClose}
+      {...labels}
+    />,
+  );
+  expect(screen.getByRole('button', { name: labels.showLabel })).toHaveAttribute('aria-pressed', 'false');
+  expect(screen.getByRole('status')).toBeEmptyDOMElement();
+  expect(document.body.innerHTML).not.toContain('synthetic_replacement_value');
+  await user.click(screen.getByRole('button', { name: labels.showLabel }));
+  rerender(
+    <CredentialDisclosureDialog
+      disclosure={{ ...stored, credentialId: 'cred_demo_02' }}
+      onClose={onClose}
+      {...labels}
+    />,
+  );
+  expect(screen.getByRole('button', { name: labels.showLabel })).toHaveAttribute('aria-pressed', 'false');
+});
+
+it('shows a fresh secret with one kit copy action and replacement warning, and discards it on dismissal', async () => {
+  const user = userEvent.setup();
+  const onClose = vi.fn();
+  const fresh: CredentialDisclosure = { ...stored, variant: 'fresh' };
+  const { rerender } = render(
+    <CredentialDisclosureDialog
+      disclosure={fresh}
+      onClose={onClose}
+      {...labels}
+      warningTitle="Replacement"
+      warningText="This value replaces the previous secret."
+    />,
+  );
+  const dialog = await screen.findByRole('dialog');
+  expect(within(dialog).getByRole('region', { name: labels.secretLabel })).toHaveTextContent(stored.secret);
+  expect(within(dialog).getByRole('alert')).toHaveTextContent('Replacement');
+  expect(within(dialog).getByRole('alert')).toHaveTextContent('This value replaces the previous secret.');
+  expect(screen.getAllByRole('button', { name: labels.copyLabel })).toHaveLength(1);
+  await user.click(screen.getByRole('button', { name: labels.closeLabel }));
+  expect(onClose).toHaveBeenCalledTimes(1);
+  expect(document.body.innerHTML).not.toContain(stored.secret);
+  rerender(<CredentialDisclosureDialog disclosure={null} onClose={onClose} {...labels} />);
+  expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+  expect(document.body.innerHTML).not.toContain(stored.secret);
+  expect(onClose).toHaveBeenCalledTimes(1);
+});
+
+function FocusHarness({
+  triggerVersion = 0,
+  disclosureVersion = 0,
+  resolveReturnFocus,
+  fallbackFocus,
+}: Pick<CredentialDisclosureDialogProps, 'resolveReturnFocus' | 'fallbackFocus'> & {
+  triggerVersion?: number;
+  disclosureVersion?: number;
+}) {
+  const [disclosure, setDisclosure] = useState<CredentialDisclosure | null>(null);
+  return (
+    <>
+      <h1 id="fallback" tabIndex={-1}>
+        Credentials
+      </h1>
+      <button key={triggerVersion} id="opener" onClick={() => setDisclosure(stored)}>
+        Open
+      </button>
+      <div>
+        <button id="return">Return action</button>
+      </div>
+      <CredentialDisclosureDialog
+        disclosure={
+          disclosure && { ...disclosure, secret: disclosureVersion ? 'synthetic_new_value' : disclosure.secret }
+        }
+        onClose={() => setDisclosure(null)}
+        resolveReturnFocus={resolveReturnFocus}
+        fallbackFocus={fallbackFocus}
+        {...labels}
+      />
+    </>
+  );
+}
+
+it('focuses the popup, traps Tab, closes on Escape and resolves the live replaced trigger at close time', async () => {
+  const user = userEvent.setup();
+  const resolveReturnFocus = vi.fn(() => document.getElementById('opener'));
+  const props = { resolveReturnFocus, fallbackFocus: () => document.getElementById('fallback') };
+  const { rerender } = render(<FocusHarness {...props} />);
+  const oldTrigger = screen.getByRole('button', { name: 'Open' });
+  await user.click(oldTrigger);
+  const dialog = await screen.findByRole('dialog');
+  await waitFor(() => expect(dialog).toHaveFocus());
+  for (let index = 0; index < 8; index++) {
+    await user.tab();
+    await waitFor(() => expect(dialog.contains(document.activeElement)).toBe(true));
+  }
+  await user.tab({ shift: true });
+  await waitFor(() => expect(dialog.contains(document.activeElement)).toBe(true));
+  rerender(<FocusHarness {...props} triggerVersion={1} />);
+  expect(oldTrigger.isConnected).toBe(false);
+  expect(resolveReturnFocus).not.toHaveBeenCalled();
+  await user.keyboard('{Escape}');
+  await waitFor(() => expect(screen.getByRole('button', { name: 'Open' })).toHaveFocus());
+  expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+});
+
+it.each([
+  'null',
+  'detached',
+  'disabled',
+  'removed',
+  'hidden',
+  'inert',
+  'nonfocusable',
+  'hidden-parent',
+  'disabled-fieldset',
+] as const)('uses the fallback heading for a %s return target', async (reason) => {
+  const user = userEvent.setup();
+  const resolveReturnFocus = () =>
+    reason === 'null'
+      ? null
+      : reason === 'detached'
+        ? document.createElement('button')
+        : document.getElementById('return');
+  render(
+    <FocusHarness resolveReturnFocus={resolveReturnFocus} fallbackFocus={() => document.getElementById('fallback')} />,
+  );
+  await user.click(screen.getByRole('button', { name: 'Open' }));
+  await screen.findByRole('dialog');
+  const target = document.getElementById('return')!;
+  if (reason === 'disabled') target.setAttribute('disabled', '');
+  if (reason === 'removed') target.remove();
+  if (reason === 'hidden') target.hidden = true;
+  if (reason === 'inert') target.setAttribute('inert', '');
+  if (reason === 'nonfocusable') {
+    const span = document.createElement('span');
+    span.id = 'return';
+    target.replaceWith(span);
+  }
+  if (reason === 'hidden-parent' || reason === 'disabled-fieldset') {
+    const wrapper = document.createElement(reason === 'hidden-parent' ? 'div' : 'fieldset');
+    if (reason === 'hidden-parent') wrapper.style.display = 'none';
+    else wrapper.setAttribute('disabled', '');
+    target.before(wrapper);
+    wrapper.append(target);
+  }
+  await user.click(screen.getByRole('button', { name: labels.closeLabel }));
+  await waitFor(() => expect(screen.getByRole('heading', { name: 'Credentials' })).toHaveFocus());
+});
+
+it.each(['null', 'detached', 'disabled', 'hidden', 'inert', 'nonfocusable'] as const)(
+  'returns to the original opener for a %s fallback',
+  async (reason) => {
+    const user = userEvent.setup();
+    const fallbackFocus = () =>
+      reason === 'null'
+        ? null
+        : reason === 'detached'
+          ? document.createElement('h1')
+          : document.getElementById('fallback');
+    render(<FocusHarness resolveReturnFocus={() => null} fallbackFocus={fallbackFocus} />);
+    const opener = screen.getByRole('button', { name: 'Open' });
+    await user.click(opener);
+    await screen.findByRole('dialog');
+    const heading = document.getElementById('fallback')!;
+    if (reason === 'disabled') heading.setAttribute('aria-disabled', 'true');
+    if (reason === 'hidden') heading.hidden = true;
+    if (reason === 'inert') heading.setAttribute('inert', '');
+    if (reason === 'nonfocusable') heading.removeAttribute('tabindex');
+    await user.keyboard('{Escape}');
+    await waitFor(() => expect(opener).toHaveFocus());
+  },
+);
+
+it.each([
+  ['stored', 'rejected'],
+  ['stored', 'missing'],
+  ['fresh', 'rejected'],
+  ['fresh', 'missing'],
+] as const)('announces %s clipboard %s politely, without logging secrets', async (variant, clipboard) => {
+  const user = userEvent.setup();
+  const logs = [
+    vi.spyOn(console, 'log'),
+    vi.spyOn(console, 'info'),
+    vi.spyOn(console, 'warn'),
+    vi.spyOn(console, 'error'),
+    vi.spyOn(console, 'debug'),
+  ];
+  const writeText = vi.fn().mockRejectedValue(new Error('Synthetic clipboard denial'));
+  Object.defineProperty(navigator, 'clipboard', {
+    value: clipboard === 'missing' ? undefined : { writeText },
+    configurable: true,
+  });
+  Object.defineProperty(document, 'execCommand', { value: () => false, configurable: true });
+  render(<CredentialDisclosureDialog disclosure={{ ...stored, variant }} onClose={() => {}} {...labels} />);
+  await screen.findByRole('dialog');
+  const feedback = document.querySelector('[data-live-announcer="polite"]');
+  expect(feedback).toBeEmptyDOMElement();
+  await user.click(screen.getByRole('button', { name: labels.copyLabel }));
+  expect(feedback).toHaveAttribute('aria-live', 'polite');
+  expect(feedback).toHaveTextContent(labels.failureAnnouncement);
+  expect(document.querySelector('[data-live-announcer="assertive"]')).toBeEmptyDOMElement();
+  if (clipboard === 'rejected') expect(writeText).toHaveBeenCalledWith(stored.secret);
+  else expect(writeText).not.toHaveBeenCalled();
+  expect(document.querySelector('textarea')).toBeNull();
+  for (const log of logs) {
+    expect(log.mock.calls.flat().some((value) => typeof value === 'string' && value.includes(stored.secret))).toBe(
+      false,
+    );
+    log.mockRestore();
+  }
+});
+
+it.each(['stored', 'fresh'] as const)('%s has no axe violations in all three themes', async (variant) => {
+  render(<CredentialDisclosureDialog disclosure={{ ...stored, variant }} onClose={() => {}} />);
+  const dialog = await screen.findByRole('dialog');
+  for (const theme of ['dark', 'light', 'high_contrast']) {
+    document.documentElement.className = theme;
+    await expectNoAxeViolations(dialog);
+  }
+});
+
+it('preserves the original opener when the credential value changes while open', async () => {
+  const user = userEvent.setup();
+  const { rerender } = render(<FocusHarness resolveReturnFocus={() => null} fallbackFocus={() => null} />);
+  const opener = screen.getByRole('button', { name: 'Open' });
+  await user.click(opener);
+  await waitFor(() => expect(screen.getByRole('dialog')).toHaveFocus());
+  rerender(<FocusHarness disclosureVersion={1} resolveReturnFocus={() => null} fallbackFocus={() => null} />);
+  await waitFor(() => expect(screen.getByRole('dialog')).toHaveFocus());
+  await user.keyboard('{Escape}');
+  await waitFor(() => expect(opener).toHaveFocus());
+});

package/src/forms/CredentialDisclosureDialog/CredentialDisclosureDialog.tsx

@@ -0,0 +1,193 @@
+import {
+  Button,
+  CopyButton,
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogDescription,
+  DialogBody,
+  DialogFooter,
+  DialogClose,
+  LiveAnnouncer,
+  SecretField,
+  CodeBlock,
+  Alert,
+  useI18n,
+} from '@gntik-ai/ui';
+import { useRef, useState, type ReactNode } from 'react';
+
+export interface CredentialDisclosure {
+  variant: 'stored' | 'fresh';
+  credentialId: string;
+  /** Caller-formatted expiry; the block applies no expiry policy. */
+  expiresAt: ReactNode;
+  secret: string;
+}
+
+export interface CredentialDisclosureDialogProps {
+  /** 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. */
+  onClose: () => void;
+  /** Resolve the current row action at close time, including after list reloads. */
+  resolveReturnFocus?: () => HTMLElement | null;
+  /** Resolve a fallback such as a page heading with tabIndex={-1}. */
+  fallbackFocus?: () => HTMLElement | null;
+  title?: string;
+  description?: string;
+  credentialIdLabel?: string;
+  expiryLabel?: string;
+  secretLabel?: string;
+  showLabel?: string;
+  hideLabel?: string;
+  copyLabel?: string;
+  copiedLabel?: string;
+  successAnnouncement?: string;
+  failureAnnouncement?: string;
+  warningTitle?: string;
+  warningText?: string;
+  closeLabel?: string;
+}
+
+/**
+ * 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.
+ */
+export function CredentialDisclosureDialog(props: CredentialDisclosureDialogProps) {
+  if (!props.disclosure) return null;
+  return <DisclosureOpening {...props} disclosure={props.disclosure} />;
+}
+
+type OpeningProps = CredentialDisclosureDialogProps & { disclosure: CredentialDisclosure };
+
+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 { 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} />;
+}
+
+function DisclosureSession({
+  disclosure,
+  onClose,
+  resolveReturnFocus,
+  fallbackFocus,
+  opener,
+  ...labels
+}: OpeningProps & { opener: Element | null }) {
+  const { t } = useI18n();
+  const [open, setOpen] = useState(true);
+  const popup = useRef<HTMLDivElement>(null);
+  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 closeLabel = labels.closeLabel ?? t('credentialDisclosure.close');
+  const secretLabel = labels.secretLabel ?? t('credentialDisclosure.secret');
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(next) => {
+        if (!next && !dismissed.current) {
+          dismissed.current = true;
+          setOpen(false);
+          onClose();
+        }
+      }}
+    >
+      <DialogContent
+        ref={popup}
+        initialFocus={popup}
+        finalFocus={returnFocus}
+        showClose={false}
+        closeLabel={closeLabel}
+      >
+        {open && (
+          <>
+            <DialogHeader>
+              <DialogTitle>{labels.title ?? t('credentialDisclosure.title')}</DialogTitle>
+              <DialogDescription>{labels.description ?? t('credentialDisclosure.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>
+            <DialogFooter>
+              <DialogClose render={<Button variant="secondary" />}>{closeLabel}</DialogClose>
+            </DialogFooter>
+          </>
+        )}
+      </DialogContent>
+    </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/block.meta.ts

@@ -0,0 +1,10 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Credential disclosure dialog',
+  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.',
+  uses: ['Dialog', 'SecretField', 'CodeBlock', 'CopyButton', 'Alert', 'LiveAnnouncer', 'Button'],
+};

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

@@ -0,0 +1,32 @@
+import { Button } from '@gntik-ai/ui';
+import { useRef, useState } from 'react';
+import { CredentialDisclosureDialog, type CredentialDisclosure } from '../CredentialDisclosureDialog';
+import { freshDisclosure } from '../fixtures';
+
+/** Closed on load: no preview or visual baseline exposes the synthetic fresh value. */
+export default function Fresh() {
+  const [disclosure, setDisclosure] = useState<CredentialDisclosure | null>(null);
+  const heading = useRef<HTMLHeadingElement>(null);
+  const trigger = useRef<HTMLButtonElement>(null);
+  return (
+    <>
+      <h1 ref={heading} tabIndex={-1}>
+        Credentials
+      </h1>
+      <Button
+        ref={trigger}
+        onClick={() => {
+          void Promise.resolve({ ...freshDisclosure }).then(setDisclosure);
+        }}
+      >
+        Disclose fresh secret
+      </Button>
+      <CredentialDisclosureDialog
+        disclosure={disclosure}
+        onClose={() => setDisclosure(null)}
+        resolveReturnFocus={() => trigger.current}
+        fallbackFocus={() => heading.current}
+      />
+    </>
+  );
+}