@muraldevkit/ui-toolkit 1.10.1 → 1.12.0

package/dist/components/form/MrlSelect/SelectContext.d.ts

@@ -0,0 +1,47 @@
+import * as React from 'react';
+type Action = {
+    type: 'open';
+} | {
+    type: 'close';
+} | {
+    type: 'focus';
+    payload: number;
+} | {
+    type: 'default';
+} | {
+    type: 'disabled';
+} | {
+    type: 'select';
+    payload: string;
+};
+type Dispatch = (action: Action) => void;
+type State = {
+    open: boolean;
+    focus: boolean;
+    disabled: boolean;
+    focusIndex?: number;
+    selectedId?: string;
+    id?: string;
+};
+type SelectProviderProps = {
+    children: React.ReactNode;
+    hookChange?: (newValue?: string) => void | undefined;
+    id?: string;
+};
+/**
+ * Select provider
+ *
+ * @param {SelectProviderProps} props SelectProvider props
+ * @returns {React.ReactElement} returns a booted select provider.
+ */
+declare function SelectProvider({ children, hookChange, id }: SelectProviderProps): React.ReactElement;
+/**
+ * useSelect hook
+ *
+ * @returns returns hook for the select provider.
+ */
+declare function useSelect(): {
+    state: State;
+    dispatch: Dispatch;
+};
+export { SelectProvider, useSelect };

package/dist/components/form/MrlSelect/index.d.ts

@@ -0,0 +1,9 @@
+import * as React from 'react';
+import { MrlSelectProptypes } from './select';
+/**
+ * Creates and exports component class for Mural Select
+ *
+ * @param {MrlSelectProptypes} props MrlSelectProptypes
+ * @returns {React.ReactElement} returns a MrlSelect wrapped in a select provider.
+ */
+export declare const MrlSelect: ({ hookChange, id, children, ...rest }: MrlSelectProptypes) => React.ReactElement;

package/dist/components/form/MrlSelect/select.d.ts

@@ -0,0 +1,50 @@
+import * as React from 'react';
+import { SelectStates, InputKinds, InputSizes } from '../constants';
+import { AttrsObject } from '../../../utils';
+export interface MrlSelectProptypes extends React.HTMLAttributes<HTMLDivElement> {
+    /** Additional function to be run when the value of the select changes */
+    hookChange?: (newValue?: string) => void | undefined;
+    /** State of the select element based on user actions or permissions */
+    state?: SelectStates;
+    /** Current value of the select input */
+    value?: string;
+    /**
+     * Because this is a custom element, we can't use a standard "for" attribute setup. The label
+     * element needs to have an id and then we reference via the select with aria
+     */
+    labelId: string;
+    /**
+     * Changes the visual style of the select trigger; Use 'inline when your select is inline
+     * with other content
+     */
+    kind?: InputKinds;
+    /**
+     * Changes the visual size of the select trigger; Currently only supported when kind="inline"
+     */
+    size?: InputSizes;
+    /**
+     * Applies additional HTML attributes to the `mrl-select` element after the
+     * hydration process. It is recommended only to use when overwriting an attribute
+     * assigned internally by the design system.
+     * When using in a framework wrapper (e.g., React), treat it as an object and don't stringify.
+     * Otherwise, the value object needs to be stringified to not receive `"[Object object]"`.
+     * Example: `attrs='{ "tabindex": "1" }'`
+     */
+    attrs?: AttrsObject | string;
+    /**
+     * menu - list of options for the user to chose from; expects an `MrlSelectMenu` component
+     */
+    children?: React.ReactNode;
+    /**
+     * optional id - we will generate a unique one if it isn't given.
+     * ID will be decorated with `${id}-mrl-select` to not conflict with aria controls.
+     */
+    id?: string;
+}
+/**
+ * Creates and exports component class for Mural Select
+ *
+ * @param {MrlSelectProptypes} props the props for your MrlLink
+ * @returns {React.ReactElement} an a element containing the text you pass
+ */
+export declare const MrlSelect: ({ attrs, children, kind, labelId, size, state, value, id, ...theRest }: MrlSelectProptypes) => React.ReactElement;

package/dist/components/form/MrlSelectItem/index.d.ts

@@ -0,0 +1,32 @@
+import * as React from 'react';
+import { AttrsObject } from '../../../utils';
+export interface MrlSelectItemProptypes extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * value of the select item that is stored as the selected value of the select input
+     */
+    value: string;
+    /**
+     * index of the select item starting at 0
+     */
+    index: number;
+    /**
+     * Applies additional HTML attributes to the `mrl-select-item` element after the
+     * hydration process. It is recommended only to use when overwriting an attribute
+     * assigned internally by the design system.
+     * When using in a framework wrapper (e.g., React), treat it as an object and don't stringify.
+     * Otherwise, the value object needs to be stringified to not receive `"[Object object]"`.
+     * Example: `attrs='{ "aria-disabled": "true" }'`
+     */
+    attrs?: AttrsObject;
+    /**
+     * content for the item
+     */
+    children: React.ReactNode;
+}
+/**
+ * Renders a select component
+ *
+ * @param {MrlSelectItemProptypes} props the props for your MrlLink
+ * @returns {React.ReactElement} an a element containing the text you pass
+ */
+export declare const MrlSelectItem: ({ attrs, children, index, value, ...theRest }: MrlSelectItemProptypes) => React.ReactElement;

package/dist/components/form/MrlSelectMenu/index.d.ts

@@ -0,0 +1,47 @@
+import * as React from 'react';
+import { SelectMenuPositions } from '../constants';
+import { AttrsObject } from '../../../utils';
+export interface MrlSelectMenuProptypes extends React.HTMLAttributes<HTMLDivElement> {
+    /** The placement of the menu in relation to its trigger */
+    position?: SelectMenuPositions;
+    /** Current value of the select input */
+    value?: string;
+    /**
+     * Allows the select component to pass through which item should be focused;
+     * Set it to the index of the focused item
+     */
+    focused?: number;
+    /**
+     * Allows the select component to pass through which item should be selected
+     * Set it to the id of the selected item
+     */
+    selected?: string;
+    /**
+     * Applies additional HTML attributes to the `mrl-select-menu` elements
+     * It is recommended only to use when overwriting an attribute
+     * assigned internally by the design system.
+     * When using in a framework wrapper (e.g., React), treat it as an object and don't stringify.
+     * Otherwise, the value object needs to be stringified to not receive `"[Object object]"`.
+     * Example: `attrs='{ "tabindex": "0" }'`
+     */
+    attrs?: AttrsObject | string;
+    /**
+     * menu - list of options for the user to chose from; expects an `MrlSelectMenu` component
+     */
+    children?: React.ReactNode;
+    /**
+     * label element needs to have an id and then we reference via the select with aria
+     */
+    labelId: string;
+}
+/**
+ * Creating and exporting component class for Mural Select Menu
+ * Note, this component doesn't doesn't handle any functionality
+ * For accessibility and keyboard support, all functionality is
+ * controlled by the wrapping mrl-select but we need this component
+ * within our HTML structure for valid aria usage.
+ *
+ * @param {MrlSelectMenuProptypes} props MrlSelectMenuProptypes
+ * @returns {React.ReactElement} returns a MrlSelectMenu
+ */
+export declare const MrlSelectMenu: ({ attrs, children, selected, labelId, position, ...theRest }: MrlSelectMenuProptypes) => React.ReactElement;

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

@@ -0,0 +1,77 @@
+export type InputStates = 'disabled' | 'error';
+export type InputKinds = 'default' | 'inline';
+export type InputSizes = 'default' | 'large';
+export declare const allowedCheckboxValues: {
+    selected: readonly ["default", "checked", "indeterminate"];
+    states: readonly ["default", "disabled", "error"];
+};
+export type CheckboxStates = (typeof allowedCheckboxValues.states)[number];
+export type CheckboxSelected = (typeof allowedCheckboxValues.selected)[number];
+interface CheckboxDefaults {
+    selected: CheckboxSelected;
+    state: CheckboxStates;
+}
+export declare const checkboxDefaults: CheckboxDefaults;
+export declare const allowedSelectItemValues: {
+    states: readonly ["default", "disabled", "selected"];
+};
+export type SelectItemStates = (typeof allowedSelectItemValues.states)[number];
+interface SelectItemDefaults {
+    state: SelectItemStates;
+}
+export declare const selectItemDefaults: SelectItemDefaults;
+export declare const allowedSelectMenuValues: {
+    positions: readonly ["bottom", "top"];
+};
+export type SelectMenuPositions = (typeof allowedSelectMenuValues.positions)[number];
+interface SelectMenuDefaults {
+    position: SelectMenuPositions;
+}
+export declare const selectMenuDefaults: SelectMenuDefaults;
+export declare const allowedSelectValues: {
+    states: readonly ["default", "disabled", "open"];
+};
+export type SelectStates = (typeof allowedSelectValues.states)[number];
+interface SelectDefaults {
+    size: InputSizes;
+    kind: InputKinds;
+    state: SelectStates;
+}
+export declare const selectDefaults: SelectDefaults;
+export interface StaticIconConfig {
+    icon: Record<string, unknown>;
+    theme?: string;
+}
+export interface RightActionConfig extends StaticIconConfig {
+    action: (event: MouseEvent) => void;
+    label: string;
+}
+export declare const allowedLabelValues: {
+    kinds: readonly ["block", "inline"];
+    states: readonly ["default", "disabled"];
+};
+export type LabelStates = (typeof allowedLabelValues.states)[number];
+export type LabelKind = (typeof allowedLabelValues.kinds)[number];
+interface LabelDefaults {
+    kind: LabelKind;
+    state: LabelStates;
+}
+export declare const labelDefaults: LabelDefaults;
+export interface FormControlDefaults {
+    disabled: boolean;
+    label: string;
+}
+export interface FieldsetDefault {
+    label: string;
+}
+/**
+ * Default values for props on the Fieldset component;
+ * Shared between the component and Storybook
+ */
+export declare const fieldsetDefault: FieldsetDefault;
+/**
+ * Default values for props on the Fieldset component which is used to group Textarea components;
+ * Shared between the component and Storybook
+ */
+export declare const textareaDefaults: FormControlDefaults;
+export {};

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

@@ -0,0 +1,3 @@
+export * from './MrlSelect';
+export * from './MrlSelectItem';
+export * from './MrlSelectMenu';

package/dist/components/form/utils.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Defines all of the possible actions a user can take with their keyboard in a select.
+ * This is used to create a more human-friendly connection between the actions and
+ * keyboard short cuts since multiple keys may perform the same action.
+ * See getActionFromKey for more details.
+ *
+ * @todo - need to verify what the pageDown/Up keys do differently. They have a
+ * 		different action in the getUpdatedIndex function but need to understand
+ * 		a bit more.  This is not merge blocking for MVP
+ */
+export declare const actions: {
+    Close: number;
+    CloseSelect: number;
+    First: number;
+    Last: number;
+    Next: number;
+    Open: number;
+    PageDown: number;
+    PageUp: number;
+    Previous: number;
+    Type: number;
+};
+/**
+ * Map a key press to an action (see the )
+ *
+ * @param {React.KeyboardEvent} event - keyboard event
+ * @param {boolean} isMenuOpen - dropdown menu state
+ * @param {string | undefined} search - current searchstring to determine how to handle space presses
+ * @returns {number | undefined} - returns action number or quits from function execution
+ */
+export declare const getActionFromKey: (event: React.KeyboardEvent, isMenuOpen: boolean, search?: string | undefined) => number | undefined;
+/**
+ * Get an updated item index based on the action
+ *
+ * @param {number} currentIndex - index of the active menu item
+ * @param {number} maxIndex - last menu item's index
+ * @param {action} action - keyboard key action
+ * @returns {number} - returns updated index
+ */
+export declare const getUpdatedIndex: (currentIndex: number, maxIndex: number | undefined, action: number) => number;
+/**
+ * Checks if the select menu items has scrollable overflow
+ *
+ * @param {HTMLElement} menu - select menu component
+ * @returns {boolean} - true if the menu has overflow content
+ */
+export declare const isScrollable: (menu: HTMLElement) => boolean;
+/**
+ * Ensures a given child element is within the parents's visible scroll area.
+ * If the child is not visible, it scrolls the parent element.
+ *
+ * @param {HTMLElement} childEl - clicked/focused select item
+ * @param {HTMLElement} scrollParent - select menu component
+ * @todo - POST MVP - this could be a more reusable util function for other components
+ * @todo - POST MVP - the marginY should be more dynamic
+ */
+export declare const maintainScrollVisibility: (childEl: HTMLElement, scrollParent: HTMLElement) => void;
+/**
+ * Returns the index of an option from an array of options, based on a search string
+ * if the filter is multiple iterations of the same letter (e.g "aaa"), then cycle through first-letter matches
+ *
+ * @param {Element[]} options - menu items list
+ * @param {string} filter - pressed letters combination
+ * @param {number} startIndex - start index
+ * @returns {number} - menu item's index
+ */
+export declare const getIndexByLetter: (options: Element[], filter: string, startIndex?: number) => number;
+type DebounceType = number | null | undefined;
+type CallbackType = (_debounce: number) => void;
+/**
+ * Waits a predetermined time before calling a function
+ *
+ * @param {Function} func - function to call after timeout
+ * @param {number} timeout - time to wait before calling function
+ * @param {number} debounce - existing debounce to clear
+ * @param {Function} callback - callback function to update debounce
+ * @returns {Function} - function to reset debounce and call callback
+ * @todo - 4969 investigate combining this debounce function with the modal debounce function
+ */
+export declare const debounce: (func: () => void, timeout: number | undefined, debounce: DebounceType, callback: CallbackType) => (() => void);
+export {};

package/dist/components/index.d.ts

@@ -2,4 +2,6 @@ export * from './button';
 export * from './svg';
 export * from './tooltip';
 export * from './link';
+export * from './form';
 export * from './modal';
+export * from './text';

package/dist/components/text/MrlText/MrlText.d.ts

@@ -0,0 +1,38 @@
+import React from 'react';
+import { AttrsObject } from '../../../utils';
+import { TextHierarchies, TextKinds, TextSizes } from '../constants';
+interface CommonProps {
+    /** Applies additional HTML attributes to the text element */
+    attrs?: AttrsObject;
+    /** Children to be rendered within the text component */
+    children?: React.ReactNode | string;
+    /** Hierarchy level within the use case and sizing scales */
+    hierarchy?: TextHierarchies;
+    /** Textual content when it's a static string; if you have nested elements, use children to provide content */
+    text?: string;
+}
+interface DefaultKindWithSize extends CommonProps {
+    /**
+     * Visual kind of the text
+     * If the value is default it allows to change the "size" prop
+     */
+    kind: 'default';
+    /** Visual size of the text, only applies if kind="default" */
+    size: TextSizes;
+}
+interface KindWithoutSize extends CommonProps {
+    /**
+     * Visual kind of the text
+     * If the value is default it allows to change the "size" prop
+     */
+    kind: Exclude<TextKinds, 'default'>;
+}
+type MrlTextProps = DefaultKindWithSize | KindWithoutSize;
+/**
+ * MrlText Component
+ *
+ * @param {MrlTextProps} props - MrlText component props
+ * @returns a paragraph element
+ */
+export declare function MrlText(props: MrlTextProps): JSX.Element;
+export {};

package/dist/components/text/MrlText/index.d.ts

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

package/dist/components/text/MrlTextHeading/MrlTextHeading.d.ts

@@ -0,0 +1,31 @@
+import React from 'react';
+import { AttrsObject } from '../../../utils';
+import { LevelType, HeadingSizes, TextSizes, TextHierarchies, HeadingKinds } from '../constants';
+interface MrlTextHeadingProps {
+    /** Applies additional HTML attributes to the text element */
+    attrs?: AttrsObject;
+    /** Children to be rendered within the text heading component */
+    children?: React.ReactNode;
+    /** Set the semantic level of the heading based on its usage in the page hierarchy */
+    level?: LevelType;
+    /** Visual styling use case for the heading */
+    kind?: HeadingKinds;
+    /**
+     * Visual size of the heading
+     * xsmall and xxsmall are only supported when kind="title"
+     */
+    size?: HeadingSizes | TextSizes;
+    /** Clear and concise description of the content that the heading describes */
+    text?: string;
+    /** Hierarchy level within the use case and sizing scales */
+    hierarchy?: TextHierarchies;
+}
+/**
+ * MuralTextHeading component
+ * Used for creating semantic headings within a page
+ *
+ * @param {MrlTextHeadingProps} props - MrlTextHeading component props
+ * @returns a heading element
+ */
+export declare function MrlTextHeading({ attrs, children, hierarchy, kind, level, size, text }: MrlTextHeadingProps): JSX.Element;
+export {};

package/dist/components/text/MrlTextHeading/index.d.ts

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

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

@@ -0,0 +1,44 @@
+import { AttrsObject } from '../../utils';
+export type TextSizes = 'xxsmall' | 'xsmall' | 'small' | 'medium' | 'large';
+export type TextHierarchies = 'primary' | 'secondary';
+export type TextKinds = 'default' | 'body' | 'meta' | 'supporting';
+export interface TextDefaults {
+    attrs: AttrsObject;
+    hierarchy: TextHierarchies;
+    size: TextSizes;
+    kind: TextKinds;
+}
+export declare const textAllowedValues: {
+    hierarchy: string[];
+    kind: string[];
+    sizes: string[];
+};
+/**
+ * Default values for props on the Text component;
+ * Shared between the component and Storybook
+ */
+export declare const textDefaults: TextDefaults;
+export type LevelType = '1' | '2' | '3' | '4' | '5' | '6';
+export type HeadingKinds = 'poster' | 'display' | 'headline' | 'title';
+export type HeadingSizes = 'small' | 'medium' | 'large';
+export interface HeadingDefaults {
+    attrs: AttrsObject;
+    hierarchy: TextHierarchies;
+    kind: HeadingKinds;
+    level: LevelType;
+    size: HeadingSizes | TextSizes;
+}
+/**
+ * Defines all of classes allowed for the type attribute;
+ * used for Storybook and testing
+ */
+export declare const headingAllowedValues: {
+    kinds: string[];
+    level: string[];
+    sizes: string[];
+};
+/**
+ * Default values for props on the Text component;
+ * Shared between the component and Storybook
+ */
+export declare const headingDefaults: HeadingDefaults;

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

@@ -0,0 +1,2 @@
+export * from './MrlText';
+export * from './MrlTextHeading';