@blocklet/ui-react/docs/components-utilities.md

Some useful front-end web components that can be used in Blocklets.

# 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:

<x-cards data-columns="2">
  <x-card data-title="Icon Component" data-icon="lucide:image" data-href="/components/utilities/icon">
    A versatile component for displaying icons from various sources, including Iconify, image URLs, or as letter avatars.
  </x-card>
  <x-card data-title="OverridableThemeProvider" data-icon="lucide:palette">
    A theme provider that allows developers to supply their own theme object to override the default Blocklet UI theme.
  </x-card>
  <x-card data-title="withHideWhenEmbed HOC" data-icon="lucide:eye-off">
    A Higher-Order Component that conditionally renders a component, hiding it when the application is in an embedded mode.
  </x-card>
  <x-card data-title="JavaScript Helpers" data-icon="lucide:function-square">
    A suite of standalone functions for tasks such as recursive array manipulation, URL validation, and path matching.
  </x-card>
</x-cards>

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.

```javascript Theme Provider Example icon=logos:javascript
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.

```javascript HOC Example icon=logos:javascript
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](./components-utilities-icon.md)**