Spire Trading Inc. - User contributions [en]

Layout

2026-07-07T20:32:06Z

Jon: Created page with "<code>layout.xd</code> defines the visual composition for a component and its child elements. It’s required whenever a new element arrangement is needed. <code>layout.xd</co..."

<code>layout.xd</code> defines the visual composition for a component and its child elements. It’s required whenever a new element arrangement is needed. <code>layout.xd</code> is not necessary when it inherits its layout from another component and does not modify that layout. For example, <code>Label</code> is a customized <code>TextBox</code> that makes no changes to the layout, so <code>layout.xd</code> is not needed.

This document is the go-to for widths, heights, and positions; it takes precedence in the event of conflicts with <code>preview.xd</code> or <code>components.xd</code>. However, dynamic adjustments tied to user input can override it, as specified in <code>user_flow.drawio</code>.

While <code>components.xd</code> outlines the parts of a component, <code>layout.xd</code> is about fitting these parts together. <code>layout.xd</code> answers the question: “What goes where?” It should include the following details:
* '''Position:''' Specifying where child components are positioned relative to each other.
* '''Size Policy:''' Define the size or proportions of child components and how they change with resizing.
* '''Spacing:''' Detailing the spacing or gaps between child components.
* '''Layer Hierarchy:''' How the elements of a child component are visually stacked.

== Getting Started ==

<code>layout.xd</code> comes after <code>preview.xd</code>, <code>model.txt</code>, and <code>components.xd</code>. It is generally advised to ensure <code>components.xd</code> is finalized first, as the names defined there carry over to <code>layout.xd</code>.

<code>layout.xd</code> communicates spatial relations (position and size policy) through a primarily visual language. Each element is portrayed as a rectangle, with constraints along each edge indicated by edge color. When first learning the system, start by reviewing the [https://drive.spiretrading.com/f/91480 layout reference document].

Before starting <code>layout.xd</code>, the visual design for all scenarios should already be worked out, with the key ones ideally captured in <code>preview.xd</code>. Use <code>layout.xd</code> to formalize the layout.

Sketch the component’s layout and that of each child at the preferred size. Maintain simplicity by restricting layouts to a single depth level; nesting layouts within layouts isn’t a convention in the visual layout language. If a child’s layout is specified elsewhere and remains unchanged, omit it. When included, consider it an ''override'': the specified layout takes precedence over the existing one within the component instance.

=== Example: Slider ===

[[File:Slider_preview.png|640px|center|A Slider component that can be oriented horizontally or vertically]]

From the preview, we can see that <code>Slider</code> has a different layout depending on its orientation. Based on the examples, it appears that the thumb and the track are customizable.

<pre>Styles:
orientation: The orientation of the slider.
HORIZONTAL - The thumb can be dragged horizontally.
VERTICAL - The thumb can be dragged vertically.

Data:
current: The current value represented by the slider. Cannot be null.
Defaults to halfway between min and max.
min: The minimum value that current is allowed to be. Default 0.
max: The maximum value that current is allowed to be. Default 100.
step: The granularity that current must adhere to. Default 0.
default_increment: The amount of change in current when the user increments or
decrements the slider.
shift_increment: The amount of change in current when the user increments or
decrements the slider while holding the shift key.
track: The component representing the track of the slider.
thumb: The component representing the thumb of the slider.
...</pre>

The model for <code>Slider</code> shows a style <code>orientation</code> (<code>HORIZONTAL</code> | <code>VERTICAL</code>) corresponding to the preview. There are also two slots <code>track</code> and <code>thumb</code>, indicating that these are customizable.

[[File:Slider_components.png|640px|center|Components breakdown of a Slider component]]

In <code>components.xd</code>, child names and styles are defined.

[[File:Slider_layout_Thumb.png|640px|center|Layout definition for the Slider Thumb]]

[[File:Slider_layout_Track.body.png|640px|center|Layout definition for the Slider Track]]

[[File:Slider_layout_Box.body.png|640px|center|Layout definition for the Slider Box]]

[[File:Slider_layout_Slider.png|640px|center|Layout definition for the Slider]]

By contrast with <code>components.xd</code>, in <code>layout.xd</code> the bottommost (outermost) element receives the title of the component itself. This is necessary to clarify how the component’s children are arranged within it and to provide its size constraints. In the above, <code>Slider</code> is a <code>Box</code> that contains <code>track</code> on layer 0 and <code>thumb</code> on layer 1.

'''Note''': The <code>Box</code> did not appear in <code>components.xd</code> as no customization is done to it, but it is required in <code>layout.xd</code> to define <code>Slider</code>. The use of <code>Box</code> means that components using <code>Slider</code> can customize it with <code>Box</code>-specific styling such as <code>border</code>, <code>padding</code>, and <code>background_color</code>.

Separate layers in <code>Box.body</code> allow for overlap between <code>thumb</code> and <code>track</code>. Similarly, two layers are used in the layout of <code>Track.body</code> for <code>Rail</code> and <code>Fill</code>. To avoid overriding <code>Track</code>’s layout, <code>Track.body</code> is laid out instead. Generally, when a component has slots, composition is done by laying out the slots without altering the overall layout.

The width of <code>Fill</code> is determined by an expression, creating a ''binding'' that updates with model property changes.

<code>Thumb</code> is laid out directly using absolute <code>FIXED</code> size. Here, an ''anonymous'' element is used to specify the size without overriding the layout.

To understand <code>layout.xd</code>, one must be familiar with Spire’s visual layout language.

== Visual Layout Language ==

Within <code>layout.xd</code>, each element has a specific color and an identifier, rather than appearing as they do in <code>preview.xd</code>. These colors convey size constraints.

=== Elements ===

Layouts are composed of ''elements'', representing components like <code>Box</code> or <code>Button</code>, spacers for visual separation, or containers strictly for layout. Elements are generally depicted as rectangles, with center-aligned identifiers like <code><ElementName></code>. The appearance of the identifier doesn’t align with text orientation within the element. An element without an identifier is ''anonymous''. Each element can be thought of as having <code>top</code>, <code>bottom</code>, <code>left</code>, and <code>right</code> for its position and <code>width</code> and <code>height</code> for its size.

[[File:Element Basics.png|640px|center|Diagram of a box identifying its left, top, right, bottom, width, height and identifier]]

=== Size Constraints ===

Elements are sized through either fixed dimensions, expressed in pixels, or by occupying all available container space. An element’s size may also come from its contents, but ultimately any contents are either <code>FIXED</code> or <code>FILL</code>.

{| class="wikitable"
|-
! Constraint
! Meaning
|-
| <code>FIXED</code>
| The size of the component is a literal value that comes directly from the visual. An element drawn 12px wide is rendered 12px wide. As the size of the layout changes, the element size is unchanged.
|-
| <code>FILL</code>
| The size of the component fills the available space. The literal size of the depicted element represents the ''preferred'' size if no preferred size can be determined from the layout bottom-up. As the size of the layout changes, the element shrinks or grows to fill all available space. When multiple components in a layout have this constraint, the available space is distributed equally among them.
|-
| <code>FIT</code>
| The size of the component is determined by its contents. The literal size of the depicted element represents the ''preferred'' size if no preferred size can be determined from the layout bottom-up. This is often used for text which takes on a fixed value at any time, but changes dynamically or for windows that can be resized by the user and simultaneously restricted by their contents.
|}

Uniform constraints (same in both axes) encode edges and background color with the appropriate constraint color. For non-uniform constraints, edges are color-encoded, and the background remains neutral. Optionally, a neutral background helps distinguish adjacent components with identical constraints.

[[File:LayoutSpecificity.png|640px|center|Diagram of a box with shaded edges indicating vertical and horizontal constraints]]

Color-encoding for borders and backgrounds is as follows:

[[File:LayoutColorSemantics.png|640px|center|Diagram of different colored boxes with each color mapped to its interpretation within the layout]]

A <code>Repeat</code> element can be used to describe repetitive layouts. <code>Repeat</code> duplicates adjacent layouts, following the color-encoded <code>Repeat Direction</code>. It is useful for dynamic lists where the content dictates the number of items.

[[File:LayoutExamples.png|640px|center|Diagram of different boxes representing different possible layout elements based on their size constraints]]

==== Example: Box ====

[[File:Box_preview.png|640px|center|Preview of the Box component]]

<code>Box</code> establishes the basic style properties. The relevant properties are detailed in <code>model.txt</code>:

<pre>Styles:
border_top_size: The height of the top border.
border_right_size: The width of the right border.
border_bottom_size: The height of the bottom border.
border_left_size: The width of the left border.
...
padding_top: The amount of padding on the top of the box.
padding_right: The amount of padding to the right of the box.
padding_bottom: The amount of padding on the bottom of top of the box.
padding_left: The amount of padding to the left of the box.
...

Data:
body: The component displayed in the box.
</pre>

<code>Box</code> has a <code>border</code>, <code>padding</code>, and a <code>body</code>. <code>border</code> and <code>padding</code> are specified as fixed sizes for each edge, while <code>body</code> can be any component. <code>layout.xd</code> for <code>Box</code> shows how these elements are arranged:

[[File:Box_layout.png|640px|center|Diagram of a box labelled <body> with edges denoted as <padding> and <border> where each edge is a separate element]]

In the layout, <code>body</code> adopts <code>FIT</code> constraints on all sides. By default, the size of the <code>Box</code> adapts to its content. <code>padding</code> is specified with separate components for each edge using <code>FIXED</code> constraints. <code>border</code>, akin to <code>padding</code>, uses the same specifications but lies outside it. The layout makes clear that <code>border</code> extends beyond <code>padding</code>, and both consume space that <code>body</code> cannot occupy.

'''Note:''' <code>Box</code> introduces a unique scenario as both <code>border</code> and <code>padding</code> elements converge at angles, presenting trapezoids instead of rectangles.

=== Position Constraints ===

The positioning of an element is considered relative to its container.

[[File:Positioning 1.png|640px|center|Diagram of a rectangular <Item> inside a rectangular container with its distances to the container edges highlighted]]

In the above diagram, the element <code>Item</code> is placed inside a container at some distances to its edges. Within the visual layout language, the layout must be drawn so that all of the space is taken up by elements, as shown below:

[[File:Positioning 2.png|640px|center|Diagram of a rectangular <Item> inside a rectangular container with its distances to the container edges filled by rectangular elements denoted <A>, , <C>, and <D> ]]

Above, the position of <code>Item</code> is defined by the surrounding elements <code>A</code>, <code>B</code>, <code>C</code>, and <code>D</code>. These elements can be other components or ''anonymous'' and they each have their own size constraints. How <code>Item</code> is positioned will depend on the ''size'' of the adjacent elements. The layout ensures no underflow, meaning no unoccupied space between components (the gaps shown in the diagram are for illustration only).

Edges of elements that touch are bound together. Where the right edge of <code>A</code> is adjacent to the left edge of <code>B</code>, it signifies <code>A.right = B.left</code>. Likewise, where the bottom edge of <code>B</code> aligns with the top edge of <code>Item</code>, it signifies <code>B.bottom = Item.top</code>.

==== Example: A Fixed and B Fill ====

[[File:Example1_1.png|640px|center|Layout of two adjacent elements <A> and where <A> is FIXED size and is FILL]]

In this scenario, <code>A</code> is <code>FIXED</code>, signifying a literal size, while <code>B</code> has <code>FILL</code> constraints so that it occupies the available space.

When the width is reduced, <code>B</code> goes to zero width:

[[File:Example1_2.png|640px|center|Layout of two adjacent elements <A> and where <A> is FIXED size and is FILL and there is no available space so is not visible]]

When the width is increased, <code>B</code> stretches to fill the available space:

[[File:Example1_3.png|640px|center|Layout of two adjacent elements <A> and where <A> is FIXED size and is FILL and there is lots of available space so is very wide]]

For the horizontal direction, the constraints are:

<pre>A.left = left
A.right = left + 128px
B.left = A.right
B.right = right</pre>

And in the vertical direction:

<pre>A.top = top
A.bottom = top + 128px
B.top = top
B.bottom = bottom</pre>

Since underflow is forbidden, the layout cannot exceed the height of <code>A</code>: there’s nothing to occupy the additional space.

=== Spacers ===

Negative space is specified with spacers — elements absent from <code>components.xd</code> and devoid of interactive and styling attributes. Spacers, often ''anonymous'', serve the sole purpose of defining space between components.

'''Note:''' Negative space can also be introduced by using internal padding on adjacent components. Doing so is often preferred for <code>FIXED</code> spacing.

==== Example: A Fixed and B Fixed ====

[[File:Example2_1.png|640px|center|Layout of two adjacent elements <A> and where <A> is FIXED size and is FIXED and there is FILL space between them]]

In this scenario, both <code>A</code> and <code>B</code> are <code>FIXED</code>, with literal sizes of 128px in <code>width</code> and <code>height</code>. They are positioned on opposite ends of the layout through the use of a spacer that is constrained to <code>FILL</code> the available space. The spacer lacks an identifier: it is ''anonymous''.

When the width of the layout is reduced, the spacer collapses and <code>A</code> and <code>B</code> touch:

[[File:Example2_2.png|640px|center|Layout of two adjacent elements <A> and where <A> is FIXED size and is FIXED and there is zero space between them]]

When the width of the layout is increased, the spacer expands to fill the available space:

[[File:Example2_3.png|640px|center|Layout of two adjacent elements <A> and where <A> is FIXED size and is FIXED and there is lots of available space between them]]

For the horizontal constraints:

<pre>A.left = left
A.right = left + 128px
spacer.left = A.right
spacer.right = B.left
B.left = right - 128px
B.right = right</pre>

For the vertical constraints:

<pre>A.top = top
A.bottom = top + 128px
spacer.top = top
spacer.bottom = bottom
B.top = top
B.bottom = top + 128px</pre>

=== Containers ===

Layouts can be subdivided at the designer’s choosing using containers. They are used to encapsulate the arrangement of elements. Unlike spacers, containers cannot be anonymous; they require identification for referencing.

==== Example: ListView ====

When <code>direction = VERTICAL and overflow = WRAP</code> , the layout is divided into containers named <code>Column</code>. <code>Column</code> is purely a layout element, without any representation in <code>components.xd</code>

[[File:ListView_layout.png|640px|center|Layout diagram showing <Column> elements repeated from left to right]]

The layout for <code>Column</code> is shown the same as for any other component.

[[File:ListView_layout-2.png|640px|center|Layout diagram showing <Item> elements repeated from top to bottom]]

=== Example: TitleBar ===

[[File:TitleBar_preview-2.png|640px|center|Preview of Title Bar component]]

From <code>preview.xd</code>, we can see that <code>TitleBar</code> consists of a few elements:
* Icon
* Title
* Window controls
* Container

The height of <code>TitleBar</code> is constant, while its width can vary.

[[File:TitleBar_components.png|640px|center|Components breakdown of Title Bar component]]

<code>components.xd</code> introduces aliases:
* WindowIcon
* WindowName
* Minimize, Maximize, and Close
* Box

Appearance tweaks—background colors, icons, and title text—are handled in the property declarations.

[[File:TitleBar_layout.png|640px|center|Layout breakdown of Title Bar component]]

<code>WindowIcon</code> is an <code>Icon</code> with <code>FIXED</code> size of 10px that is vertically centered. Top and bottom spacers with <code>FILL</code> size ensure center alignment.

'''Note:''' Centering is indicated because the two elements are equally sized. Any positional bias could be provided by adjusting the relative sizes of the spacers.

The contents of <code>TitleBar</code> are arranged in <code>Box.body</code>:
* <code>WindowIcon</code> is given a vertical constraint of <code>FILL</code> and a horizontal constraint of <code>FIT</code>. It will be as tall as allowed by <code>Box</code> and only as wide as required by its content.
* <code>WindowName</code> is constrained vertically as <code>FILL</code> and horizontally as <code>FILL</code>, adapting to available space.
* <code>Minimize</code>, <code>Maximize</code>, and <code>Close</code> are all given constraints of <code>FIXED</code> in height and width (22px x 26px). Their literal size is defined by the visual.

<code>Box</code> is the container with a vertical constraint of <code>FIT</code> and a horizontal constraint of <code>FILL</code>. An expression for width restricts its minimum size.

<syntaxhighlight lang="css">width: max(FIT_CONTENT, 100%)</syntaxhighlight>
This takes precedence over the sketch.

The layout ensures that <code>TitleBar</code> matches the width of its parent window without getting so narrow that the user is unable to interact with the controls.

== Anatomy ==

The structure of <code>layout.xd</code> is a vertical list of sections, each dedicated to the layout of a single element. Each section is divided into a grid with columns for scenarios and rows for layers and property declarations.

==== Example: SplitView ====

[[File:SplitView_layout_anatomy.png|640px|center|Structural breakdown of Layout definition on Split View component]]

The heading is the name of the element being laid out.

Layers are stacked vertically in the column for a scenario. If only one layer is needed, the layer name is omitted.

When the scenario shown is the default condition, the scenario condition heading is omitted.

Each scenario and layer has a layout. Layouts are sketched at 1:1 scale.

At the bottom of each column are property declarations. These declarations supersede visual layout statements. They are useful for specifying sizes that are impractical to depict visually and for incorporating expressions.

== Heading ==

The heading identifies the element that is being laid out. If an alias is assigned in <code>components.xd</code>, the alias is used.

== Scenarios ==

Scenarios are used to create conditional layouts. While the presence or absence of components can be handled in <code>components.xd</code> using the <code>visibility</code> property, specific positioning of children must be specified in <code>layout.xd</code>

==== Example: OverlayPanel ====

<pre>Data:
parent: The component that showed the OverlayPanel.
...
positioning: Specifies the positioning of the panel relative to the parent:
NONE: The panel is not positioned relative to any other component.
PARENT: The panel is positioned relative to the parent. Default.

State:
vertical_orientation: Whether the OverlayPanel is placed above or below the
its parent, this is determined based on the position
of the parent and the size of the body. If the body
can fit entirely below the parent then the orientation
will be BELOW, otherwise it will be ABOVE.
BELOW: The OverlayPanel is below the parent.
ABOVE: The OverlayPanel is above the parent.

...</pre>

[[File:OverlayPanel_layout.png|640px|center|Layout definition for Overlay Panel component]]

<code>OverlayPanel</code> has a conditional layout based on whether the panel is:
* <code>default</code>
* <code>positioning = PARENT and vertical_orientation = BELOW</code>
* <code>positioning = PARENT and vertical_orientation = ABOVE</code>

These are the scenario conditions.

Scenario evaluation follows a right-to-left sequence: the first matching scenario takes effect. In the <code>OverlayPanel</code> example, the match depends on <code>parent</code>’s location relative to the screen and the size of <code>Box</code>.

Scenario conditions are written using selectors. Refer to the [https://wiki.spiretrading.com/index.php/Components#Selectors documentation for selectors on components] for details on using selectors to specify a condition.

== Layers ==

Layouts can be separated into layers. This is done by prepending <code>layer n:</code> before the layout, where <code>n</code> is the layer number. Layers are zero-indexed and arranged vertically from bottom to top. Lower layers have ''z-priority''.

Layers are useful for specifying where components need to overlap.

=== Example: DecimalBox ===

[[File:DecimalBox_layout.png|640px|center|Layout definition for Decimal Box component]]

A <code>TextBox</code> is placed on layer 0 while the step buttons <code>Increment</code> and <code>Decrement</code> are placed on layer 1. This allows the step buttons to be visually nested in the <code>TextBox</code> without modifying the <code>TextBox</code> layout.

[[File:DecimalBox_preview.png|640px|center|Preview for Decimal Box component]]

== Layout ==

The layout is a 1:1 scale sketch of the scenario using the visual layout language. The size used to represent a layout is the ''preferred size''.

Through the use of the visual layout language and property declarations, the layout fully specifies the positions and sizes of an element’s children for all possible sizes of the element.

== Identifier ==

Each element is labeled with an identifier. The identifier is shown in angle brackets as <code><ElementName></code>. Naming follows the '''PascalCase''' convention from <code>components.xd</code>.

When an identifier matches the name of an existing component, the layout is for an ''instance'' of that component.

''Slots'', components specified in <code>model.txt</code> under Data, earmark children open to substitution with different components. When identifying slots, the '''snake_case''' convention from <code>model.txt</code> is used.

When an identifier does not match a component name or a slot, the layout is for a spacer or a container used for organizational purposes within the document.

=== Example: SplitView ===

The model for <code>SplitView</code> shows two slots: <code>primary</code> and <code>secondary</code>.

<pre>...
Data:
primary: The primary pane.
secondary: The secondary pane.
...</pre>

In <code>layout.xd</code>, these are represented as <code><primary></code> and <code><secondary></code>.

[[File:SplitView_layout.png|640px|center|Layout definition for Split View component]]

Additionally, three named elements are depicted—<code>Padding</code>, <code>Offset</code>, and <code>Sash</code>. These lack correspondence to any components or slots and serve as reference points for property declarations.

While <code>Padding</code> is intended to be 2px wide, it’s shown at an enlarged size for readability. The declaration is used to provide the true size. A similar approach applies to <code>Sash</code>.

== Multiples ==

In a component, you might have several instances of the same type, and their layouts could be identical. In such cases, the element identifiers in <code>layout.xd</code> drop the index found in <code>components.xd</code>.

=== Example: ListView ===

[[File:ListView_components.png|640px|center|Component definition for List Item within List View component]]

In <code>components.xd</code> there is a child <code>Item[i]</code>, as there are multiple <code>Item</code> children depending on the data given to <code>ListView</code>.

[[File:ListView_layout-2.png|640px|center|Layout diagram showing <Item> elements repeated from top to bottom]]

However, in <code>layout.xd</code>, we simply use <code>Item</code> without an index in the identifier. Because the layout is positioning the items, specific index values would not accurately convey our intent. Instead, the <code>Repeat</code> element is used to signify repetition and dictate the direction.

== Property Declaration ==

Property declarations take precedence over the visual layout. Properties come from the child being defined. To understand what’s available, consult its <code>model.txt</code>. Generally, only size and position properties, such as <code>width</code>, <code>height</code>, and <code>position</code> should be declared in <code>layout.xd</code>.

The key properties are as follows:

{| class="wikitable"
|-
! Property
! Definition
|-
| <code>width</code>
| The width of the component in pixels.
|-
| <code>height</code>
| The height of the component in pixels.
|-
| <code>position</code>
| The position of the component relative to its parent, if the component has no parent, then the position is equal to <code>screen_position</code>.
|-
|
| <code>x</code> The x-coordinate in pixels.
|-
|
| <code>y</code> The y-coordinate in pixels.
|}

Property declarations are made using expressions which support basic mathematical operators (<code>+</code>, <code>×</code>, <code>/</code>, <code>-</code>) and various functions. These are used for more complex constraints that are not easily visually represented.

A fluid layout with a minimum width of 20px and a maximum width of 100px can be specified as:

<syntaxhighlight lang="css">width: clamp(20px, FILL_AVAILABLE, 100px)</syntaxhighlight>
The preferred size is the middle value (<code>FILL_AVAILABLE</code>), but it is bounded by 20px and 100px on either side.

Expressions containing dependencies establish a binding.

<syntaxhighlight lang="css">Offset.width: primary.width - (Sash.width - Divider.width) / 2</syntaxhighlight>
Whenever <code>primary.width</code> changes, <code>Offset.width</code> will also change.

=== Expression Values and Units ===

Expressions use a fixed set of units and preset values.

{| class="wikitable"
|-
! Unit / Value
! Description
|-
| <code>n</code> px
| A literal amount in pixels
|-
| <code>n</code> ch
| The width of the “0” character for the element font. A width value of <code>6ch</code> is approximately 6 characters wide in the specified font.
|-
| <code>n</code> em
| Represents the calculated font size of the element.
|-
| <code>n</code> %
| A percentage amount relative to the immediate parent layout
|-
| <code>FILL_AVAILABLE</code>
| Fills its parent
|-
| <code>FIT_CONTENT</code>
| Fits its contents
|}

Additional units may be used provided they have compelling use cases and are documented. The above units come from [https://developer.mozilla.org/en-US/docs/Web/CSS/length CSS]

=== Expression Functions ===

Any function can be used in an expression provided its definition is provided or it is sufficiently self-explanatory. In practice, it is best to stick to a limited set of functions. The following have been used in layout specifications:

{| class="wikitable"
|-
! Function !! Description
|-
| <code>min(a, b)</code> || The minimum of <code>a</code> and <code>b</code>
|-
| <code>max(a, b)</code> || The maximum of <code>a</code> and <code>b</code>
|-
| <code>clamp(lower, value, upper)</code> || <code>value</code>, clamped to between <code>lower</code> and <code>upper</code> (inclusive)
|}

These have CSS equivalents: - [https://developer.mozilla.org/en-US/docs/Web/CSS/min min()] - [https://developer.mozilla.org/en-US/docs/Web/CSS/max max()] - [https://developer.mozilla.org/en-US/docs/Web/CSS/clamp clamp()]

Expressions can also be set to animation values as outlined in the documentation on [https://wiki.spiretrading.com/index.php/Animations Animations].

==== Example: DropDownList ====

[[File:DropDownList_layout.png|640px|center|Layout definition for Drop Down List component]]

<code>DropDownList</code> sets the <code>width</code> to the greater of its parent’s width or the content width of the <code>ScrollableListBox</code>. The <code>height</code> is set dynamically to display either ten items or all available items, whichever is less.

== Ordering ==

When structuring <code>layout.xd</code>, maintain an order mirroring <code>components.xd</code>—from innermost to outermost. This ensures clarity and consistency.

=== Example: TabView ===

<code>components.xd</code> lists a <code>Box</code>, a <code>ScrollableListBox</code>, and a custom <code>ListView</code> that uses a <code>Tab</code> component for each <code>ListItem</code>.

[[File:TabView_components.png|640px|center|Components breakdown for Tab View component]]

From top to bottom, the order is:
* Tab[i]
* ListItem[i]
* ListView:TabList
* ScrollableListBox
* Box:TabBar

<code>layout.xd</code> lays out <code>TabView</code> as <code>TabBar</code> and <code>body</code>, along with two spacing elements. <code>TabBar</code> is laid out as <code>ScrollableListBox</code> and a spacer, and <code>ScrollableListBox</code> is laid out as <code>TabList</code>.

[[File:TabView_layout.png|640px|center|Layout breakdown for Tab View component]]

From top to bottom, the order is:
* ScrollableListBox
* TabBar
* TabView

Unlike <code>components.xd</code>, <code>TabView</code> itself is included in <code>layout.xd</code>. As in <code>components.xd</code>, <code>ScrollableListBox</code> comes before <code>TabBar</code> as the order moves from innermost to outermost. While <code>components.xd</code> lists <code>TabList</code>, <code>ListItem[i]</code> and <code>Tab[i]</code>, they are absent from <code>layout.xd</code>. As these components all specify their layouts and <code>TabView</code> does not override any of these layouts, they are omitted.

== Referencing ==

In property declarations, only elements positioned higher in the document can be referenced.

=== Example: HighlightPicker ===

[[File:HighlightPicker_layout.png|640px|center|Layout breakdown for Highlight Picker component]]

The property declaration in <code>OverlayPanel.body</code> references the width of <code>ListItem</code>:

<syntaxhighlight lang="css">HighlightPalette.width: 8 * ListItem.width</syntaxhighlight>
This is a valid reference, as <code>ListItem</code> is a child of <code>OverlayPanel.body</code> so the layout for <code>ListItem.body</code> comes above that for <code>OverlayPanel.body</code>.

== Adaptive Layouts ==

Sometimes it is necessary to specify a different layout according to the available space. Instead of a gradual transition of elements, a step-change may be appropriate such as switching between an even grid and a linear arrangement, or switching labels between a long-form and a short-hand. Consider the <code>TechnicalsPanel</code> from <code>BookView</code>:

[[File:TechnicalsPanel_preview.png|640px|center|Preview of a grid of technical indicators and their respective labels used within the Book View Window]]

The six technical indicators <code>High</code>, <code>Low</code>, <code>Open</code>, <code>Close</code>, <code>Def</code>, and <code>Vol</code> are shown stacked in a 3x2 grid or linearly as a 6x1 row. They are also shown either as a full name (e.g. <code>High</code>) or an abbreviation (e.g. <code>H</code>). There should be a step-change between the 3x2 and 6x1 arrangements, as a partially filled second row makes for more difficult reading. There should also be a step-change between full labels and abbreviations, since if the labels are not coordinated it becomes visually confusing.

This behavior is not specified directly in the visual layout language. Instead, a purpose-built component <code>AdaptiveBox</code> is used.

To use <code>AdaptiveBox</code>, the designer specifies each layout within <code>components.xd</code>. It is convention to use size-based naming: <code>ExtraSmall</code>, <code>Small</code>, <code>Medium</code>, <code>Large</code>, but this can be adjusted to suit the specific use-case. <code>AdaptiveBox</code> is placed in <code>components.xd</code> and its <code>components</code> property is set to a list containing the named layouts.

[[File:TechnicalsPanel_components.png|640px|center|Components breakdown of the Technicals Panel]]

The <code>components</code> are listed in order of largest size to smallest size when passed to <code>AdaptiveBox</code>. Within <code>layout.xd</code>, the layout for <code>AdaptiveBox</code> and each layout in <code>layouts</code> is specified.

[[File:TechnicalsPanel_layout.png|640px|center|Layout breakdown of the Technicals Panel]]

<code>AdaptiveBox</code> then manages which layout is displayed based on the available space. There is no specifying of fixed-pixel ''breakpoints''.

== Usage ==

When laying out children from <code>components.xd</code> that have been assigned an alias, use the alias to title the layout. When laying out a component slot, use dot notation to title the slot (e.g. <code>Box.body</code>) and avoid repeating the layout for the component itself.

<code>layout.xd</code> is used to bring a component together, formalizing the position and size relations of it and its children. Approach <code>layout.xd</code> after fully utilizing <code>components.xd</code> to enumerate the component’s children and with a firm understanding of how the component will adjust at different sizes.

== References ==

# [https://drive.spiretrading.com/f/91480 Layout Reference Document]
# [https://wiki.spiretrading.com/index.php/Components#Selectors Selectors Documentation]
# [https://developer.mozilla.org/en-US/docs/Web/CSS/length CSS Length Units]
# [https://developer.mozilla.org/en-US/docs/Web/CSS/clamp Clamp Function]

File:LayoutExamples.png

2026-07-07T20:04:11Z

Jon: Examples of various layout elements

== Summary ==
Examples of various layout elements

File:TechnicalsPanel layout.png

2026-07-07T19:56:18Z

Jon: Layout breakdown for Technicals Panel component

== Summary ==
Layout breakdown for Technicals Panel component

File:TechnicalsPanel components.png

2026-07-07T19:55:52Z

Jon: Components breakdown for Technicals Panel component

== Summary ==
Components breakdown for Technicals Panel component

File:TechnicalsPanel preview.png

2026-07-07T19:55:25Z

Jon: Preview of Technicals Panel component

== Summary ==
Preview of Technicals Panel component

File:TabView layout.png

2026-07-07T19:54:32Z

Jon: Layout breakdown for Tab View component

== Summary ==
Layout breakdown for Tab View component

File:TabView components.png

2026-07-07T19:54:07Z

Jon: Components breakdown for Tab View component

== Summary ==
Components breakdown for Tab View component

File:DropDownList layout.png

2026-07-07T19:53:33Z

Jon: Layout definition for Drop Down List component

== Summary ==
Layout definition for Drop Down List component

File:ListView components.png

2026-07-07T19:52:43Z

Jon: Component definition for List Item within List View component

== Summary ==
Component definition for List Item within List View component

File:SplitView layout.png

2026-07-07T19:41:18Z

Jon: Layout definition for Split View component in HORIZONTAL orientation

== Summary ==
Layout definition for Split View component in HORIZONTAL orientation

File:DecimalBox preview.png

2026-07-07T19:40:29Z

Jon: Preview of Decimal Box component

== Summary ==
Preview of Decimal Box component

File:DecimalBox layout.png

2026-07-07T19:40:04Z

Jon: Layout definition for Decimal Box component

== Summary ==
Layout definition for Decimal Box component

File:OverlayPanel layout.png

2026-07-07T19:39:30Z

Jon: Layout definition for Overlay Panel component

== Summary ==
Layout definition for Overlay Panel component

File:SplitView layout anatomy.png

2026-07-07T19:38:44Z

Jon: Structural breakdown of layout definition for Split View component

== Summary ==
Structural breakdown of layout definition for Split View component

File:TitleBar layout.png

2026-07-07T19:38:02Z

Jon: Layout for Title Bar component

== Summary ==
Layout for Title Bar component

File:TitleBar preview-2.png

2026-07-07T19:36:36Z

Jon: Preview of Title Bar component

== Summary ==
Preview of Title Bar component

File:ListView layout-2.png

2026-07-07T19:35:55Z

Jon: Layout definition for Column sub-component in List View component

== Summary ==
Layout definition for Column sub-component in List View component

File:ListView layout.png

2026-07-07T19:35:20Z

Jon: Layout definition for List View component

== Summary ==
Layout definition for List View component

File:Example2 3.png

2026-07-07T19:34:30Z

Jon: Layout example of two FIXED elements <A> and with a FILL_AVAILABLE space between them where there is a lot of available space

== Summary ==
Layout example of two FIXED elements <A> and with a FILL_AVAILABLE space between them where there is a lot of available space

File:Example2 2.png

2026-07-07T19:33:48Z

Jon: Layout example of two FIXED elements <A> and with a FILL_AVAILABLE element between them when there is zero available space

== Summary ==
Layout example of two FIXED elements <A> and with a FILL_AVAILABLE element between them when there is zero available space

File:Example2 1.png

2026-07-07T19:33:10Z

Jon: Layout example of two FIXED elements <A> and , with a FILL_AVAILABLE element between them

== Summary ==
Layout example of two FIXED elements <A> and , with a FILL_AVAILABLE element between them

File:Example1 3.png

2026-07-07T19:32:15Z

Jon: Layout example of two elements with one FIXED and one FILL_AVAILABLE when there is a lot of available space

== Summary ==
Layout example of two elements with one FIXED and one FILL_AVAILABLE when there is a lot of available space

File:Example1 2.png

2026-07-07T19:31:40Z

Jon: Layout example of two elements with one FIXED and the other FILL_AVAILABLE when there is zero available space

== Summary ==
Layout example of two elements with one FIXED and the other FILL_AVAILABLE when there is zero available space

File:Example1 1.png

2026-07-07T19:30:45Z

Jon: Layout example of two elements with one FIXED and the other FILL_AVAILABLE

== Summary ==
Layout example of two elements with one FIXED and the other FILL_AVAILABLE

File:Positioning 2.png

2026-07-07T19:29:57Z

Jon: Positioning diagram of an item and surrounding layout elements in a layout

== Summary ==
Positioning diagram of an item and surrounding layout elements in a layout

File:Positioning 1.png

2026-07-07T19:29:09Z

Jon: Positioning diagram of a single element in a layout

== Summary ==
Positioning diagram of a single element in a layout

File:Box layout.png

2026-07-07T19:28:12Z

Jon: Layout definition for Box component

== Summary ==
Layout definition for Box component

File:Box preview.png

2026-07-07T19:27:39Z

Jon: Preview of Box component

== Summary ==
Preview of Box component

File:LayoutColorSemantics.png

2026-07-07T19:27:11Z

Jon: Diagram of color encoding semantics used in layout files

== Summary ==
Diagram of color encoding semantics used in layout files

File:LayoutSpecificity.png

2026-07-07T19:26:01Z

Jon: Layout constraints specificity diagram

== Summary ==
Layout constraints specificity diagram

File:Element Basics.png

2026-07-07T19:25:05Z

Jon: Structural breakdown of a layout element

== Summary ==
Structural breakdown of a layout element

File:Slider layout Slider.png

2026-07-07T19:24:03Z

Jon: Layout definition for Slider

== Summary ==
Layout definition for Slider

File:Slider layout Box.body.png

2026-07-07T19:23:26Z

Jon: Layout definition for Slider Box body sub-component

== Summary ==
Layout definition for Slider Box body sub-component

File:Slider layout Track.body.png

2026-07-07T19:22:53Z

Jon: Layout definition for Slider Track body sub-component

== Summary ==
Layout definition for Slider Track body sub-component

File:Slider layout Thumb.png

2026-07-07T19:22:14Z

Jon: Layout definition for Slider Thumb sub-component

== Summary ==
Layout definition for Slider Thumb sub-component

File:Slider components.png

2026-07-07T19:21:31Z

Jon: Components breakdown for the Slider component

== Summary ==
Components breakdown for the Slider component

File:Slider preview.png

2026-07-07T19:21:00Z

Jon: Preview of the Slider component

== Summary ==
Preview of the Slider component

File:HighlightPicker layout.png

2026-07-07T18:50:31Z

Jon: Layout for Highlight Picker component

== Summary ==
Layout for Highlight Picker component

Model

2026-07-07T18:21:33Z

Jon:

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>model.txt</code> document.

<code>model.txt</code> provides the complete description of the data the component operates on and displays, the state of the component, and the signals it produces. Any component with new behavior requires <code>model.txt</code>. Components that simply customize the properties of existing components omit <code>model.txt</code> as there is nothing to describe that is not already defined in <code>components.xd</code>.


== Data and Behavior ==

<code>model.txt</code> is necessary when the component being defined has specific data that it displays or manipulates or introduces novel behavior not found elsewhere in the UI Kit.


=== 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 model for <code>AccountListItem</code> is very simple and deals only with data. There is no special behavior associated with <code>AccountListItem</code>: it behaves no differently than any other <code>ListItem</code> that has been defined elsewhere. <code>AccountListItem</code> takes a structured set of data:
* <code>identicon</code>
* <code>id</code>
* <code>name</code>

Using a specific <code>AccountListItem</code> for displaying user accounts in this way keeps components contained and simple.


=== Example: Button ===

<pre>Data:
body: The component to display inside of the button.

State:
press: Whether the button is currently pressed.

Signals:
Click: Indicates that the button was clicked.</pre>
<code>Button</code> is a more generic component. From <code>body</code>, we see that it can be used to display any component, so there is no specific data associated with it. What distinguishes <code>Button</code> from <code>Component</code> is its behavior:
* <code>press</code> is a new '''State''' that <code>Button</code> can be in.
* <code>Click</code> is a new '''Signal''' that <code>Button</code> can send.


== Getting Started ==

<code>model.txt</code> is written after <code>preview.xd</code>. Clarifying in writing what data the component uses greatly simplifies the making of <code>components.xd</code>, <code>use_cases.drawio</code> and <code>user_flow.drawio</code>.

Most expected behavior is specified in <code>Component</code>, the base component for all UI components. Any property or signal found in <code>Component</code> can be used by any component without repeating them in the model. This makes the model for most components sparse and keeps the focus on their ''unique'' data and behavior.

Components are built using composition: complexity is built up from simple elements that manage a small set of responsibilities. These smaller elements are the <code>children</code> and when we consider the model for a component it is helpful to think about what responsibilities are handled by its children rather than being its concern.


=== Example: DropDownBox ===

[[File:Drop_down_box_preview.png|640px|center|Closed and open states of Drop Down Box]]

<code>DropDownBox</code> lets the user select a single value from a list of options and submit that value. It has a child <code>DropDownList</code>: the list of options and whether the list is open or closed can be thought of as properties of <code>DropDownList</code>.

To describe <code>DropDownBox</code>, we need to understand a little more of its behavior:
* It represents a single value that the user can select.
* Selecting a value is different from submitting a value. The user can select a value without submitting it.
* The user can revert a selection to what was last submitted (by pressing the Escape key).
* Focusing out of the <code>DropDownBox</code> is treated as a submission when the selected value has changed from the last submitted value.
* It can be set to be read only.

Based on its behavior, we need a few properties:
* A property to track the selected value
* A property to track the last submitted value
* A property to indicate if it is read only

Other components will need to be notified when the user has made a submission so they can respond to changes. We can add one more requirement:
* A signal to indicate a submission

<pre>Data:
read_only: Whether the value is modifiable by the user.
current: The item currently represented by the DropDownBox.

State:
submission: The last value submitted by the user.
modified: Whether current has been modified since last Submit.

Signals:
Submit: Indicates the user is submitting current.</pre>
Reviewing the <code>model.txt</code>, we see the following:
* <code>current</code> to track the selected value
* <code>submission</code> to track the last submitted value
* <code>read_only</code> to indicate if it is read only
* <code>modified</code> to track whether <code>current</code> changed from <code>submission</code> (not strictly necessary)
* <code>Submit</code>, a signal to indicate a submission

We note that <code>read_only</code> and <code>current</code> have been placed in <code>Data</code>, while <code>submission</code> and <code>modified</code> are in <code>State</code>. This means that external components can modify <code>read_only</code> and <code>current</code>, while <code>DropDownBox</code> manages <code>submission</code> and <code>modified</code> itself. <code>Submit</code> is placed in <code>Signals</code>. Properties are named using '''snake_case''' while signals use '''PascalCase'''.

It may be useful for external components to respond to changes in <code>current</code> as well as <code>submission</code>, such as showing a preview based on the current selection, but a <code>Current</code> signal is not necessary for this. Because properties in <code>Data</code> are read-write for external components, components can subscribe to property changes directly without requiring a signal.


== Anatomy ==

The structure of <code>model.txt</code> is a linear document divided into preset sections. These sections are as follows:
* Definitions
* Styles
* Selectors
* Pseudo-Elements
* Data
* State
* Signals

<code>Definitions</code> serve as an optional index for terms used throughout the model. <code>Selectors</code> are used in older specs but should be avoided for simplicity. <code>Pseudo-Elements</code> define sub-sections of the component and make them available for styling. The remaining sections <code>Styles</code>, <code>Data</code>, <code>State</code>, and <code>Signals</code> can be conceptualized as relating to the interface as shown:

[[File: Model_Component_anatomy.png|640px|center|Diagram of dataflow through a component]]

<code>Data</code> flows through the interface, depending on the component, both external resources and the user may be able to modify <code>Data</code> properties.

<code>Styles</code> can be set by external components to change the appearance of the component. Generally, the user doesn’t directly modify the style of a component, so these can be thought of as one-way.

<code>State</code> is managed internally by the component. It can be influenced by user interactions, by <code>Data</code>, or any combination of properties, but it remains encapsulated.

<code>Signals</code> are messages sent out by the component. They inform other components about changes that are useful to know about resulting from a user action.


=== Breakdown ===

Within each section is a list of properties followed by their definitions.

<pre>Section Heading:
property_name: Property description. Optional default.</pre>
Property names should balance brevity with self-description. Leaning on familiar and established terminology is preferred over introducing new terms with the same meaning.

Descriptions should be precise, concise, and readable, expressing in plain language the meaning of the property. If a property can only be one of a finite set of values, the possible values are enumerated directly in the definition by nesting them below the property name and definition.

<pre>Section Heading:
property_name: Property description.
POSSIBLE_VALUE_1: Value description for 1. Default.
POSSIBLE_VALUE_2: Value description for 2.</pre>
Values are distinguished using UPPERCASE.

Properties can consist of sub-properties, such as list or tabular data, or properties consisting of multiple orthogonal components such as the <code>x</code> and <code>y</code> components of a position. Sub-properties are nested beneath properties.

<pre>Section Heading:
property_name: Property description. Optional default.
sub_property_name: Sub property description. Optional default.</pre>
Descriptions can include inline expressions provided they are trivial. With expressions, it is understood that they represent a ''binding'': they update automatically without requiring a sub-flow in <code>user_flow.drawio</code>. When an expression is used, it is placed on its own line below the last sentence for the description. The equality is implied.

<pre>Section Heading:
property_name_1: Property description. Optional default.
property_name_2: Property description.
property_name_1 + 10</pre>

=== Example: Component ===

<pre>Styles:
visibility: Shows or hides the component.
VISIBLE: The component is visible, (default).
INVISIBLE: The component is invisible.
NONE: The component is both invisible and removed from the layout.</pre>
In the above excerpt from <code>model.txt</code> for <code>Component</code>, the <code>visibility</code> property is defined within the <code>Styles</code> section. <code>visibility</code> can be one of three values:
* <code>VISIBLE</code>
* <code>INVISIBLE</code>
* <code>NONE</code>

Each possible value is named and defined directly below the definition for <code>visibility</code>.

<pre>Data:
parent: The parent of this component, for top-level components this is NULL.
window: The window that this component belongs to.
children: The list of this component's children.
width: The width of the component in pixels.
height: The height of the component in pixels.
position: The position of the component relative to its parent, if the
component has no parent, then the position is equal to
screen_position.
x - The x-coordinate in pixels.
y - The y-coordinate in pixels.</pre>
Continuing to the <code>Data</code> section, the <code>position</code> property is a composite of two independent values: <code>x</code> and <code>y</code>. These properties can be referenced in other documentation with dot notation as <code>position.x</code> and <code>position.y</code>.


=== Example: SaleConditionBox ===

<pre>State:
conditions_list: A list of all conditions.
code: The identifier for the condition.
name: The name for the condition.
terms: The list of words from the name for the condition.
name.split(' ')</pre>
<code>conditions_list</code> is a list of items, where each item has the fields specified. Visually it can be shown as tabular data. Below is what some of this data might look like:

{| class="wikitable"
|-
! code !! name !! terms
|-
| @ || Regular Settlement || Regular, Settlement
|-
| C || Cash Settlement || Cash, Settlement
|-
| N || Next Day Settlement || Next, Day, Settlement
|-
| R || Seller Settlement || Seller, Settlement
|-
| F || Intermarket Sweep || Intermarket, Sweep
|-
| O || Opening Print || Opening, Print
|-
| 4 || Derivative Price || Derivative, Priced
|-
| 5 || Re-Opening Print || Re-Opening, Print
|-
| 6 || Closing Print || Closing, Print
|}

<code>terms</code> is clearly derived from <code>name</code>, the result of the inline expression. If the expression is non-trivial or not unconditionally true, then it does not belong in <code>model.txt</code>. If you are unsure if an expression improves the clarity of the model, leave it out.


=== Example: InputBox ===

Boolean (true or false) properties have implied values.

<pre>Data:
read_only: Whether the InputBox is in read_only mode.
rejected: Whether the last submission was rejected.</pre>
<code>InputBox</code> has two boolean properties: <code>read_only</code> and <code>rejected</code>. Each may be <code>true</code> or <code>false</code>, which is implied from their definitions.


== Definitions ==

This section is optional. It provides definitions for terms used throughout the model to improve clarity.


=== Example: TimeAndSalesWindow ===

<pre>Definitions:
TimeAndSale: A trade on a security.
timestamp: The time of the trade.
price: The price of the trade.
size: The number of shares traded.
condition: A code that indicates the conditions of the trade.
market_center: The market that facilitated the trade.
bbo_indicator: An indicator that relates the price to the bbo.
BBO_UNKNOWN: The bbo is unknown.
ABOVE_ASK: The price is above the ask.
AT_ASK: The price is equal to the ask.
INSIDE: The price is between the bid and the ask.
AT_BID: The price is equal to the bid.
BELOW_BID: The price is below the bid.</pre>
<code>Definitions</code> is used to define a <code>TimeAndSale</code>. Each <code>TimeAndSale</code> has a set of properties associated with it:
* <code>timestamp</code>
* <code>price</code>
* <code>size</code>
* <code>condition</code>
* <code>market_center</code>
* <code>bbo_indicator</code>

<code>TimeAndSale</code> can be referenced elsewhere in the model.

It is at the designer’s discretion whether to include a <code>Definitions</code> section or to provide the description inline where the term is used. The following heuristics are helpful in determining whether to place a definition in a <code>Definitions</code> section:
* The term is referenced by multiple properties throughout the model
* The definition is long or contains multiple levels of nesting which would impede the readability if included directly in the normal flow of the document

When unsure, err on the side of putting the description inline rather than including a Definitions section.


== Styles ==

<code>Styles</code> is for defining any style properties available on the component. Style properties affect the visual appearance of a component but do not directly relate to the data it displays. Style properties can be inputs that are provided externally to the component.


=== Example: Box ===

<pre>Styles:
background_color: The background color. #FFFFFF by default.
border_top_size: The height of the top border.
border_right_size: The width of the right border.
border_bottom_size: The height of the bottom border.
border_left_size: The width of the left border.
...</pre>
<code>Box</code> defines a number of style properties for customizing its color, border, and padding. External components using <code>Box</code> can make use of any of these properties as needed.

No matter how deep in the component hierarchy a <code>Box</code> is nested as a child, the component can access the properties for that <code>Box</code> and make customizations. This avoids creating redundant properties to enable customization.


=== Example: TimeAndSale ===

<pre>Styles:
font: The font used to render the text in the cells.
Default 10px Roboto 500.
bbo_unknown: The bbo is unknown.
background_color: Default #FFFFFF.
text_color: Default #000000.
above_ask: The price is above the ask.
background_color: Default #D2F6E0.
text_color: Default #007735.
at_ask: The price is equal to the ask.
background_color: Default #D2F6E0.
text_color: Default #007735.
inside: The price is between the bid and the ask.
background_color: Default #FFFFFF.
text_color: Default #000000.
at_bid: The price is equal to the bid.
background_color: Default #FAD8D9.
text_color: Default #B71C1C.
below_bid: The price is below the bid.
background_color: Default #FAD8D9.
text_color: Default #B71C1C.</pre>
<code>TimeAndSale</code> defines a number of style properties specific to its function. <code>font</code> is defined in <code>TextBox</code> and ordinarily does not need to be redefined: here it is done for convenience so that all the children of <code>TimeAndSale</code> are styled with the same font without having to make separate declarations for each child. The remaining properties relate to <code>TimeAndSale</code>: they depend on a comparison between the price of the <code>TimeAndSale</code> to the bid and ask prices.

Note that each comparative style (<code>bbo_unknown</code>, <code>above_ask</code>, etc.) is a composite style of <code>background_color</code> and <code>text_color</code>: coordinating separate styles into a set of presets is a common use case for <code>Styles</code>.

The basic styles are all available in <code>Box</code> and <code>TextBox</code>. Components should only define styles that are sensible to their function. Styles are not restricted to the properties and selectors of CSS or other languages, they are defined within <code>model.txt</code> to suit the specific needs of the component.


== Selectors ==

Selectors may be deprecated. They were used to bundle <code>Styles</code> and <code>State</code> in an opt-in manner. It is recommended to use <code>Styles</code> in combination with <code>State</code> for any properties that can be used to style the component.


== Pseudo-Elements ==

Pseudo-elements are a way to give full styling properties to portions of a component that are not components themselves. They are used infrequently but can be useful for fundamental components that consist of semantic portions that are not components. Consider the following usage in TextBox:

<pre>Pseudo-elements:
placeholder: Styles the placeholder sub-component.</pre>
This enables the placeholder to be styled using the same properties as for TextBox, even though it is not itself a component. Text is the most obvious use case for pseudo-elements, as it can be broken up semantically into granular parts. See [https://web.dev/learn/css/pseudo-elements/ Pseudo-Elements on Web.dev] and [https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors/Pseudo-classes_and_pseudo-elements#what_is_a_pseudo-element Pseudo-Elements on MDN] for more detail.


== Data ==

<code>Data</code> is for properties that do not deal directly with styling and are provided externally. Properties in <code>Data</code> are read-write to external components and may be modifiable by the user (such as the value of an input field).

<code>Data</code> properties are not fixed, they can be updated from an external source at any time. It is common to have <code>Data</code> properties that represent a stream, such as quotes from an exchange, which update as soon as they change without requiring a user-initiated update request. Anytime a property in <code>Data</code> is changed, the change is immediately reflected in the component. It is sufficient to declare where the value resides in the component and it will always reflect the latest value.

A default value is often declared. Where the data comes from is not specified (e.g. from a backend or a local file), that should be determined by the type of data and the application architecture.

The following heuristic may be useful in determining whether property values belong in <code>Data</code> or <code>State</code>. It belongs in <code>Data</code> if:
* The value can be modified by the user through interaction with the component
* The value is read from an external source requiring real-time updates
* There are obvious use-cases where external components will need to read or write to the value

Otherwise, put the value in <code>State</code>.


=== Example: TextBox ===

<pre>Data:
current: The text currently represented by the TextBox.
cursor_position: The current cursor position. When 0, the cursor is at the
start of the TextBox.
selection_start: The index position of the character in current at
the start of selection.
selection_end: The index position of the character in current at the
end of selection. When selection_end < selection_start,
the direction of selection is opposite of reading order.
read_only: Whether the text is modifiable by the user.
placeholder: The text to be displayed when current is empty.
max_length: The maximum number of characters to accept.</pre>
<code>TextBox</code> has a number of bi-directional properties: <code>current</code>, <code>cursor_position</code>, <code>selection_start</code>, and <code>selection_end</code> are all typically driven by user actions, but they can also be set by external components or when the component is customized, such as setting an initial <code>current</code> value to display. There are also properties that are not modifiable by the user: <code>read_only</code>, <code>placeholder</code>, and <code>max_length</code>. However, it is possible for external components to modify these, so a component could be made that let the user change these properties.


=== Standard Property Names ===

Properties are directly defined in the <code>model.txt</code> and may be anything the designer can define. That said, there are commonly recurring properties that have come to form an implicit convention and it is preferable to use consistent names and descriptions when the intended behavior is the same.


==== Current ====

In the <code>TextBox</code> example, the text is named <code>current</code> and not <code>text</code> or <code>value</code>. This is intentional: <code>current</code> is a standard property name.


===== Example: DecimalBox =====

In <code>DecimalBox</code>, <code>current</code> refers to a number rather than a text string.

<pre>Data:
current: The current number represented by the DecimalBox.</pre>

===== Example: DateBox =====

In <code>DateBox</code>, <code>current</code> refers to a date value, not a number or text string.

<pre>Data:
current: The current date represented by the DateBox, in ISO format
(YYYY-MM-DD).</pre>
By convention, <code>current</code> refers to the current value of the component. The type of the value is generally defined by what the component displays.


===== Example: ScalarFilterPanel =====

If there is no logical single current value for the component, it should not have <code>current</code>.

<pre>Data:
min: If set defines the minimum value to include.
default_min: The default min value.
max: If set defines the maximum value to include.
default_max: The default max value.</pre>
<code>ScalarFilterPanel</code> has two <code>DecimalBox</code>, one aliased as <code>MinValue</code> and another aliased as <code>MaxValue</code>, and has access to <code>MinValue.current</code> and <code>MaxValue.current</code>. It does not have a <code>current</code> as it does not represent a single value.


===== Example: TableBody =====

<code>current</code> can be made more specific where appropriate.

<pre>Data:
rows: A list of table_rows each having an equal number of columns, used to
populate the body.
row_selection_mode: The selection mode used by rows (NONE by default).
row_selection: Stores the list of selected rows.
column_selection_mode: The selection mode used by columns (NONE by default).
column_selection: Stores the list of selected columns.
cell_selection: Stores the list of selected cells, indexed by row and column.
cell_selection_mode: The selection mode used by cells (NONE by default).
current_cell: The currently selected cell (null by default). The current cell
can be used to implicitly specify a current row and current column
if such functionality is desirable, for example the current cell's
row is implicitly the current row.</pre>
<code>TableBody</code> has a <code>current_cell</code> property but no <code>current</code> property. Because <code>TableBody</code> can only have one cell as current, it makes sense that this is a property of <code>TableBody</code> and not of any of its children. However, <code>TableBody</code> does not represent a single cell, so <code>current</code> without added specificity could cause confusion.


===== Example: ListView =====

Do not use current for lists of data: <code>current</code> refers to one value that varies in time.

<pre>Data:
current: The view's current value, can be null.
selected: The value of the selected list item.
items: A list of items used to populate the list.
component: The component to display in the list.
value: A text value associated with an item, used to select an item by
keyboard.</pre>
<code>ListView</code> uses <code>current</code> for the single value that is current, and <code>items</code> contains the list of values that make up the list. While <code>ListView</code> represents a list of values, only a single value can be <code>current</code>.


==== Body ====

<code>body</code> represents a slot that fills the entirety of the component. Some components, like <code>Button</code>, are generic enough that they can be used to display anything, and <code>body</code> is the name these components are assigned to.


===== Example: Box =====

<pre>Data:
body: The component displayed in the box.</pre>

===== Example: Button =====

<pre>Data:
body: The component to display inside of the button.</pre>

==== Items ====

<code>items</code> represents a generic list of values that are managed by a single component.


===== Example: ListView =====

<pre>
Data:
current: The view's current value, can be null.
selected: The value of the selected list item.
items: A list of items used to populate the list.
component: The component to display in the list.
value: A text value associated with an item, used to select an item by
keyboard.</pre>
Note that, strictly following the <code>body</code> naming convention, <code>items.component</code> should be named <code>items.body</code>.


== State ==

<code>State</code> is for declaring properties that are internal to the component. These are properties that are useful to have because they simplify descriptions of the component’s behavior and map to the user’s mental model of the component. A common use-case for <code>State</code> is for declaring properties that can be used for styling the component.


=== Example: Component ===

<pre>State:
active: Whether the component belongs to the currently active window.
enabled: The negation of disabled, enabled = !disabled.
hover: Whether the mouse is located on top of the component.
focus: Whether the component receives keyboard input.
focus_in: Whether the component or any of its descendants has focus.
focus_visible: Whether the box has focus and it is determined that focus
should be indicated on the box to assist the user:
- the user focused the box via non-pointing device
- the box received programmatic focus from a component that
had focus_visible</pre>
<code>component</code> declares a number of <code>State</code> properties that are used for styling purposes by many components. It is common for a component to have a certain appearance when it is <code>hover</code>. Because <code>hover</code> is defined in <code>component</code>, it is trivial to style a component like a button based on its hover state. Each component doesn’t need to reinvent or redeclare the logic for what <code>hover</code> means.


=== Example: SecurityBox ===

A common use-case for <code>State</code> is for storing data that is intrinsic to the component that the user cannot manipulate.

<pre>State:
security_list: A list of all tradeable securities.
symbol: The symbol of the security.
name: The full name of the security.
country: The ISO country code for the country in which the security's
exchange is located in.</pre>
In <code>SecurityBox</code>, <code>security_list</code> is all tradeable securities. This list is dynamic, since securities are delisted and new securities listed all the time. It could be obtained from a remote resource that is periodically updated. Unlike with <code>Data</code>, it is not automatically assumed that this data is continuously flowing as a stream. Because the <code>security_list</code> is neither a real-time feed or modifiable by the user, <code>State</code> is an appropriate location for it. This also ensures that <code>security_list</code> cannot be tampered with by external components and makes using <code>SecurityBox</code> more ergonomic: <code>SecurityBox</code> always contains the list of all tradeable securities.


== Signals ==

Signals are how components notify other components about changes to their internal state. Any external component can listen for a signal from a specific component and respond accordingly. Use signals whenever there is a change in a component that it would be useful for external components to know about based on real use cases.

Signals are not necessary for notifying external components about simple changes in <code>Data</code>: the properties in <code>Data</code> are already externally accessible: an external component can see if <code>DecimalBox.current</code> changed without needing a signal. However, sometimes a component will need to perform some operations on the data when it changes, and it should send a signal when these operations are completed.

Signals should reflect the behavior of the component they belong to. Components should not pass along signals from their children if it does not make sense to their function.

Components can define signals with the same name as their children. For a component with a child <code>DecimalBox</code>, it can define its own <code>Submit</code> signal which is what is referenced by <code>A.Submit</code>. The <code>DecimalBox</code> is specified with dot notation as <code>A.DecimalBox.Submit</code>. Ideally, only <code>A</code> should be interested in <code>DecimalBox.Submit</code>, while other components should subscribe to <code>A.Submit</code>.


=== Standard Signal Names ===

As with properties, there are a few standard signals.


==== Change ====

The <code>Change</code> signal may be fired by a component that needs to notify other components of a change to the <code>current</code> of its children. This may be useful when some logic should be performed such as validation before sending out the signal so that components listening for changes do not concern themselves with handling an invalid change. It is similar to the [https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event Input Event] event in HTML


==== Submit ====

<code>Submit</code> indicates that the user has submitted the value. A <code>Submit</code> signal should only be generated in response to an intentional user action, such as a key press. <code>Submit</code> is conventionally signaled on a <code>FocusOut</code> event when <code>current</code> has changed from its previous value: the user’s change in focus is interpreted as an implicit submission. <code>Submit</code> typically follows an Enter key press. It is similar to the [https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event Change Event] in HTML.


==== Reject ====

<code>Reject</code> is fired to indicate that a submitted value was rejected.


=== Payload ===

When a signal is fired, it carries with it a payload that components can read. For the <code>Submit</code> signal, its payload consists of <code>submission</code> by default. The payload of any signal can be customized to better suit the use-cases.


==== Example: TimeFilterPanel ====

<pre>Signals:
Submit: The user has submitted their time range.
start: The submitted start time of the range or NULL if offset is set.
end: The submitted end time of the range or NULL if offset is set.
offset: The submitted offset to filter by or NULL if start and end are set.</pre>
The <code>Submit</code> payload carries three values: <code>start</code>, <code>end</code>, and <code>offset</code>. This reflects <code>TimeFilterPanel</code> which lacks a <code>current</code> or <code>submission</code> but has <code>start</code>, <code>end</code>, and <code>offset</code> values. Within <code>user_flow.drawio</code>, the values used for each payload slot are clarified.


== Ordering ==

Keep the sections ordered as they appear in this overview and repeated below:
* Definitions
* Styles
* Data
* State
* Signals

Omit any section that is unused.


== Usage ==

When placing data into <code>components.xd</code>, use the property names exactly as they appear in <code>model.txt</code>. States used by selectors in <code>components.xd</code> should also appear exactly as they appear in <code>model.txt</code>. The property and signal names should also carry over to <code>layout.xd</code>, <code>use_cases.drawio</code>, and <code>user_flow.drawio</code>.

<code>model.txt</code> is the most powerful tool in the designer’s toolkit; taking time upfront to provide good descriptions in the model can save a lot of designer and developer headaches later on.


== References ==

# [https://web.dev/learn/css/pseudo-elements/ Web.dev: Pseudo-Elements]
# [https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors/Pseudo-classes_and_pseudo-elements#what_is_a_pseudo-element MDN: Pseudo-Elements]
# [https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event MDN: The Input Event]
# [https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event MDN: The Change Event]

Animations

2026-07-07T18:13:32Z

Jon: Created page with "Animations in Spire follow a philosophy of enhancing clarity and communication without embellishment or impedance to the user. In CSS there are transitions, in Spire an anima..."

Animations in Spire follow a philosophy of enhancing clarity and communication without embellishment or impedance to the user.

In CSS there are transitions, in Spire an animation is just a value. This means that a property value such as <code>background_color</code> or <code>border_color</code> can be directly set to an animation value to achieve a property value that changes over time.

== Example: Rejected Style for InputBox ==

[[File:TextBox_Rejected.gif|640px|center|Animation of a text input field flashing red to indicate a rejection]]

When the InputBox is in the <code>rejected</code> state, an animation plays. The animation can be defined as follows:

<syntaxhighlight lang="css">background_color: chain(timeout(#FFF1F1, 250ms), linear(#FFF1F1, revert, 300ms))
border_color: chain(timeout(#B71C1C, 550ms), revert)</syntaxhighlight>
In this case the value says:

<blockquote>Chain together two styles, the first style is a value of <code>#FFF1F1</code> that times out after 250ms, the second value is a linear interpolation from <code>#FFF1F1</code> to whatever the style was before (that’s what <code>revert</code> does), over 300ms.
</blockquote>
Border color is styled as:

<blockquote>Chain two styles, the first is the color <code>#B71C1C</code> that expires after 550ms and then reverts to whatever it was previously.
</blockquote>
This is reflected in <code>components.xd</code> for InputBox.

[[File:InputBox_components.png|640px|center|Definition card for Input Box component]]

When the InputBox is <code>rejected</code>, property declarations are made for the <code>background_color</code> and <code>color</code> that are animation values. Whenever the InputBox is put into the <code>rejected</code> state, the animations will play.

Each property value is independent, and there is no necessary connection between the timing used for the animation values for each property.

== Example: Uptick/Downtick Style for DecimalBox ==

[[File:DecimalBox_Uptick_Downtick.gif|640px|center|Animation of a numeric input field flashing red and green alternately to indicate the direction change as its value changes]]

When the DecimalBox uses the uptick/downtick styling, its background color flashes when its value changes, reflecting whether the value increased or decreased.

When the value increases, it is uptick:

<syntaxhighlight lang="css">background_color: linear(#EBFFF0, revert, 550ms)</syntaxhighlight>
When the value decreases, it is downtick:

<syntaxhighlight lang="css">background_color: linear(#FFF1F1, revert, 550ms)</syntaxhighlight>

== Functions ==

Unlike static values, animation values use functions that allow them to change over time. The list of functions that have been used are as follows:

{| class="wikitable"
|-
! Function !! Description
|-
| <code>chain(X, Y, *ARGS)</code> || An animation that applies <code>X</code> until <code>X</code> ends, then applies <code>Y</code> until <code>Y</code> ends, and so on for any additional arguments.
|-
| <code>timeout(X, Y)</code> || Applies <code>X</code> for a period of <code>Y</code>
|-
| <code>linear(X, Y, Z)</code> || Linearly interpolates from <code>X</code> to <code>Y</code> over a period <code>Z</code>. <code>linear = cubic_bezier(0.0, 0.0, 1.0, 1.0)</code>
|-
| <code>ease(X, Y, Z)</code> || Interpolates from <code>X</code> to <code>Y</code> over a period <code>Z</code> using the <code>ease</code> timing function. <code>ease = cubic_bezier(0.25, 0.1, 0.25, 1.0)</code>
|}

Additional functions may be added provided they have a clear use case and are documented.

== Keywords ==

Values within functions may be literal values (e.g. a color value or a time in milliseconds), or they may be a keyword with a defined meaning.

{| class="wikitable"
|-
! Keyword !! Description
|-
| <code>revert</code> || Applies whatever style would have otherwise been applied.
|}

== References ==

# [https://developer.mozilla.org/en-US/docs/Web/CSS/easing-function Easing Functions]
# [https://easings.net/ Easing Functions Cheat Sheet]

File:TextBox Rejected.gif

2026-07-07T18:12:20Z

Jon:

File:DecimalBox Uptick Downtick.gif

2026-07-07T18:12:03Z

Jon:

File:DecimalBox Uptick Downtick.webp

2026-07-07T18:02:24Z

Jon: Uptick and downtick animation for Decimal Box component

== Summary ==
Uptick and downtick animation for Decimal Box component

File:InputBox components.png

2026-07-07T18:01:48Z

Jon: Components breakdown for Input Box component

== Summary ==
Components breakdown for Input Box component

File:TextBox Rejected.webp

2026-07-07T18:00:59Z

Jon: Rejection animation for Text Box component

== Summary ==
Rejection animation for Text Box component

Preview

2026-07-07T17:59:25Z

Jon: Created page with "<code>preview.xd</code> covers the visual overview of the component and its essential use cases. It provides the developer with a basic first impression of the component and h..."

<code>preview.xd</code> covers the visual overview of the component and its essential use cases. It provides the developer with a basic first impression of the component and helps them grasp the design intent. Any component with a visual representation requires <code>preview.xd</code>.

A good preview will:
* Document the component’s appearance and highlight its states
* Illustrate use cases visually that would be difficult to understand fully from other documentation
* Provide context, by showing places where the component is used by other components

<code>preview.xd</code> is non-normative. If there is a conflict between the appearance in <code>preview.xd</code> and subsequent specifications (e.g. <code>components.xd</code> or <code>layout.xd</code>) due to designer error, the other specifications take precedence. It is the designer’s responsibility to ensure that specifications are consistent and accurate.


== Getting Started ==

<code>preview.xd</code> comes first in the specifications, at the end of all exploratory work and user research necessary to define the component. The preview informs the developer up front of ''what'' is being built. At a minimum the preview consists of a high-fidelity mock-up of the component that is a visual representation of the designer’s intent.

Use an existing file as a baseline. Start with an initial, default visualization of the component. Use cases may be shown as static visualizations. Keep each use case to its own row and show the next step in a use case in the adjacent column.


=== Example: HexColorBox ===

[[File:HexColorBox_preview.png|640px|center|Preview of a hexadecimal color value input field component]]

<code>HexColorBox</code> is a specialized input based on <code>TextBox</code>. Because <code>TextBox</code> functionality is documented in its respective preview, <code>HexColorBox</code> is primarily concerned with showcasing its unique features.

The preview communicates the following:
* <code>HexColorBox</code> is essentially a <code>TextBox</code>.
* Hex values can be entered with our without a <code>#</code> mark in front.
* The submitted value always contains the <code>#</code> mark in front.
* It is used within <code>ColorPicker</code> as an alternative input for color selection.


== Anatomy ==

All <code>preview.xd</code> files contain a title block with the name of the component. Beneath it is the visual representation of the component in a default state. Other notable states are expected to be shown here as well, and may include:
* <code>open</code>
* <code>closed</code>
* <code>highlighted</code>
* <code>focus</code>
* <code>hover</code>
* <code>active</code>
* <code>read_only</code>

Provide text labels as identifiers for non-default states.

It is important to document the states that are specific to the component to serve as a reference not only for the developer building the component but also for the designer when assessing a completed component demo.

If the preview is including many states of its children, that is a clue that those children should probably be separate components with their own preview to cover these details.

Provide text labels as identifiers for use cases. Separate use cases into rows, providing a visual journey from left to right.


==== Example: TableView ====

[[File:TableView_preview_1x.png|640px|center|Preview of a table component]]

The preview showcases two places where <code>TableView</code> is used. There are some styling differences between the two, indicating that some customization is available. A variety of components are shown as table cells, with different styling, indicating that table cells are customizable without being an exhaustive enumeration.

Beneath the usages are rows for a few use cases and scenarios:
* Reordering a column
* Resizing a column
* Column overflow/underflow
* First row current

The use cases are divided into a few simple steps that are read left to right.

'''Note:''' Detailed state variations for the column headers and detailed state variations for cells are excluded - these are handled by the child components.


==== Example: Time and Sales Window ====

[[File:TimeAndSalesWindow_preview_1x.png|640px|center|Preview of the Time and Sales Window component]]

<code>TimeAndSalesWindow</code> showcases the possible variations for the window:
* New window
* Searching a security
* Loading a security
* Displaying an inactive security
* Displaying an active security
As well it shows customizations that can be made by the user for displaying columns.

Beneath the variations are rows for use cases and scenarios: pull delayed, no more entries, linking a window, displaying the full titlebar label, and displaying with a larger font. For pull delayed and link window, the steps are shown left to right.

The preview provides an overview of components acting together in sequence which is not shown in the isolated breakdowns in <code>components.xd</code> and <code>layout.xd</code>.


==== Example: FontBox ====

[[File:FontBox_preview.png|640px|center|Preview for a font selector input field component]]

<code>FontBox</code> uses an adaptive layout that changes based on the available space. This is made apparent in the preview by showing the two different layouts while the particulars are delegated to <code>components.xd</code> and <code>layout.xd</code>. As a composite component, <code>FontBox</code> does not include all of the various states for its children.

Basic selecting and submitted states are shown to clarify its usage without specifying any novel behavior not covered by its children.

For context, <code>FontBox</code> is shown being used in <code>TimeAndSalesPropertiesWindow</code>.


== What to Leave Out ==

Don’t include any text specifications in <code>preview.xd</code> (e.g. <code>padding_left: 15px</code>); these belong in <code>components.xd</code>.

For components that have adaptive layouts, do not include pixel breakpoints for different layouts. Layouts are specified in <code>layouts.xd</code> and the preview should be solely a visual reference in this regard.

Do not list children, these are enumerated in <code>components.xd</code>.


== Usage ==

<code>preview.xd</code> is an important first step in specifying a component. A good preview synchronizes communication and understanding between designers and developers and provides a reference against which to compare the functioning final component.

File:FontBox preview.png

2026-07-07T17:48:59Z

Jon: Preview of Font Box component

== Summary ==
Preview of Font Box component

File:TimeAndSalesWindow preview 1x.png

2026-07-07T17:48:02Z

Jon: Preview of Time and Sales Window component

== Summary ==
Preview of Time and Sales Window component

File:TableView preview 1x.png

2026-07-07T17:47:27Z

Jon: Preview of TableView component

== Summary ==
Preview of TableView component

File:HexColorBox preview.png

2026-07-07T17:42:42Z

Jon: Preview of the Hex Color Box component, an input field for a hexadecimal color value

== Summary ==
Preview of the Hex Color Box component, an input field for a hexadecimal color value