Version: 2.x

🖼 mlc-layout

Web component providing a classic navigation top bar/sidebar layout for micro-lc applications.

Usage

caution

This component is intended to be used inside micro-lc, since it makes use of micro-lc API.

You can use it standalone, but you will have to manually provide a matching API with the property microlcApi.

The component can be sourced from jsDelivr CDN.

To use the component in micro-lc, declare it as part of the application layout with its properties and attributes. An unnamed <slot> is already set in the component so that content will be automatically mounted in the right position.

micro-lc.config.yaml
layout: 
  sources: https://cdn.jsdelivr.net/npm/@micro-lc/layout@latest/dist/mlc-layout.js
  content: 
    tag: mlc-layout
    properties: # See properties & attributes table below
    attributes: # See properties & attributes table below
    booleanAttributes: # See properties & attributes table below
    content: # See slots table below

Minified version

The component is also shipped in a minified version, that does not bundle peer dependencies. Using this version will save bundle size, but requires import maps for the needed dependencies, which are:

react compatible with version 18.2.0
react-dom compatible with version 18.2.0

micro-lc.config.yaml
layout:
  sources:
    importmap:
      imports:
        react: https://esm.sh/react@18.2.0
        react-dom: https://esm.sh/react-dom@18.2.0
      scopes:
        https://esm.sh/react-dom@next:
          /client: https://esm.sh/react-dom@18.2.0/client
    uris:
      - https://cdn.jsdelivr.net/npm/@micro-lc/layout@latest/dist/mlc-layout.min.js
  content:
    tag: mlc-layout
    # ...

Showcase

Top bar slot

Properties & attributes

Property	Attribute	Type	Default	Description
`mode`	`mode`	`fixedSideBar \| overlaySideBar \| topBar`	`overlaySideBar`	How the layout will be structured
`menuItems`	-	`MenuItem[]`	Required	Menu configuration
`logo`	-	`Logo`		Customization of the logo object
`helpMenu`	-	`HelpMenu`	-	Configuration of the help menu
`userMenu`	-	`UserMenu`	-	Configuration of the user menu
`head`	-	`Head`	-	Configuration for the HTML document head

`MenuItem`

type MenuItem = HrefMenuItem | ApplicationMenuItem | CategoryMenuItem | GroupMenuItem

`HrefMenuItem`

Link to specific url.

Property	Type	Default	Description
`href`	`string`	Required	Link's destination
`icon`	`Icon`	Ant Design `LinkOutlined`	Icon icon of the menu item
`id`	`string`	Required	Unique identifier of the menu item
`label`	`string \| LocalizedText`	Value of `id` prop	Menu label
`target`	`_blank \| _self \| _parent \| _top`	`_self`	HTML anchor target attribute
`type`	`href`	Required	Type of the item: hyperlink to another page

`ApplicationMenuItem`

This type of menu items triggers the navigation to a specific micro-lc application, identified by the id prop.

Property	Type	Default	Description
`icon`	`Icon`	Ant Design `DeploymentUnitOutlined`	Icon icon of the menu item
`id`	`string`	Required	Unique identifier of the menu item. It must match the id of the micro-lc application the menu item should navigate to
`selectedAlsoOn`	`string[]`	Optional subapplication `id`s	Applications that also select this item
`label`	`string \| LocalizedText`	Value of `id` prop	Menu label
`type`	`application`	Required	Type of the item: micro-lc application

`CategoryMenuItem`

This type of menu items is a container of other items. You can stack virtually any number of categories.

Property	Type	Default	Description
`children`	`MenuItem`	[]	Content of the category
`icon`	`Icon`	Ant Design `ContainerOutlined`	Icon icon of the menu item
`id`	`string`	Required	Unique identifier of the menu item.
`label`	`string \| LocalizedText`	Value of `id` prop	Menu label
`type`	`category`	Required	Type of the item: container of items

`GroupMenuItem`

caution

Groups cannot be used at first level when mode is topBar.

This type of menu items is a grouping of other items.

Property	Type	Default	Description
`children`	`MenuItem`	[]	Content of the group
`id`	`string`	Required	Unique identifier of the menu item.
`label`	`string \| LocalizedText`	Value of `id` prop	Menu label
`type`	`group`	Required	Type of the item: group of items

`Icon`

Definition of a dynamically loaded icon.

Property	Type	Default	Description
`library`	`@ant-design/icons-svg \| @fortawesome/free-brands-svg-icons \| @fortawesome/free-regular-svg-icons \| @fortawesome/free-solid-svg-icons \| phosphor/bold \| phosphor/duotone \| phosphor/fill \| phosphor/light \| phosphor/regular \| phosphor/thin`	Required	Library from witch the icon is pulled
`selector`	`string`	Required	Name of the icon according to the chosen library

there is also a list of available icons, divided by library.

`LocalizedText`

Definition of a translatable text through a map linking rfc5646 language codes to localized strings.

type LocalizedText = Record<string, string>

`Logo`

The logo will be rendered in the left corner of the top bar, regardless of the mode.

You can specify where to navigate when the logo is clicked. If it is an external link, it will open in a new tab. If no value is provided, the logo will not be clickable.

Property	Type	Default	Description
`altText`	`string`	`Logo`	Alternative text to display if the logo is not found
`onClickHref`	`string`	-	Link to navigate to when the logo is clicked
`url`	`string`	Required	URL to the logo image

`HelpMenu`

The help menu will be rendered in the right portion of the top bar, regardless of the mode.

You can specify where to navigate when the button is clicked. The link will always be opened in a new tab.

Property	Type	Default	Description
`helpHref`	`string`	Required	Link to navigate to when the help button is clicked

`UserMenu`

The user menu will be rendered in the right corner of the top bar, displaying name and avatar of the user. If logout property is provided, a menu from which the user can log out will also be rendered.

User data are retrieved with a GET call to userInfoUrl. Among these information, the menu utilizes name (required, otherwise the menu will not be rendered) and avatar. If userInfoUrl returns those properties with different name, userPropertiesMapping can be used to adapt the keys of the response to the ones used by the menu.

For example, the following response

{
  "fullName": "John Doe",
  "image": "https://avatar.com"
}

has to be accompanied by the following userPropertiesMapping property

{
  "fullName": "name",
  "image": "avatar"
}

Property	Type	Default	Description
`logout`	`UserMenuLogout`	-	Configuration needed to perform user logout
`userInfoUrl`	`string`	Required	URL called in GET to retrieve user data
`userPropertiesMapping`	`UserPropertiesMapping`	-	Mapping between the properties returned from the user info URL call and the ones expected by the component

`UserMenuLogout`

Configurations regarding how the user should be logged out.

If the url property is specified, a call with method to url will be performed. If the call is successful, a redirection will be performed to redirectUrl (if present). The properties are independent: if url is not given, but redirectUrl is, the redirection will still be performed.

tip

We advise to use POST as method, since using GET will make browsers pre-fetch pages they should not.

Property	Type	Default	Description
`method`	`GET \| POST`	`POST`	Method used to perform the call to the URL specified in the `url` property
`redirectUrl`	`string`	-	URL to be redirected to after the logout
`url`	`string`	-	URL called to log out the user

`UserPropertiesMapping`

type UserPropertiesMapping = Record<string, 'name' | 'avatar' | string>

`Head`

Information used by micro-lc to manipulate the head of the document.

Property	Type	Default	Description
`favIconUrl`	`string`	-	Url of the fav icon
`title`	`string`	-	Title of the tab

Slots

Name	Description
`top-bar`	Content is placed on the right side of the top bar

CSS custom properties

This component is based on Ant Design and makes use of its dynamic theme functionality to expose a set of CSS variables for style customization.

Follows the list of CSS variables used by Ant Design dynamic theme. The exact usage of each variable is hidden in Ant Design components implementations and some of them may not be used by mlc-layout.

tip

We recommend using mlc-antd-theme-manager component to customize the layout theme in an easier and more organic way.

Name
`--micro-lc-primary-1`
`--micro-lc-primary-2`
`--micro-lc-primary-3`
`--micro-lc-primary-4`
`--micro-lc-primary-5`
`--micro-lc-primary-6`
`--micro-lc-primary-7`
`--micro-lc-primary-8`
`--micro-lc-primary-9`
`--micro-lc-primary-10`
`--micro-lc-primary-color`
`--micro-lc-primary-color-active`
`--micro-lc-primary-color-active-deprecated-d-02`
`--micro-lc-primary-color-active-deprecated-f-30`
`--micro-lc-primary-color-deprecated-bg`
`--micro-lc-primary-color-deprecated-border`
`--micro-lc-primary-color-deprecated-f-12`
`--micro-lc-primary-color-deprecated-l-20`
`--micro-lc-primary-color-deprecated-l-35`
`--micro-lc-primary-color-deprecated-t-20`
`--micro-lc-primary-color-deprecated-t-50`
`--micro-lc-primary-color-disabled`
`--micro-lc-primary-color-hover`
`--micro-lc-primary-color-outline`
`--micro-lc-success-color`
`--micro-lc-success-color-active`
`--micro-lc-success-color-deprecated-bg`
`--micro-lc-success-color-deprecated-border`
`--micro-lc-success-color-disabled`
`--micro-lc-success-color-hover`
`--micro-lc-success-color-outline`
`--micro-lc-info-color`
`--micro-lc-info-color-active`
`--micro-lc-info-color-deprecated-bg`
`--micro-lc-info-color-deprecated-border`
`--micro-lc-info-color-disabled`
`--micro-lc-info-color-hover`
`--micro-lc-info-color-outline`
`--micro-lc-warning-color`
`--micro-lc-warning-color-active`
`--micro-lc-warning-color-deprecated-bg`
`--micro-lc-warning-color-deprecated-border`
`--micro-lc-warning-color-disabled`
`--micro-lc-warning-color-hover`
`--micro-lc-warning-color-outline`
`--micro-lc-error-color`
`--micro-lc-error-color-active`
`--micro-lc-error-color-deprecated-bg`
`--micro-lc-error-color-deprecated-border`
`--micro-lc-error-color-disabled`
`--micro-lc-error-color-hover`
`--micro-lc-error-color-outline`
`--micro-lc-font-family`

micro-lc API

Reactive state object

The component inserts the following values in the reactive state of micro-lc API.

Key	Type	Description
`user`	`Record<string, unknown>`	User data retrieved with call to `userInfoUrl`.

🖼 mlc-layout

Usage

Minified version

Showcase

Top bar menu

Overlay sidebar

Fixed sidebar

User menu

Help menu

Top bar slot

Properties & attributes

`MenuItem`

`HrefMenuItem`

`ApplicationMenuItem`

`CategoryMenuItem`

`GroupMenuItem`

`Icon`

`LocalizedText`

`Logo`

`HelpMenu`

`UserMenu`

`UserMenuLogout`

`UserPropertiesMapping`

`Head`

Slots

CSS custom properties

micro-lc API

Reactive state object

Usage​

Minified version​

Showcase​

Top bar menu​

Overlay sidebar​

Fixed sidebar​

User menu​

Help menu​

Top bar slot​

Properties & attributes​

MenuItem​

HrefMenuItem​

ApplicationMenuItem​

CategoryMenuItem​

GroupMenuItem​

Icon​

LocalizedText​

Logo​

HelpMenu​

UserMenu​

UserMenuLogout​

UserPropertiesMapping​

Head​

Slots​

CSS custom properties​

micro-lc API​

Reactive state object​

Usage

Minified version

Showcase

Top bar menu

Overlay sidebar

Fixed sidebar

User menu

Help menu

Top bar slot

Properties & attributes

`MenuItem`

`HrefMenuItem`

`ApplicationMenuItem`

`CategoryMenuItem`

`GroupMenuItem`

`Icon`

`LocalizedText`

`Logo`

`HelpMenu`

`UserMenu`

`UserMenuLogout`

`UserPropertiesMapping`

`Head`

Slots

CSS custom properties

micro-lc API

Reactive state object