Displays are essential to every component as they specify the "container" in which the component will be rendered. This could be a modal, popover, inline, or any other type of container.

In addition to specifying the container, displays also control the visibility of the component. For example, a modal display will render the component in a modal container and prevent other parts of the page from being interacted with until the modal is dismissed. Different displays can be used in different contexts to provide the best user experience.

Displays are distinct from Elements and Layouts because they do not inherit from the Element class, but rather from the LitElement class, thereby becoming web components themselves.

As such, they have a slightly different implementation than Elements and Layouts. Check out our displays that are available in our open-source framework: https://bit.cloud/unless/component-library/display/bar.

Import

import {Display} from '@unless/component-library.display.display'

Abstract methods

When creating a new display, these methods must be implemented.

Static methods

While TypeScript does not formally implement abstract static, these methods must be implemented, otherwise, the component will not render correctly.

Static properties

In addition to ‘abstract’ static methods that must be implemented, the static property of type must also be implemented.

Instance methods

These methods should be implemented when creating a new display. Some of these methods are marked as protected and should not be called outside of the display class itself.

Instance properties

These properties are available in display instances.

Lifecycle methods

These methods are automatically called during the display's lifecycle.

Constructor

This constructor should be called when creating a new display instance.

Display settings

Display settings are crucial in any component library, as they allow users to customise the appearance and behavior of display components to fit their specific needs. In this section, we will explain what display settings are, how to use them, and some best practices for implementing them.

What are display settings?

Display settings are options that can be configured for a display component within a component library. They allow users to modify the appearance and behavior of the display component without changing its underlying code. Examples of display settings include CSS selectors, positions, background colours, and shadows. By providing users with display settings, you can make your display components more flexible and adaptable to different use cases.

How to use display settings

To use display settings in your components, you first need to define them by creating a settings model that extends the DisplaySettings class.

Here's an example of how to define a display settings model:

import { 
	BooleanSelectSetting, 
	CssSelectorSetting, 
	SelectSetting, 
	Setting 
} from '@unless/component-library.utils.types'
import { DisplaySettings } from '@unless/component-library.display.display'

interface InlineSetting extends Setting {
  selector: CssSelectorSetting
  position: SelectSetting
  shadow: SelectSetting
  margin: BooleanSelectSetting
}

export type InlineSettings = DisplaySettings<'inline', InlineSetting>

Once the display settings model is defined, you need to create the default settings file.

Here's an example of how to create the default settings file:

/* esbuild-ignore */

import { InlineSettings } from './settings-model'
import { 
	backgroundColorSetting, 
	destroyUponNavigateSettings, 
	stepperSettings 
} from '@unless/component-library.display.display'
import { BooleanOptions } from '@unless/component-library.utils.types'

const settings: InlineSettings = {
  inline: {
    selector: {
      label: 'css selector',
      type: 'cssSelector',
      value: '#placeholder',
      placeholder: 'Enter a valid CSS selector',
      helpText: 
				'Enter a CSS selector after which the custom inline add-on will be inserted.',
      fallback: undefined as string | undefined,
    },
    position: {
      label: 'position',
      type: 'select',
      options: ['before', 'after', 'replace', 'replace-child'],
      value: 'after',
      placeholder: 'after',
      helpText: 
				'Choose where to insert the inline add-on. Either before, after or replace the selected element.',
    },
    backgroundColor: { ...backgroundColorSetting, expert: true },
    shadow: {
      expert: true,
      label: 'shadow',
      type: 'select',
      options: ['none', 'small', 'regular', 'large'],
      value: 'none',
      placeholder: 'none',
      helpText: 'Show a shadow on the inline component.',
    },
    destroyUponNavigate: destroyUponNavigateSettings,
    margin: {
      expert: true,
      label: 'margin',
      type: 'select',
      options: Object.values(BooleanOptions),
      value: BooleanOptions.No,
      placeholder: BooleanOptions.No,
      helpText: 'Show a margin on the inline component.',
    },
  },
  stepper: stepperSettings,
}

export default settings

Best practices for implementing display settings

1. Use DisplaySettings: Ensure that your display settings model uses the DisplaySettings type. This provides a consistent structure for display settings across your component library.
2. Provide default values: Always provide default values for your display settings. This ensures that your display component works out of the box and allows users to customise only the settings they need.
3. Use the esbuild-ignore comment: Include the /* esbuild-ignore */ comment at the beginning of your settings file to