Utilities

This section provides documentation for a collection of helper components, Higher-Order Components (HOCs), and utility functions. These tools are designed to simplify common development tasks, manage application themes, and handle complex data structures.

The primary utilities available are:

For a detailed guide on the Icon component, please see its dedicated documentation page. The other utilities are documented below.

OverridableThemeProvider#

This component is a wrapper around Material-UI's ThemeProvider. It allows you to apply a consistent theme to its child components. By default, it uses the standard Blocklet UI theme, but you can provide a custom theme object via the theme prop to override the default styles.

Usage#

To apply a custom theme, pass a theme object to the theme prop. The component will merge your overrides with the default theme.

import OverridableThemeProvider from '@blocklet/ui-react/lib/common/overridable-theme-provider';
import { Button } from '@mui/material';

const customTheme = {
  palette: {
    primary: {
      main: '#ff5722',
    },
  },
};

function App() {
  return (
    <OverridableThemeProvider theme={customTheme}>
      <Button color="primary" variant="contained">
        Custom Themed Button
      </Button>
    </OverridableThemeProvider>
  );
}

withHideWhenEmbed#

withHideWhenEmbed is a Higher-Order Component (HOC) that prevents a component from rendering if the application is in "embed mode." It checks a session storage key (EMBED_MODE_KEY) to determine the current mode. If the value is 1, the wrapped component will return null.

This is useful for hiding elements like headers or footers in an embedded context where they are not needed.

Usage#

Wrap the component you wish to conditionally hide with the withHideWhenEmbed HOC.

import withHideWhenEmbed from '@blocklet/ui-react/lib/libs/with-hide-when-embed';

function PageHeader() {
  return (
    <header>
      <h1>My Application</h1>
    </header>
  );
}

const MaybeHiddenHeader = withHideWhenEmbed(PageHeader);

function App() {
  return (
    <div>
      <MaybeHiddenHeader />
      <main>
        {/* Main content goes here */}
      </main>
    </div>
  );
}

Helper Functions#

A set of pure JavaScript functions are available for common data manipulation and validation tasks. These can be imported directly from the library's utility module.

Array Manipulation#

These functions are designed to work with arrays of nested objects, such as navigation menus or file trees.

Function	Description
mapRecursive(array, fn, childrenKey = 'children')	Recursively applies a function to each item in a nested array.
flatRecursive(array, childrenKey = 'children')	Flattens a nested array into a single-level array.
countRecursive(array, childrenKey = 'children')	Counts the total number of items in a nested array.
filterRecursive(array, predicate, childrenKey = 'children')	Recursively filters a nested array based on a predicate function, preserving parent structure if children match.

String & URL Validation#

Simple helpers for checking string formats.

Function	Description
isUrl(str)	Returns true if the string starts with http:// or https://.
isMailProtocol(str)	Returns true if the string starts with mailto:.

Routing#

Utilities to assist with client-side routing logic.

Function	Description
matchPath(path)	Checks if a given path matches the current window.location.pathname.
matchPaths(paths)	Finds the best matching path from an array of paths against the current location.

Layout#

Function	Description
splitNavColumns(items, options)	Splits a list of navigation items into a specified number of columns, useful for creating mega menus.

Summary#

This section provided an overview of the general-purpose utilities included in the library. For more powerful, specialized functionality, proceed to the detailed documentation for individual components.

For a comprehensive guide on using the flexible Icon component, please refer to the next section.

• Icon