@muraldevkit/ui-toolkit 4.67.0 → 4.68.0-dev-NFbt.1

package/dist/types/components/layout/error-page/MrlErrorPage/MrlErrorPage.d.ts

@@ -0,0 +1,28 @@
+import * as React from 'react';
+export interface MrlErrorPageProps extends React.ComponentProps<'div'> {
+    /**
+     * A string value used for data-qa attribute.
+     */
+    ['data-qa']?: string;
+    /**
+     * Children to be rendered within the main tag of the error page
+     */
+    children?: React.ReactNode;
+    /**
+     * Title of the error page
+     */
+    title: string;
+    /**
+     * Add custom components to the error page header
+     */
+    headerUtils?: React.ReactNode;
+}
+/**
+ * MrlErrorPage component
+ *
+ * @param props - MrlErrorPage component props
+ * @param props.children - Children to be rendered within the main tag of the error page
+ * @param props.title - Title of the error page
+ * @returns  MrlErrorPage component
+ */
+export declare const MrlErrorPage: (props: MrlErrorPageProps) => JSX.Element;

package/dist/types/components/layout/error-page/MrlErrorPage/index.d.ts

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

package/dist/types/components/layout/error-page/index.d.ts

@@ -0,0 +1,2 @@
+export * from './MrlErrorPage';
+export * from './MrlBrandColors';

package/dist/types/components/layout/index.d.ts

@@ -0,0 +1,5 @@
+export * from './MrlMain';
+export * from './MrlPage';
+export * from './MrlTopbar';
+export * from './MrlSidebar';
+export * from './error-page';

package/dist/types/components/layout/utils.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Returns true/false depending on if we are in a mobile view
+ *
+ * @param {string} breakpoint - The breakpoint value
+ * @returns {boolean} Returns `true` if the breakpoint corresponds to a mobile size ('xs', 'sm', or 'md')
+ */
+export declare const isMobile: (breakpoint: string) => boolean;
+/**
+ * Returns true/false if the topbar is present within the given element
+ *
+ * @param element - The element to search for the topbar
+ * @param selector - The selector to search for the topbar
+ * @returns true/false if the topbar is present within the element
+ */
+export declare const hasElement: (element: HTMLElement | null, selector: string) => boolean;

package/dist/types/components/link/MrlLink/MrlLink.d.ts

@@ -0,0 +1,49 @@
+import * as React from 'react';
+import { LinkColor, LinkKind, LinkSize, LinkTargetType } from '../constants';
+import { AttrsObject } from '../../../utils';
+export interface MrlLinkProptypes extends React.ComponentProps<'a'> {
+    /** The textual label describing the link's purpose */
+    text: string;
+    /** Specifies where to redirect the linked document */
+    href: string;
+    /** Specifies how to open the linked document */
+    target?: LinkTargetType;
+    /**
+     * Color scheme to use based on the link's container background
+     * - bold (default): a thicker underline to help a link stand out in a large amount of body copy
+     * - simple: a thinner underline to help address visual hierarchy issues when many links are in a list
+     */
+    kind?: LinkKind;
+    /**
+     * Color scheme to use based on the link's container background
+     * - default: most use cases
+     * - mono: use on colored/saturated backgrounds (e.g. warning notifications)
+     * - inverse: use on dark backgrounds
+     */
+    color?: LinkColor;
+    /**
+     * Allows developers to chose a specific font-size for the link. By default,
+     * it will inherit the font-size of its parent/surrounding text.
+     */
+    size?: LinkSize;
+    /**
+     * Applies additional HTML attributes to the nested anchor (`a`) element.
+     * Example: `attrs='{ "aria-label": "Special message for screen reader users" }'`
+     */
+    attrs?: AttrsObject;
+    /**
+     * classes to apply to the component
+     */
+    className?: string;
+    /**
+     * Custom on click listener
+     */
+    onClick?: (e: React.MouseEvent<HTMLElement>) => void | undefined;
+}
+/**
+ * Renders a link component
+ *
+ * @param {MrlLinkProptypes} props the props for your MrlLink
+ * @returns {React.ReactElement} an a element containing the text you pass
+ */
+export declare const MrlLink: ({ target, className, color, kind, size, href, attrs, onClick, text, ...remainingProps }: MrlLinkProptypes) => React.ReactElement;

package/dist/types/components/link/MrlLink/index.d.ts

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

package/dist/types/components/link/MrlLinkButton/MrlLinkButton.d.ts

@@ -0,0 +1,54 @@
+import * as React from 'react';
+import { MrlButtonSize, IconPosition } from '../../button/constants';
+import { LinkTargetType, MrlLinkButtonKind } from '../constants';
+import { TooltipConfig } from '../../';
+import { MrlComponentProps } from '../../../utils';
+import './MrlLinkButton.global.scss';
+export interface MrlLinkButtonProps extends Omit<MrlComponentProps, 'style'>, React.ComponentProps<'a'> {
+    /** Specifies where to redirect the linked document */
+    href: string;
+    /** Specifies how to open the linked document */
+    target?: LinkTargetType;
+    /**
+     * Allow developers to add icon to buttons.
+     */
+    icon?: React.ReactElement;
+    /**
+     * Allows developers to right-align an icon within a button.
+     */
+    iconPos?: IconPosition;
+    /**
+     * Changes the visual emphasis of the button.
+     */
+    kind?: MrlLinkButtonKind;
+    /**
+     * Displays a spinner in the button to indicate some action is in progress.
+     */
+    loading?: boolean;
+    /**
+     * Text for the spinner when the button is in a loading state.
+     */
+    loadingText?: string;
+    /**
+     * onClick event for the button.
+     */
+    onClick?: (e: React.SyntheticEvent<HTMLAnchorElement>) => void;
+    /**
+     * Changes the size of the button so it can scale with its surrounding context.
+     */
+    size?: MrlButtonSize;
+    /**
+     * The textual label describing the button's purpose/action.
+     * Icon buttons require a text label to ensure accessibility.
+     */
+    text: string;
+    /**
+     * Tooltip configuration for the button
+     */
+    tooltip?: TooltipConfig;
+}
+/**
+ * Warning: use this component with care. Our links generally do not look like buttons.
+ * If this interaction does not navigate the user - use `MrlButton`.
+ */
+export declare const MrlLinkButton: React.ForwardRefExoticComponent<Omit<MrlLinkButtonProps, "ref"> & React.RefAttributes<HTMLAnchorElement>>;

package/dist/types/components/link/MrlLinkButton/index.d.ts

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

package/dist/types/components/link/constants.d.ts

@@ -0,0 +1,24 @@
+export declare const allowedValues: {
+    colors: readonly ["default", "mono", "inverse"];
+    kind: readonly ["bold", "simple"];
+    linkButtonKind: readonly ["secondary", "primary", "inverse"];
+    sizes: readonly ["default", "large", "medium", "small", "xsmall"];
+    targets: readonly ["_blank", "_parent", "_top", "_self"];
+};
+export type LinkColor = (typeof allowedValues.colors)[number];
+export type LinkKind = (typeof allowedValues.kind)[number];
+export type LinkSize = (typeof allowedValues.sizes)[number];
+export type LinkTargetType = (typeof allowedValues.targets)[number];
+export type MrlLinkButtonKind = (typeof allowedValues.linkButtonKind)[number];
+export interface LinkDefaults {
+    color: LinkColor;
+    kind: LinkKind;
+    linkButtonKind: MrlLinkButtonKind;
+    size: LinkSize;
+    target: LinkTargetType;
+}
+/**
+ * Default values for props on the Link component;
+ * Shared between the component and Storybook
+ */
+export declare const defaults: LinkDefaults;

package/dist/types/components/link/index.d.ts

@@ -0,0 +1,2 @@
+export * from './MrlLink';
+export * from './MrlLinkButton';

package/dist/types/components/live-region/MrlLiveRegion/MrlLiveRegion.d.ts

@@ -0,0 +1,19 @@
+import * as React from 'react';
+type AriaRelevant = 'additions' | 'all' | 'removals' | 'text' | 'additions text' | undefined;
+export interface MrlLiveRegionProps extends React.HTMLAttributes<HTMLParagraphElement> {
+    ariaAtomic?: boolean;
+    ariaLive: 'polite' | 'assertive' | 'off';
+    ariaRelevant?: AriaRelevant;
+    id?: string;
+    shouldClearContent?: boolean;
+    srContent: string;
+    visible?: boolean;
+}
+/**
+ * Live region component to render an HTML live region with the provided content.
+ *
+ * @param props - The live region component props.
+ * @returns The live region component.
+ */
+export declare const MrlLiveRegion: ({ ariaAtomic, ariaLive, ariaRelevant, id, srContent, visible, shouldClearContent, ...props }: MrlLiveRegionProps) => React.ReactElement;
+export {};

package/dist/types/components/live-region/MrlLiveRegion/index.d.ts

@@ -0,0 +1 @@
+export { MrlLiveRegion } from './MrlLiveRegion';

package/dist/types/components/live-region/demo/LiveRegionDemo.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="react" />
+/**
+ * Demo of a live region
+ *
+ * @returns {Element} The Live Region Demo
+ */
+export declare const LiveRegionDemo: () => JSX.Element;

package/dist/types/components/live-region/index.d.ts

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

package/dist/types/components/loader/MrlProgressBar/MrlProgressBar.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="react" />
+import { ProgressBarComponent } from '../constants';
+import '../../../styles/shared/a11y-helpers/a11y.global.scss';
+/**
+ * MrlProgressBar React component.
+ *
+ * @param props - component props
+ * @returns a MrlProgressBar React component.
+ */
+export declare function MrlProgressBar({ children, className, indeterminate, name, percent, showText, text, time, ...rest }: ProgressBarComponent): JSX.Element;

package/dist/types/components/loader/MrlProgressBar/index.d.ts

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

package/dist/types/components/loader/MrlSpinner/MrlSpinner.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="react" />
+import { SpinnerComponent } from '../constants';
+import '../../../styles/shared/a11y-helpers/a11y.global.scss';
+/**
+ * MrlSpinner React component.
+ *
+ * @param props - component props
+ * @returns a MrlSpinner React component.
+ */
+export declare function MrlSpinner({ className, logo, kind, role, size, text, ...rest }: SpinnerComponent): JSX.Element;

package/dist/types/components/loader/MrlSpinner/index.d.ts

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

package/dist/types/components/loader/constants.d.ts

@@ -0,0 +1,88 @@
+/// <reference types="react" />
+type CreateArrayWithLengthX<LENGTH extends number, ACC extends unknown[] = []> = ACC['length'] extends LENGTH ? ACC : CreateArrayWithLengthX<LENGTH, [...ACC, 1]>;
+type NumericRange<START_ARR extends number[], END extends number, ACC extends number = never> = START_ARR['length'] extends END ? ACC | END : NumericRange<[...START_ARR, 1], END, ACC | START_ARR['length']>;
+export type ProgressRange = NumericRange<CreateArrayWithLengthX<0>, 100>;
+/**
+ * Default values for props on the MrlProgressBar component;
+ * Shared between the component and Storybook
+ */
+export declare const progressBarDefaults: ProgressBarComponent;
+export interface ProgressBarComponent {
+    /**
+     * Custom content that lives below the progress bar.
+     *
+     * Note: This should be limited to descriptive text regarding
+     * what is in progress.
+     */
+    children?: React.ReactNode;
+    /**
+     * Custom class to be applied to the component.
+     */
+    className?: string;
+    /**
+     * Display an infinite loading indicator until completion
+     *
+     * Note: do not use with `time`.
+     */
+    indeterminate?: boolean;
+    /**
+     * Name of the progress bar (applied via aria-label)
+     */
+    name: string;
+    /**
+     * The percent complete.
+     *
+     * Note: This should be a whole number between 0 and 100.
+     */
+    percent?: ProgressRange;
+    /**
+     * Display the percent complete text
+     */
+    showText?: boolean;
+    /**
+     * Custom text to use under the progress bar.
+     */
+    text?: string;
+    /**
+     * The length of time to reach 100% in milliseconds.
+     *
+     * Note: do not use with `indeterminate`.
+     */
+    time?: number;
+}
+export type SpinnerSize = 'large' | 'medium' | 'small' | 'xsmall';
+export type SpinnerStyle = 'default' | 'inverse';
+/**
+ * Default values for props on the MrlSpinner component;
+ * Shared between the component and Storybook
+ */
+export declare const spinnerDefaults: SpinnerComponent;
+export interface SpinnerComponent {
+    /**
+     * Custom class to be applied to the component.
+     */
+    className?: string;
+    /**
+     * Display the Mural logo under the spinner.
+     */
+    logo?: boolean;
+    /**
+     * Style of the spinner.
+     */
+    kind?: SpinnerStyle;
+    /**
+     * The role of the spinner.
+     *
+     * Note: Use with care. This prop has accessibility implications.
+     */
+    role?: string;
+    /**
+     * Size of the spinner.
+     */
+    size?: SpinnerSize;
+    /**
+     * Hidden text label while loading
+     */
+    text?: string;
+}
+export {};

package/dist/types/components/loader/index.d.ts

@@ -0,0 +1,3 @@
+export * from './MrlProgressBar';
+export * from './MrlSpinner';
+export * from './constants';

package/dist/types/components/menu/MrlMenu/MrlMenu.d.ts

@@ -0,0 +1,119 @@
+import * as React from 'react';
+import { PortalProps } from '../../../components';
+import { MenuPosition, MenuAlignment, ActionState, CustomMenuPosition } from '../constants';
+export interface MrlMenuProps {
+    /** Custom position for the menu */
+    customPosition?: CustomMenuPosition;
+    /** Children to be rendered within the menu component*/
+    children: React.ReactNode;
+    /** Event to close the menu */
+    clickOutsideEvent?: 'mousedown' | 'mouseup' | 'click';
+    /**
+     * Enables closing the menu when scrolling. Default is false.
+     *
+     */
+    closeOnScroll?: boolean;
+    /**
+     * Private closeParent prop for use with MrlMenuItem
+     *
+     * !!! Please do not use this prop directly, it is only used internally by MrlMenuItem !!!
+     * @private
+     */
+    closeParent?: () => void;
+    /**
+     * Disable arrows from opening the menu
+     * - This is useful when you want to disable the default browser behavior of opening a menu on arrow down.
+     *
+     * Example usage: the menu is within a vertical toolbar and you want to use the arrow keys to navigate the toolbar.
+     * By using this prop you can disable the arrow key open/close so that navigating the toolbar does not conflict
+     *  with opening/closing the menu.
+     */
+    disableArrowOpen?: boolean;
+    /**
+     * Disable flipping of the menu when it goes off the screen
+     * @default false
+     */
+    disableFlipping?: boolean;
+    /** Unique identifier for the menu */
+    id?: string;
+    /**
+     * Use when the menu is embedded within another component
+     * Removes the following styles:
+     * - padding on the menu
+     * - drop shadow and border
+     * @default false
+     */
+    isInternal?: boolean;
+    /**
+     * Private isSubMenu prop for use with MrlMenuItem
+     *
+     * !!! Please do not use this prop directly, it is only used internally by MrlMenuItem !!!
+     * @private
+     */
+    isSubMenu?: boolean;
+    /**
+     * spacing of menu
+     * - compact has less padding
+     * @default 'default'
+     */
+    spacing?: 'default' | 'compact';
+    /**
+     * Offset of the menu from the trigger element in pixels
+     * @default 10px
+     */
+    menuOffset?: number;
+    /**
+     * Configuration for the portal component
+     */
+    portalProps?: Omit<PortalProps, 'children'>;
+    /**
+     * Horizontal and vertical alignment of the menu relative to the trigger element
+     * - position 'left', 'right', 'top', 'bottom' position relative to the trigger
+     * - position 'static' renders the menu in place, not using the portal
+     * - position 'ignore' will not position the menu, allowing you to use the customPosition prop to position the element
+     * @default 'bottom'
+     */
+    position?: MenuPosition;
+    /**
+     * Set initial state of menu
+     * @default { actionType: null, isOpen: false }
+     */
+    actionState?: ActionState;
+    /**
+     * Reference to the DOM element that triggers this menu.
+     */
+    triggerRef?: React.RefObject<HTMLButtonElement>;
+    /**
+     * Trigger stop propagation on click
+     *
+     * In some instances we may want the trigger element to stop propogation to the
+     * rest of the DOM. Use this flag to enable and disable it.
+     * @default false
+     */
+    triggerStopPropagation?: boolean;
+    /**
+     * Vertical and horizontal alignment of the menu relative to the position of the menu with the trigger
+     * - 'left' and 'right' work with position 'top' and 'bottom'
+     * - 'top' and 'bottom' work with position 'left' and 'right'
+     * - 'center' works with all positions
+     *
+     * This does not impact submenus
+     */
+    alignment?: MenuAlignment;
+    /**
+     * Callback to be called when the menu is closed
+     * @param type - type of close event
+     */
+    onClose?: (type?: string) => void;
+}
+/**
+ * MrlMenu component
+ *
+ * Renders a menu component with alignment relative to a trigger element
+ * @param {MrlMenuProps} props - The props for the MrlMenu component
+ * @returns {Element} - rendered MrlMenu component
+ */
+export declare function MrlMenu({ actionState, alignment, children, closeOnScroll, closeParent, customPosition, clickOutsideEvent, disableArrowOpen, disableFlipping, id, isInternal, isSubMenu, spacing, menuOffset, portalProps, position, triggerStopPropagation, onClose, triggerRef, ...remainingProps }: MrlMenuProps): JSX.Element;
+export declare namespace MrlMenu {
+    var componentType: string;
+}

package/dist/types/components/menu/MrlMenu/index.d.ts

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

package/dist/types/components/menu/MrlMenu/utilities.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Find the closest menu parent of an element
+ *
+ * @param el - The element to start searching from
+ * @returns The closest menu parent or null if none is found
+ */
+export declare const findClosestMenuParent: (el: HTMLElement | null) => HTMLElement | null | undefined;
+/**
+ * Calculate the horizontal positioning of the submenu
+ *
+ * @param overlapsRight - Whether the menu overlaps the right side of the screen
+ * @param overlapsLeft - Whether the menu overlaps the left side of the screen
+ * @param menuRect - The bounding rectangle of the menu
+ * @param triggerRef - The ref of the trigger element
+ * @returns The left position of the menu
+ */
+export declare const calculateLeftPosition: (overlapsRight: boolean, overlapsLeft: boolean, menuRect: DOMRect, triggerRef: React.RefObject<HTMLElement>) => string;
+/**
+ * Calculate vertical positioning of the submenu
+ *
+ * @param overlapsRight - Whether the menu overlaps the right side of the screen
+ * @param overlapsLeft - Whether the menu overlaps the left side of the screen
+ * @param triggerRef - The ref of the trigger element
+ * @param menuRect - The bounding rectangle of the menu
+ * @param parentMenu - The parent menu element
+ * @param triggerRect - The bounding rectangle of the trigger element
+ * @returns The top position of the menu
+ */
+export declare const calculateTopPosition: (overlapsRight: boolean, overlapsLeft: boolean, triggerRef: React.RefObject<HTMLElement>, menuRect: DOMRect, parentMenu: HTMLElement, triggerRect: DOMRect) => string;

package/dist/types/components/menu/MrlMenuGroup/MrlMenuGroup.d.ts

@@ -0,0 +1,12 @@
+import * as React from 'react';
+export interface MrlMenuGroupPropTypes {
+    children: React.ReactNode;
+    divider?: boolean;
+    groupLabel?: string;
+}
+/**
+ * MrlMenuGroup
+ * @param props - component properties
+ * @returns JSX.Element
+ */
+export declare const MrlMenuGroup: ({ children, divider, groupLabel, ...rest }: MrlMenuGroupPropTypes) => JSX.Element;

package/dist/types/components/menu/MrlMenuGroup/index.d.ts

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

package/dist/types/components/menu/MrlMenuItem/MrlMenuItem.d.ts

@@ -0,0 +1,50 @@
+import * as React from 'react';
+import { DSIconType } from '../../../';
+import { AriaHasPopup, MenuItemRole } from '../constants';
+export interface MrlMenuItemProps {
+    /** ID for associated description */
+    ariaDescribedBy?: string;
+    /** Indicates whether the menu item has a popup menu using aria-haspopup attribute */
+    ariaHasPopup?: AriaHasPopup;
+    /**
+      Children to be rendered within the menu component
+     */
+    children: React.ReactNode | string;
+    /** Classname for the menu item */
+    className?: string;
+    /** If the menu item is disabled */
+    disabled?: boolean;
+    /** Icon for menu item */
+    icon?: DSIconType;
+    /** Unique ID for the menu item */
+    id?: string;
+    /** Callback to be called when the menu item is clicked */
+    onClick?: (e?: React.MouseEvent<HTMLButtonElement>) => void;
+    /** Callback to be called when the menu item is hovered */
+    onMouseOver?: (e?: React.MouseEvent) => void;
+    /** Callback to be called when the menu item is hovered out */
+    onMouseOut?: (e?: React.MouseEvent) => void;
+    /** Data-qa attribute for the menu item */
+    dataQa?: string;
+    /**
+     * Role for the menu item
+     *
+     * When using `menuitemcheckbox` or `menuitemradio`, the menu item will be treated as a selectable item,
+     * aria-checked will be set to 'true' or 'false' based on the selected state.
+     *
+     * @default 'menuitem' - for regular menu items
+     * @example 'menuitemcheckbox' - for checkbox menu items
+     * @example 'menuitemradio' - for radio menu items
+     */
+    role?: MenuItemRole;
+    /** If the menu item is selected */
+    selected?: boolean;
+}
+/**
+ * MrlMenuItem component
+ *
+ * Renders a menu item to be used within the MrlMenu component
+ * @param {MrlMenuItemProps} props - The props for the MrlMenuItem component
+ * @returns {Element} - rendered MrlMenuItem component
+ */
+export declare function MrlMenuItem({ ariaDescribedBy, ariaHasPopup, children, className, dataQa, disabled, icon, id, onClick, onMouseOut, onMouseOver, role, selected, ...rest }: MrlMenuItemProps): JSX.Element;

package/dist/types/components/menu/MrlMenuItem/index.d.ts

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

package/dist/types/components/menu/MrlMenuItemLink/MrlMenuItemLink.d.ts

@@ -0,0 +1,38 @@
+import * as React from 'react';
+import { DSIconType } from '../../../';
+export interface MrlMenuItemLinkProps {
+    /** ID for associated description */
+    ariaDescribedBy?: string;
+    /**
+      Children to be rendered within the menu component
+     */
+    children: React.ReactNode | string;
+    /** Class names for the menu item */
+    className?: string;
+    /** If the menu item is disabled */
+    disabled?: boolean;
+    /** Href for the menu item */
+    href: string;
+    /** Icon for menu item */
+    icon?: DSIconType;
+    /** Target for links */
+    target?: string;
+    /** Unique ID for the menu item */
+    id?: string;
+    /** Callback to be called when the menu item is clicked */
+    onClick?: (e: React.MouseEvent<HTMLElement>) => void;
+    /** Data-qa attribute for the menu item */
+    dataQa?: string;
+    /** If the menu item is selected */
+    selected?: boolean;
+    /** Rel attr for the menu item */
+    rel?: string;
+}
+/**
+ * MrlMenuItem component
+ *
+ * Renders a menu item to be used within the MrlMenu component
+ * @param {MrlMenuItemLinkProps} props - The props for the MrlMenuItem component
+ * @returns {Element} - rendered MrlMenuItem component
+ */
+export declare function MrlMenuItemLink({ ariaDescribedBy, children, className, dataQa, disabled, href, icon, id, onClick, selected, target, ...rest }: MrlMenuItemLinkProps): JSX.Element;

package/dist/types/components/menu/MrlMenuItemLink/index.d.ts

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