@blocklet/ui-react

# Core Concepts This document explains the fundamental principles of the Blocklet UI React library. The core design philosophy is a **metadata-driven approach**, where UI components such as the `Header`, `Footer`, and `Dashboard` are automatically configured and rendered based on the blocklet's metadata. This strategy ensures consistency, reduces boilerplate code, and enables dynamic UIs that adapt to user roles and language preferences. The central idea is that a single configuration file, typically `blocklet.yml`, serves as the single source of truth for the application's overall structure and appearance. The library reads this metadata, processes it, and uses it to construct the appropriate UI elements. ## The Metadata-Driven Principle The library's operation can be visualized as a simple data flow: the blocklet metadata is provided as input to the library, which then processes it through a pipeline to produce fully rendered UI components. This eliminates the need for developers to manually build and configure common layout elements for each application. The following diagram illustrates this data flow:  ![Core Concepts](assets/diagram/core-concepts-diagram-0.jpg)  This automated process relies on a well-defined metadata structure, which is detailed in the following section. ## Anatomy of Blocklet Metadata The library expects a specific object structure, referred to as `BlockletMetaProps`, which contains all the necessary information for rendering the UI. Below is a detailed breakdown of this structure. <x-field-group> <x-field data-name="appName" data-type="string" data-required="false" data-desc="The name of the application, typically displayed in the Header."></x-field> <x-field data-name="appLogo" data-type="React.ReactNode" data-required="false" data-desc="A React node for the application's logo, also displayed in the Header."></x-field> <x-field data-name="enableConnect" data-type="boolean" data-required="false" data-desc="Determines whether to display a DID Connect button."></x-field> <x-field data-name="enableLocale" data-type="boolean" data-required="false" data-desc="Determines whether to display the language selection component."></x-field> <x-field data-name="theme" data-type="object" data-required="false"> <x-field-desc markdown>Defines the color scheme for the application layout.</x-field-desc> <x-field data-name="background" data-type="string" data-required="false" data-desc="Sets the background color for layout components like the Header and Footer."></x-field> </x-field> <x-field data-name="navigation" data-type="array" data-required="false"> <x-field-desc markdown>An array of navigation item objects that define the links and menus throughout the application.</x-field-desc> <x-field data-name="title" data-type="string | object" data-required="true" data-desc="The display text for the navigation item. Can be an object for i18n."></x-field> <x-field data-name="link" data-type="string | object" data-required="false" data-desc="The URL for the navigation item. Can be an object for i18n."></x-field> <x-field data-name="icon" data-type="string" data-required="false" data-desc="An Iconify-compatible string for an icon to display next to the title."></x-field> <x-field data-name="section" data-type="string | array" data-required="false" data-desc="Specifies where the item should appear, e.g., 'header', 'footer', 'dashboard'."></x-field> <x-field data-name="role" data-type="string | array" data-required="false" data-desc="Defines which user roles can see this item, e.g., 'admin', 'guest'."></x-field> <x-field data-name="items" data-type="array" data-required="false" data-desc="An array of nested navigation items to create dropdown menus or sub-menus."></x-field> </x-field> </x-field-group> ### Navigation Configuration Example The `navigation` array is the most critical part of the metadata. It provides a structured way to define all links, menus, and their placement. ```yaml Navigation Configuration in blocklet.yml icon=mdi:code-braces # blocklet.yml navigation: - title: Features link: /features - title: en: About Us zh: 关于我们 link: en: /about zh: /about-us section: footer - title: Admin Dashboard link: /admin section: dashboard role: admin - title: Social section: social items: - title: Twitter link: https://twitter.com/arcblock icon: mdi:twitter - title: GitHub link: https://github.com/arcblock icon: mdi:github ``` This example illustrates several key features: - A simple header link ("Features"). - A multi-language footer link ("About Us"). - An admin-only link for the dashboard. - A group of social media links intended for the footer. ## The Data Processing Pipeline Before rendering, the library processes the raw metadata through a series of steps to prepare it for the UI components. ### 1. Parsing and Sectioning The first step is to parse the `navigation` array and group items based on their `section` property. A single navigation item can be assigned to multiple sections by using an array for the `section` value. The `parseNavigation` utility categorizes each item into predefined sections: - `header`: For the main application header. - `footer`: For primary links in the footer. - `social`: For social media icons, typically in the footer. - `bottom`: For legal or secondary links at the very bottom of the footer. - `dashboard`: For the sidebar navigation in a dashboard layout. - `sessionManager`: For menus within the user session component. - `userCenter`: For tabs or links within the user profile area. If an item has no `section` property, it defaults to `header`. ### 2. Internationalization (i18n) The library provides built-in support for multiple languages. If a `title` or `link` property in a navigation item is an object with language keys (e.g., `en`, `zh`), the `getLocalizedNavigation` function automatically selects the correct string based on the user's current locale. ```javascript i18n Object Example icon=logos:javascript // A navigation item with multi-language support { title: { en: 'Home', zh: '首页' }, link: { en: '/home', zh: '/zh/home' } } ``` ### 3. Role-Based Filtering To create a dynamic user experience, navigation items can be restricted to specific user roles. The `filterNavByRole` function filters the navigation list by comparing the `role` property of each item against the `user.role` from the current session. - If an item has no `role` property, it is visible to everyone. - If an item has a `role` property (e.g., `['admin', 'editor']`), it is only visible to users whose role is in that array. - The `guest` role is a special value that applies to unauthenticated users. This mechanism allows you to define a comprehensive navigation structure in your metadata and have the UI automatically adapt based on the logged-in user's permissions. ## Summary The core concept of the Blocklet UI React library is to leverage a centralized metadata object to drive the configuration and rendering of common UI components. This metadata-driven approach offers several advantages: - **Single Source of Truth**: Application structure, branding, and navigation are defined in one place. - **Consistency**: Ensures a consistent look and feel across different parts of the application. - **Reduced Boilerplate**: Eliminates the need to manually code common layout elements like headers and footers. - **Dynamic UI**: Natively supports internationalization and role-based access control, allowing the UI to adapt dynamically to the user and their permissions. With a clear understanding of these principles, you can effectively utilize the library's components. For more information on specific components and their usage, please refer to the [Components](./components.md) section.