@muraldevkit/ui-toolkit 4.45.2-dev-jOrv.1 → 4.45.2

package/dist/components/rovingTabindex/MrlRovingTabindex/MrlRovingTabindex.d.ts

@@ -0,0 +1,127 @@
+import * as React from 'react';
+type RefType = HTMLElement | HTMLDivElement | null;
+/**
+ * Gets tabbable elements in a given bit of the DOM
+ *
+ * @param {RefType} ref - the ref of the container
+ * @param {string} selector - the selector to query
+ * @returns {HTMLElement[]} - an array of tabbable HTML elements
+ */
+export declare const getTabbableElements: (ref: RefType, selector: string) => HTMLElement[];
+export type FocusOnInitPosition = 'first' | 'last';
+export interface RovingPropTypes {
+    activeSelector?: string;
+    children: React.ReactNode;
+    /**
+     * delayMount is used to apply a delay to the mounting
+     * of the RovingTabindex component. This can be helpful in
+     * the event that a component's children have not been fully
+     * rendered by the time the componentDidMount function is triggered
+     */
+    delayMount?: number;
+    focusOnInit?: FocusOnInitPosition;
+    focusWithShortcut?: boolean;
+    forceUpdate?: boolean;
+    hasChildRoving?: boolean;
+    ignoreElements?: string;
+    isFocused?: boolean;
+    onBlur?: () => void;
+    onRefocus?: (shouldRefocus: boolean) => void;
+    orientation?: RovingOrientation;
+    qa?: string;
+}
+type RovingOrientation = 'horizontal' | 'vertical';
+type NavigationDirection = 'forward' | 'back';
+/**
+ * Component to create a Roving Tabindex in the DOM
+ *
+ * @returns {HTMLDivElement}
+ */
+declare class MrlRovingTabindex extends React.Component<RovingPropTypes> {
+    elements: Array<Element | null>;
+    orientation: RovingOrientation;
+    ref: HTMLDivElement | null;
+    selector: string;
+    /**
+     * MrlRovingTabindex class constructor
+     *
+     * @param props - the MrlRovingTabindex props
+     * @returns new instance
+     */
+    constructor(props: RovingPropTypes);
+    /**
+     * Runs when the MrlRovingTabindex component mounts
+     */
+    componentDidMount(): void;
+    /**
+     * Runs when the MrlRovingTabindex component updates
+     *
+     * @param {RovingPropTypes} prevProps - the props before the component updated
+     */
+    componentDidUpdate(prevProps: RovingPropTypes): void;
+    handleRef: (ref: HTMLDivElement) => HTMLDivElement;
+    /**
+     * Sets component array of elements
+     *
+     * @returns {void}
+     */
+    setElements: () => void;
+    /**
+     * Gets the components active element based on priority order.
+     *
+     * @returns {HTMLElement | undefined} - the active HTML element
+     */
+    getActiveElement: () => HTMLElement | undefined;
+    /**
+     * Sets an element to `tabindex=0` and sets all other elements to `tabindex=-1`
+     *
+     * @param {HTMLElement | undefined} el - the element to set as active
+     * @returns {void}
+     */
+    setActiveElement: (el: HTMLElement | undefined) => void;
+    /**
+     * Sets focus to a specific element
+     *
+     * @param {HTMLElement | undefined} el - the element to set in focus
+     * @returns {void}
+     */
+    setElementFocus: (el: HTMLElement | undefined) => void;
+    /**
+     * Sets focus to an element based on a direction (`forward` or `back`)
+     *
+     * @param {NavigationDirection} direction 'forward' | 'back'
+     * @returns {void}
+     */
+    setFocusByDirection: (direction: NavigationDirection) => void;
+    /**
+     * Sets all tabindex for elements of this component to -1
+     *
+     * @returns {void}
+     */
+    unsetTabbableElements: () => void;
+    /**
+     * Will return `false` if the orientation param matches the
+     * orientation of the component and the actively focused element has a menu or select
+     *
+     * @param orientation : 'horizontal' | 'vertical'
+     * @returns boolean
+     */
+    canUseArrows: (orientation: RovingOrientation) => boolean;
+    handleKeyUp: (e: React.KeyboardEvent) => void;
+    handleFocusedFirst: () => void;
+    handleFocusedLast: () => void;
+    handleRefocus: () => void;
+    /**
+     * Mounts the MrlRovingTabindex component
+     *
+     * @returns {void}
+     */
+    mount(): void;
+    /**
+     * Renders the MrlRovingTabindex component
+     *
+     * @returns {HTMLDivElement} - the rendered MrlRovingTabindex component
+     */
+    render(): JSX.Element;
+}
+export { MrlRovingTabindex };

package/dist/components/rovingTabindex/MrlRovingTabindex/index.d.ts

@@ -0,0 +1 @@
+export * from './MrlRovingTabindex';

package/dist/components/rovingTabindex/index.d.ts

@@ -0,0 +1 @@
+export * from './MrlRovingTabindex';

package/dist/components/skeleton/MrlSkeleton/MrlSkeleton.d.ts

@@ -0,0 +1,20 @@
+import * as React from 'react';
+export interface MrlSkeletonProps extends React.ComponentProps<'div'> {
+    /** An object with CSS properties */
+    style?: React.CSSProperties;
+    /** MrlSkeleton wrapper class */
+    className?: string;
+    /** The height of the MrlSkeleton component */
+    height?: React.CSSProperties['height'];
+    /** The width of the MrlSkeleton component */
+    width?: React.CSSProperties['width'];
+    /** The shape of the Skeleton component */
+    shape?: 'circle' | 'default';
+}
+/**
+ * MrlSkeleton React component.
+ *
+ * @param props {MrlSkeletonProps} - component props
+ * @returns a MrlSkeleton React component.
+ */
+export declare function MrlSkeleton({ height, shape, style, width, className, ...rest }: MrlSkeletonProps): JSX.Element;

package/dist/components/skeleton/MrlSkeleton/index.d.ts

@@ -0,0 +1 @@
+export * from './MrlSkeleton';

package/dist/components/skeleton/MrlSkeletonText/MrlSkeletonText.d.ts

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import { TextSizes } from '../../text/constants';
+export interface MrlSkeletonTextProps extends React.ComponentProps<'div'> {
+    /** An object of CSS properties */
+    style?: React.CSSProperties;
+    /** MrlSkeletonText wrapper class */
+    className?: string;
+    /** The width of the MrlSkeletonText component */
+    width?: React.CSSProperties['width'];
+    /** Number of lines to render */
+    lines?: number;
+    /** Size of the text which is the same as MrlText component */
+    size?: TextSizes;
+}
+/**
+ * MrlSkeletonText React component. Used to create skeleton elements as placeholders
+ * for the MrlText component. It supports the same text sizes as the MrlText component.
+ *
+ * @param props {MrlSkeletonTextProps} - component props
+ * @returns a MrlSkeleton React component.
+ */
+export declare function MrlSkeletonText({ className, style, width, lines, size, ...rest }: MrlSkeletonTextProps): JSX.Element;

package/dist/components/skeleton/MrlSkeletonText/index.d.ts

@@ -0,0 +1 @@
+export * from './MrlSkeletonText';

package/dist/components/skeleton/index.d.ts

@@ -0,0 +1,2 @@
+export * from './MrlSkeleton';
+export * from './MrlSkeletonText';

package/dist/components/svg/MrlSvg/MrlSvg.d.ts

@@ -0,0 +1,31 @@
+import * as React from 'react';
+import { MrlComponentProps } from '../../../utils';
+import { SVGSize } from '../constants';
+export type DSIcons = typeof import('@muraldevkit/ds-icons');
+export type DSPictograms = typeof import('@muraldevkit/ds-pictograms');
+export type DSIconType = DSIcons[keyof DSIcons] | DSPictograms[keyof DSPictograms];
+export interface SvgPropTypes extends Omit<MrlComponentProps, 'style'>, Omit<React.ComponentProps<'svg'>, 'ref'> {
+    /** Any additional classes to style the SVG's container */
+    className?: string;
+    /**
+     * @todo: Add optional path prop to point to a static SVG url
+     * @todo: Make SVG prop optional and must pass one of path or SVG
+     */
+    isClone?: boolean;
+    /** The size of an SVG Component */
+    size?: SVGSize;
+    /**
+     * A object of CSS properties. Please use style sparingly, and only in cases where your
+     * needs can not be met by passing a class to the component.
+     */
+    style?: Record<string, unknown>;
+    /** The SVG object to parse into an HTML SVG element */
+    svg: DSIconType;
+}
+/**
+ * Creating and exporting component class for Mural SVG
+ *
+ * @param {SvgPropTypes} props the props for your MrlSvg
+ * @returns {React.ReactElement} a rendered SVG
+ */
+export declare const MrlSvg: React.MemoExoticComponent<(props: SvgPropTypes) => React.ReactElement>;

package/dist/components/svg/MrlSvg/index.d.ts

@@ -0,0 +1 @@
+export { MrlSvg, type SvgPropTypes } from './MrlSvg';

package/dist/components/svg/MrlSvgAnimate/MrlSvgAnimate.d.ts

@@ -0,0 +1,51 @@
+import * as React from 'react';
+import { AnimatedState } from '../constants';
+/**
+ * Props for MrlSvgAnimate component
+ */
+export interface MrlSvgAnimateProps {
+    /** Any additional classes to style the SVG's container */
+    className?: string;
+    /**
+     * JSON file contents used by Lottie to generate an animated SVG to render.
+     * This attribute is mutually exclusive with fullPath and cdnFile.
+     * Note: When dynamically changing the svgData, if a configuration change
+     * is required be sure to set any new values before changing the svgData.
+     */
+    svgData?: string;
+    /**
+     * Path to a JSON file used by Lottie to generate an animated SVG to render.
+     * This attribute is mutually exclusive with svgData and cdnFile.
+     * Note: When dynamically changing the fullPath, if a configuration change
+     * is required be sure to set any new values before changing the fullPath.
+     */
+    fullPath?: string;
+    /**
+     * File name of an animation hosted on Mural's CDN used by Lottie to generate
+     * an animated SVG to render. This is the preferred usage of this component
+     * in terms of performance. It supports any file located at `static/animations`.
+     * This attribute is mutually exclusive with fullPath and svgData.
+     * Note: When dynamically changing the cdnFile, if a configuration change
+     * is required be sure to set any new values before changing the cdnFile.
+     */
+    cdnFile?: string;
+    /** Icon animation state. */
+    state?: AnimatedState;
+    /** Delay (in ms) before animation begins. */
+    delay?: number;
+    /**
+     * Optional [Lottie configuration object](http://airbnb.io/lottie/#/web) for the
+     * loadAnimation method
+     */
+    config?: string;
+}
+/**
+ * MrlSvgAnimate
+ *
+ * This is a React functional component used for SVGs with robust After Effects animations.
+ *
+ * @param {MrlSvgAnimateProps} props - The properties for the MrlSvgAnimate component.
+ * @returns {React.ReactElement} - The rendered MrlSvgAnimate component.
+ */
+export declare const MrlSvgAnimate: React.FC<MrlSvgAnimateProps>;
+export default MrlSvgAnimate;

package/dist/components/svg/MrlSvgAnimate/index.d.ts

@@ -0,0 +1 @@
+export { MrlSvgAnimate, type MrlSvgAnimateProps } from './MrlSvgAnimate';

package/dist/components/svg/config.d.ts

@@ -0,0 +1,112 @@
+/** Storybook configurations allowed for the SVG component. */
+export interface SvgArgs {
+    color: string;
+}
+export declare const storyData: {
+    args: {
+        color: string;
+        size: import("./constants").SVGSize;
+    };
+    argTypes: {
+        color: {
+            control: {
+                type: string;
+            };
+        };
+        size: {
+            control: {
+                options: string[];
+                type: string;
+            };
+        };
+    };
+    manifest: {
+        scans: {
+            size: string[];
+        };
+    };
+    title: string;
+};
+export declare const iconStoryData: {
+    manifest: {
+        exclude: {
+            default: string[];
+        };
+    };
+    title: string;
+};
+export declare const pictogramStoryData: {
+    manifest: {
+        exclude: {
+            default: string[];
+        };
+    };
+    title: string;
+};
+export declare const visualThinkingContainerStyles: {
+    display: string;
+    flexDirection: string;
+};
+export declare const brandContainerStyles: {
+    background: string;
+    width: string;
+};
+export declare const headingStyles: {
+    marginTop: string;
+};
+export declare const colorPictoStoryData: {
+    args: {
+        state: string;
+    };
+    argTypes: {
+        state: {
+            control: {
+                options: string[];
+                type: string;
+            };
+        };
+    };
+    manifest: {
+        exclude: {
+            default: string[];
+        };
+        scans: {
+            state: string[];
+        };
+    };
+    name: string;
+    title: string;
+};
+export declare const animateStoryData: {
+    args: {
+        delay: number;
+        state: "stop" | "play";
+    };
+    argTypes: {
+        delay: {
+            max: number;
+            min: number;
+            name: string;
+            step: number;
+            type: string;
+        };
+        state: {
+            control: {
+                options: readonly ["stop", "play"];
+                type: string;
+            };
+        };
+    };
+    manifest: {
+        exclude: {
+            default: string[];
+        };
+    };
+    name: string;
+    title: string;
+};
+export declare const animateContainerStyles: {
+    backgroundColor: string;
+    height: string;
+    width: string;
+};

package/dist/components/svg/constants.d.ts

@@ -0,0 +1,36 @@
+import { AttrsObject } from '../../utils';
+import { AnimationConfigWithData } from 'lottie-web';
+export type SVGSize = 'small' | 'medium' | 'large' | 'auto';
+export interface SVGDefaults {
+    attrs: AttrsObject;
+    size: SVGSize;
+}
+interface AllowedValues {
+    sizes: Array<string>;
+}
+/**
+ * Defines all of values allowed for attributes with limited values;
+ * used for Storybook and testing
+ */
+export declare const allowedSvgValues: AllowedValues;
+/**
+ * Default values for props on the SVG component;
+ * Shared between the component and Storybook
+ */
+export declare const svgDefaults: SVGDefaults;
+export type SVGObject = Record<string, any>;
+export type LottieConfig = Omit<AnimationConfigWithPath, 'container'>;
+export declare const baseLottieConfig: LottieConfig;
+interface AnimationConfigWithPath extends AnimationConfigWithData<'svg'> {
+    path?: string;
+}
+export declare const allowedAnimatedValues: {
+    states: readonly ["stop", "play"];
+};
+export type AnimatedState = (typeof allowedAnimatedValues.states)[number];
+export interface AnimatedDefaults {
+    delay: number;
+    state: AnimatedState;
+}
+export declare const animatedDefaults: AnimatedDefaults;
+export {};

package/dist/components/svg/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./MrlSvg/MrlSvg";
+export * from "./MrlSvgAnimate/MrlSvgAnimate";
+export * from './constants';

package/dist/components/table/MrlSmartTable/MrlSmartTable.d.ts

@@ -0,0 +1,216 @@
+import * as React from 'react';
+import { MrlTableProps } from '../MrlTable';
+import { MrlSortDirection, MrlTableCellHorizontalAlign, MrlTableColumnId, MrlTableColumnSortDescriptor, MrlTableItemId, MrlTableSelectionMode } from '../constants';
+export interface MrlSmartColumnRendererProps {
+    /**
+     * The column being rendered.
+     */
+    column: MrlSmartTableColumn;
+    /**
+     * A function to change current sort descriptor.
+     */
+    handleSortClick: ({ column, direction, name }: {
+        column: MrlSmartTableColumn['id'];
+        direction: MrlSortDirection;
+        name: string;
+    }) => void;
+    /**
+     * The element id of the table.
+     */
+    tableElementId: string;
+    /**
+     * The data-qa prefix of the table.
+     */
+    dataQaPrefix: string;
+    /**
+     * The current sort descriptor.
+     */
+    sortDescriptor?: MrlTableColumnSortDescriptor;
+    hasScrollShadowLeft: boolean;
+    hasScrollShadowRight: boolean;
+    horizontalAlign?: MrlTableCellHorizontalAlign;
+}
+export interface MrlSmartCellRendererProps {
+    /**
+     * The item for the cell being rendered.
+     */
+    item: MrlTableItem;
+    /**
+     * The column for the cell being rendered.
+     */
+    column: MrlSmartTableColumn;
+    /**
+     * The element id of the table.
+     */
+    tableElementId: string;
+    /**
+     * The data-qa prefix of the table.
+     */
+    dataQaPrefix: string;
+    hasScrollShadowLeft: boolean;
+    hasScrollShadowRight: boolean;
+}
+export interface MrlTableItem extends Record<string, unknown> {
+    /**
+     * A unique identifier for the row item.
+     */
+    id: MrlTableItemId;
+    /**
+     * This makes the row item not selectable.
+     */
+    isSelectable?: boolean;
+    /**
+     * This makes the row item visually disabled.
+     */
+    isDisabled?: boolean;
+    /**
+     * A ref to the table row element
+     * The ref is an object where the key is the item id and the value is the table row element
+     */
+    rowRef?: React.MutableRefObject<Record<MrlTableItemId, HTMLTableRowElement>>;
+}
+export type MrlTableColumnSticky = 'left' | 'right';
+export interface MrlSmartTableColumn {
+    /**
+     * The key used to retrieve the cell value from the item object,
+     * e.g. `item[key]`.
+     */
+    id: MrlTableColumnId;
+    /**
+     * The display name of the column.
+     */
+    name: string;
+    /**
+     * The horizontal alignment of the column content.
+     * If not provided, the default alignment is left.
+     */
+    horizontalAlign?: MrlTableCellHorizontalAlign;
+    /**
+     * A component used to override rendering for each column cell. The
+     * component is expected to render a MrlTableColumn.
+     */
+    renderColumn?: (props: MrlSmartColumnRendererProps) => JSX.Element;
+    /**
+     * A component used to override rendering for each row cell. The
+     * component is expected to render a MrlTableCell.
+     */
+    renderCell?: (props: MrlSmartCellRendererProps) => JSX.Element;
+    /**
+     * Whether the column allows sorting.
+     */
+    allowsSorting?: boolean;
+    /**
+     * A sort comparator function for the column.
+     *
+     * @default sortAlphabeticallyAsCoercedStrings
+     */
+    sortBy?: (aValue: unknown, bValue: unknown) => number;
+    /**
+     * A sort comparator function for the column that receives the entire
+     * row context. Will override the `sortBy` function (if provided).
+     *
+     * @param aValue
+     * @param bValue
+     * @returns number
+     */
+    sortByRowContext?: (aValue: unknown, bValue: unknown) => number;
+    /**
+     * Whether the column is sticky
+     * the sticky effect will only work on the first or last column.
+     * Set to 'left' for the first column and 'right' for the last column
+     *
+     * @example The container of the table will need overflow:scroll/auto
+     * and the width will need to be constrained in order for
+     * the columns to be 'sticky'
+     */
+    sticky?: MrlTableColumnSticky;
+    /**
+     * A tooltip to display on the column header.
+     */
+    tooltip?: string;
+}
+/**
+ * A set of item ids.
+ */
+export type MrlTableSelection = Set<MrlTableItemId>;
+export interface MrlSmartTableSelectionOptions {
+    /**
+     * The type of selection that is allowed in the collection.
+     *
+     * @default none
+     */
+    mode: MrlTableSelectionMode;
+    /**
+     * The currently selected keys in the collection (controlled).
+     */
+    selectedKeys: MrlTableSelection;
+    /**
+     * Handler that is called when the selection changes.
+     */
+    onSelectionChange: (keys: MrlTableSelection) => void;
+}
+export interface MrlTableColumnSortOptions {
+    /**
+     * The column to sort by.
+     */
+    sortColumn: MrlSmartTableColumn;
+    /**
+     * The details of the sort.
+     */
+    sortDescriptor: MrlTableColumnSortDescriptor;
+}
+export interface MrlSmartTableProps extends Partial<Pick<MrlTableProps, 'aria-label' | 'aria-labelledby' | 'aria-describedby' | 'aria-details'>> {
+    /**
+     * A list of table columns.
+     */
+    columns: MrlSmartTableColumn[];
+    /**
+     * A list of items to populate the table.
+     */
+    items: MrlTableItem[];
+    /**
+     * When provided, enables and controls table selection.
+     */
+    selectionOptions?: MrlSmartTableSelectionOptions;
+    /**
+     * A prefix applied to each data-qa element within the table.
+     *
+     * @default "mrl-smart-table"
+     */
+    dataQaPrefix?: string;
+    /**
+     * Text to be displayed when there are no rows in the table.
+     * Will be ignored if `emptyState` is provided.
+     *
+     * @default "There's no data available to be displayed in this table."
+     */
+    emptyStateText?: string;
+    /**
+     * Provides content to display when there are no rows in the table.
+     *
+     * @default MrlTableEmptyState
+     */
+    emptyState?: JSX.Element;
+    /**
+     * An element id (and if not provided, a unique value decorated
+     * to prevent conflict with aria controls will be generated).
+     *
+     * @default ${id}-mrl-smart-table
+     */
+    id?: string;
+    /**
+     * A function to override the default sort items when a sort descriptor is set.
+     */
+    customSortItems?: ({ sortColumn, sortDescriptor }: MrlTableColumnSortOptions) => void;
+    /**
+     * Provides information on how the table should be sorted on initialization.
+     */
+    defaultSortDescriptor?: MrlTableColumnSortDescriptor;
+}
+/**
+ * MrlSmartTable Component
+ *
+ * @param {MrlSmartTableProps} props - MrlSmartTable component props
+ * @returns a table
+ */
+export declare function MrlSmartTable(props: MrlSmartTableProps): JSX.Element;

package/dist/components/table/MrlSmartTable/index.d.ts

@@ -0,0 +1 @@
+export * from './MrlSmartTable';

package/dist/components/table/MrlTable/MrlTable.d.ts

@@ -0,0 +1,17 @@
+import * as React from 'react';
+export interface MrlTableProps extends React.ComponentPropsWithoutRef<'table'> {
+    /**
+     * An element id (and if not provided, a unique value decorated
+     * to prevent conflict with aria controls will be generated).
+     *
+     * @default `${id}-mrl-table`
+     */
+    id?: string;
+}
+/**
+ * MrlTable Component
+ *
+ * @param {MrlTable} props - MrlTable component props
+ * @returns a table element
+ */
+export declare const MrlTable: React.ForwardRefExoticComponent<MrlTableProps & React.RefAttributes<HTMLTableElement>>;

package/dist/components/table/MrlTable/index.d.ts

@@ -0,0 +1 @@
+export * from './MrlTable';