@telus-uds/components-base 1.9.0 → 1.10.0

package/CHANGELOG.md

@@ -1,12 +1,25 @@
 # Change Log - @telus-uds/components-base
 
-This log was last generated on Fri, 08 Jul 2022 22:41:05 GMT and should not be manually modified.
+This log was last generated on Wed, 20 Jul 2022 23:56:08 GMT and should not be manually modified.
 
 <!-- Start content -->
 
+## 1.10.0
+
+Wed, 20 Jul 2022 23:56:08 GMT
+
+### Minor changes
+
+- Add Carousel component 🎉 (shahzaibkhalidmalik@outlook.com)
+- Bump @telus-uds/system-theme-tokens to v2.1.0
+
+### Patches
+
+- Fix an issue where StepTracker might break where `stepLabel` and/or `stepTrackerLabel` are not read before reading their `dictionary` values  (shahzaibkhalidmalik@outlook.com)
+
 ## 1.9.0
 
-Fri, 08 Jul 2022 22:41:05 GMT
+Fri, 08 Jul 2022 22:41:55 GMT
 
 ### Minor changes
 

package/component-docs.json

@@ -81,6 +81,14 @@
         "minWidth": "size",
         "shadow": "shadow"
       },
+      "Carousel": {
+        "nextIcon": "icon",
+        "previousIcon": "icon",
+        "showPreviousNextNavigation": "show",
+        "showPanelNavigation": "show",
+        "spaceBetweenSlideAndPreviousNextNavigation": "size",
+        "spaceBetweenSlideAndPanelNavigation": "size"
+      },
       "Checkbox": {
         "containerBackgroundColor": "color",
         "feedbackMarginBottom": "size",
@@ -8288,6 +8296,326 @@
         }
       }
     },
+    "Carousel": {
+      "docs": {
+        "description": "Carousel is a general-purpose content slider that can be used to render content in terms of slides.\n\n  ## Usage\n  - `Carousel` is a top-level export from `@telus-uds/components-base` which is used to render a Carousel\n  - Immediately within `Carousel`, individual slides are wrapped in `Carousel.Item` for the top-level `Carousel` to know how to identify an individual slide\n  - You can use any UDS component or other platform-specific component, (based on the platform you're rendering) to achieve any desired layout\n  - By default, Carousel takea all the `width` available to it and the `height` is determined based on the content in the slide with more content\n  - You may want to wrap Carousel in other layout components like `Box`, `FlexGrid` etc, to achieve a responsive layout of your need\n\n  ## `useCarousel` custom hook\n\n  ```jsx\n  import { useCarousel } from '@telus-uds/components-base'\n\n  const SomeComponentWithinCarouselItem = () => {\n    const {\n      activeIndex,\n      totalItems,\n      width,\n      goTo\n    } = useCarousel()\n    return <Text>Hi!</Text>\n  }\n  ```\n\n  You can use `useCarousel` to hook into internal state of the Carousel component like:\n  - `activeIndex`: Index of the current slide\n  - `totalItems`: Total number of items/slides passed to the Carousel\n  - `width`: Width of the individual carousel slide\n  - `goTo`: A function to go to a particular slide by passing the index of that slide, e.g: goTo(0) where `0` is the index of the first slide\n\n  ## Accessibility\n\n  - Top-level `Carousel` and `Carousel.Item` can take all possible React Native's `View` and `a11y` props\n  - If your slide contains input elements like buttons, you may want to configure them to be only focusable when `activeIndex` is equal to the current slide index in order to avoid tabbing going between slides\n\n  ## Platform considerations\n  The component is available on both native platforms and web.\n\n  ## Other considerations\n  - You may want to use the same kind of layout in all your slides to avoid visual and height differences\n  - `previous` and `next` navigation buttons are automatically removed in `sm` and `xs` viewports, as these smaller viewports offers swipe functionality\n\n  ## Tokens\n\n  You can override the following tokens in exceptional circumstances:\n  - `previousIcon` - Icon of the previous button\n  - `nextIcon` - Icon of the next button\n  - `showPreviousNextNavigation` - If you want to show/hide the previous/next navigation\n  - `showPanelNavigation` - If you want to show/hide the panel navigation\n  - `spaceBetweenSlideAndPreviousNextNavigation` - Horizontal space between slide and previous/next navigational buttons\n  - `spaceBetweenSlideAndPanelNavigation` - Vertical space between slide area and panel navigation area",
+        "props": {
+          "previousNextNavigationPosition": {
+            "defaultValue": {
+              "value": "'inside'",
+              "computed": false
+            },
+            "type": {
+              "name": "enum",
+              "value": [
+                {
+                  "value": "'inside'",
+                  "computed": false
+                },
+                {
+                  "value": "'outside'",
+                  "computed": false
+                },
+                {
+                  "value": "'edge'",
+                  "computed": false
+                }
+              ]
+            },
+            "required": false,
+            "description": "`inside` renders the previous and next buttons inside the slide\n`outside` renders the previous and next buttons outside the slide\n`edge` renders the previous and next buttons at the edge of the slide"
+          },
+          "previousNextIconSize": {
+            "defaultValue": {
+              "value": "'default'",
+              "computed": false
+            },
+            "type": {
+              "name": "enum",
+              "value": [
+                {
+                  "value": "'default'",
+                  "computed": false
+                },
+                {
+                  "value": "'small'",
+                  "computed": false
+                },
+                {
+                  "value": "'large'",
+                  "computed": false
+                }
+              ]
+            },
+            "required": false,
+            "description": "Defines the size of the `IconButton` which is being used to render next and previous buttons"
+          },
+          "minDistanceToCapture": {
+            "defaultValue": {
+              "value": "5",
+              "computed": false
+            },
+            "type": {
+              "name": "number"
+            },
+            "required": false,
+            "description": "Initiate animation after swipe this distance."
+          },
+          "minDistanceForAction": {
+            "defaultValue": {
+              "value": "0.2",
+              "computed": false
+            },
+            "type": {
+              "name": "number"
+            },
+            "required": false,
+            "description": "Minimal part of slide width must be swiped for changing index.\nOtherwise animation restore current slide. Default value 0.2 means that 20% must be swiped for change index"
+          },
+          "springConfig": {
+            "defaultValue": {
+              "value": "undefined",
+              "computed": true
+            },
+            "type": {
+              "name": "object"
+            },
+            "required": false,
+            "description": "Carousel uses `Animated.spring` to animate slide changes, use this option to pass custom animation configuration"
+          },
+          "panelNavigationTextDictionary": {
+            "defaultValue": {
+              "value": "{\n  en: {\n    stepTrackerLabel: 'Showing %{stepNumber} of %{stepCount}'\n  },\n  fr: {\n    stepTrackerLabel: 'Étape %{stepNumber} sur %{stepCount}: %{stepLabel}'\n  }\n}",
+              "computed": false
+            },
+            "type": {
+              "name": "shape",
+              "value": {
+                "en": {
+                  "name": "shape",
+                  "value": {
+                    "stepTrackerLabel": {
+                      "name": "string",
+                      "required": true
+                    }
+                  },
+                  "required": false
+                },
+                "fr": {
+                  "name": "shape",
+                  "value": {
+                    "stepTrackerLabel": {
+                      "name": "string",
+                      "required": true
+                    }
+                  },
+                  "required": false
+                }
+              }
+            },
+            "required": false,
+            "description": "Use this to override the default text for panel navigation"
+          },
+          "accessibilityRole": {
+            "defaultValue": {
+              "value": "'adjustable'",
+              "computed": false
+            },
+            "type": {
+              "name": "string"
+            },
+            "required": false,
+            "description": "Provide custom accessibilityRole for Carousel container"
+          },
+          "accessibilityLabel": {
+            "defaultValue": {
+              "value": "'carousel'",
+              "computed": false
+            },
+            "type": {
+              "name": "string"
+            },
+            "required": false,
+            "description": "Provide custom accessibilityLabel for Carousel container"
+          },
+          "tokens": {
+            "type": {
+              "name": "custom",
+              "raw": {
+                "nextIcon": "icon",
+                "previousIcon": "icon",
+                "showPreviousNextNavigation": "show",
+                "showPanelNavigation": "show",
+                "spaceBetweenSlideAndPreviousNextNavigation": "size",
+                "spaceBetweenSlideAndPanelNavigation": "size"
+              }
+            },
+            "required": false,
+            "description": ""
+          },
+          "variant": {
+            "type": {
+              "name": "objectOf",
+              "value": {
+                "name": "union",
+                "value": [
+                  {
+                    "name": "string"
+                  },
+                  {
+                    "name": "number"
+                  },
+                  {
+                    "name": "bool"
+                  }
+                ]
+              }
+            },
+            "required": false,
+            "description": ""
+          },
+          "children": {
+            "type": {
+              "name": "union",
+              "value": [
+                {
+                  "name": "arrayOf",
+                  "value": {
+                    "name": "node"
+                  }
+                },
+                {
+                  "name": "node"
+                }
+              ]
+            },
+            "required": true,
+            "description": "Slides to render in Carousel. Wrap individual slides in `Carousel.Item`"
+          },
+          "onIndexChanged": {
+            "type": {
+              "name": "func"
+            },
+            "required": false,
+            "description": "Called when active index changed\nThis function is also provided with a parameter indicating changed index (either 1, or -1)\nUse it as follows:\n```js\n   const onIndexChangedCallback = React.useCallback((changedIndex) => {\n     console.log(changedIndex)\n   }, [])  // pass local dependencies as per your component\n   <Carousel\n     onIndexChanged={onIndexChangedCallback}\n   >\n     <Carousel.Item>First Slide</Carousel.Item>\n   </Carousel>\n```\nCaution: Always consider wrapping your callback for `onIndexChanged` in `useCallback` in order to avoid bugs and performance issues"
+          },
+          "onRenderPanelNavigation": {
+            "type": {
+              "name": "func"
+            },
+            "required": false,
+            "description": "Use this to render a custom panel navigation element instead of dots navigation\nThis function is also provided with an object with the following properties\nactiveIndex: index of current slide\ntotalItems: total number of slides\nUse it as follows:\n```js\n   <Carousel\n     onRenderPanelNavigation={({ totalItems, activeIndex }) => <Text>Showing {activeIndex + 1}</Text>}\n   >\n     <Carousel.Item>First Slide</Carousel.Item>\n   </Carousel>\n```"
+          },
+          "onAnimationStart": {
+            "type": {
+              "name": "func"
+            },
+            "required": false,
+            "description": "When slide animation start\nThis function is also provided with a parameter indicating the current slide index before animation starts\nUse it as follows:\n```js\n   const onAnimationStartCallback = React.useCallback((currentIndex) => {\n     console.log(currentIndex)\n   }, [])  // pass local dependencies as per your component\n   <Carousel\n     onAnimationStart={onAnimationStartCallback}\n   >\n     <Carousel.Item>First Slide</Carousel.Item>\n   </Carousel>\n```\nCaution: Always consider wrapping your callback for `onAnimationStart` in `useCallback` in order to avoid bugs and performance issues"
+          },
+          "onAnimationEnd": {
+            "type": {
+              "name": "func"
+            },
+            "required": false,
+            "description": "When slide animation end with parameter of current index (after animation ends)\nThis function is also provided with a parameter indicating the updated slide index after animation ends\nUse it as follows:\n```js\n   const onAnimationEndCallback = React.useCallback((changedIndex) => {\n     console.log(changedIndex)\n   }, [])  // pass local dependencies as per your component\n   <Carousel\n     onAnimationEnd={onAnimationEndCallback}\n   >\n     <Carousel.Item>First Slide</Carousel.Item>\n   </Carousel>\n```\nCaution: Always consider wrapping your callback for `onAnimationEnd` in `useCallback` in order to avoid bugs and performance issues"
+          }
+        },
+        "attributes": {
+          "acceptsRNA11yProps": false
+        }
+      },
+      "Item": {
+        "docs": {
+          "description": "`Carousel.Item` is used to wrap the content of an individual slide and is suppsoed to be the\nonly top-level component passed to the `Carousel`",
+          "props": {
+            "elementIndex": {
+              "type": {
+                "name": "number"
+              },
+              "required": false,
+              "description": "Index of the current slide\nDon't pass this prop when using `Carousel.Item` as it is already being passed by `Carousel` top-level component"
+            },
+            "accessibilityLabelledBy": {
+              "type": {
+                "name": "string"
+              },
+              "required": false,
+              "description": "Provide custom accessibilityLabelledBy for Carousel slide"
+            },
+            "children": {
+              "type": {
+                "name": "union",
+                "value": [
+                  {
+                    "name": "arrayOf",
+                    "value": {
+                      "name": "node"
+                    }
+                  },
+                  {
+                    "name": "node"
+                  }
+                ]
+              },
+              "required": true,
+              "description": "Content of the slide"
+            }
+          },
+          "attributes": {
+            "acceptsRNA11yProps": false
+          }
+        }
+      }
+    },
+    "CarouselProvider": {
+      "docs": {
+        "description": "",
+        "props": {
+          "children": {
+            "type": {
+              "name": "arrayOf",
+              "value": {
+                "name": "element"
+              }
+            },
+            "required": true,
+            "description": ""
+          },
+          "activeIndex": {
+            "type": {
+              "name": "number"
+            },
+            "required": true,
+            "description": ""
+          },
+          "totalItems": {
+            "type": {
+              "name": "number"
+            },
+            "required": true,
+            "description": ""
+          },
+          "width": {
+            "type": {
+              "name": "number"
+            },
+            "required": true,
+            "description": ""
+          },
+          "goTo": {
+            "type": {
+              "name": "func"
+            },
+            "required": true,
+            "description": ""
+          }
+        },
+        "attributes": {
+          "acceptsRNA11yProps": false
+        }
+      }
+    },
     "CheckboxGroup": {
       "docs": {
         "description": "A group of Checkboxs that behave as a fieldset. Use when users select any number of choices from options.\n\n## Component API\n\nUse the `items` prop to pass an array of objects describing each Checkbox in the group:\n\n - `label`: main text passed to CheckboxGroup's `label` prop\n - `id`: identifier used to store which CheckboxGroup is selected (uses `label` if undefinded)\n - `onChange`: optional function called on selection, in addition to updating the group's selection state\n\n### Controlled version\n\nIf the selection state is controlled from outside, it needs to receive `checkedId` and `onChange` props.\n\n### Uncontrolled version\n\nIf the CheckboxGroup manages its own state, you can use `initialCheckedId` prop to provide the initial value.\nWhenever the radio card gets toggled, it calls the `onChange` callback with the new value (string).\n\n### Use in forms\n\nFor web forms, the `name` prop may be used to define the name of the group's `fieldset` and input elements.\n\n### Validation\n\nValidation state may be set by passing 'error' or 'success' to the `validation` prop.\n\n## A11y guidelines\n\nCheckboxGroup accepts all the common accessibility props, and controls the accessibility state\nof children like Checkbox and Feedback based on current state.\n\n@example\n```jsx\n<CheckboxGroup\n  initialCheckedId=\"check1\"\n  items={[\n    { label: 'Checkbox 1', id: 'check1' },\n    { label: 'Checkbox 2', id: 'check2' },\n    { label: 'Checkbox 3', id: 'check3' }\n  ]}\n  legend=\"Checkboxes\"\n  hint=\"Choose from these options\"\n/>\n```",