@simoncomputing/mui-bueno-v3 0.1.12

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)<sup>1</sup>.
+
+<sup>1</sup>We'll be following the following versioning practices to make it easier for devs to determine whether or not they are ready to upgrade to a newer verison of Mui Bueno:
+
+- Major increment --> large/many changes. SEVERAL breaking changes.
+- Minor increment --> singlular/minor changes. Minimal breaking changes.
+- Patch increment --> singlular/minor changes. Zero breaking changes.
+
+## [0.1.2] - 2025-07-09
+
+### Changed
+- Update index.ts to include MForm
+
+## [0.1.1] - 2025-07-08
+
+### Changed
+- Converting existing input components for react-hook-form
+- Components:
+    - Inputs
+        - AutoComplete
+        - Switch
+
+## [0.1.0] - 2025-07-08
+
+### Changed
+- Converting existing input components for react-hook-form
+- Components:
+    - Inputs
+        - Checkbox
+        - CheckboxGroup
+        - DateField
+        - FileUPload
+        - RadioGroup
+        - RangeSlider
+        - Select
+        - Switch
+        - TextField
+        - RichTextField
+    - Error
+    - FormDebugger

package/README.md

@@ -0,0 +1,33 @@
+# MUI Bueno v3
+
+A React component library based on [Material UI](https://mui.com/material-ui) components with built-in support for [Formik](https://formik.org/). Rebuilt & redesigned based on the original [mui-bueno](https://www.npmjs.com/package/mui-bueno) library, and expanded to provide additional components beyond form components.
+
+![SimonComputing Logo](https://simoncomputing.com/staging/img/sc-logo/SC_logo_scratched_bluer_mobile.png)
+
+A product of the [SimonComputing Technology Innovations Lab](https://www.simoncomputing.com/technology-innovations-lab)
+
+## Installation
+
+```bash
+npm install mui-bueno-v3
+```
+
+## Basic Example
+
+```tsx
+<MForm>
+    <TextField label="First Name" name="first-name" />
+    <TextField name="lastName" label="Last Name" />
+    <TextField name="dob" label="Date of Birth" format="99/99/9999" placeholder="MM/DD/YYYY" />
+    <TextField name="email" label="Email" />
+    <Submit>Submit</Submit>
+</MForm>
+```
+
+## Documentation & Demo
+
+This project uses Storybook to document and demonstrate the components. _URL COMING SOON._
+
+## Release History
+
+Details for every release are documented in [CHANGELOG.md](https://www.npmjs.com/package/mui-bueno-v3?activeTab=code)

package/dist/@types/index.d.ts

@@ -0,0 +1,192 @@
+import { ButtonProps } from '@mui/material';
+export type ObjectWithId = {
+    id?: number | string;
+};
+
+// TODO remove duplicate DTOs from golden ui, otherwise they'll be defined twice
+// TODO bring over SimpleRequest & PageRequest too, for consistency?
+
+/**
+ * State for the current page for pagination. NOTE: Use `PageRequest` for API calls.
+ */
+export type PageState = {
+    /**
+     * Page number (starts at 0) for paginated results.
+     */
+    pageNo: number;
+
+    /**
+     * Page size for paginated results (number of rows).
+     */
+    pageSize: number;
+};
+
+/**
+ * Paginated API response
+ */
+export type PageResponse<T> = {
+    data: T[];
+    pageNo: number;
+    pageSize: number;
+    totalCount: number;
+};
+
+/**
+ * Filter definition for narrowing down results from the service.
+ */
+export type Filter = {
+    column: string;
+    value: any;
+    /**
+     * These are the only supported operations for now
+     * More can be added in the future, but support may need to be added on the backend
+     * (i.e. ILIKE is a POSTGRES operation, the backend converts it to LIKE when using SQLITE)
+     */
+    operation?: 'ILIKE' | '=' | 'IS DISTINCT FROM' | 'CLOSEST';
+};
+
+export type PaginationState = PageState & {
+    totalCount: number;
+    // searchTerm?: string;
+    sortField?: string;
+    sortOrder?: 'asc' | 'desc';
+};
+
+type LabelWithIcon = {
+    icon?: React.ReactElement;
+    label: string;
+};
+
+export type MenuOption = LabelWithIcon & {
+    /**
+     * The minimum permission required to access this page (most commonly will be some sort of view permission).
+     *
+     * If not defined, this nav item will always be rendered in the navigation components regardless of user permissions.
+     * If defined, this nav item will be removed the navigation components if the user is missing the permission.
+     *
+     * @default undefined
+     */
+    minPermission?: string | string[];
+
+    /**
+     * Performs the action when clicked (ex. toggle dark mode). Avoid using this to navigate (use `path` or `externalLink` instead).
+     *
+     * When `path` or `externalLink` is defined, this onClick will run right before navigating. Use this to handle any non-navigation logic that needs to happen.
+     */
+    onClick?: () => void; // TODO update this to allow for conditional navigating based on the return value (true = navigate, false = don't navigate)
+} & (
+        | {
+              /**
+               * Internal path that this navigation item should navigate to (ex '/home')
+               */
+              path: string;
+              externalLink?: never;
+          }
+        | {
+              /**
+               * External path that this navigation item should navigate to (ex 'https://www.google.com')
+               */
+              externalLink: string;
+              path?: never;
+          }
+        | {
+              path?: never;
+              externalLink?: never;
+          }
+    );
+
+export type EnvironmentInfo = {
+    env?: string; // ex 'Development'
+    isProd?: boolean;
+};
+
+/**
+ * TableColumn represents a column in a table where `K` represents a property of `T`
+ * EXAMPLE: For a table of users, this would be the `TableColumn` defintion for the
+ *          phone number column:  TableColumn<User, Phone>.
+ *
+ * @property {string} label - Label that will display in the Table header for the column
+ * @property {string} fieldName - Property name of the object
+ * @property {(value: K, object: T, isMobile: boolean) => React.ReactNode} render - customize
+ *      how the data is displayed in the column where `value` is the property value. `object`
+ *      is the whole object, in case you need to determine styling based on another property
+ *      within the object. isMobile in case your styling depends on whether the user is viewing
+ *      on a phone vs tablet/desktop
+ * @property {string} sortName - (Optional) Passed instead of `fieldName` to onSortChange(fieldName, ...). Useful if you're rendering the same object in 2+ columns and need a way to differentiate when sorting.
+ */
+export type TableColumn<T, K> = {
+    key?: string;
+    label?: string;
+    fieldName: string;
+    render?: (value: K, object: T, isMobile: boolean) => React.ReactNode; // used to customize how the data `obj` is displayed in the table
+    sortName?: string;
+};
+
+// Sort order for Tables
+export type SortOrder = 'asc' | 'desc';
+
+export type TableConfig<T> = {
+    [K in keyof T]: TableColumn<T, T[K]>; // columns is an array of TableColumns, where the type of each TableColumn matches one of the properties of T (ex. `User`)
+}[keyof T][];
+
+/**
+ * Convenience Interface for autocomplete dropdown options
+ * @label string displayed in the dropdown
+ * @value generic-type value associated with the option
+ */
+export interface AutocompleteOption<T> {
+    label: string;
+    value: T;
+}
+
+/**
+ * Checkbox Option
+ *
+ * Can be string OR:
+ * {
+ *      label: string;          // UI label
+ *      sublabel?: string;      // Smaller text that appears below UI label. Supplemental/help text.
+ *      withTextField?: string; // Displays textfield for additional information needed from user (ex. "Other" checkbox). At mininmum, make sure to pass in `name` property.
+ * }
+ */
+export type CheckboxOption =
+    | string
+    | {
+          label: string;
+          sublabel?: string;
+          textField?: TextFieldProps;
+      };
+
+/**
+ * Used for CitationField
+ * Represents a citation (web article/attachment/other url)
+ */
+export type Citation = {
+    id: number;
+    createdBy?: number;
+    updatedBy?: number;
+    deletedBy?: number;
+
+    fileName?: string;
+    url?: string;
+    title: string;
+    source?: string; // publisher
+    accessedAt?: string | null;
+    classification?: string; // public, unclassified
+};
+
+/**
+ * Used for CitationField
+ * Used to represent a (potentially) unsaved Citation (no id defined yet)
+ */
+export type UnsavedCitation = {
+    id?: number;
+} & Omit<Citation, 'id'>;
+
+/**
+ * Used for CitationField
+ * Used to represent a (potentially) unsaved Attachment (same as UnsavedCitation but with a File obj)
+ */
+export type UnsavedAttachment = {
+    file?: File;
+} & UnsavedCitation;

package/dist/common/TestUtils/reactHookForms.d.ts

@@ -0,0 +1,54 @@
+export declare const setMockDefaultValue: <T>(val: T) => void;
+export declare const setMockErrorState: <T>(val: T) => void;
+export declare const clearRHFMocks: () => void;
+export declare const setValueSpy: import('vitest').Mock<(...args: any[]) => any>;
+export declare const useFormContext: () => {
+    register: import('vitest').Mock<(...args: any[]) => any>;
+    handleSubmit: import('vitest').Mock<(...args: any[]) => any>;
+    formState: {
+        defaultValues: {
+            testCheckBox: unknown;
+        };
+        errors: {};
+    };
+    control: {};
+    setValue: import('vitest').Mock<(...args: any[]) => any>;
+    getValues: import('vitest').Mock<() => unknown>;
+};
+export declare const useForm: () => {
+    register: import('vitest').Mock<(...args: any[]) => any>;
+    handleSubmit: import('vitest').Mock<(...args: any[]) => any>;
+    formState: {
+        defaultValues: {
+            testCheckBox: unknown;
+        };
+        errors: {};
+    };
+    control: {};
+};
+interface ControllerProps {
+    name: string;
+    render: (params: {
+        field: {
+            name: string;
+            value: unknown;
+            onChange: (...args: any[]) => void;
+            onBlur: (...args: any[]) => void;
+            ref: (...args: any[]) => void;
+        };
+        fieldState: {
+            invalid: boolean;
+            isTouched: boolean;
+            isDirty: boolean;
+            error?: any;
+        };
+        formState: {
+            isSubmitting: boolean;
+            isValid: boolean;
+            defaultValues: unknown;
+            errors: unknown;
+        };
+    }) => Element;
+}
+export declare const Controller: ({ render, name }: ControllerProps) => Element;
+export {};

package/dist/common/TestUtils/renderWithReactHookForm.d.ts

@@ -0,0 +1,7 @@
+import { ReactElement } from 'react';
+import { UseFormProps, FieldValues } from 'react-hook-form';
+import { RenderResult } from '@testing-library/react';
+interface RenderWithReactHookFormOptions<TFieldValues extends FieldValues> extends UseFormProps<TFieldValues> {
+}
+declare const renderWithReactHookForm: <TFieldValues extends Record<string, any>>(ui: ReactElement, options?: RenderWithReactHookFormOptions<TFieldValues>) => RenderResult;
+export default renderWithReactHookForm;

package/dist/common/Utils/index.d.ts

@@ -0,0 +1,65 @@
+import { MenuOption } from '../../@types';
+import { SelectOption } from '../../components/Form/Inputs/Select/Select';
+export declare const isNumber: (char: number) => boolean;
+export declare const isLetter: (char: number) => boolean;
+export declare const autoformat: (input: string, format: string, currValue: string, element: HTMLInputElement) => string;
+export declare const isFormatted: (item?: string, format?: string) => boolean;
+/**
+ * Helper function to remove unwanted prop fields from the provided props object
+ *
+ * @param props Props
+ * @param omit List of keys to omit from props
+ * @returns Clean props object
+ */
+export declare function removeStrayProps(props: Record<string, unknown>, omit: readonly string[]): object;
+/**
+ * Converts string to label (ex. "this.isMy-string" --> "This Is My String")
+ */
+export declare const makeLabel: (s: string) => string;
+/**
+ * Finds value/values in option list, and returns correct label string.
+ * If there are multiples values, the labels will be listed based on their order
+ * in the options list
+ * @param options Options
+ * @param value string
+ * @param multiple specifies if the value string will contain more than one value to
+ * @param placeholder placeholder to display in a field if the value is null
+ * @returns string representation of value
+ */
+export declare function renderValue<T>(options: SelectOption<T>[], value?: string, multiple?: boolean, placeholder?: string): string;
+/**
+ * Generates the proper parameters for a MenuOption. For each `MenuOption`, if `path` is defined, but
+ * NOT `onClick`, it will behave as a link. Otherwise, it will behave as a button. In other words:
+ *   path only --> link
+ *   onClick only --> button
+ *   path & onClick --> button (onClick will be executed before navigating to path)
+ *
+ * @param menuOption -- menuOption to generate the button/link props for
+ * @param naviate -- pass useNavigate's navigate fn. used when onClick & path are both present to navigate to the path
+ * @param onClickCallback -- (optional) called at the end of the onClick in case any additional execution is needed (ex. closing a modal)
+ */
+export declare function generateButtonLinkProps(menuOption: MenuOption, navigate: (path: string) => void, onClickCallback?: () => void): {
+    onClick: () => void;
+    component?: undefined;
+    to?: undefined;
+    href?: undefined;
+} | {
+    component: import('react').ForwardRefExoticComponent<import('react-router-dom').LinkProps & import('react').RefAttributes<HTMLAnchorElement>>;
+    to: string;
+    onClick?: undefined;
+    href?: undefined;
+} | {
+    href: string;
+    onClick?: undefined;
+    component?: undefined;
+    to?: undefined;
+} | {
+    onClick?: undefined;
+    component?: undefined;
+    to?: undefined;
+    href?: undefined;
+};
+/**
+ * Opens the specified URL in a new tab
+ */
+export declare const launchTab: (url: string) => Window | null;

package/dist/common/WindowDimensions/WindowDimensions.d.ts

@@ -0,0 +1,26 @@
+interface WindowDimensions {
+    height: number;
+    width: number;
+}
+/**
+ * Gets the dimensions of the window (height and width in pixels)
+ * and updates the values on window resize.
+ *
+ * Some Mui Bueno components rely on the screen size to establish styling based on breakpoints.
+ * This function can be used to get the window width, without having to set a window context
+ * in the BForm component, as originally was occurring. Thus, components do not have to be nested
+ * in a BForm component in order to be styled properly.
+ *
+ * This function will not be exported from the library.
+ *
+ * **Example Usage**
+ * ```tsx
+ * const { width } = useWindowDimensions();
+ * // or
+ * const { width, height } = useWindowDimensions();
+ * ```
+ *
+ * @returns Window dimensions
+ */
+export declare const useWindowDimensions: () => WindowDimensions;
+export {};

package/dist/components/Alerts/Alert.d.ts

@@ -0,0 +1,30 @@
+import { AlertProps as MuiAlertProps } from '@mui/material/Alert/Alert';
+import { ReactNode } from 'react';
+type BaseAlertProps = {
+    /** Hides the icon */
+    noIcon?: boolean;
+    /** Body of the alert. Recommend passing a string or component. */
+    children?: ReactNode;
+    /**
+     * Variant of the alert: "standard", "filled", "outlined", or "leftBorder"
+     * @default leftBorder
+     */
+    variant?: MuiAlertProps['variant'];
+    /** (optional) Title for the alert */
+    title?: string;
+};
+export type AlertProps = BaseAlertProps & Omit<MuiAlertProps, 'variant'>;
+export type InternalAlertProps = Omit<AlertProps, 'color' | 'severity'>;
+/**
+ * Compatible with all of MUI's Alert props EXCEPT FOR:
+ * - `severity` -- instead of `<Alert severity='success' {...props}>`, use `<SuccessAlert {...props}>`
+ * - `color` -- do not mix up severity colors
+ *
+ * Additional props:
+ * - `noIcon` -- icons are displayed by default. Use this to hide the icon.
+ *
+ * Modified props:
+ * - `variant` -- works with standard MUI variants: `standard`, `filled`, `outlined`, with one additional: `leftBorder` (default) which adds a border to the left of the alert matching the severity color
+ */
+export declare const Alert: (props: AlertProps) => import("react/jsx-runtime").JSX.Element;
+export default Alert;

package/dist/components/Alerts/ErrorAlert.d.ts

@@ -0,0 +1,4 @@
+import { InternalAlertProps } from './Alert';
+export type ErrorAlertProps = InternalAlertProps;
+export declare const ErrorAlert: (props: ErrorAlertProps) => import("react/jsx-runtime").JSX.Element;
+export default ErrorAlert;

package/dist/components/Alerts/InfoAlert.d.ts

@@ -0,0 +1,4 @@
+import { InternalAlertProps } from './Alert';
+export type InfoAlertProps = InternalAlertProps;
+export declare const InfoAlert: (props: InfoAlertProps) => import("react/jsx-runtime").JSX.Element;
+export default InfoAlert;

package/dist/components/Alerts/SuccessAlert.d.ts

@@ -0,0 +1,4 @@
+import { InternalAlertProps } from './Alert';
+export type SuccessAlertProps = InternalAlertProps;
+export declare const SuccessAlert: (props: SuccessAlertProps) => import("react/jsx-runtime").JSX.Element;
+export default SuccessAlert;

package/dist/components/Alerts/WarningAlert.d.ts

@@ -0,0 +1,4 @@
+import { InternalAlertProps } from './Alert';
+export type WarningAlertProps = InternalAlertProps;
+export declare const WarningAlert: (props: WarningAlertProps) => import("react/jsx-runtime").JSX.Element;
+export default WarningAlert;

package/dist/components/Breadcrumbs/Breadcrumbs.d.ts

@@ -0,0 +1,10 @@
+import * as React from 'react';
+export type BreadcrumbsProps = {
+    crumbInfo: BreadcrumbInfo[];
+};
+export type BreadcrumbInfo = {
+    label: string;
+    path?: string;
+};
+export declare const Breadcrumbs: React.FC<BreadcrumbsProps>;
+export default Breadcrumbs;

package/dist/components/Buttons/Button/Button.d.ts

@@ -0,0 +1,24 @@
+import { ButtonProps as MuiButtonProps } from '@mui/material';
+import * as React from 'react';
+type BaseButtonProps = {
+    /**
+     * Name of the button.
+     * @default 'button'
+     */
+    name?: string;
+    /**
+     * If true, buttons become full width at the default xs Material-UI Breakpoint (form width < 600).
+     * @default true
+     */
+    fullWidthOnMobile?: boolean;
+};
+export type ButtonProps = BaseButtonProps & MuiButtonProps;
+/**
+ * Button doesn't have any default action. You may use for toggling or changing your own state.
+ * For type 'submit', use `Submit`
+ *
+ * To include the Button within the layout grid of MUI-Bueno, provide either a w or a breakpoint size (xs, sm, md, lg, xl).
+ * Otherwise, the button will be rendered as is (`<button>`).
+ */
+export declare const Button: React.FC<ButtonProps>;
+export {};

package/dist/components/Buttons/ScrollToTop/ScrollToTop.d.ts

@@ -0,0 +1,14 @@
+export type ScrollToTopProps = {
+    label?: string;
+    icon?: React.ComponentType;
+    /**
+     *  Number of pixels needed to scroll to toggle `trigger` to `true`. @default 100px
+     */
+    scrollThresholdPx?: number;
+};
+/**
+ * ScrollToTop is a FAB (Floating Action Button) that appears when the user scrolls down so that
+ * they can easily scroll back up by clicking on the FAB.
+ */
+export declare const ScrollToTop: (props: ScrollToTopProps) => import("react/jsx-runtime").JSX.Element;
+export default ScrollToTop;

package/dist/components/Buttons/Submit/Submit.d.ts

@@ -0,0 +1,11 @@
+import { ButtonProps } from '../Button/Button';
+import * as React from 'react';
+export type SubmitProps = ButtonProps;
+/**
+ * IMPORTANT: Has to be a child of Form
+ *
+ * This button will automatically submit the form. It accepts all the props that Button accepts, since it is a specific type of Button.
+ *
+ * This button does not have its own props; it uses the props from Button.
+ */
+export declare const Submit: React.FC<SubmitProps>;

package/dist/components/Form/Error/Error.d.ts

@@ -0,0 +1,23 @@
+import * as React from 'react';
+export type ErrorProps = {
+    /**
+     * Name of the component.
+     * @required
+     */
+    name: string;
+    /**
+     * ID of the element.
+     * @required
+     */
+    id: string;
+    /**
+     * Specifies the styling on the typography.
+     */
+    className?: string;
+};
+/**
+ * This component provides a simple error block containing
+ * an error and status
+ */
+export declare const Error: React.FC<ErrorProps>;
+export default Error;

package/dist/components/Form/FormDebugger/FormDebugger.d.ts

@@ -0,0 +1,8 @@
+import * as React from 'react';
+/**
+ * FormDebugger is a special convenience component developed to help debugging with React Hook Forms. FormDebugger will display field values currently in the form's state.
+ * It also displays the errors that currently exist along with the field that the error is associated to.
+ * Finally, this component displays the status 'errors' that arise when the form receives errors from the back-end service.
+ * These status 'errors' are also linked to specific fields within the form.
+ */
+export declare const FormDebugger: React.FC;

package/dist/components/Form/Inputs/Autocomplete/Autocomplete.d.ts

@@ -0,0 +1,81 @@
+import { AutocompleteProps as MuiAutocompleteProps, TypographyProps } from '@mui/material';
+export type BaseAutocompleteProps<T> = {
+    /**
+     * Name of the component. Must match a key from initialValues in Formik.
+     * @required
+     */
+    name: string;
+    /**
+     * The label for the text field.
+     * @recommended
+     */
+    label?: string;
+    /**
+     * List of options for the autocomplete in label/value format
+     * @recommended
+     */
+    options: T[];
+    /**
+     * Specifies the visual input style.
+     * @default 'outlined'
+     */
+    variant?: 'filled' | 'outlined' | 'standard';
+    /**
+     * If true, the prepackaged dynamic input label that comes with Material UI's input components
+     * will be replaced with a static typography label above the input.
+     * @default false
+     */
+    staticLabel?: boolean;
+    /**
+     * Props from MUI-Bueno's Typography component.
+     * Used to customize the label when the static label option is selected.
+     */
+    staticLabelProps?: TypographyProps;
+    /**
+     * Margin for the FormControl
+     */
+    margin?: 'dense' | 'none' | 'normal';
+    /**
+     * If true, an asterisk will be displayed next to the label
+     * Most browsers will automatically validate this, but it's recommended to also
+     * have Formik also validate as well so that `Error` displays for consistency.
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * When true, clears the input text when the user selects an option from the dropdown.
+     * Useful when adding items from the Autocomplete to a list or table.
+     */
+    clearOnSelect?: boolean;
+    /**
+     * When using Autocomplete with objects, this prop can be used to store only a property of that object in formik.
+     *
+     * For example, if you have `type User = { id: number; firstName: string; lastName: string; ... }`, you can
+     * set useFieldAsValue="id" if you want formik to only store the user's id rather than the whole user object.
+     *
+     * NOTE: This will require extra processing on the client-side compared to just using the object for the formik value
+     * because the Autocomplete will have to search `options` for the object with the property matching formik's initial value.
+     *
+     */
+    useFieldAsValue?: string;
+};
+/**
+ * Type used to define props passed into Autocomplete component
+ */
+export type AutocompleteProps<T> = BaseAutocompleteProps<T> & Omit<MuiAutocompleteProps<T, // Option type
+false, // Multiple -- allows multiple options to be selected (enables `multiple` prop)
+boolean, // DisableClearable -- allows disabling of the clear button (enables `disableClearable` prop)
+false>, 'renderInput' | 'options' | 'value' | 'multiple' | 'freeSolo' | 'inputValue'>;
+/**
+ * `Autocomplete` is a mix between a `TextField` and `Select` component.
+ * As the user types, options that match their query are presented.
+ *
+ * Use this component when you have a lot of options and want to reduce the amount of scrolling
+ * users would have to do if they were to use a `Select`.
+ *
+ * Can be used with primitives or objects. For objects, make sure to override `getOptionLabel`.
+ *
+ * __IMPORTANT__: If you need to dynamically load options as the user types, check out `DynamicAutocomplete`, as this
+ * has automated a lot of the settings.
+ */
+export declare const Autocomplete: <T>(props: AutocompleteProps<T>) => import("react/jsx-runtime").JSX.Element;