feat(Carousel): base component

CHANGELOG.md

@@ -36,6 +36,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - Add bounce animation to button clicks in Teams theme @notandrew ([#1724](https://github.com/stardust-ui/react/pull/1724))
 - Update Silver color scheme, adding `foregroundHover`, `foregroundPressed` and `background` definitions @pompomon ([#2078](https://github.com/microsoft/fluent-ui-react/pull/2078))
 - Expanding experimental accessibility schema to more components @mshoho ([#2052](https://github.com/stardust-ui/react/pull/2052))
+- Add base `Carousel` component @silviuavram ([#1979](https://github.com/microsoft/fluent-ui-react/pull/1979))
 
 ### Documentation
 - Add usage example for `Tooltip` on disabled elements @mnajdova ([#2091](https://github.com/microsoft/fluent-ui-react/pull/2091))

docs/src/components/ComponentPlayground/ComponentPlayground.tsx

@@ -14,6 +14,7 @@ const unsupportedComponents = [
   'Accordion',
   'Animation',
   'Box',
+  'Carousel',
   'Chat',
   'Dropdown',
   'Flex',

docs/src/examples/components/Carousel/Types/CarouselExample.tsx

@@ -0,0 +1,49 @@
+import * as React from 'react'
+import { Carousel, Image } from '@stardust-ui/react'
+
+const imageAltTags = {
+  ade: 'Portrait of Ade',
+  elliot: 'Portrait of Elliot',
+  kristy: 'Portrait of Kristy',
+  nan: 'Portrait of Nan',
+}
+const carouselItems = [
+  {
+    key: 'ade',
+    id: 'ade',
+    content: <Image src="public/images/avatar/large/ade.jpg" fluid alt={imageAltTags.ade} />,
+  },
+  {
+    key: 'elliot',
+    id: 'elliot',
+    content: <Image src="public/images/avatar/large/elliot.jpg" fluid alt={imageAltTags.elliot} />,
+  },
+  {
+    key: 'kristy',
+    id: 'kristy',
+    content: <Image src="public/images/avatar/large/kristy.png" fluid alt={imageAltTags.kristy} />,
+  },
+  {
+    key: 'nan',
+    id: 'nan',
+    content: <Image src="public/images/avatar/large/nan.jpg" fluid alt={imageAltTags.nan} />,
+  },
+]
+
+const CarouselExample = () => (
+  <Carousel
+    ariaRoleDescription="carousel"
+    navigation={{
+      'aria-label': 'people portraits',
+      items: carouselItems.map((item, index) => ({
+        key: item.id,
+        'aria-label': imageAltTags[item.id],
+        'aria-controls': item.id,
+      })),
+    }}
+    items={carouselItems}
+    getItemPositionText={(index: number, size: number) => `${index + 1} of ${size}`}
+  />
+)
+
+export default CarouselExample

docs/src/examples/components/Carousel/Types/CarouselPaginationExample.tsx

@@ -0,0 +1,33 @@
+import * as React from 'react'
+import { Carousel, Image } from '@stardust-ui/react'
+
+const carouselItems = [
+  {
+    key: 'ade',
+    content: <Image src="public/images/avatar/large/ade.jpg" fluid alt={'Portrait of Ade'} />,
+  },
+  {
+    key: 'elliot',
+    content: <Image src="public/images/avatar/large/elliot.jpg" fluid alt={'Portrait of Elliot'} />,
+  },
+  {
+    key: 'kristy',
+    content: <Image src="public/images/avatar/large/kristy.png" fluid alt={'Portrait of Kristy'} />,
+  },
+  {
+    key: 'nan',
+    content: <Image src="public/images/avatar/large/nan.jpg" fluid alt={'Portrait of Nan'} />,
+  },
+]
+
+const CarouselExample = () => (
+  <Carousel
+    ariaRoleDescription="carousel"
+    items={carouselItems}
+    paddleNext={{ 'aria-label': 'go to next slide' }}
+    paddlePrevious={{ 'aria-label': 'go to previous slide' }}
+    getItemPositionText={(index: number, size: number) => `${index + 1} of ${size}`}
+  />
+)
+
+export default CarouselExample

docs/src/examples/components/Carousel/Types/index.tsx

@@ -0,0 +1,21 @@
+import * as React from 'react'
+
+import ComponentExample from 'docs/src/components/ComponentDoc/ComponentExample'
+import ExampleSection from 'docs/src/components/ComponentDoc/ExampleSection'
+
+const Types = () => (
+  <ExampleSection title="Types">
+    <ComponentExample
+      title="Carousel"
+      description="A carousel can display images."
+      examplePath="components/Carousel/Types/CarouselExample"
+    />
+    <ComponentExample
+      title="Carousel with Pagination"
+      description="A carousel can have pagination instead of navigation."
+      examplePath="components/Carousel/Types/CarouselPaginationExample"
+    />
+  </ExampleSection>
+)
+
+export default Types

docs/src/examples/components/Carousel/Variations/CarouselCircularExample.tsx

@@ -0,0 +1,50 @@
+import * as React from 'react'
+import { Carousel, Image } from '@stardust-ui/react'
+
+const imageAltTags = {
+  ade: 'Portrait of Ade',
+  elliot: 'Portrait of Elliot',
+  kristy: 'Portrait of Kristy',
+  nan: 'Portrait of Nan',
+}
+const carouselItems = [
+  {
+    key: 'ade',
+    id: 'ade',
+    content: <Image src="public/images/avatar/large/ade.jpg" fluid alt={imageAltTags.ade} />,
+  },
+  {
+    key: 'elliot',
+    id: 'elliot',
+    content: <Image src="public/images/avatar/large/elliot.jpg" fluid alt={imageAltTags.elliot} />,
+  },
+  {
+    key: 'kristy',
+    id: 'kristy',
+    content: <Image src="public/images/avatar/large/kristy.png" fluid alt={imageAltTags.kristy} />,
+  },
+  {
+    key: 'nan',
+    id: 'nan',
+    content: <Image src="public/images/avatar/large/nan.jpg" fluid alt={imageAltTags.nan} />,
+  },
+]
+
+const CarouselExample = () => (
+  <Carousel
+    circular
+    ariaRoleDescription="carousel"
+    navigation={{
+      'aria-label': 'people portraits',
+      items: carouselItems.map((item, index) => ({
+        key: index,
+        'aria-controls': item.id,
+        'aria-label': imageAltTags[item.id],
+      })),
+    }}
+    items={carouselItems}
+    getItemPositionText={(index: number, size: number) => `${index + 1} of ${size}`}
+  />
+)
+
+export default CarouselExample

docs/src/examples/components/Carousel/Variations/index.tsx

@@ -0,0 +1,15 @@
+import * as React from 'react'
+import ComponentExample from 'docs/src/components/ComponentDoc/ComponentExample'
+import ExampleSection from 'docs/src/components/ComponentDoc/ExampleSection'
+
+const Variations = () => (
+  <ExampleSection title="Variations">
+    <ComponentExample
+      title="Circular"
+      description="A Carousel's items navigation can be circular."
+      examplePath="components/Carousel/Variations/CarouselCircularExample"
+    />
+  </ExampleSection>
+)
+
+export default Variations

docs/src/examples/components/Carousel/index.tsx

@@ -0,0 +1,13 @@
+import * as React from 'react'
+
+import Types from './Types'
+import Variations from './Variations'
+
+const CarouselExamples = () => (
+  <>
+    <Types />
+    <Variations />
+  </>
+)
+
+export default CarouselExamples

packages/accessibility/src/behaviors/Carousel/carouselBehavior.ts

@@ -0,0 +1,68 @@
+import { Accessibility } from '../../types'
+import * as keyboardKey from 'keyboard-key'
+
+/**
+ * @specification
+ * Adds attribute 'role=region' to 'root' slot.
+ * Adds attribute 'aria-live=polite' to 'itemsContainerWrapper' slot if 'ariaLiveOn' property is true. Sets the attribute to 'off' otherwise.
+ * Adds attribute 'aria-hidden=true' to 'paddleNext' slot if 'navigation' property is true. Does not set the attribute otherwise.
+ * Adds attribute 'aria-hidden=true' to 'paddlePrevious' slot if 'navigation' property is true. Does not set the attribute otherwise.
+ * Adds attribute 'tabIndex=-1' to 'paddlePrevious' slot if 'navigation' property is true. Does not set the attribute otherwise.
+ * Adds attribute 'tabIndex=-1' to 'paddlePrevious' slot if 'navigation' property is true. Does not set the attribute otherwise.
+ * Triggers 'showNextSlideByKeyboardNavigation' action with 'ArrowRight' on 'itemsContainer'.
+ * Triggers 'showPreviousSlideByKeyboardNavigation' action with 'ArrowLeft' on 'itemsContainer'.
+ * Triggers 'showNextSlideByPaddlePress' action with 'Enter' or 'Spacebar' on 'paddleNext'.
+ * Triggers 'showPreviousSlideByPaddlePress' action with 'Enter' or 'Spacebar' on 'paddlePrevious'.
+ */
+const carouselBehavior: Accessibility<CarouselBehaviorProps> = props => ({
+  attributes: {
+    root: {
+      role: 'region',
+    },
+    itemsContainerWrapper: {
+      'aria-live': props.ariaLiveOn ? 'polite' : 'off',
+    },
+
+    paddleNext: {
+      ...(props.navigation && {
+        tabIndex: -1,
+        'aria-hidden': 'true',
+      }),
+    },
+    paddlePrevious: {
+      ...(props.navigation && {
+        tabIndex: -1,
+        'aria-hidden': 'true',
+      }),
+    },
+  },
+
+  keyActions: {
+    itemsContainer: {
+      showNextSlideByKeyboardNavigation: {
+        keyCombinations: [{ keyCode: keyboardKey.ArrowRight }],
+      },
+      showPreviousSlideByKeyboardNavigation: {
+        keyCombinations: [{ keyCode: keyboardKey.ArrowLeft }],
+      },
+    },
+    paddleNext: {
+      showNextSlideByPaddlePress: {
+        keyCombinations: [{ keyCode: keyboardKey.Enter }, { keyCode: keyboardKey.Spacebar }],
+      },
+    },
+    paddlePrevious: {
+      showPreviousSlideByPaddlePress: {
+        keyCombinations: [{ keyCode: keyboardKey.Enter }, { keyCode: keyboardKey.Spacebar }],
+      },
+    },
+  },
+})
+
+export type CarouselBehaviorProps = {
+  /** Element type. */
+  navigation: Object | Object[]
+  ariaLiveOn: boolean
+}
+
+export default carouselBehavior

packages/accessibility/src/behaviors/Carousel/carouselItemBehavior.ts

@@ -0,0 +1,28 @@
+import { Accessibility } from '../../types'
+
+/**
+ * @specification
+ * Adds attribute 'role=tabpanel' to 'root' slot.
+ * Adds attribute 'aria-hidden=false' to 'root' slot if 'active' property is true. Sets the attribute to 'true' otherwise.
+ * Adds attribute 'tabIndex=0' to 'root' slot if 'active' property is true. Sets the attribute to '-1' otherwise.
+ */
+const carouselItemBehavior: Accessibility<CarouselItemProps> = props => ({
+  attributes: {
+    root: {
+      role: 'tabpanel',
+      'aria-hidden': props.active ? 'false' : 'true',
+      tabIndex: props.active ? 0 : -1,
+    },
+  },
+
+  keyActions: {
+    root: {},
+  },
+})
+
+export default carouselItemBehavior
+
+export type CarouselItemProps = {
+  /** If item is visible in the carousel. */
+  active?: boolean
+}

packages/accessibility/src/behaviors/Tab/tabBehavior.ts

@@ -15,7 +15,7 @@ import { Accessibility, AccessibilityAttributes } from '../../types'
  * Adds attribute 'aria-describedby' based on the property 'aria-describedby' to 'root' slot.
  * Adds attribute 'aria-controls' based on the property 'aria-controls' to 'root' slot.
  * Adds attribute 'aria-disabled=true' to 'root' slot based on the property 'disabled'. This can be overriden by providing 'aria-disabled' property directly to the component.
- * Triggers 'performClick' action with 'Enter' or 'Spacebar' on 'wrapper'.
+ * Triggers 'performClick' action with 'Enter' or 'Spacebar' on 'root'.
  */
 const tabBehavior: Accessibility<TabBehaviorProps> = props => ({
   attributes: {
@@ -36,7 +36,7 @@ const tabBehavior: Accessibility<TabBehaviorProps> = props => ({
   },
 
   keyActions: {
-    wrapper: {
+    root: {
       performClick: {
         keyCombinations: [{ keyCode: keyboardKey.Enter }, { keyCode: keyboardKey.Spacebar }],
       },

packages/accessibility/src/behaviors/index.ts

@@ -74,6 +74,8 @@ export { default as treeItemAsListItemBehavior } from './Tree/treeItemAsListItem
 export {
   default as treeTitleAsListItemTitleBehavior,
 } from './Tree/treeTitleAsListItemTitleBehavior'
+export { default as carouselBehavior } from './Carousel/carouselBehavior'
+export { default as carouselItemBehavior } from './Carousel/carouselItemBehavior'
 export { default as tableBehavior } from './Table/tableBehavior'
 export { default as tableRowBehavior } from './Table/tableRowBehavior'
 export { default as tableCellBehavior } from './Table/tableCellBehavior'

packages/accessibility/src/types.ts

@@ -98,6 +98,7 @@ export interface AriaWidgetAttributes {
   'aria-invalid'?: boolean | 'false' | 'true' | 'grammar' | 'spelling'
   'aria-label'?: string
   'aria-level'?: number
+  'aria-live'?: 'polite' | 'off' | 'assertive'
   'aria-modal'?: boolean
   'aria-multiline'?: boolean | 'false' | 'true'
   'aria-multiselectable'?: boolean | 'false' | 'true'

packages/accessibility/test/behaviors/behavior-test.tsx

@@ -66,6 +66,8 @@ import {
   treeAsListBehavior,
   treeItemAsListItemBehavior,
   treeTitleAsListItemTitleBehavior,
+  carouselItemBehavior,
+  carouselBehavior,
   tableBehavior,
   tableCellBehavior,
   tableHeaderCellBehavior,
@@ -140,6 +142,8 @@ testHelper.addBehavior('textAreaBehavior', textAreaBehavior)
 testHelper.addBehavior('treeAsListBehavior', treeAsListBehavior)
 testHelper.addBehavior('treeItemAsListItemBehavior', treeItemAsListItemBehavior)
 testHelper.addBehavior('treeTitleAsListItemTitleBehavior', treeTitleAsListItemTitleBehavior)
+testHelper.addBehavior('carouselItemBehavior', carouselItemBehavior)
+testHelper.addBehavior('carouselBehavior', carouselBehavior)
 testHelper.addBehavior('tableBehavior', tableBehavior)
 testHelper.addBehavior('tableCellBehavior', tableCellBehavior)
 testHelper.addBehavior('tableHeaderCellBehavior', tableHeaderCellBehavior)

packages/accessibility/test/behaviors/testDefinitions.ts

@@ -239,7 +239,7 @@ definitions.push({
 
 // Example: Adds attribute 'aria-disabled=true' to 'trigger' slot if 'disabled' property is true. Sets the attribute to 'false' otherwise.
 definitions.push({
-  regexp: /Adds attribute '([\w-]+)=([\w\d]+)' to '([\w-]+)' slot if '([\w-]+)' property is true\. Sets the attribute to '([\w\d]+)' otherwise\./g,
+  regexp: /Adds attribute '([\w-]+)=([\w\d]+)' to '([\w-]+)' slot if '([\w-]+)' property is true\. Sets the attribute to '([\w\d-]+)' otherwise\./g,
   testMethod: (parameters: TestMethod) => {
     const [
       attributeToBeAdded,