KeyedObservableStack

Description

KeyedObservableStack renders an ObservableList<IComponentWithID> as a stack and, on each change, reconciles the DOM instead of rebuilding it. Rows are matched by their Identifier; a matched row is re-rendered only when its ContentHash changes, surviving rows are moved into the new order, dropped rows are removed and new ones inserted. Any reorder moves the existing elements, so scroll position, focus and DOM state in untouched rows are kept. Changes are debounced unless the stack is constructed with debounce: false.

Usage

There is no UI. factory: construct it with new KeyedObservableStack(items) and drive it by mutating the list. Each item implements IComponentWithID, returning a stable Identifier and a ContentHash that changes exactly when the rendered content would.

API reference

class

KeyedObservableStack

public class KeyedObservableStack : IComponent, IHasBackgroundColor, IHasMarginPadding, ISpecialCaseStyling, ICanWrap

A Stack whose children are driven by an ObservableList{T} of IComponentWithID. On every change it performs a keyed reconcile against the live DOM rather than rebuilding: existing children are matched by their string Identifier, a matched child is re-rendered (replaceChild) only when its ContentHash changes, surviving children are reordered to match the new sequence, dropped items are removed and new items inserted. Changes are debounced by default.

Remarks

Use this when your items are (or can cheaply be) rendered components that each expose a stable key and a content hash, and you want reordering and/or content-hash-driven replacement (e.g. a server-driven or streaming list such as Chat). For the complementary case, see ObservableStack{T}: it keys data models by reference identity, builds each row lazily via a factory, and never replaces a matched row (rows refresh their own content via observation). Prefer that when items are data objects identified by reference and each row is a self-managing component you do not want rebuilt. Note that it only diffs a common prefix/suffix, so a reorder of interior rows rebuilds that span, whereas KeyedObservableStack handles arbitrary reorders.

Namespace
Tesserae
Implements
IComponent, IHasBackgroundColor, IHasMarginPadding, ISpecialCaseStyling, ICanWrap

Constructors

NameDescription
KeyedObservableStackInitializes a new instance of this class.
Constructor
KeyedObservableStack
public KeyedObservableStack(ObservableList<IComponentWithID> observableList, Orientation orientation = Orientation.Vertical, bool debounce = true)

Initializes a new instance of this class.

Properties

NameDescription
StackOrientationGets or sets the stack orientation.
CanWrapGets or sets a value indicating whether the component's text can wrap onto multiple lines.
IsInlineReturns a value indicating whether the component is inline.
InnerElementGets the underlying DOM element backing this component.
BackgroundGets or sets the CSS background of the component.
MarginGets or sets the CSS margin of the component.
PaddingGets or sets the CSS padding of the component.
StylingContainerGets or sets the styling container.
PropagateStylesToWrapperGets whether a sizing helper applied to this component should tag it so a wrapper-building container hoists the style onto the wrapper.
Property
KeyedObservableStack.StackOrientation
public Orientation StackOrientation { get ; set ; }

Gets or sets the stack orientation.

Property
KeyedObservableStack.CanWrap
public bool CanWrap { get ; set ; }

Gets or sets a value indicating whether the component's text can wrap onto multiple lines.

Property
KeyedObservableStack.IsInline
public bool IsInline { get ; set ; }

Returns a value indicating whether the component is inline.

Property
KeyedObservableStack.InnerElement
public HTMLElement InnerElement { get; private set; }

Gets the underlying DOM element backing this component.

Property
KeyedObservableStack.Background
public string Background { get ; set ; }

Gets or sets the CSS background of the component.

Property
KeyedObservableStack.Margin
public string Margin { get ; set ; }

Gets or sets the CSS margin of the component.

Property
KeyedObservableStack.Padding
public string Padding { get ; set ; }

Gets or sets the CSS padding of the component.

Property
KeyedObservableStack.StylingContainer
public HTMLElement StylingContainer

Gets or sets the styling container.

Property
KeyedObservableStack.PropagateStylesToWrapper
public bool PropagateStylesToWrapper { get; private set; }

Gets whether a sizing helper applied to this component should tag it so a wrapper-building container hoists the style onto the wrapper.

Methods

NameDescription
AlignItemsSets the align-items css property for this stack
AlignItemsCenterSets the align-items css property for this stack to 'center'
RelativeMake this stack relative (i.e. position:relative)
AlignContentSets the align-content CSS property for this stack.
JustifyContentSets the justify-content CSS property for this stack.
JustifyItemsSets the justify-items CSS property for this stack.
RemovePropagationRemoves the given propagation from the component.
OnMouseOverRegisters a callback invoked when the mouse over event fires.
OnMouseOutRegisters a callback invoked when the mouse out event fires.
ClearClears the component's current state.
RenderRenders the component's root HTML element.
HorizontalConfigures the component to horizontal.
VerticalConfigures the component to vertical.
HorizontalReverseConfigures the horizontal reverse on the component.
VerticalReverseConfigures the vertical reverse on the component.
WrapAllows the component's content to wrap onto multiple lines.
InlineRenders the component inline.
NoWrapRemoves / disables the wrap on the component.
OverflowHiddenHides any content that overflows the component's bounds.
NoDefaultMarginRemoves / disables the default margin on the component.
SkeletonConfigures the component to skeleton.
Method
KeyedObservableStack.AlignItems
public KeyedObservableStack AlignItems(ItemAlign align)

Sets the align-items css property for this stack

Parameters

align
Method
KeyedObservableStack.AlignItemsCenter
public KeyedObservableStack AlignItemsCenter()

Sets the align-items css property for this stack to 'center'

Parameters

align
Method
KeyedObservableStack.Relative
public KeyedObservableStack Relative()

Make this stack relative (i.e. position:relative)

Method
KeyedObservableStack.AlignContent
public KeyedObservableStack AlignContent(ItemAlign align)

Sets the align-content CSS property for this stack.

Parameters

align
The alignment.

Returns

The current instance.

Method
KeyedObservableStack.JustifyContent
public KeyedObservableStack JustifyContent(ItemJustify justify)

Sets the justify-content CSS property for this stack.

Parameters

justify
The justification.

Returns

The current instance.

Method
KeyedObservableStack.JustifyItems
public KeyedObservableStack JustifyItems(ItemJustify justify)

Sets the justify-items CSS property for this stack.

Parameters

justify
The justification.

Returns

The current instance.

Method
KeyedObservableStack.RemovePropagation
public KeyedObservableStack RemovePropagation()

Removes the given propagation from the component.

Method
KeyedObservableStack.OnMouseOver
public KeyedObservableStack OnMouseOver(ComponentEventHandler<KeyedObservableStack, Event> onMouseOver)

Registers a callback invoked when the mouse over event fires.

Method
KeyedObservableStack.OnMouseOut
public KeyedObservableStack OnMouseOut(ComponentEventHandler<KeyedObservableStack, Event> onMouseOut)

Registers a callback invoked when the mouse out event fires.

Method
KeyedObservableStack.Clear
public virtual void Clear()

Clears the component's current state.

Method
KeyedObservableStack.Render
public virtual HTMLElement Render()

Renders the component's root HTML element.

Method
KeyedObservableStack.Horizontal
public KeyedObservableStack Horizontal()

Configures the component to horizontal.

Method
KeyedObservableStack.Vertical
public KeyedObservableStack Vertical()

Configures the component to vertical.

Method
KeyedObservableStack.HorizontalReverse
public KeyedObservableStack HorizontalReverse()

Configures the horizontal reverse on the component.

Method
KeyedObservableStack.VerticalReverse
public KeyedObservableStack VerticalReverse()

Configures the vertical reverse on the component.

Method
KeyedObservableStack.Wrap
public KeyedObservableStack Wrap()

Allows the component's content to wrap onto multiple lines.

Method
KeyedObservableStack.Inline
public KeyedObservableStack Inline()

Renders the component inline.

Method
KeyedObservableStack.NoWrap
public KeyedObservableStack NoWrap()

Removes / disables the wrap on the component.

Method
KeyedObservableStack.OverflowHidden
public KeyedObservableStack OverflowHidden()

Hides any content that overflows the component's bounds.

Method
KeyedObservableStack.NoDefaultMargin
public KeyedObservableStack NoDefaultMargin()

Removes / disables the default margin on the component.

Method
KeyedObservableStack.Skeleton
public IComponent Skeleton(bool enabled = true)

Configures the component to skeleton.

interface

IComponentWithID

public interface IComponentWithID : IComponent
Namespace
Tesserae
Implements
IComponent

See also