Jon: Describes components.xd for a UI component specification: how to get started, how to define a component in terms of its children, how to define scenarios using selectors, and how to set property declarations.

2023-05-25T20:18:37Z

Describes components.xd for a UI component specification: how to get started, how to define a component in terms of its children, how to define scenarios using selectors, and how to set property declarations.

New page

User interfaces are composed of reusable semantic elements called components. Each component is specified by a set of documents: <code>model.txt</code>, <code>preview.xd</code>, <code>components.xd</code>, <code>layout.xd</code>, <code>user_flow.drawio</code>, and <code>use_cases.drawio</code>. This page covers the <code>components.xd</code> document.

<code>components.xd</code> lists all children for the component. Children may be omitted where there is no customization done and their inclusion is made clear from <code>layout.xd</code> . If the component has no children (e.g. it is primitive or purely layout) then <code>components.xd</code> is omitted. Most components will require <code>components.xd</code>.

== Component Breakdown ==

The question of when to define a component on its own rather than as a child of its parent is generally one of complexity: when the child is so complex that defining it within the <code>components.xd</code> of the parent impedes readability, it should be split off into its own component. The following heuristics are helpful in determining whether a child should become its own component:

* It is shared by multiple parents and should be generally available in the application (e.g. <code>FilterPanel</code> could be defined in <code>TableView</code>, but filtering could conceivably be used outside of a table)
* It has multiple children that require conditional styling (e.g. <code>HeaderCell</code> could be defined in <code>TableView</code>, but it has many children with lots of conditional styling that would be harder to follow alongside all the other children of <code>TableView</code>)
* It contains its own logic that is best described by its own model and user flow (e.g. <code>OverflowLabel</code> in <code>CategoricalList</code>)
* It contains children that themselves must have conditional styling based on their state (e.g. <code>ColorSwatch</code> in <code>ColorBox</code>)

== Getting Started ==

<code>components.xd</code> comes after <code>preview.xd</code> and <code>model.txt</code>. From <code>preview.xd</code>, the children can be listed and the essential scenarios understood. From <code>model.txt</code>, specific data, styles and states can be referenced.

=== Example: AccountListItem ===

<pre>Data:
identicon: A unique icon identifier for the account.
id: A unique username for the account.
name: The full name associated with the account.</pre>
The above model for <code>AccountListItem</code> shows 3 pieces of data. There are no component-specific states or styles described in the model. We infer that the job of <code>components.xd</code> will be to indicate where these 3 pieces of data will appear and how they will be displayed.

[[File:AccountListItem_preview.png|360px|Preview of a list item displaying a user account]]

From the above preview, there are no scenarios showcased: the component appears to be display-only, without any specific interactions. There are (at least) 3 children:
* <code>Icon</code> for <code>identicon</code>
* <code>Label</code> for <code>id</code>
* <code>Label</code> for <code>name</code>

The designer could split the children into other components (e.g. a <code>Box</code>) for styling purposes, so we can have more than the expected 3 children. Based on <code>preview.xd</code> and <code>model.txt</code>, we infer that <code>components.xd</code> will list the 3 expected children and cascade the data to the appropriate child. It should also describe the font settings for the <code>name</code>, which have been customized away from the default.

[[File:AccountListItem_components.png|720px|Definition cards for AccountListItem's children]]

Reviewing the actual <code>components.xd</code>, that is exactly what we get. A <code>Box</code> has been used to contain the <code>Icon</code> so that some padding can be added to it. The children are siblings, so they are ordered left-to-right and top-to-bottom.

We note that <code>id</code> is assigned to the <code>current</code> property of the <code>Label</code> named <code>ID</code>: for a <code>Label</code>, <code>current</code> refers to its displayed text. Also, <code>name</code> is assigned to the <code>current</code> property of the <code>Label</code> named <code>Name</code>. At the top, <code>identicon</code> is assigned to the <code>icon</code> property of the <code>Icon</code> named <code>Identicon</code>.

It is common practice to name children by the data that they display when they are solely responsible for one piece of data. The capitalization conventions ('''snake_case''' for properties and '''PascalCase''' for components is used to disambiguate the child from the value).

== Anatomy ==

The structure of <code>components.xd</code> is a vertical list of cards. Each card displays exactly one child and its scenarios. Wherever possible, a visual preview of the child should be displayed for each scenario.

=== Example: LabelButton ===

[[File:LabelButton_anatomy.png|720px|Definition Card anatomical breakdown for the Label in LabelButton]]

Each card consists of a heading and table of scenarios for the child. Often, there may only be one scenario, the <code>default</code>: a condition is not necessary, but <code>any</code> may be used to indicate that it applies to any state. Each column in the scenario table has a condition that describes it, a visual preview, and a list of property declarations. Property declarations are how values are assigned to the child.

The visual preview is non-normative and intended only as a guide. The property declarations are authoritative so take care to get them right.

== Heading ==

The heading is the name of the child. It is used to identify what component is being used. Any referenced component should already be defined in the specifications. If there are multiple children that are instances of the same component (e.g. two labels), they should be renamed using an alias.

=== Aliases ===

Aliases are named instances of components. An alias can have conditional styling not present on the main component. Aliases take the format <code>OriginalComponentName:Alias</code> (e.g. <code>TableRow:EmptyRow</code>). An alias is referred to by its assigned name (<code>EmptyRow</code> is how we refer to the child).

Aliases can be a convenient way to customize a component and reuse the customization without having to redeclare the customization for each use case.

=== Example: TitleBar ===

[[File:TitleBar_preview.png|492px|Preview of the TitleBar component]]

<code>TitleBar</code> customizes the <code>IconButton</code> for use as the minimize, maximize, and close buttons. Because the custom styling is shared, aliasing provides a concise way to declare the customizations.

[[File:TitleBar_components.png|720px|Definition cards for TitleBar's children]]

In the example, <code>TitleBarButton</code> is an alias for <code>IconButton</code> with customizations for when it is <code>not active</code> and <code>hover</code> '''or''' <code>press</code>.

The buttons <code>Minimize</code>, <code>Maximize</code>, and <code>Close</code> are themselves aliases for <code>TitleBarButton</code>, with further customization for the icon and, in the case of <code>Close</code>, a different styling for <code>hover</code> '''or''' <code>press</code>.

Aliases make the scenarios more readable, as only the differences are listed for each alias. For <code>Maximize</code>, it is more clear that there is conditional styling for the icon used than it would be if all scenarios were declared on the same card.

Note that <code>TitleBarButton</code> is a ''virtual child'': it doesn’t actually appear anywhere in the layout of <code>TitleBar</code>. The designer is free to make arbitrary virtual children provided they make the document more readable.

=== Multiples ===

Frequently, the children of a component will be multiples of the same type, and the same conditional styles apply to all of them. In these cases, one child is given a card and it is referred to as one item in a list using array indexing (e.g. <code>Label</code> becomes <code>Label[i]</code> to indicate the ''ith'' <code>Label</code> in a list).

=== Example: ClosedFilterPanel ===

[[File:ClosedFilterPanel_components.png|720px|Definition cards for ClosedFilerPanel's children]]

The <code>ScrollableListBox</code> contains customized <code>ListItem</code>. These are indicated as <code>ListItem[i]</code>. Each <code>ListItem</code> contains a <code>CheckBox</code>, which becomes <code>CheckBox[i]</code> in the card, as there are multiple checkboxes. This notation can also be used to target specific items in the list, such as only the even items (<code>2i</code>) or the first item (<code>0</code>), but such usage is rare.

== Scenarios ==

Scenarios are conditions in which children can be in. These are like variants or states.

Scenarios are used to set properties on children. Data and styling properties are set in <code>components.xd</code>, while layout properties (e.g. <code>height</code>, <code>width</code>) are reserved for <code>layout.xd</code>.

=== Example: LabelButton ===

[[File:LabelButton_components.png|720px|Definition card for the LabelButton's children]]

<code>LabelButton</code> has conditional styling based on whether the <code>Button</code> is:
* <code>disabled</code>
* <code>focus_visible</code>
* <code>press</code>
* <code>hover</code>

These conditions are the scenarios.

Scenarios are evaluated from right to left: the first scenario that matches is the one that is evaluated.

All properties declared under a scenario are applied. Any undeclared properties are inherited from the <code>default</code> scenario. Any properties undeclared in the <code>default</code> scenario are inherited from the defaults for that child.

=== Example: HeaderCell ===

Scenarios can consist of one or more selectors, which can be chained using newlines or commas to indicate <code>or</code> conditions.

[[File:ResizeHandle_definition.png|720px|Definition card for ResizeHandle from HeaderCell]]

In the example, <code>ResizeHandle</code> receives a specific <code>background_color</code> and <code>pointer</code> when <code>Sash</code> is <code>hover</code> '''or''' when <code>Sash</code> is <code>drag</code>. <code>Sash</code> is another child of <code>HeaderCell</code>.

== Selectors ==

Selectors are used to compose conditions for scenarios. They take the form:

<pre>A state [[combinator B and state]]</pre>
<code>A</code> is the name of the child being defined. It may be omitted. <code>state</code> is the state of <code>A</code>. The double-bracket enclosed parts are optional.

=== State ===

<code>any</code> is used when no specific state applies and may be omitted for the <code>default</code> scenario. Outside of the <code>default</code> scenario, <code>state</code> is mandatory.

<code>state</code> must refer to a property that exists on the child. If it exists, it is declared in the model of the child (or the model of the component that the child wraps or extends). For example: <code>hover</code>, <code>disabled</code>, <code>focus</code>, <code>focus_visible</code> are all declared in the model for <code>component</code>, which is the base for all components.

=== Combinators ===

<code>combinator</code> are operators that indicate a relation between two components. The child being styled is always on the left, the <code>combinator</code> indicates the relation between child and the component that determines the condition:

* <code>A < B</code> means <code>B</code> is a parent of <code>A</code>
* <code>A > B</code> means <code>B</code> is a child of <code>A</code>
* <code>A ~ B</code> means <code>B</code> is a general sibling of <code>A</code>

<code>A</code> can be omitted, as it always refers to the child being defined. When <code>B</code> is omitted and the combinator is <code><</code>, <code>B</code> is implicitly interpreted to be the parent for the <code>components.xd</code>.

=== Example: HeaderCell ===

[[File:ResizeHandle_definition.png|720px|Definition card for ResizeHandle from HeaderCell]]

Returning to the <code>ResizeHandle</code>, the <code><</code> combinator tells us that <code>Sash</code> is a parent of <code>ResizeHandle</code>. The <code>ResizeHandle</code> is styled based on when its parent <code>Sash</code> is <code>hover</code> '''or''' <code>drag</code>.

=== Visual Preview ===

The visual preview is non-normative but should be provided wherever possible and made as correct as is feasible. When data is displayed in the preview, variables may be cascaded using angle brackets < >, or representative data may be used. Generally, cascading the variables is preferred, but optimize for readability.

== Properties ==

Properties come from the child being defined. To see what properties are available on a component, refer to its <code>model.txt</code>.

=== Common Components ===

The most commonly referenced properties come from the following:

==== Component ====

All components have these properties available, it is worth being familiar with them. The most commonly referenced states (<code>hover</code>, <code>disabled</code>, <code>active</code>, etc.) are available through <code>Component</code>.

==== Box ====

All styled components are derived from <code>Box</code>. All the common style properties (padding, borders, color, etc.) are available through <code>Box</code>.

==== TextBox ====

All displayed text is derived from <code>TextBox</code>. Text styling properties (font, alignment, text color, etc.) are available through <code>TextBox</code>.

=== Property Definitions ===

If a property is not defined in the model, it doesn’t exist, even if a similar property exists in CSS or some other language. New properties can be added as needed by updating the appropriate model.

When a component changes its appearance based on a composite of conditions, it can be convenient to use a named property for those conditions. That enables other components to easily style the component as a child, based on the property. Consider the following excerpt from the model for <code>DecimalBox</code>:

<pre> up_tick: The current value has increased.
down_tick: The current value has decreased.
positive: The current value is positive.
negative: The current value is negative.</pre>
<code>DecimalBox</code> can be readily styled based on whether the current value has increased or decreased or is positive or negative without having to define that logic anytime the styling is desired.

=== Slots ===

There is precedent for using properties to swap one child for another, akin to using slots in some templating frameworks (slots here refer to placeholder components and not functions in the Qt sense of the term). It is preferrable to plan for this by assigning a name for the intended slots in the model, but it can be done without a specific property in the model provided the components being swapped have the same functionality or will not otherwise interfere with the user flow.

==== Example: QuantityFilterPanel ====

[[File:QuantityFilterPanel_components.png|720px|Definition cards for QuantityFilterPanel's children]]

In the example, <code>ScalarFilterPanel</code> has two <code>DecimalBox</code> children aliased as <code>MinValue</code> and <code>MaxValue</code>. These are swapped with the children <code>MinQuantity</code> and <code>MaxQuantity</code> using property assignment, themselves aliased <code>QuantityBox</code> children. Because <code>QuantityBox</code> is simply a customized <code>DecimalBox</code>, this swap is non-breaking.

While properties are always '''snake_case''', named components are '''PascalCase'''.

==== Example: Box ====

<pre>Data:
body: The component displayed in the box.</pre>
The above excerpt from the model for <code>Box</code> defines <code>body</code> as a property that is a component. This makes it clear that any component can be displayed inside <code>Box</code>. This is the preferred way for defining a slot in a component. When the component needs to be type-restricted (e.g. only a <code>DecimalBox</code>), this can be made explicit in the model.

=== Animations ===

Animations are just values in Spire, so they can be declared directly as property values.

To have an animated color sequence on a <code>Box</code>, its <code>background_color</code> property would be declared using a function that switches between colors.

<syntaxhighlight lang="css">border_color: chain(timeout(#B71C1C, 550ms), revert)</syntaxhighlight>
In the above snippet, the <code>border_color</code> property is set to change to a red color for 550ms and then revert to its previous color.

=== Filepaths ===

Filepaths are valid values for certain properties, such as SVGs for icons. The root folder is the folder for the component. By convention, assets belong in an /assets folder. To specify an icon:

<syntaxhighlight lang="css">icon: /assets/custom-icon.svg</syntaxhighlight>
The parent folder for all specs can also be referenced as the root folder:

<syntaxhighlight lang="css">icon: /ui_kit/assets/window_icons/dashboard.svg</syntaxhighlight>

=== Variables and Strings ===

Whether the property declaration is a variable or should be interpreted as a string value is inferred from context. Variables are normally assumed. Double quotes can be used to indicate that a string is being specified (useful when there is whitespace). Variables can be output inside a string using concatenation or angle brackets for string interpolation.

<syntaxhighlight lang="css">current: “The price is <price>”</syntaxhighlight>
In the above example, a variable named <code>price</code> is interpolated into a string. The output would look like: '''The price is 9.99'''. The following achieves the same result:

<syntaxhighlight lang="css">current: “The price is ” + price</syntaxhighlight>

=== Expressions ===

Any expression that evaluates to a value can be set as a property. Revisiting the animation example:

<syntaxhighlight lang="css">border_color: chain(timeout(#B71C1C, 550ms), revert)</syntaxhighlight>
* <code>chain(X, Y)</code> is an animation that applies animated style <code>X</code> until <code>X</code> ends, and then applies style <code>Y</code>
* <code>timeout(X, Y)</code> applies the style <code>X</code> for a period of <code>Y</code>
* <code>revert</code> is a style that applies whatever style would have otherwise been applied

The result is a sequence of values for <code>border_color</code> that changes over time. Basic math operators and self-explanatory functions can also be used. This can be useful for formatting, as in the following <code>FormattedDecimalLabel</code> example:

<syntaxhighlight lang="css">current: “<DecimalLabel.current * 100>%”</syntaxhighlight>
The variable <code>DecimalLabel.current</code> is multiplied by 100 and then formatted with a % sign.

Generally it is preferable to avoid using complex expressions in property declarations as it makes <code>components.xd</code> less readable. Expressions should be done in consultation with a developer. If considering conditional expressions, try to restructure it into a separate scenario with a comparatively simple expression.

=== Bindings ===

When a property declaration expression contains dependencies (other variables) and those dependencies update, the property is automatically assumed to update. In the following example from <code>FormattedDecimalLabel</code>

<syntaxhighlight lang="css">current: “<DecimalLabel.current * 100>%”</syntaxhighlight>
Whenever <code>DecimalLabel.current</code> changes, <code>current</code> here will also change. It is not simply an initialization that is set once. Presently, there is no formal way of specifying that a declaration should be an initialization only and non-binding as a use-case has not come up.

== Ordering ==

List children top to bottom from innermost to outermost. If there are children at the same level in the hierarchy (siblings), they should be ordered from simplest to most complex (a more complex component is one with more children, e.g. <code>ListItem</code> is simpler than <code>ScrollableListBox</code>). If siblings have the same complexity, they should appear in the order they occur when scanning the component from left to right and top to bottom. Each child occupies a full row, with its scenarios separated into columns.

=== Example: AccountListItem ===

[[File:AccountListItem_preview_outline.png|Preview of AccountListItem with children marked]]

In the <code>AccountListItem</code> example, there are three children responsible for displaying three pieces of data: - Identicon: an <code>Icon</code> that displays the identicon for the account - ID: a <code>Label</code> that displays the account user id - Name: a <code>Label</code> that displays the name associated with the account

[[File:AccountListItem_components.png|720px|Definition cards for AccountListItem's children]]

With the exception of <code>Identicon</code>, the children are siblings, so the ordering of them follows their layout. Note that there is a <code>Box</code> named <code>IdenticonBox</code> that contains the <code>Identicon</code> and it comes below the <code>Identicon</code>.

=== Example: OpenFilterPanel ===

[[File:OpenFilterPanel_preview_outline.png|720px|Preview of OpenFilterPanel with children marked]]

The outermost component is <code>FilterPanel</code>. It contains a reset button and a slot for placing the specific filtering controls. Since the <code>components.xd</code> for <code>FilterPanel</code> already handles the reset button, it doesn’t need to be handled here. The direct children of the slot are <code>RadioButtons</code>, a group of two radio buttons, and <code>TagComboBox</code>. The radio buttons <code>Include</code> and <code>Exclude</code> are the children of <code>RadioButtons</code>.

[[File:OpenFilterPanel_components.png|720px|Definition cards for OpenFilterPanel's children]]

In the breakdown, <code>Include</code> and <code>Exclude</code> come first, followed by <code>RadioButtons</code> and <code>TagComboBox</code>, with <code>FilterPanel</code> last.

== Usage ==

It is recommended to use <code>components.xd</code> as fully as possible before considering putting information into <code>layout.xd</code> or <code>user_flow.drawio</code>. Conditional styling via scenarios is a powerful and readable way to declaratively style a component.

Components - Revision history

Jon: Describes components.xd for a UI component specification: how to get started, how to define a component in terms of its children, how to define scenarios using selectors, and how to set property declarations.