feat(react-card): add support for disabled cards (microsoft#35028)

Author: marcosmoura

apps/vr-tests-react-components/src/stories/Card/CardDisabled.stories.tsx

@@ -0,0 +1,98 @@
+import * as React from 'react';
+import { Steps, StoryWright } from 'storywright';
+import { Card } from '@fluentui/react-card';
+import { SampleCardContent } from './utils';
+import type { Meta } from '@storybook/react';
+import { getStoryVariant, DARK_MODE, HIGH_CONTRAST } from '../../utilities';
+
+export default {
+  title: 'Card Converged - Disabled',
+
+  decorators: [
+    story => (
+      <StoryWright
+        steps={new Steps()
+          .snapshot('normal', { cropTo: '.testWrapper' })
+          .hover('[role="group"]')
+          .snapshot('hover', { cropTo: '.testWrapper' })
+          .end()}
+      >
+        <div className="testWrapper" style={{ width: '300px' }}>
+          {story()}
+        </div>
+      </StoryWright>
+    ),
+  ],
+} satisfies Meta<typeof Card>;
+
+export const AppearanceDisabledFilled = () => (
+  <Card disabled appearance="filled">
+    <SampleCardContent controlsDisabled />
+  </Card>
+);
+
+AppearanceDisabledFilled.storyName = 'appearance disabled - Filled';
+
+export const AppearanceDisabledFilledDarkMode = getStoryVariant(AppearanceDisabledFilled, DARK_MODE);
+export const AppearanceDisabledFilledHighContrast = getStoryVariant(AppearanceDisabledFilled, HIGH_CONTRAST);
+
+export const AppearanceDisabledFilledAlternative = () => (
+  <Card disabled appearance="filled-alternative">
+    <SampleCardContent controlsDisabled />
+  </Card>
+);
+
+AppearanceDisabledFilledAlternative.storyName = 'appearance disabled - Filled Alternative';
+
+export const AppearanceDisabledFilledAlternativeDarkMode = getStoryVariant(
+  AppearanceDisabledFilledAlternative,
+  DARK_MODE,
+);
+export const AppearanceDisabledFilledAlternativeHighContrast = getStoryVariant(
+  AppearanceDisabledFilledAlternative,
+  HIGH_CONTRAST,
+);
+
+export const AppearanceDisabledOutline = () => (
+  <Card disabled appearance="outline">
+    <SampleCardContent controlsDisabled />
+  </Card>
+);
+
+AppearanceDisabledOutline.storyName = 'appearance disabled - Outline';
+
+export const AppearanceDisabledOutlineDarkMode = getStoryVariant(AppearanceDisabledOutline, DARK_MODE);
+export const AppearanceDisabledOutlineHighContrast = getStoryVariant(AppearanceDisabledOutline, HIGH_CONTRAST);
+
+export const AppearanceDisabledSubtle = () => (
+  <Card disabled appearance="subtle">
+    <SampleCardContent controlsDisabled />
+  </Card>
+);
+
+AppearanceDisabledSubtle.storyName = 'appearance disabled - Subtle';
+
+export const AppearanceDisabledSubtleDarkMode = getStoryVariant(AppearanceDisabledSubtle, DARK_MODE);
+export const AppearanceDisabledSubtleHighContrast = getStoryVariant(AppearanceDisabledSubtle, HIGH_CONTRAST);
+
+export const AppearanceDisabledInteractive = () => (
+  <Card disabled onClick={() => console.log('This should not trigger')}>
+    <SampleCardContent controlsDisabled />
+  </Card>
+);
+
+AppearanceDisabledInteractive.storyName = 'appearance disabled + interactive';
+
+export const AppearanceDisabledInteractiveDarkMode = getStoryVariant(AppearanceDisabledInteractive, DARK_MODE);
+export const AppearanceDisabledInteractiveHighContrast = getStoryVariant(AppearanceDisabledInteractive, HIGH_CONTRAST);
+
+export const AppearanceDisabledSelectable = () => (
+  <Card disabled defaultSelected={false}>
+    <SampleCardContent controlsDisabled />
+  </Card>
+);
+
+AppearanceDisabledSelectable.storyName = 'appearance disabled + selectable';
+
+export const AppearanceDisabledSelectableDarkMode = getStoryVariant(AppearanceDisabledSelectable, DARK_MODE);
+export const AppearanceDisabledSelectableHighContrast = getStoryVariant(AppearanceDisabledSelectable, HIGH_CONTRAST);

apps/vr-tests-react-components/src/stories/Card/utils.tsx

@@ -7,11 +7,11 @@ import { Open16Regular, Share16Regular } from '@fluentui/react-icons';
 const ASSET_URL =
   'https://raw.githubusercontent.com/microsoft/fluentui/master/packages/react-components/react-card/stories/src/assets/';
 
-export const powerpointLogoURL = ASSET_URL + 'powerpoint_logo.svg';
+export const powerpointLogoURL = ASSET_URL + 'pptx.png';
 export const salesPresentationTemplateURL = ASSET_URL + 'sales_template.png';
 export const appLogoUrl = ASSET_URL + 'app_logo.svg';
 
-export const SampleCardContent = () => (
+export const SampleCardContent = ({ controlsDisabled }: { controlsDisabled?: boolean }) => (
   <>
     <CardHeader
       image={{ as: 'img', src: powerpointLogoURL, alt: 'Microsoft PowerPoint logo' }}
@@ -26,10 +26,12 @@ export const SampleCardContent = () => (
       Donut chocolate bar oat cake. Dragée tiramisu lollipop bear claw. Marshmallow pastry jujubes toffee sugar plum.
     </div>
     <CardFooter>
-      <Button appearance="primary" icon={<Open16Regular />}>
+      <Button disabled={controlsDisabled} appearance="primary" icon={<Open16Regular />}>
         Open
       </Button>
-      <Button icon={<Share16Regular />}>Share</Button>
+      <Button disabled={controlsDisabled} icon={<Share16Regular />}>
+        Share
+      </Button>
     </CardFooter>
   </>
 );

change/@fluentui-react-card-e857edb4-5fad-4ea3-82d5-8ea04c9b0e2f.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "feat: add support for disabled cards",
+  "packageName": "@fluentui/react-card",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

packages/react-components/react-card/library/etc/react-card.api.md

@@ -108,6 +108,7 @@ export type CardProps = ComponentProps<CardSlots> & {
     selected?: boolean;
     defaultSelected?: boolean;
     onSelectionChange?: (event: CardOnSelectionChangeEvent, data: CardOnSelectData) => void;
+    disabled?: boolean;
 };
 
 // @internal (undocumented)
@@ -126,6 +127,7 @@ export type CardState = ComponentState<CardSlots> & CardContextValue & Required<
     selectable: boolean;
     selected: boolean;
     selectFocused: boolean;
+    disabled: boolean;
 }>;
 
 // @public

packages/react-components/react-card/library/src/components/Card/Card.cy.tsx

@@ -464,4 +464,202 @@ describe('Card', () => {
       });
     });
   });
+
+  describe('disabled', () => {
+    it('should have aria-disabled attribute when disabled', () => {
+      mountFluent(<CardSample disabled />);
+
+      cy.get('#card').should('have.attr', 'aria-disabled', 'true');
+    });
+
+    it('should not be focusable when disabled', () => {
+      mountFluent(<CardSample disabled focusMode="no-tab" />);
+
+      cy.get('#before').focus();
+      cy.realPress('Tab');
+
+      cy.get('#card').should('not.be.focused');
+      cy.get('#open-button').should('be.focused');
+    });
+
+    it('should not respond to click events when disabled', () => {
+      const onClickSpy = cy.spy().as('onClickSpy');
+
+      mountFluent(<CardSample disabled onClick={onClickSpy} />);
+
+      cy.get('#card').realClick();
+
+      cy.get('@onClickSpy').should('not.have.been.called');
+    });
+
+    it('should not respond to keyboard events when disabled', () => {
+      const onClickSpy = cy.spy().as('onClickSpy');
+
+      mountFluent(<CardSample disabled onClick={onClickSpy} focusMode="no-tab" />);
+
+      // Since the card is disabled and not focusable, we can't send keyboard events to it
+      // This test verifies that the card doesn't receive focus and therefore can't respond to keyboard events
+      cy.get('#card').should('have.attr', 'aria-disabled', 'true');
+
+      // Try to focus the card - it should not be focusable
+      cy.get('#before').focus();
+      cy.realPress('Tab');
+      cy.get('#card').should('not.be.focused');
+
+      cy.get('@onClickSpy').should('not.have.been.called');
+    });
+
+    describe('selectable disabled', () => {
+      it('should not be selectable when disabled', () => {
+        mountFluent(<CardSample disabled selected />);
+
+        cy.get(`.${cardClassNames.checkbox}`).should('be.disabled');
+      });
+
+      it('should not change selection state when clicked and disabled', () => {
+        mountFluent(<CardSample disabled defaultSelected={false} />);
+
+        cy.get(`.${cardClassNames.checkbox}`).should('not.be.checked');
+        cy.get('#card').realClick();
+        cy.get(`.${cardClassNames.checkbox}`).should('not.be.checked');
+      });
+
+      it('should not change selection state with keyboard when disabled', () => {
+        mountFluent(<CardSample disabled defaultSelected={false} />);
+
+        cy.get(`.${cardClassNames.checkbox}`).should('not.be.checked');
+        // Disabled checkbox should not respond to keyboard events
+        cy.get(`.${cardClassNames.checkbox}`).should('be.disabled');
+        // The checkbox is disabled, so trying to type on it should not work
+        cy.get(`.${cardClassNames.checkbox}`).should('not.be.checked');
+      });
+
+      it('should maintain selected state when disabled', () => {
+        mountFluent(<CardSample disabled defaultSelected />);
+
+        cy.get(`.${cardClassNames.checkbox}`).should('be.checked');
+        cy.get('#card').realClick();
+        cy.get(`.${cardClassNames.checkbox}`).should('be.checked');
+      });
+
+      it('should have disabled checkbox when card is disabled and selectable', () => {
+        mountFluent(<CardSample disabled selected />);
+
+        cy.get(`.${cardClassNames.checkbox}`).should('be.disabled');
+        // HTML inputs use the 'disabled' attribute, not 'aria-disabled'
+        cy.get(`.${cardClassNames.checkbox}`).should('have.attr', 'disabled');
+      });
+
+      it('should not trigger onSelectionChange when disabled', () => {
+        const onSelectionChangeSpy = cy.spy().as('onSelectionChangeSpy');
+
+        const DisabledSelectableCard = () => (
+          <CardSample disabled defaultSelected={false} onSelectionChange={onSelectionChangeSpy} />
+        );
+
+        mountFluent(<DisabledSelectableCard />);
+
+        cy.get('#card').realClick();
+        cy.get('@onSelectionChangeSpy').should('not.have.been.called');
+      });
+    });
+
+    describe('focus modes when disabled', () => {
+      it('should not be focusable with focusMode="no-tab" when disabled', () => {
+        mountFluent(<CardSample disabled focusMode="no-tab" />);
+
+        cy.get('#before').focus();
+        cy.realPress('Tab');
+
+        cy.get('#card').should('not.be.focused');
+        cy.get('#open-button').should('be.focused');
+      });
+
+      it('should not be focusable with focusMode="tab-exit" when disabled', () => {
+        mountFluent(<CardSample disabled focusMode="tab-exit" />);
+
+        cy.get('#before').focus();
+        cy.realPress('Tab');
+
+        cy.get('#card').should('not.be.focused');
+        cy.get('#open-button').should('be.focused');
+      });
+
+      it('should not be focusable with focusMode="tab-only" when disabled', () => {
+        mountFluent(<CardSample disabled focusMode="tab-only" />);
+
+        cy.get('#before').focus();
+        cy.realPress('Tab');
+
+        cy.get('#card').should('not.be.focused');
+        cy.get('#open-button').should('be.focused');
+      });
+
+      it('should not receive programmatic focus when disabled', () => {
+        mountFluent(<CardSample disabled focusMode="no-tab" />);
+
+        // Disabled cards should not be focusable, so we verify the focus doesn't change
+        cy.get('#before').focus();
+        cy.get('#before').should('be.focused');
+
+        // This should not change the focus since the card is disabled
+        cy.get('#card').should('have.attr', 'aria-disabled', 'true');
+        cy.get('#before').should('be.focused'); // Focus should remain on #before
+      });
+    });
+
+    describe('interactive behaviors when disabled', () => {
+      it('should not be interactive when disabled even with click handlers', () => {
+        const onClickSpy = cy.spy().as('onClickSpy');
+
+        mountFluent(<CardSample disabled onClick={onClickSpy} />);
+
+        cy.get('#card').realClick();
+
+        // The onClick handler should not be called when disabled
+        cy.get('@onClickSpy').should('not.have.been.called');
+      });
+
+      it('should not respond to mouse events when disabled', () => {
+        // When a card is disabled, the onClick handler is removed
+        // but other mouse events may still bubble up from child elements
+        // This test verifies that the main onClick interaction is disabled
+        mountFluent(<CardSample disabled />);
+
+        cy.get('#card').should('have.attr', 'aria-disabled', 'true');
+
+        // The card should be visually disabled
+        cy.get('#card').realClick();
+
+        // Since we didn't provide an onClick handler, we just verify the disabled state
+        cy.get('#card').should('have.attr', 'aria-disabled', 'true');
+      });
+    });
+
+    describe('child element interaction when card is disabled', () => {
+      it('should allow child elements to be interacted with when card is disabled', () => {
+        mountFluent(<CardSample disabled />);
+
+        // Child buttons should still be clickable unless explicitly disabled
+        cy.get('#open-button').should('not.be.disabled');
+        cy.get('#close-button').should('not.be.disabled');
+
+        cy.get('#open-button').realClick();
+        cy.get('#close-button').realClick();
+      });
+
+      it('should focus child elements normally when card is disabled', () => {
+        mountFluent(<CardSample disabled />);
+
+        cy.get('#before').focus();
+        cy.realPress('Tab');
+
+        cy.get('#open-button').should('be.focused');
+
+        cy.realPress('Tab');
+
+        cy.get('#close-button').should('be.focused');
+      });
+    });
+  });
 });