@telus-uds/components-base 1.9.0 → 1.12.0

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",
@@ -4326,6 +4334,125 @@
         }
       }
     },
+    "InputSupports": {
+      "docs": {
+        "description": "",
+        "props": {
+          "copy": {
+            "defaultValue": {
+              "value": "'en'",
+              "computed": false
+            },
+            "type": {
+              "name": "enum",
+              "value": [
+                {
+                  "value": "'en'",
+                  "computed": false
+                },
+                {
+                  "value": "'fr'",
+                  "computed": false
+                }
+              ]
+            },
+            "required": false,
+            "description": "Whether the English or French copy will be used (e.g. for accessibility labels)."
+          },
+          "hintPosition": {
+            "defaultValue": {
+              "value": "'inline'",
+              "computed": false
+            },
+            "type": {
+              "name": "enum",
+              "value": [
+                {
+                  "value": "'inline'",
+                  "computed": false
+                },
+                {
+                  "value": "'below'",
+                  "computed": false
+                }
+              ]
+            },
+            "required": false,
+            "description": "Position of the hint relative to label."
+          },
+          "children": {
+            "type": {
+              "name": "union",
+              "value": [
+                {
+                  "name": "func"
+                },
+                {
+                  "name": "node"
+                }
+              ]
+            },
+            "required": false,
+            "description": ""
+          },
+          "label": {
+            "type": {
+              "name": "string"
+            },
+            "required": false,
+            "description": "The input label."
+          },
+          "hint": {
+            "type": {
+              "name": "string"
+            },
+            "required": false,
+            "description": "A short description of the expected input."
+          },
+          "feedback": {
+            "type": {
+              "name": "string"
+            },
+            "required": false,
+            "description": "A detailed description of validation error/success or additional instructions.\nVisual variant is determined based on the `validation` prop."
+          },
+          "tooltip": {
+            "type": {
+              "name": "string"
+            },
+            "required": false,
+            "description": "Content of an optional `Tooltip`. If set, a tooltip button will be shown next to the label."
+          },
+          "validation": {
+            "type": {
+              "name": "enum",
+              "value": [
+                {
+                  "value": "'error'",
+                  "computed": false
+                },
+                {
+                  "value": "'success'",
+                  "computed": false
+                }
+              ]
+            },
+            "required": false,
+            "description": "Use to visually mark an input as valid or invalid."
+          },
+          "nativeID": {
+            "type": {
+              "name": "string"
+            },
+            "required": false,
+            "description": "ID for DOM element on web"
+          }
+        },
+        "attributes": {
+          "acceptsRNA11yProps": false
+        }
+      }
+    },
     "List": {
       "docs": {
         "description": "An unordered List component has a child a ListItem that\nallows icon, dividers and customized typography",
@@ -6908,15 +7035,24 @@
               "computed": false
             },
             "type": {
-              "name": "enum",
+              "name": "union",
               "value": [
                 {
-                  "value": "'en'",
-                  "computed": false
+                  "name": "enum",
+                  "value": [
+                    {
+                      "value": "'en'",
+                      "computed": false
+                    },
+                    {
+                      "value": "'fr'",
+                      "computed": false
+                    }
+                  ]
                 },
                 {
-                  "value": "'fr'",
-                  "computed": false
+                  "name": "custom",
+                  "raw": "dictionaryContentShape"
                 }
               ]
             },
@@ -6932,31 +7068,13 @@
               "name": "shape",
               "value": {
                 "en": {
-                  "name": "shape",
-                  "value": {
-                    "stepLabel": {
-                      "name": "string",
-                      "required": false
-                    },
-                    "stepTrackerLabel": {
-                      "name": "string",
-                      "required": false
-                    }
-                  },
+                  "name": "custom",
+                  "raw": "dictionaryContentShape",
                   "required": false
                 },
                 "fr": {
-                  "name": "shape",
-                  "value": {
-                    "stepLabel": {
-                      "name": "string",
-                      "required": false
-                    },
-                    "stepTrackerLabel": {
-                      "name": "string",
-                      "required": false
-                    }
-                  },
+                  "name": "custom",
+                  "raw": "dictionaryContentShape",
                   "required": false
                 }
               }
@@ -8288,6 +8406,511 @@
         }
       }
     },
+    "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": {
+          "itemLabel": {
+            "defaultValue": {
+              "value": "'item'",
+              "computed": false
+            },
+            "type": {
+              "name": "string"
+            },
+            "required": false,
+            "description": "Lowercase language-appropriate user-facing description of what each Carousel slide represents.\nThis is used when generating item labels. For example, if a carousel contains offers,\npass itemLabel=\"summer offer\" (or copy=\"fr\" and an appropriate French translation) to genereate\naccessible labels such as \"Summer offer 1 of 3\" and \"Show summer offer 2 of 3\"."
+          },
+          "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"
+          },
+          "tag": {
+            "defaultValue": {
+              "value": "'ul'",
+              "computed": false
+            },
+            "type": {
+              "name": "enum",
+              "value": [
+                {
+                  "value": "'h1'",
+                  "computed": false
+                },
+                {
+                  "value": "'h2'",
+                  "computed": false
+                },
+                {
+                  "value": "'h3'",
+                  "computed": false
+                },
+                {
+                  "value": "'h4'",
+                  "computed": false
+                },
+                {
+                  "value": "'h5'",
+                  "computed": false
+                },
+                {
+                  "value": "'h6'",
+                  "computed": false
+                },
+                {
+                  "value": "'article'",
+                  "computed": false
+                },
+                {
+                  "value": "'aside'",
+                  "computed": false
+                },
+                {
+                  "value": "'blockquote'",
+                  "computed": false
+                },
+                {
+                  "value": "'footer'",
+                  "computed": false
+                },
+                {
+                  "value": "'figure'",
+                  "computed": false
+                },
+                {
+                  "value": "'form'",
+                  "computed": false
+                },
+                {
+                  "value": "'header'",
+                  "computed": false
+                },
+                {
+                  "value": "'ul'",
+                  "computed": false
+                },
+                {
+                  "value": "'li'",
+                  "computed": false
+                },
+                {
+                  "value": "'main'",
+                  "computed": false
+                },
+                {
+                  "value": "'nav'",
+                  "computed": false
+                },
+                {
+                  "value": "'section'",
+                  "computed": false
+                },
+                {
+                  "value": "'label'",
+                  "computed": false
+                }
+              ]
+            },
+            "required": false,
+            "description": "HTML tag to use for the Carousel item's immediate parent. Defaults to `'ul'` so that\nassistive technology tools know to intepret the carousel as a list.\n\nNote that if the immediate Carousel children do not all render as `'li'` elements,\nthis should be changed (e.g. pass tag=\"div\") because only 'li' is a valid child of 'ul'."
+          },
+          "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"
+          },
+          "panelNavigationTextDictionary": {
+            "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"
+          }
+        },
+        "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": {
+            "tag": {
+              "defaultValue": {
+                "value": "'li'",
+                "computed": false
+              },
+              "type": {
+                "name": "enum",
+                "value": [
+                  {
+                    "value": "'h1'",
+                    "computed": false
+                  },
+                  {
+                    "value": "'h2'",
+                    "computed": false
+                  },
+                  {
+                    "value": "'h3'",
+                    "computed": false
+                  },
+                  {
+                    "value": "'h4'",
+                    "computed": false
+                  },
+                  {
+                    "value": "'h5'",
+                    "computed": false
+                  },
+                  {
+                    "value": "'h6'",
+                    "computed": false
+                  },
+                  {
+                    "value": "'article'",
+                    "computed": false
+                  },
+                  {
+                    "value": "'aside'",
+                    "computed": false
+                  },
+                  {
+                    "value": "'blockquote'",
+                    "computed": false
+                  },
+                  {
+                    "value": "'footer'",
+                    "computed": false
+                  },
+                  {
+                    "value": "'figure'",
+                    "computed": false
+                  },
+                  {
+                    "value": "'form'",
+                    "computed": false
+                  },
+                  {
+                    "value": "'header'",
+                    "computed": false
+                  },
+                  {
+                    "value": "'ul'",
+                    "computed": false
+                  },
+                  {
+                    "value": "'li'",
+                    "computed": false
+                  },
+                  {
+                    "value": "'main'",
+                    "computed": false
+                  },
+                  {
+                    "value": "'nav'",
+                    "computed": false
+                  },
+                  {
+                    "value": "'section'",
+                    "computed": false
+                  },
+                  {
+                    "value": "'label'",
+                    "computed": false
+                  }
+                ]
+              },
+              "required": false,
+              "description": "Sets the HTML tag of the outer container. By default `'li'` so that assistive technology sees\nthe Carousel as a list of items.\n\nCarousel's innermost container defaults to `'ul'` which can be overridden. If the tag of either\n`Carousel` or `Carousel.Item` is overriden, the other should be too, to avoid producing invalid HTML."
+            },
+            "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```",