@blocklet/ui-react/docs/getting-started.md

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

# Getting Started

This guide provides a step-by-step walkthrough to install the `@blocklet/ui-react` library and render your first components. The objective is to have a functional `Header` and `Footer` within your application in a minimal amount of time.

## Prerequisites

Before proceeding, ensure you have the following installed in your development environment:
*   A functional React project.
*   Node.js and a package manager (npm or yarn).

## Installation

To begin, add the `@blocklet/ui-react` package to your project using your preferred package manager.

With npm:
```bash npm
npm install @blocklet/ui-react
```

With yarn:
```bash yarn
yarn add @blocklet/ui-react
```

## Basic Usage: Header and Footer

The `Header` and `Footer` components are designed for simplicity and can be rendered without any initial configuration. They automatically source their data from the blocklet's metadata.

1.  Import the `Header` and `Footer` components into your main application file (e.g., `App.js`).
2.  Place them at the top and bottom of your application's layout, respectively.

```jsx App.js icon=logos:react
import React from 'react';
import Header from '@blocklet/ui-react/lib/Header';
import Footer from '@blocklet/ui-react/lib/Footer';

function App() {
  return (
    <div>
      <Header />
      <main style={{ padding: '20px', minHeight: 'calc(100vh - 128px)' }}>
        {/* Your application content goes here */}
        <h1>Welcome to My Blocklet</h1>
      </main>
      <Footer />
    </div>
  );
}

export default App;
```

The components automatically retrieve configuration details—such as the application name, logo, and navigation links—from the `window.blocklet` metadata object, which is injected by the Blocklet Server environment.

Furthermore, the `Header` component will intelligently render additional controls:
*   A **user session manager** is displayed if a `SessionContext` is available.
*   A **language selector** is displayed if a `LocaleContext` is available.

## Manual Configuration

For development, testing, or cases where you need to override the default metadata, you can pass a configuration object directly to the components using the `blockletMeta` prop.

```jsx App.js icon=logos:react
import React from 'react';
import Header from '@blocklet/ui-react/lib/Header';

const customBlockletMeta = {
  appName: 'My Custom App',
  appLogo: 'https://path.to/your/logo.png',
  navigation: [
    {
      title: 'Home',
      link: '/',
    },
    {
      title: 'Documentation',
      link: '/docs',
    },
  ],
};

function App() {
  return (
    <div>
      <Header blockletMeta={customBlockletMeta} />
      {/* ... rest of your app */}
    </div>
  );
}
```

This approach gives you precise control over the component's appearance and behavior by overriding any data provided by the global `window.blocklet` object.

## Customizing the Header

The `Header` component includes an `addons` area on the right side, which you can customize to include your own components, such as action buttons or custom links.

The `addons` prop accepts a function that receives the default addon components as an argument. This allows you to prepend, append, or completely replace them.

```jsx CustomHeader.js icon=logos:react
import React from 'react';
import Header from '@blocklet/ui-react/lib/Header';
import Button from '@mui/material/Button'; // Example using Material-UI

function CustomHeader() {
  return (
    <Header
      addons={existingAddons => {
        return [
          <Button
            key="custom-action"
            variant="contained"
            color="primary"
            size="small"
            style={{ marginRight: 8 }}>
            Custom Action
          </Button>,
          ...existingAddons, // Important: preserves default session/locale addons
        ];
      }}
    />
  );
}
```

In this example, a custom button is prepended to the existing addons. By including `...existingAddons`, you ensure that the default session and locale controls remain visible.

## Summary

You have successfully installed the `@blocklet/ui-react` library, rendered default `Header` and `Footer` components, and learned how to provide custom configurations and addons.

With these fundamentals in place, you are now prepared to explore the full range of components available in the library. For detailed documentation on layout, user management, and utility components, please proceed to the [Components](./components.md) section.