IS-11495 Render WebAuthn registration attachment options as selection cards

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: aleixsuau

src/haapi-react-app/src/shared/util/css/styles.css

@@ -297,6 +297,54 @@ svg {
   }
 }
 
+/* WebAuthn registration attachment-selection option cards */
+.haapi-stepper-webauthn-registration-attachment {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  width: 100%;
+  margin-block-start: var(--space-2);
+  padding: var(--space-3);
+  text-align: left;
+  background-color: transparent;
+  color: var(--color-text);
+  border: var(--form-field-border-width) var(--form-field-border-style) var(--form-field-border-color);
+  border-radius: var(--form-field-border-radius);
+  cursor: pointer;
+  transition: color 200ms, background-color 200ms, border-color 200ms;
+
+  /* Match the corporate `.button-primary-outline` hover: fill with the brand colour, invert text. */
+  &:hover,
+  &:focus-visible {
+    background-color: var(--button-color);
+    border-color: var(--button-color);
+    color: white;
+
+    .haapi-stepper-webauthn-registration-attachment-icon {
+      color: white;
+    }
+  }
+}
+
+.haapi-stepper-webauthn-registration-attachment-icon {
+  display: inline-flex;
+  flex-shrink: 0;
+  width: 48px;
+  height: 48px;
+  /* Brand blue-grey of the source artwork; the icons use currentColor so this can be overridden. */
+  color: #626c87;
+
+  svg {
+    width: 100%;
+    height: 100%;
+  }
+}
+
+.haapi-stepper-webauthn-registration-attachment-title {
+  font-family: var(--type-bold);
+  margin-inline-end: var(--space-2);
+}
+
 .haapi-stepper-heading {
   &:is(h1) {
     font-size: calc(var(--type-base-size) * 1.75);

src/haapi-react-sdk/haapi-stepper/README.md

@@ -147,7 +147,9 @@ Check out [the HaapiStepperStepUI documentation and usage examples](./feature/st
 
 ### ViewName built-in UIs
 
-The HaapiStepperStepUI ships built-in UIs for specific HAAPI `viewName`s (`step.metadata.viewName`) that need a more tailored UI than the generic step shell can provide (e.g. the BankID requires the QR link to be lifted above the actions). They are displayed by default and can be customized like any other step by using render interceptors.
+The HaapiStepperStepUI ships built-in UIs for specific HAAPI `viewName`s (`step.metadata.viewName`) that need a more tailored UI than the generic step shell can provide (e.g. the BankID requires the QR link to be lifted above the actions). 
+
+ViewName built-in UIs operate at the **step** level: they reshape the whole step for a given `viewName`. They are displayed by default and can be customized like any other step by using render interceptors.
 
 Check out documentation and usage examples in [`HaapiStepperStepUI`](./feature/steps/HaapiStepperStepUI.tsx), and the test use cases in [`HaapiStepperStepUI.spec.tsx`](./feature/steps/HaapiStepperStepUI.spec.tsx) (`describe('ViewName built-in UIs Rendering')`) for more details.
 
@@ -237,6 +239,10 @@ The Curity utility composition shown above is just how *this* project chose to i
 | `.haapi-stepper-userName` | `HaapiStepperMessagesUI` | User name display |
 | `.haapi-stepper-userCode` | `HaapiStepperMessagesUI` | User code display (e.g. recovery codes) |
 | `.haapi-stepper-polling-progress` | `HaapiStepperClientOperationUI` | Remaining polling time indicator (e.g. recovery codes) |
+| `.haapi-stepper-webauthn-registration-attachment` | `HaapiStepperWebAuthnRegistrationAttachmentCard` | WebAuthn registration attachment-selection option card (icon + title + description) |
+| `.haapi-stepper-webauthn-registration-attachment-icon` | `HaapiStepperWebAuthnRegistrationAttachmentCard` | Attachment card icon |
+| `.haapi-stepper-webauthn-registration-attachment-title` | `HaapiStepperWebAuthnRegistrationAttachmentCard` | Attachment card option label |
+| `.haapi-stepper-webauthn-registration-attachment-description` | `HaapiStepperWebAuthnRegistrationAttachmentCard` | Attachment card option description |
 | `.haapi-stepper-error-boundary-fallback` | `DefaultErrorFallback` | Error boundary fallback container |
 | `.haapi-validation-errors-container` | `HaapiStepperFormValidationErrorInputWrapper` | Wrapper around a form field that has validation errors. Receives the `.has-errors` modifier class while errors are visible |
 | `.haapi-validation-errors` | `HaapiStepperFormValidationErrorInputWrapper` | Inner container that holds the list of validation error messages |

src/haapi-react-sdk/haapi-stepper/feature/actions/client-operation/HaapiStepperClientOperationUI.spec.tsx

@@ -19,6 +19,7 @@ import {
   createMockExternalBrowserFlowAction,
   createMockStep,
   createMockWebAuthnAnyDeviceBothOptionsAction,
+  createMockWebAuthnCrossPlatformOnlyAnyDeviceAction,
   createMockWebAuthnPlatformOnlyAnyDeviceAction,
   createMockWebAuthnRegistrationAction,
   externalBrowserFlowActionTitle,
@@ -28,15 +29,22 @@ import {
 } from '../../../util/tests/mocks';
 import { HaapiStepperActionsUI } from '../../../ui/actions/HaapiStepperActionsUI';
 import { HaapiStepperClientOperationUI } from './HaapiStepperClientOperationUI';
-import { useIsWebAuthnPlatformAuthenticatorAvailable } from './operations/webauthn';
-
-vi.mock('./operations/webauthn', async () => {
-  const actual = await vi.importActual('./operations/webauthn');
-  return {
-    ...(actual as object),
-    useIsWebAuthnPlatformAuthenticatorAvailable: vi.fn(() => undefined),
-  };
-});
+import { useIsWebAuthnPlatformAuthenticatorAvailable } from './operations/webauthn/useIsWebAuthnPlatformAuthenticatorAvailable';
+import { WebAuthnRegistrationAttachmentKind } from '../../stepper/haapi-stepper.types';
+
+const PLATFORM_TITLE = 'Built-in';
+const PLATFORM_DESCRIPTION = 'A non-removable built-in device.';
+const PLATFORM_ICON_VIEW_BOX = '0 0 64.2 83.9';
+const CROSS_PLATFORM_TITLE = 'Security key';
+const CROSS_PLATFORM_DESCRIPTION =
+  'A security key, such as a portable key attached through USB or wirelessly through NFC.';
+const CROSS_PLATFORM_ICON_VIEW_BOX = '0 0 49 72.6';
+const REGISTER_VIEW_NAME = 'authenticator/webauthn/register/get';
+const MESSAGE_PREFIX = 'authenticator.webauthn.register.view.';
+
+vi.mock('./operations/webauthn/useIsWebAuthnPlatformAuthenticatorAvailable', () => ({
+  useIsWebAuthnPlatformAuthenticatorAvailable: vi.fn(() => undefined),
+}));
 
 describe('HaapiStepperClientOperationUI', () => {
   let user: ReturnType<typeof userEvent.setup>;
@@ -141,6 +149,76 @@ describe('HaapiStepperClientOperationUI', () => {
         screen.getByRole('button', { name: `${webAuthnAnyDeviceActionTitle} (Security key)` })
       ).toBeInTheDocument();
     });
+
+    describe('WebAuthn registration attachment card (any device mode (platform/cross-platform))', () => {
+      it.each([
+        {
+          name: 'platform',
+          makeAction: createMockWebAuthnPlatformOnlyAnyDeviceAction,
+          kind: WebAuthnRegistrationAttachmentKind.PLATFORM,
+          title: PLATFORM_TITLE,
+          description: PLATFORM_DESCRIPTION,
+          iconViewBox: PLATFORM_ICON_VIEW_BOX,
+        },
+        {
+          name: 'cross-platform',
+          makeAction: createMockWebAuthnCrossPlatformOnlyAnyDeviceAction,
+          kind: WebAuthnRegistrationAttachmentKind.CROSS_PLATFORM,
+          title: CROSS_PLATFORM_TITLE,
+          description: CROSS_PLATFORM_DESCRIPTION,
+          iconViewBox: CROSS_PLATFORM_ICON_VIEW_BOX,
+        },
+      ])(
+        'renders the $name attachment option as a card (title, description and matching icon)',
+        ({ makeAction, kind, title, description, iconViewBox }) => {
+          const action = { ...makeAction(), webauthn: { registrationAttachment: { kind, title, description } } };
+
+          const { container } = render(<HaapiStepperClientOperationUI action={action} onAction={vi.fn()} />);
+
+          expect(screen.getByTestId('webauthn-registration-attachment-card')).toBeInTheDocument();
+          expect(screen.getByText(title)).toBeInTheDocument();
+          expect(screen.getByText(description)).toBeInTheDocument();
+          expect(container.querySelector('.haapi-stepper-webauthn-registration-attachment-icon svg')).toHaveAttribute(
+            'viewBox',
+            iconViewBox
+          );
+        }
+      );
+
+      it('renders one card per option when a both-options any-device registration supplies messages', () => {
+        const step = createMockStep(HAAPI_STEPS.REGISTRATION, {
+          actions: [createMockWebAuthnAnyDeviceBothOptionsAction()],
+          metadata: {
+            viewName: REGISTER_VIEW_NAME,
+            viewData: {
+              messages: {
+                [`${MESSAGE_PREFIX}button.platform`]: PLATFORM_TITLE,
+                [`${MESSAGE_PREFIX}button.cross-platform`]: CROSS_PLATFORM_TITLE,
+                [`${MESSAGE_PREFIX}authenticator-attachment.platform`]: PLATFORM_DESCRIPTION,
+                [`${MESSAGE_PREFIX}authenticator-attachment.cross-platform`]: CROSS_PLATFORM_DESCRIPTION,
+              },
+            },
+          },
+        });
+
+        render(<HaapiStepperActionsUI actions={step.dataHelpers.actions?.all} onAction={vi.fn()} />);
+
+        // The both-options action is split upstream into two single-option actions, so it renders as
+        // two separate cards — the component itself never receives both attachments at once.
+        expect(screen.getAllByTestId('webauthn-registration-attachment-card')).toHaveLength(2);
+        expect(screen.getByText(PLATFORM_TITLE)).toBeInTheDocument();
+        expect(screen.getByText(CROSS_PLATFORM_TITLE)).toBeInTheDocument();
+      });
+
+      it('renders the default button (no card) when the action has no attachment copy', () => {
+        render(
+          <HaapiStepperClientOperationUI action={createMockWebAuthnPlatformOnlyAnyDeviceAction()} onAction={vi.fn()} />
+        );
+
+        expect(screen.queryByTestId('webauthn-registration-attachment-card')).not.toBeInTheDocument();
+        expect(screen.getByTestId('client-operation-action')).toBeInTheDocument();
+      });
+    });
   });
 });
 

src/haapi-react-sdk/haapi-stepper/feature/actions/client-operation/HaapiStepperClientOperationUI.tsx

@@ -11,6 +11,10 @@
 
 import { HaapiStepperClientOperationAction, HaapiStepperFormAction } from '../../stepper/haapi-stepper.types';
 import { useIsClientOperationAvailable } from './useIsClientOperationAvailable';
+import {
+  HaapiStepperWebAuthnRegistrationAttachmentCard,
+  isAnyDeviceWebAuthnRegistrationClientOperation,
+} from './operations/webauthn';
 
 interface HaapiStepperClientOperationUIProps {
   action: HaapiStepperClientOperationAction;
@@ -50,6 +54,16 @@ export function HaapiStepperClientOperationUI({
 }: HaapiStepperClientOperationUIProps) {
   const isAvailable = useIsClientOperationAvailable(action);
 
+  if (isAnyDeviceWebAuthnRegistrationClientOperation(action) && action.webauthn?.registrationAttachment) {
+    return (
+      <HaapiStepperWebAuthnRegistrationAttachmentCard
+        action={action}
+        disabled={!isAvailable}
+        onClick={() => onAction(action)}
+      />
+    );
+  }
+
   return (
     <div data-testid="client-operation-action">
       {showBankIdSessionTimeLeft && action.maxWaitRemainingTime !== undefined && (

src/haapi-react-sdk/haapi-stepper/feature/actions/client-operation/operations/webauthn/HaapiStepperWebAuthnRegistrationAttachmentCard.spec.tsx

@@ -0,0 +1,94 @@
+/*
+ * Copyright (C) 2026 Curity AB. All rights reserved.
+ *
+ * The contents of this file are the property of Curity AB.
+ * You may not copy or use this file, in either source code
+ * or executable form, except in compliance with terms
+ * set by Curity AB.
+ *
+ * For further information, please contact Curity AB.
+ */
+
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createMockWebAuthnPlatformOnlyAnyDeviceAction } from '../../../../../util/tests/mocks';
+import {
+  HaapiStepperWebAuthnAnyDeviceRegistrationAction,
+  HaapiWebAuthnRegistrationAttachment,
+  WebAuthnRegistrationAttachmentKind,
+} from '../../../../stepper/haapi-stepper.types';
+import { HaapiStepperWebAuthnRegistrationAttachmentCard } from './HaapiStepperWebAuthnRegistrationAttachmentCard';
+
+const PLATFORM_TITLE = 'Built-in';
+const PLATFORM_DESCRIPTION = 'A non-removable built-in device.';
+const PLATFORM_ICON_VIEW_BOX = '0 0 64.2 83.9';
+const CROSS_PLATFORM_TITLE = 'Security key';
+const CROSS_PLATFORM_ICON_VIEW_BOX = '0 0 49 72.6';
+
+const actionWith = (
+  registrationAttachment?: HaapiWebAuthnRegistrationAttachment
+): HaapiStepperWebAuthnAnyDeviceRegistrationAction => ({
+  ...createMockWebAuthnPlatformOnlyAnyDeviceAction(),
+  webauthn: registrationAttachment ? { registrationAttachment } : undefined,
+});
+
+describe('HaapiStepperWebAuthnRegistrationAttachmentCard', () => {
+  it('renders the title, description and icon resolved from the action attachment', () => {
+    const { container } = render(
+      <HaapiStepperWebAuthnRegistrationAttachmentCard
+        action={actionWith({
+          kind: WebAuthnRegistrationAttachmentKind.PLATFORM,
+          title: PLATFORM_TITLE,
+          description: PLATFORM_DESCRIPTION,
+        })}
+        onClick={vi.fn()}
+      />
+    );
+
+    expect(screen.getByText(PLATFORM_TITLE)).toBeInTheDocument();
+    expect(screen.getByText(PLATFORM_DESCRIPTION)).toBeInTheDocument();
+    expect(container.querySelector('.haapi-stepper-webauthn-registration-attachment-icon svg')).toHaveAttribute(
+      'viewBox',
+      PLATFORM_ICON_VIEW_BOX
+    );
+  });
+
+  it('omits the description when the attachment has none, still rendering the icon', () => {
+    const { container } = render(
+      <HaapiStepperWebAuthnRegistrationAttachmentCard
+        action={actionWith({ kind: WebAuthnRegistrationAttachmentKind.CROSS_PLATFORM, title: CROSS_PLATFORM_TITLE })}
+        onClick={vi.fn()}
+      />
+    );
+
+    const card = screen.getByTestId('webauthn-registration-attachment-card');
+    expect(screen.getByText(CROSS_PLATFORM_TITLE)).toBeInTheDocument();
+    expect(card.querySelector('.haapi-stepper-webauthn-registration-attachment-description')).toBeNull();
+    expect(container.querySelector('.haapi-stepper-webauthn-registration-attachment-icon svg')).toHaveAttribute(
+      'viewBox',
+      CROSS_PLATFORM_ICON_VIEW_BOX
+    );
+  });
+
+  it('renders nothing when the action carries no attachment', () => {
+    render(<HaapiStepperWebAuthnRegistrationAttachmentCard action={actionWith()} onClick={vi.fn()} />);
+
+    expect(screen.queryByTestId('webauthn-registration-attachment-card')).not.toBeInTheDocument();
+  });
+
+  it('calls onClick when the card is clicked', async () => {
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    render(
+      <HaapiStepperWebAuthnRegistrationAttachmentCard
+        action={actionWith({ kind: WebAuthnRegistrationAttachmentKind.PLATFORM, title: PLATFORM_TITLE })}
+        onClick={onClick}
+      />
+    );
+
+    await user.click(screen.getByTestId('webauthn-registration-attachment-card'));
+    expect(onClick).toHaveBeenCalledOnce();
+  });
+});

src/haapi-react-sdk/haapi-stepper/feature/actions/client-operation/operations/webauthn/HaapiStepperWebAuthnRegistrationAttachmentCard.tsx

@@ -0,0 +1,61 @@
+/*
+ * Copyright (C) 2026 Curity AB. All rights reserved.
+ *
+ * The contents of this file are the property of Curity AB.
+ * You may not copy or use this file, in either source code
+ * or executable form, except in compliance with terms
+ * set by Curity AB.
+ *
+ * For further information, please contact Curity AB.
+ */
+
+import { HaapiStepperWebAuthnAnyDeviceRegistrationAction } from '../../../../stepper/haapi-stepper.types';
+import { REGISTRATION_ATTACHMENT_ICON } from './webauthn-registration-attachment-icon-map';
+
+export interface HaapiStepperWebAuthnRegistrationAttachmentCardProps {
+  /** The any-device `webauthn-registration` action this option advances the flow with. */
+  action: HaapiStepperWebAuthnAnyDeviceRegistrationAction;
+  /** Disables the card (e.g. when the required authenticator capability is unavailable). */
+  disabled?: boolean;
+  onClick: () => void;
+}
+
+/**
+ * A single WebAuthn registration attachment-selection option, rendered as a clickable card
+ * (icon + bold title + description). Resolves the localized copy and icon from the action's
+ * `attachment` and wires `onClick` to advance the flow.
+ *
+ * Exported so consumers building a custom WebAuthn registration UI can reuse it.
+ */
+export const HaapiStepperWebAuthnRegistrationAttachmentCard = ({
+  action,
+  disabled,
+  onClick,
+}: HaapiStepperWebAuthnRegistrationAttachmentCardProps) => {
+  const registrationAttachment = action.webauthn?.registrationAttachment;
+  if (!registrationAttachment) {
+    return null;
+  }
+
+  return (
+    <button
+      type="button"
+      className="haapi-stepper-webauthn-registration-attachment"
+      data-testid="webauthn-registration-attachment-card"
+      disabled={disabled}
+      onClick={onClick}
+    >
+      <span className="haapi-stepper-webauthn-registration-attachment-icon" aria-hidden="true">
+        {REGISTRATION_ATTACHMENT_ICON[registrationAttachment.kind]}
+      </span>
+      <span className="haapi-stepper-webauthn-registration-attachment-text">
+        <strong className="haapi-stepper-webauthn-registration-attachment-title">{registrationAttachment.title}</strong>
+        {registrationAttachment.description && (
+          <span className="haapi-stepper-webauthn-registration-attachment-description">
+            {registrationAttachment.description}
+          </span>
+        )}
+      </span>
+    </button>
+  );
+};

src/haapi-react-sdk/haapi-stepper/feature/actions/client-operation/operations/webauthn/index.ts

@@ -13,3 +13,6 @@ export * from './webauthn';
 export * from './utils';
 export * from './useIsWebAuthnPlatformAuthenticatorAvailable';
 export * from './auto-start';
+export * from './HaapiStepperWebAuthnRegistrationAttachmentCard';
+export * from './webauthn-registration-attachment-icons';
+export * from './webauthn-registration-attachment-icon-map';