@lumx/react 2.2.19 → 2.2.20-alpha-type.1

package/src/hooks/useCallbackOnEscape.ts

@@ -1,25 +1,33 @@
 import { DOCUMENT } from '@lumx/react/constants';
 import { Callback, onEscapePressed } from '@lumx/react/utils';
 import { useEffect } from 'react';
+import { Listener, makeListenerTowerContext } from '@lumx/react/utils/makeListenerTowerContext';
+
+const LISTENERS = makeListenerTowerContext();
 
 /**
- * Triggers a callback when the escape key is pressed.
+ * Register a global listener on 'Escape' key pressed.
+ *
+ * If multiple listener are registered, only the last one is maintained. When a listener is unregistered, the previous
+ * one gets activated again.
  *
  * @param callback      Callback
  * @param closeOnEscape Disables the hook when false
- * @param rootElement   Element on which to listen the escape key
  */
-export function useCallbackOnEscape(
-    callback: Callback | undefined,
-    closeOnEscape = true,
-    rootElement = DOCUMENT?.body,
-) {
+export function useCallbackOnEscape(callback: Callback | undefined, closeOnEscape = true) {
     useEffect(() => {
-        if (closeOnEscape && callback && rootElement) {
-            const onKeyDown = onEscapePressed(callback);
-            rootElement.addEventListener('keydown', onKeyDown);
-            return () => rootElement.removeEventListener('keydown', onKeyDown);
+        const rootElement = DOCUMENT?.body;
+        if (!closeOnEscape || !callback || !rootElement) {
+            return undefined;
         }
-        return undefined;
-    }, [callback, closeOnEscape, rootElement]);
+        const onKeyDown = onEscapePressed(callback);
+
+        const listener: Listener = {
+            enable: () => rootElement.addEventListener('keydown', onKeyDown),
+            disable: () => rootElement.removeEventListener('keydown', onKeyDown),
+        };
+
+        LISTENERS.register(listener);
+        return () => LISTENERS.unregister(listener);
+    }, [callback, closeOnEscape]);
 }

package/src/hooks/useFocusTrap.ts

@@ -2,67 +2,84 @@ import { useEffect } from 'react';
 
 import { DOCUMENT } from '@lumx/react/constants';
 import { getFirstAndLastFocusable } from '@lumx/react/utils/focus/getFirstAndLastFocusable';
+import { Falsy } from '@lumx/react/utils';
+import { Listener, makeListenerTowerContext } from '@lumx/react/utils/makeListenerTowerContext';
+
+const FOCUS_TRAPS = makeListenerTowerContext();
 
 /**
- * Add a key down event handler to the given root element (document.body by default) to trap the move of focus
- * (TAB and SHIFT-TAB keys) inside the given focusZoneElement.
- * Will focus the given focus element when activating the focus trap.
+ * Trap 'Tab' focus switch inside the `focusZoneElement`.
+ *
+ * If multiple focus trap are activated, only the last one is maintained and when a focus trap closes, the previous one
+ * gets activated again.
  *
  * @param focusZoneElement The element in which to trap the focus.
- * @param focusElement     The element to focus when the focus trap is activated.
- * @param rootElement      The element on which the key down event will be placed.
+ * @param focusElement     The element to focus when the focus trap is activated (otherwise the first focusable element
+ *                         will be focused).
  */
-export function useFocusTrap(
-    focusZoneElement: HTMLElement | null,
-    focusElement?: HTMLElement | null,
-    rootElement = DOCUMENT?.body,
-): void {
+export function useFocusTrap(focusZoneElement: HTMLElement | Falsy, focusElement?: HTMLElement | null): void {
     useEffect(() => {
-        if (rootElement && focusZoneElement) {
-            (document.activeElement as HTMLElement)?.blur();
-            if (focusElement) {
-                focusElement.focus();
+        // Body element can be undefined in SSR context.
+        const rootElement = DOCUMENT?.body;
+
+        if (!rootElement || !focusZoneElement) {
+            return undefined;
+        }
+
+        // Trap 'Tab' key down focus switch into the focus zone.
+        const trapTabFocusInFocusZone = (evt: KeyboardEvent) => {
+            const { key } = evt;
+            if (key !== 'Tab') {
+                return;
             }
+            const focusable = getFirstAndLastFocusable(focusZoneElement);
 
-            const onKeyDown = (evt: KeyboardEvent) => {
-                const { key } = evt;
-                if (key !== 'Tab') {
-                    return;
-                }
-                const focusable = getFirstAndLastFocusable(focusZoneElement);
+            // Prevent focus switch if no focusable available.
+            if (!focusable.first) {
+                evt.preventDefault();
+                return;
+            }
 
-                // Prevent focus switch if no focusable available.
-                if (!focusable.first) {
-                    evt.preventDefault();
-                    return;
-                }
+            if (
+                // No previous focus
+                !document.activeElement ||
+                // Previous focus is at the end of the focus zone.
+                (!evt.shiftKey && document.activeElement === focusable.last) ||
+                // Previous focus is outside the focus zone
+                !focusZoneElement.contains(document.activeElement)
+            ) {
+                focusable.first.focus();
+                evt.preventDefault();
+                return;
+            }
 
-                if (
-                    // No previous focus
-                    !document.activeElement ||
-                    // Previous focus is at the end of the focus zone.
-                    (!evt.shiftKey && document.activeElement === focusable.last) ||
-                    // Previous focus is outside the focus zone
-                    !focusZoneElement.contains(document.activeElement)
-                ) {
-                    focusable.first.focus();
-                    evt.preventDefault();
-                    return;
-                }
+            if (
+                // Focus order reversed
+                evt.shiftKey &&
+                // Previous focus is at the start of the focus zone.
+                document.activeElement === focusable.first
+            ) {
+                focusable.last.focus();
+                evt.preventDefault();
+            }
+        };
 
-                if (
-                    // Focus order reversed
-                    evt.shiftKey &&
-                    // Previous focus is at the start of the focus zone.
-                    document.activeElement === focusable.first
-                ) {
-                    focusable.last.focus();
-                    evt.preventDefault();
-                }
-            };
-            rootElement.addEventListener('keydown', onKeyDown);
-            return () => rootElement.removeEventListener('keydown', onKeyDown);
+        const focusTrap: Listener = {
+            enable: () => rootElement.addEventListener('keydown', trapTabFocusInFocusZone),
+            disable: () => rootElement.removeEventListener('keydown', trapTabFocusInFocusZone),
+        };
+
+        // SETUP:
+        if (focusElement && focusZoneElement.contains(focusElement)) {
+            // Focus the given element.
+            focusElement.focus();
+        } else {
+            // Focus the first focusable element in the zone.
+            getFirstAndLastFocusable(focusZoneElement).first?.focus();
         }
-        return undefined;
-    }, [focusElement, focusZoneElement, rootElement]);
+        FOCUS_TRAPS.register(focusTrap);
+
+        // TEARDOWN:
+        return () => FOCUS_TRAPS.unregister(focusTrap);
+    }, [focusElement, focusZoneElement]);
 }

package/src/index.ts

@@ -15,6 +15,7 @@ export * from './components/dropdown';
 export * from './components/expansion-panel';
 export * from './components/flag';
 export * from './components/flex-box';
+export * from './components/generic-block';
 export * from './components/grid';
 export * from './components/icon';
 export * from './components/image-block';

package/src/stories/generated/GenericBlock/Demos.stories.tsx

@@ -0,0 +1,6 @@
+/**
+ * File generated when storybook is started. Do not edit directly!
+ */
+export default { title: 'LumX components/generic-block/GenericBlock Demos' };
+
+export { App as Default } from './default';

package/src/utils/focus/getFirstAndLastFocusable.test.ts

@@ -124,5 +124,11 @@ describe(getFirstAndLastFocusable.name, () => {
             const focusable = getFirstAndLastFocusable(element);
             expect(focusable.first).toMatchInlineSnapshot(`<button />`);
         });
+
+        it('should skip hidden input', () => {
+            const element = htmlToElement(`<div><input hidden /><button /></div>`);
+            const focusable = getFirstAndLastFocusable(element);
+            expect(focusable.first).toMatchInlineSnapshot(`<button />`);
+        });
     });
 });

package/src/utils/focus/getFirstAndLastFocusable.ts

@@ -1,8 +1,8 @@
 /** CSS selector listing all tabbable elements. */
-const TABBABLE_ELEMENTS_SELECTOR = `a[href], button, textarea, input:not([type="hidden"]), [tabindex]`;
+const TABBABLE_ELEMENTS_SELECTOR = `a[href], button, textarea, input:not([type="hidden"]):not([hidden]), [tabindex]`;
 
 /** CSS selector matching element that are disabled (should not receive focus). */
-const DISABLED_SELECTOR = `[tabindex="-1"], [disabled]:not([disabled="false"]), [aria-disabled]:not([aria-disabled="false"])`;
+const DISABLED_SELECTOR = `[hidden], [tabindex="-1"], [disabled]:not([disabled="false"]), [aria-disabled]:not([aria-disabled="false"])`;
 
 const isNotDisabled = (element: HTMLElement) => !element.matches(DISABLED_SELECTOR);
 

package/src/utils/makeListenerTowerContext.ts

@@ -0,0 +1,32 @@
+import last from 'lodash/last';
+import pull from 'lodash/pull';
+
+export type Listener = { enable(): void; disable(): void };
+
+/**
+ * Keep track of listeners, only the last registered listener gets activated at any point (previously registered
+ * listener are disabled).
+ * When a listener gets unregistered, the previously registered listener gets enabled again.
+ */
+export function makeListenerTowerContext() {
+    const LISTENERS: Listener[] = [];
+
+    return {
+        register(listener: Listener) {
+            // Disable previous listener.
+            last(LISTENERS)?.disable();
+            // Keep track of current listener.
+            LISTENERS.push(listener);
+            // Enable current listener.
+            listener.enable();
+        },
+        unregister(listener: Listener) {
+            // Disable current listener.
+            listener.disable();
+            // Remove current listener.
+            pull(LISTENERS, listener);
+            // Enable previous listener.
+            last(LISTENERS)?.enable();
+        },
+    };
+}

package/src/utils/type.ts

@@ -31,6 +31,9 @@ export type Comp<P, T = HTMLElement> = {
     className?: string;
 };
 
+/** Union type of all heading elements */
+export type HeadingElement = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+
 /**
  * Define a generic props types.
  */

package/types.d.ts

@@ -1,6 +1,13 @@
 // Generated by dts-bundle-generator v5.6.0
 
-/// <reference types="react" />
+/// <reference types="cheerio" />
+/// <reference types="node" />
+/// <reference types="prop-types" />
+
+import * as CSS from 'csstype';
+import * as PropTypes from 'prop-types';
+import React from 'react';
+import { AriaAttributes, ButtonHTMLAttributes, CSSProperties, DetailedHTMLProps, ImgHTMLAttributes, InputHTMLAttributes, Key, KeyboardEventHandler, MouseEventHandler, ReactElement, ReactNode, Ref, RefObject, SetStateAction, SyntheticEvent } from 'react';
 
 /** Get types of the values of a record. */
 export declare type ValueOf<T extends Record<any, any>> = T[keyof T];
@@ -18,6 +25,8 @@ export declare type Comp<P, T = HTMLElement> = {
 	/** Component base class name. */
 	className?: string;
 };
+/** Union type of all heading elements */
+export declare type HeadingElement = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
 /**
  * Define a generic props types.
  */
@@ -32,6 +41,11 @@ export interface GenericProps {
  * Callback function type alias (use for readability)
  */
 export declare type Callback = () => void;
+/**
+ * JS falsy values.
+ * (excluding `NaN` as it can't be distinguished from `number`)
+ */
+export declare type Falsy = false | undefined | null | 0 | "";
 /**
  * Alignments.
  */
@@ -259,7 +273,7 @@ export interface AutocompleteProps extends GenericProps {
 	 * Reference to the <input> or <textarea> element.
 	 * @see {@link TextFieldProps#inputRef}
 	 */
-	inputRef?: RefObject<HTMLInputElement>;
+	inputRef?: TextFieldProps["inputRef"];
 	/**
 	 * The offset that will be applied to the Dropdown position.
 	 * @see {@link DropdownProps#offset}
@@ -476,9 +490,7 @@ export declare type HTMLButtonProps = DetailedHTMLProps<ButtonHTMLAttributes<HTM
  * Button size definition.
  */
 export declare type ButtonSize = Extract<Size, "s" | "m">;
-export interface BaseButtonProps extends GenericProps {
-	/** ARIA button label. */
-	["aria-label"]?: string;
+export interface BaseButtonProps extends GenericProps, Pick<AriaAttributes, "aria-expanded" | "aria-haspopup" | "aria-pressed" | "aria-label"> {
 	/** Color variant. */
 	color?: Color;
 	/** Emphasis variant. */
@@ -743,7 +755,7 @@ export interface DatePickerProps extends GenericProps {
 	/** Props to pass to the previous month button (minus those already set by the DatePickerControlled props). */
 	previousButtonProps: Pick<IconButtonProps, "label"> & Omit<IconButtonProps, "label" | "onClick" | "icon" | "emphasis">;
 	/** Reference to the <button> element corresponding to the current date or the selected date. */
-	todayOrSelectedDateRef?: RefObject<HTMLButtonElement>;
+	todayOrSelectedDateRef?: Ref<HTMLButtonElement>;
 	/** Currently selected date. */
 	value: Date | undefined;
 	/** On change callback. */
@@ -828,7 +840,7 @@ export interface DialogProps extends GenericProps {
 	/** Reference to the parent element that triggered modal opening (will get back focus on close). */
 	parentElement?: RefObject<HTMLElement>;
 	/** Reference to the dialog content element. */
-	contentRef?: RefObject<HTMLDivElement>;
+	contentRef?: Ref<HTMLDivElement>;
 	/** Reference to the of the element that should get the focus when the dialogs opens. By default, the first child will take focus. */
 	focusElement?: RefObject<HTMLElement>;
 	/** Whether to keep the dialog open on clickaway or escape press. */
@@ -951,6 +963,8 @@ export interface PopoverProps extends GenericProps {
 	isOpen: boolean;
 	/** Offset placement relative to anchor. */
 	offset?: Offset;
+	/** Reference to the parent element that triggered the popover (will get back focus on close or else fallback on the anchor element). */
+	parentElement?: RefObject<HTMLElement>;
 	/** Placement relative to anchor. */
 	placement?: Placement;
 	/** Whether the popover should be rendered into a DOM node that exists outside the DOM hierarchy of the parent component. */
@@ -972,10 +986,11 @@ export declare const Popover: Comp<PopoverProps, HTMLDivElement>;
  * Defines the props of the component.
  */
 export interface DropdownProps extends GenericProps {
-	/** Reference to the element around which the dropdown is placed.
+	/**
+	 * Reference to the element around which the dropdown is placed.
 	 * @see {@link PopoverProps#anchorRef}
 	 */
-	anchorRef: React.RefObject<HTMLElement>;
+	anchorRef: PopoverProps["anchorRef"];
 	/** Dropdown content. */
 	children: React.ReactNode;
 	/**
@@ -1124,6 +1139,41 @@ export interface FlexBoxProps extends GenericProps {
  * @return React element.
  */
 export declare const FlexBox: Comp<FlexBoxProps, HTMLDivElement>;
+export interface GenericBlockProps extends FlexBoxProps {
+	/** Component to use as visual element. */
+	figure?: ReactNode;
+	/** Actions to set after the main content. */
+	actions?: ReactNode;
+	/** Main content to display */
+	children: ReactNode;
+	/** Orientation of the 3 sections */
+	orientation?: FlexBoxProps["orientation"];
+	/** Horizontal alignment. */
+	hAlign?: FlexBoxProps["hAlign"];
+	/** Vertical alignment. */
+	vAlign?: FlexBoxProps["vAlign"];
+	/**
+	 * The props to forward to the content.
+	 * By default, the content will have the same alignment as wrapper.
+	 */
+	contentProps?: Omit<FlexBoxProps, "children">;
+	/** props to forward to the actions element. */
+	actionsProps?: Omit<FlexBoxProps, "children">;
+	/** props to forward to the figure element. */
+	figureProps?: Omit<FlexBoxProps, "children">;
+}
+/**
+ * The GenericBlock is a layout component made of 3 sections that can be
+ * displayed either horizontally of vertically with the same gap between each section.
+ *
+ * The sections are:
+ * * (Optional) `Figure` => A visual element to display before the main content.
+ * * (Required) `Content` => The main content displayed
+ * * (Optional) `Actions` => One or more actions to set after the element.
+ *
+ * @see https://www.figma.com/file/lzzrQmsfaXRaOyRfoEogPZ/DS%3A-playground?node-id=1%3A4076
+ */
+export declare const GenericBlock: Comp<GenericBlockProps, HTMLDivElement>;
 export declare type GridGutterSize = Extract<Size, "regular" | "big" | "huge">;
 /**
  * Defines the props of the component.
@@ -1235,7 +1285,7 @@ export interface ThumbnailProps extends GenericProps {
 	/** Image aspect ratio. */
 	aspectRatio?: AspectRatio;
 	/** Badge. */
-	badge?: ReactElement;
+	badge?: ReactElement | Falsy;
 	/** Image cross origin resource policy. */
 	crossOrigin?: ImgHTMLProps["crossOrigin"];
 	/** Fallback icon (SVG path) or react node when image fails to load. */
@@ -1433,12 +1483,12 @@ export declare const Link: Comp<LinkProps, HTMLAnchorElement | HTMLButtonElement
  * Defines the props of the component.
  */
 export interface LinkPreviewProps extends GenericProps {
-	/** Description (either a string, or sanitized html). */
-	description?: string | {
-		__html: string;
-	};
+	/** Description. */
+	description?: string;
 	/** Link URL. */
 	link: string;
+	/** Custom react component for the link (can be used to inject react router Link). */
+	linkAs?: "a" | any;
 	/** Props to pass to the link (minus those already set by the LinkPreview props). */
 	linkProps?: Omit<LinkProps, "color" | "colorVariant" | "href" | "target">;
 	/** Size variant. */
@@ -1449,6 +1499,8 @@ export interface LinkPreviewProps extends GenericProps {
 	thumbnailProps?: ThumbnailProps;
 	/** Title. */
 	title?: string;
+	/** Customize the title heading tag. */
+	titleHeading?: HeadingElement;
 }
 /**
  * LinkPreview component.
@@ -1858,6 +1910,8 @@ export interface CoreSelectProps extends GenericProps {
 	helper?: string;
 	/** Whether the select should close on click. */
 	closeOnClick?: boolean;
+	/** Icon (SVG path). */
+	icon?: string;
 	/** Whether the component is disabled or not. */
 	isDisabled?: boolean;
 	/** Whether the component is required or not. */
@@ -2512,7 +2566,7 @@ export interface TextFieldProps extends GenericProps {
 	/** Native input id property (generated if not provided to link the label element). */
 	id?: string;
 	/** Reference to the <input> or <textarea> element. */
-	inputRef?: RefObject<HTMLInputElement> | RefObject<HTMLTextAreaElement>;
+	inputRef?: Ref<HTMLInputElement | HTMLTextAreaElement>;
 	/** Whether the component is disabled or not. */
 	isDisabled?: boolean;
 	/** Whether the component is required or not. */
@@ -2532,7 +2586,7 @@ export interface TextFieldProps extends GenericProps {
 	/** Placeholder text. */
 	placeholder?: string;
 	/** Reference to the wrapper. */
-	textFieldRef?: RefObject<HTMLDivElement>;
+	textFieldRef?: Ref<HTMLDivElement>;
 	/** Theme adapting the component to light or dark background. */
 	theme?: Theme;
 	/** Value. */

package/src/components/link-preview/__snapshots__/LinkPreview.test.tsx.snap

@@ -1,51 +0,0 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
-
-exports[`<LinkPreview> Snapshots and structure should render correctly 1`] = `
-<div
-  className="lumx-link-preview lumx-link-preview--size-regular lumx-link-preview--theme-light"
->
-  <div
-    className="lumx-link-preview__wrapper"
-  >
-    <div
-      className="lumx-link-preview__container"
-    >
-      <div
-        className="lumx-link-preview__link"
-      >
-        <Link
-          className="lumx-link-preview__link"
-          color="primary"
-          colorVariant="N"
-          target="_blank"
-        />
-      </div>
-    </div>
-  </div>
-</div>
-`;
-
-exports[`<LinkPreview> Snapshots and structure should render correctly 2`] = `
-<div
-  className="lumx-link-preview lumx-link-preview--size-regular lumx-link-preview--theme-light"
->
-  <div
-    className="lumx-link-preview__wrapper"
-  >
-    <div
-      className="lumx-link-preview__container"
-    >
-      <div
-        className="lumx-link-preview__link"
-      >
-        <Link
-          className="lumx-link-preview__link"
-          color="primary"
-          colorVariant="N"
-          target="_blank"
-        />
-      </div>
-    </div>
-  </div>
-</div>
-`;