@telus-uds/components-web 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -1,12 +1,26 @@
 # Change Log - @telus-uds/components-web
 
-<!-- This log was last generated on Mon, 02 Dec 2024 20:23:48 GMT and should not be manually modified. -->
+<!-- This log was last generated on Fri, 06 Dec 2024 02:03:26 GMT and should not be manually modified. -->
 
 <!-- Start content -->
 
+## 3.2.0
+
+Fri, 06 Dec 2024 02:03:26 GMT
+
+### Minor changes
+
+- `NavigationBar`: enable hash navigation (guillermo.peitzner@telus.com)
+- `ChevronLink`, `Search` & `ResponsiveImage`: new `dataSet` prop added to the components to allow the capability to pass data (35577399+JoshHC@users.noreply.github.com)
+- Bump @telus-uds/components-base to v2.2.0
+
+### Patches
+
+- `QuantitySelector`: render hint when no label is provided (guillermo.peitzner@telus.com)
+
 ## 3.1.0
 
-Mon, 02 Dec 2024 20:23:48 GMT
+Mon, 02 Dec 2024 20:29:26 GMT
 
 ### Minor changes
 

package/lib/NavigationBar/NavigationBar.js

@@ -1,9 +1,9 @@
 var _withLinkRouter$propT, _withLinkRouter$propT2, _withLinkRouter$propT3, _withLinkRouter$propT4;
 import React from 'react';
 import PropTypes from 'prop-types';
-import { selectSystemProps, StackView, Typography, useResponsiveProp, withLinkRouter } from '@telus-uds/components-base';
+import { selectSystemProps, StackView, Typography, useHash, useInputValue, useResponsiveProp, withLinkRouter } from '@telus-uds/components-base';
 import styled from 'styled-components';
-import { htmlAttrs } from '../utils';
+import { htmlAttrs, scrollToAnchor } from '../utils';
 import NavigationItem from './NavigationItem';
 import NavigationSubMenu from './NavigationSubMenu';
 import collapseItems from './collapseItems';
@@ -33,18 +33,56 @@ const NavigationBar = /*#__PURE__*/React.forwardRef((_ref, ref) => {
     heading,
     headingLevel = 'h1',
     items,
-    onChange = () => {},
+    onChange,
     selectedId,
+    value,
     LinkRouter,
     linkRouterProps,
     ...rest
   } = _ref;
+  const {
+    currentValue,
+    setValue
+  } = useInputValue({
+    value,
+    initialValue: selectedId,
+    onChange
+  });
+  useHash((hash, event) => {
+    let hashItem = hash && items.find(_ref2 => {
+      let {
+        href
+      } = _ref2;
+      return hash === href;
+    });
+    if (!hashItem) {
+      const parentItem = items.find(_ref3 => {
+        let {
+          items: parentItems
+        } = _ref3;
+        return parentItems === null || parentItems === void 0 ? void 0 : parentItems.some(_ref4 => {
+          let {
+            href
+          } = _ref4;
+          return hash === href;
+        });
+      });
+      hashItem = parentItem === null || parentItem === void 0 ? void 0 : parentItem.items.find(_ref5 => {
+        let {
+          href
+        } = _ref5;
+        return hash === href;
+      });
+    }
+    const hashId = hashItem && (hashItem.id || hashItem.label);
+    if (hashId) setValue(hashId, event);
+  }, [items, setValue]);
   const direction = useResponsiveProp({
     xs: 'column',
     sm: 'row'
   });
   const itemsForViewport = useResponsiveProp({
-    xs: collapseItems(items, selectedId),
+    xs: collapseItems(items, currentValue),
     lg: items
   });
   const openOverlayRef = React.useRef(null);
@@ -118,7 +156,7 @@ const NavigationBar = /*#__PURE__*/React.forwardRef((_ref, ref) => {
         heading: headingLevel,
         children: heading
       })
-    }), itemsForViewport === null || itemsForViewport === void 0 ? void 0 : itemsForViewport.map((_ref2, index) => {
+    }), itemsForViewport === null || itemsForViewport === void 0 ? void 0 : itemsForViewport.map((_ref6, index) => {
       let {
         href,
         label,
@@ -129,38 +167,50 @@ const NavigationBar = /*#__PURE__*/React.forwardRef((_ref, ref) => {
         linkRouterProps: itemLinkRouterProps,
         items: nestedItems,
         ...itemRest
-      } = _ref2;
+      } = _ref6;
       const itemId = id ?? label;
       const handleClick = event => {
         if (nestedItems) {
           setOpenSubMenuId(openSubMenuId !== itemId ? itemId : null);
+          return;
+        }
+        if (href !== null && href !== void 0 && href.startsWith('#')) {
+          scrollToAnchor(href, event, () => setValue(itemId, event));
+        } else {
+          setValue(itemId, event);
         }
         onClick === null || onClick === void 0 || onClick(event);
-        onChange === null || onChange === void 0 || onChange(itemId, event);
       };
       const ItemComponent = nestedItems ? NavigationSubMenu : NavigationItem;
       const isOpen = itemId === openSubMenuId;
+      const scrollableNestedItems = (nestedItems === null || nestedItems === void 0 ? void 0 : nestedItems.map(item => ({
+        ...item,
+        onPress: event => {
+          const nestedItemId = item.id ?? item.label;
+          scrollToAnchor(item.href, event, () => setValue(nestedItemId, event));
+        }
+      }))) ?? nestedItems;
       return /*#__PURE__*/_jsx(ItemComponent, {
         ref: itemRef,
         href: href,
         onClick: handleClick
         // TODO: refactor to pass selected ID via context
         ,
-        selectedId: selectedId,
+        selectedId: currentValue,
         index: index,
         LinkRouter: ItemLinkRouter,
         linkRouterProps: {
           ...linkRouterProps,
           ...itemLinkRouterProps
         },
-        items: nestedItems,
-        selected: itemId === selectedId,
+        items: scrollableNestedItems,
+        selected: itemId === currentValue,
         itemsContainerRef: itemsRef,
         ...itemRest,
-        ...(nestedItems && {
+        ...(scrollableNestedItems && {
           isOpen
         }),
-        ...(nestedItems && isOpen && {
+        ...(scrollableNestedItems && isOpen && {
           openOverlayRef
         }),
         children: label
@@ -177,7 +227,7 @@ NavigationBar.propTypes = {
    *
    * Each `item` object must contain:
    *  - `heading` - user-facing text in the tab link
-   *  - `href` - the URL of the page linked to. Do not use hash links, for content within a page, use `Tabs`.
+   *  - `href` - the URL of the page linked to.
    *  - `id` - a stable, unique identifier of the page within the set. Not written into the HTML.
    */
   items: PropTypes.arrayOf(PropTypes.shape({
@@ -208,13 +258,17 @@ NavigationBar.propTypes = {
    */
   headingLevel: PropTypes.oneOf(['h1', 'h2', 'h3', 'h4', 'h5', 'h6']),
   /**
-   * Matches the `id` property of the item in `items` corresponding to the current page
+   * Initial selected item ID
    */
-  selectedId: PropTypes.string.isRequired,
+  selectedId: PropTypes.string,
   /**
    * Optional function to be called on pressing a link
    */
   onChange: PropTypes.func,
+  /**
+   * Controlled value for selected item ID
+   */
+  value: PropTypes.string,
   /**
    * Accesibility role for stackview
    */

package/lib/QuantitySelector/QuantitySelector.js

@@ -78,7 +78,7 @@ const QuantitySelector = /*#__PURE__*/React.forwardRef((_ref, ref) => {
       setError(getCopy('errors').invalidCharacters);
     }
   };
-  const renderLabel = () => label ? /*#__PURE__*/_jsx(InputLabel, {
+  const renderLabel = () => label || hint ? /*#__PURE__*/_jsx(InputLabel, {
     forId: id,
     label: label,
     hint: hint,

package/lib/ResponsiveImage/ResponsiveImage.js

@@ -25,11 +25,13 @@ const ResponsiveImage = /*#__PURE__*/React.forwardRef((_ref, ref) => {
     fallbackSrc,
     alt,
     loading = 'eager',
+    dataSet,
     ...rest
   } = _ref;
   return /*#__PURE__*/_jsxs("picture", {
     ...selectProps(rest),
     ref: ref,
+    ...dataSet,
     children: [/*#__PURE__*/_jsx("source", {
       srcSet: xlSrc,
       media: `(min-width: ${viewports.map.get(viewports.xl)}px)`
@@ -89,6 +91,10 @@ ResponsiveImage.propTypes = {
    * @default 'eager'
    * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-loading
    */
-  loading: PropTypes.oneOf(['eager', 'lazy'])
+  loading: PropTypes.oneOf(['eager', 'lazy']),
+  /**
+   * The dataSet prop allows to pass data-* attributes element to the component.
+   */
+  dataSet: PropTypes.object
 };
 export default ResponsiveImage;

package/lib/utils/index.js

@@ -7,4 +7,5 @@ import ssrStyles from './ssr';
 import isElementFocusable from './isElementFocusable';
 import renderStructuredContent from './renderStructuredContent';
 import useOverlaidPosition from './useOverlaidPosition';
-export { deprecate, htmlAttrs, contentfulProps, transformGradient, useTypographyTheme, warn, media, renderStructuredContent, ssrStyles, isElementFocusable, useOverlaidPosition };
+import scrollToAnchor from './scrollToAnchor';
+export { deprecate, htmlAttrs, contentfulProps, transformGradient, useTypographyTheme, warn, media, renderStructuredContent, ssrStyles, isElementFocusable, useOverlaidPosition, scrollToAnchor };

package/lib/utils/scrollToAnchor.js

@@ -0,0 +1,19 @@
+/**
+ * Scrolls smoothly to the anchor element specified by the href.
+ *
+ * @param {string} href - The href attribute value, expected to be an anchor link starting with '#'.
+ * @param {Event} event - The event object associated with the click or navigation action.
+ * @param {Function} onAfterScroll - A callback function to be executed after the scroll action is completed.
+ */
+const scrollToAnchor = (href, event, onAfterScroll) => {
+  if (href !== null && href !== void 0 && href.startsWith('#')) {
+    event.preventDefault();
+    const target = document.getElementById(href.slice(1));
+    target === null || target === void 0 || target.scrollIntoView({
+      behavior: 'smooth'
+    });
+    window.location.hash = href;
+    onAfterScroll(event);
+  }
+};
+export default scrollToAnchor;

package/package.json

@@ -6,7 +6,7 @@
   ],
   "dependencies": {
     "@gorhom/portal": "^1.0.14",
-    "@telus-uds/components-base": "^2.1.0",
+    "@telus-uds/components-base": "^2.2.0",
     "@telus-uds/system-constants": "^2.0.0",
     "fscreen": "^1.2.0",
     "lodash.omit": "^4.5.0",
@@ -81,5 +81,5 @@
     "skip": true
   },
   "types": "types/index.d.ts",
-  "version": "3.1.0"
+  "version": "3.2.0"
 }

package/src/NavigationBar/NavigationBar.jsx

@@ -4,11 +4,13 @@ import {
   selectSystemProps,
   StackView,
   Typography,
+  useHash,
+  useInputValue,
   useResponsiveProp,
   withLinkRouter
 } from '@telus-uds/components-base'
 import styled from 'styled-components'
-import { htmlAttrs } from '../utils'
+import { htmlAttrs, scrollToAnchor } from '../utils'
 import NavigationItem from './NavigationItem'
 import NavigationSubMenu from './NavigationSubMenu'
 import collapseItems from './collapseItems'
@@ -34,16 +36,37 @@ const NavigationBar = React.forwardRef(
       heading,
       headingLevel = 'h1',
       items,
-      onChange = () => {},
+      onChange,
       selectedId,
+      value,
       LinkRouter,
       linkRouterProps,
       ...rest
     },
     ref
   ) => {
+    const { currentValue, setValue } = useInputValue({ value, initialValue: selectedId, onChange })
+
+    useHash(
+      (hash, event) => {
+        let hashItem = hash && items.find(({ href }) => hash === href)
+        if (!hashItem) {
+          const parentItem = items.find(({ items: parentItems }) =>
+            parentItems?.some(({ href }) => hash === href)
+          )
+          hashItem = parentItem?.items.find(({ href }) => hash === href)
+        }
+        const hashId = hashItem && (hashItem.id || hashItem.label)
+        if (hashId) setValue(hashId, event)
+      },
+      [items, setValue]
+    )
+
     const direction = useResponsiveProp({ xs: 'column', sm: 'row' })
-    const itemsForViewport = useResponsiveProp({ xs: collapseItems(items, selectedId), lg: items })
+    const itemsForViewport = useResponsiveProp({
+      xs: collapseItems(items, currentValue),
+      lg: items
+    })
     const openOverlayRef = React.useRef(null)
     const [openSubMenuId, setOpenSubMenuId] = React.useState(null)
     const handleSubMenuClose = (event) => {
@@ -161,14 +184,28 @@ const NavigationBar = React.forwardRef(
             const handleClick = (event) => {
               if (nestedItems) {
                 setOpenSubMenuId(openSubMenuId !== itemId ? itemId : null)
+                return
+              }
+              if (href?.startsWith('#')) {
+                scrollToAnchor(href, event, () => setValue(itemId, event))
+              } else {
+                setValue(itemId, event)
               }
               onClick?.(event)
-              onChange?.(itemId, event)
             }
 
             const ItemComponent = nestedItems ? NavigationSubMenu : NavigationItem
             const isOpen = itemId === openSubMenuId
 
+            const scrollableNestedItems =
+              nestedItems?.map((item) => ({
+                ...item,
+                onPress: (event) => {
+                  const nestedItemId = item.id ?? item.label
+                  scrollToAnchor(item.href, event, () => setValue(nestedItemId, event))
+                }
+              })) ?? nestedItems
+
             return (
               <ItemComponent
                 ref={itemRef}
@@ -176,16 +213,16 @@ const NavigationBar = React.forwardRef(
                 href={href}
                 onClick={handleClick}
                 // TODO: refactor to pass selected ID via context
-                selectedId={selectedId}
+                selectedId={currentValue}
                 index={index}
                 LinkRouter={ItemLinkRouter}
                 linkRouterProps={{ ...linkRouterProps, ...itemLinkRouterProps }}
-                items={nestedItems}
-                selected={itemId === selectedId}
+                items={scrollableNestedItems}
+                selected={itemId === currentValue}
                 itemsContainerRef={itemsRef}
                 {...itemRest}
-                {...(nestedItems && { isOpen })}
-                {...(nestedItems && isOpen && { openOverlayRef })}
+                {...(scrollableNestedItems && { isOpen })}
+                {...(scrollableNestedItems && isOpen && { openOverlayRef })}
               >
                 {label}
               </ItemComponent>
@@ -207,7 +244,7 @@ NavigationBar.propTypes = {
    *
    * Each `item` object must contain:
    *  - `heading` - user-facing text in the tab link
-   *  - `href` - the URL of the page linked to. Do not use hash links, for content within a page, use `Tabs`.
+   *  - `href` - the URL of the page linked to.
    *  - `id` - a stable, unique identifier of the page within the set. Not written into the HTML.
    */
   items: PropTypes.arrayOf(
@@ -242,13 +279,17 @@ NavigationBar.propTypes = {
    */
   headingLevel: PropTypes.oneOf(['h1', 'h2', 'h3', 'h4', 'h5', 'h6']),
   /**
-   * Matches the `id` property of the item in `items` corresponding to the current page
+   * Initial selected item ID
    */
-  selectedId: PropTypes.string.isRequired,
+  selectedId: PropTypes.string,
   /**
    * Optional function to be called on pressing a link
    */
   onChange: PropTypes.func,
+  /**
+   * Controlled value for selected item ID
+   */
+  value: PropTypes.string,
   /**
    * Accesibility role for stackview
    */

package/src/QuantitySelector/QuantitySelector.jsx

@@ -96,7 +96,7 @@ const QuantitySelector = React.forwardRef(
     }
 
     const renderLabel = () =>
-      label ? (
+      label || hint ? (
         <InputLabel
           forId={id}
           label={label}

package/src/ResponsiveImage/ResponsiveImage.jsx

@@ -14,9 +14,12 @@ const staticStyles = {
  * Provide different image sources for different screen sizes.
  */
 const ResponsiveImage = React.forwardRef(
-  ({ xsSrc, smSrc, mdSrc, lgSrc, xlSrc, fallbackSrc, alt, loading = 'eager', ...rest }, ref) => {
+  (
+    { xsSrc, smSrc, mdSrc, lgSrc, xlSrc, fallbackSrc, alt, loading = 'eager', dataSet, ...rest },
+    ref
+  ) => {
     return (
-      <picture {...selectProps(rest)} ref={ref}>
+      <picture {...selectProps(rest)} ref={ref} {...dataSet}>
         <source srcSet={xlSrc} media={`(min-width: ${viewports.map.get(viewports.xl)}px)`} />
         <source srcSet={lgSrc} media={`(min-width: ${viewports.map.get(viewports.lg)}px)`} />
         <source srcSet={mdSrc} media={`(min-width: ${viewports.map.get(viewports.md)}px)`} />
@@ -65,7 +68,11 @@ ResponsiveImage.propTypes = {
    * @default 'eager'
    * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#attr-loading
    */
-  loading: PropTypes.oneOf(['eager', 'lazy'])
+  loading: PropTypes.oneOf(['eager', 'lazy']),
+  /**
+   * The dataSet prop allows to pass data-* attributes element to the component.
+   */
+  dataSet: PropTypes.object
 }
 
 export default ResponsiveImage

package/src/utils/index.js

@@ -7,6 +7,7 @@ import ssrStyles from './ssr'
 import isElementFocusable from './isElementFocusable'
 import renderStructuredContent from './renderStructuredContent'
 import useOverlaidPosition from './useOverlaidPosition'
+import scrollToAnchor from './scrollToAnchor'
 
 export {
   deprecate,
@@ -19,5 +20,6 @@ export {
   renderStructuredContent,
   ssrStyles,
   isElementFocusable,
-  useOverlaidPosition
+  useOverlaidPosition,
+  scrollToAnchor
 }

package/src/utils/scrollToAnchor.js

@@ -0,0 +1,18 @@
+/**
+ * Scrolls smoothly to the anchor element specified by the href.
+ *
+ * @param {string} href - The href attribute value, expected to be an anchor link starting with '#'.
+ * @param {Event} event - The event object associated with the click or navigation action.
+ * @param {Function} onAfterScroll - A callback function to be executed after the scroll action is completed.
+ */
+const scrollToAnchor = (href, event, onAfterScroll) => {
+  if (href?.startsWith('#')) {
+    event.preventDefault()
+    const target = document.getElementById(href.slice(1))
+    target?.scrollIntoView({ behavior: 'smooth' })
+    window.location.hash = href
+    onAfterScroll(event)
+  }
+}
+
+export default scrollToAnchor