public Sidebar(bool sortable = false)

Initializes a new instance of the Sidebar class.

Parameters

sortable

Whether the middle content items should be sortable.

public bool IsClosed { get ; set ; }

Gets or sets whether the sidebar is closed.

public bool IsNavbar

Gets whether the sidebar is currently rendering as a navbar.

public bool IsPage

Gets whether the sidebar is currently rendering as a page - see AsPage.

public IObservable<bool> PageMode

Observes whether the sidebar renders as a page - see AsPage.

public bool IsShowingContent

Gets whether a sidebar rendering as a page has stepped aside for the content next to it. Always false while the sidebar is not a page.

public IObservable<bool> ShowingContent

Observes whether a sidebar rendering as a page has stepped aside for the content (true) or is the page on screen (false).

public bool IsShifted

Gets whether the sidebar is currently showing the shifted (child) sidebar.

public Sidebar ShiftedSidebar

Gets the child sidebar that is currently mounted for shifting, if any.

public Sidebar Secondary()

Sets the sidebar background to the secondary background color.

Returns

The current instance of the type.

public void Sortable(bool sortable = true)

Sets whether the middle content items are sortable.

Parameters

sortable

Whether items are sortable.

public Sidebar AsNavbar(bool isNavbar = true)

Configures the sidebar to render as a navbar - a horizontal bar with a hamburger that opens the items in a sliding drawer - or back to an ordinary vertical sidebar.

Parameters

isNavbar

Whether to render as a navbar.

Returns

The current instance.

Remarks

Both directions are supported so an app can follow OnMobileModeChanged and switch on a window resize, rather than deciding once at startup and rendering a layout the stylesheet then reshapes underneath it.

public Sidebar AsPage(bool isPage = true)

Configures the sidebar to render as a page - the phone layout where the sidebar and the content next to it take turns filling the screen - or back to an ordinary sidebar.

Parameters

isPage

Whether to render as a page.

Returns

The current instance.

Remarks

As a page the sidebar is always open and fills its container, and everything after it in that container is hidden. Picking one of its buttons steps it aside (ShowContent), which hides the sidebar and brings the content back; ShowSidebar is the way back, and SidebarPageBar is a bar for the content that carries the button doing it. The open/closed state is kept rather than cleared, so a sidebar that stops being a page returns to the rail the user left. Follow OnMobileModeChanged to switch on a resize.

public Sidebar ShowContent()

Steps a sidebar rendering as a page aside, so the content next to it fills the screen. Does nothing visible while the sidebar is not a page, beyond remembering it for when it becomes one.

Returns

The current instance.

public Sidebar ShowSidebar()

Brings a sidebar rendering as a page back in place of the content - the back button of SidebarPageBar.

Returns

The current instance.

public Sidebar Closed(bool isClosed = true)

Sets whether the sidebar is closed.

Parameters

isClosed

Whether the sidebar is closed.

Returns

The current instance of the type.

public Sidebar Toggle()

Toggles the closed state of the sidebar.

Returns

The current instance of the type.

public Sidebar ShiftTo(Sidebar child)

Slides horizontally into a child sidebar, used when navigating into an interface that has its own sidebar. The child sidebar is rendered inside this one and follows its open/closed state. Only one depth level is supported: shifting into another child replaces the current one. Call ShiftBack to slide back into this sidebar.

Parameters

child

The sidebar to shift into.

Returns

The current instance of the type.

public Sidebar ShiftBack()

Slides back from the child sidebar into this sidebar.

Returns

The current instance of the type.

public Sidebar OnShiftChanged(Action<bool> onShiftChanged)

Adds a handler that is called whenever the sidebar shifts into the child sidebar (true) or back (false).

Parameters

onShiftChanged

The event handler.

Returns

The current instance of the type.

public Sidebar AddHeader(ISidebarItem item)

Adds an item to the sidebar header section.

Parameters

item

The item to add.

Returns

The current instance of the type.

public Sidebar InsertAfterHeader(ISidebarItem item, ISidebarItem addAfter)

Inserts an item after another item in the sidebar header section.

Parameters

item

The item to insert.

addAfter

The item to insert after.

Returns

The current instance of the type.

public Sidebar AddContent(ISidebarItem item)

Adds an item to the middle content section.

Parameters

item

The item to add.

Returns

The current instance of the type.

public Sidebar InsertAfterContent(ISidebarItem item, ISidebarItem addAfter)

Inserts an item after another item in the middle content section.

Parameters

item

The item to insert.

addAfter

The item to insert after.

Returns

The current instance of the type.

public Sidebar RemoveContent(ISidebarItem item)

Removes an item from the middle content section.

Parameters

item

The item to remove.

Returns

The current instance of the type.

public Sidebar AddFooter(ISidebarItem item)

Adds an item to the sidebar footer section.

Parameters

item

The item to add.

Returns

The current instance of the type.

public Sidebar InsertAfterFooter(ISidebarItem item, ISidebarItem addAfter)

Inserts an item after another item in the sidebar footer section.

Parameters

item

The item to insert.

addAfter

The item to insert after.

Returns

The current instance of the type.

public void Clear()

Clears all sections of the sidebar.

public void ClearHeader()

Clears the header section.

public void ClearContent()

Clears the middle content section.

public void ClearFooter()

Clears the footer section.

public HTMLElement Render()

Renders the sidebar.

Returns

The rendered HTMLElement.

public IObservable<bool> AsObservable()

Returns an observable that tracks the closed/open state of the sidebar.

public void SetBoundValue(bool value)

Programmatically opens or closes the sidebar as part of a two-way binding.

public void LoadSorting(Dictionary<string, string[]> itemOrder)

Loads the sorting order for sidebar items. Should be called after all items have been added.

Parameters

itemOrder

A dictionary mapping group identifiers to ordered item identifiers.

public Dictionary<string, string[]> GetCurrentSorting()

Gets the current sorting order of all items in the sidebar.

Returns

A dictionary mapping group identifiers to ordered item identifiers.

public void Refresh()

Refreshes the sidebar rendering.

public void OnSortingChanged(Action<Dictionary<string, string[]>> onSortingChanged)

Adds a sorting change event handler.

Parameters

onSortingChanged

The event handler.

public void Search(string searchTerm)

Searches/Filters the sidebar content items.

Parameters

searchTerm

The term to search for.

public static string GetOwnIdentifier(string identifier)

Gets the own identifier of an item by removing group identifier prefix.

Parameters

identifier

The full identifier.

Returns

The own identifier.

public static string WithGroupIdentifier(string identifier, string groupIdentifier)

Stamps an item's identifier with the group it is being placed in, unless it already carries it.

Parameters

identifier

The item's current identifier.

groupIdentifier

The group the item is being placed in.

Returns

The identifier as it reads inside that group.

Remarks

The stamped identifier is how an item is found again once it is placed, so stamping twice would leave it unfindable. That happens whenever an item is placed, taken out and placed back, and whenever a caller hands in a freshly built item for a method that has to match the one already there - which is why every method that matches an identifier normalises through this first.

public const int SIDEBAR_TRANSITION_TIME = 300

The transition time for sidebar animations in milliseconds.

public const int SIDEBAR_SHIFT_TRANSITION_TIME = 150

How long shifting into a child sidebar and back takes - half the time the sidebar's own open/close animation takes, since both places are already there and the move wants to feel immediate. Kept in step with the transition on .tss-sidebar-shift-track in tss.sidebar.css.

private const int NAV_OVERLAY_PEEK = 12

How far each panel behind the front one steps left, in pixels - the strip of it that shows.

private const int NAV_OVERLAY_MAX_PEEK_DEPTH = 3

How many panels behind the front one still peek out; deeper ones sit behind the last of them.

public const string ROOT_SIDEBAR_FOR_ORDERING = "ROOT"

The root identifier used for ordering.

public const string GroupIdentifierSeparator = "_|_"

The separator used between group identifiers and item identifiers.

public bool IsSelected { get ; set ; }

Gets or sets whether the button is currently selected.

public IObservable<bool> SelectedStatus

Gets an observable for the selected status.

public IComponent CurrentRendered

Gets the component that is currently rendered.

public string Identifier { get; private set; }

Gets the full identifier of the button.

public string OwnIdentifier

Gets the own identifier of the button.

public void AddGroupIdentifier(string groupIdentifier)

Adds a group identifier prefix to the button's identifier.

private static void ReserveRoomForCommands(HTMLElement wrapper, int commandCount)

Marks the row as one that has commands, and says how wide its strip of them is - each is a 22px button with a 4px gap between them. Only the row knows how many it has, so it writes both here and the stylesheet reads them back to lay the label out beside the strip wherever the strip is permanent - always-visible, or selected. On hover the label keeps the full width of the rail and fades out into the row where the commands begin instead (see tss-sidebar-has-commands and the scrim on it in tss.sidebar.css).

private void TrackBadgeWidth(HTMLElement wrapper, HTMLElement badges)

Marks the row as one that carries a badge, and keeps how wide the badge is up to date. A badge is drawn over the row's right edge the way the commands are, so the name has to give way to it or a long one runs underneath the glyph - which is what a shared-space icon sitting on the last letters of the space's name was. The stylesheet keeps room for it at rest and fades the name out into it under the pointer, and both are sized from how wide the badge is. Unlike the commands there is no count to compute that from - a badge is an icon, or "+3", or "+1,204" - so it is measured, and re-measured whenever its text changes, and written where the stylesheet reads it back (see tss-sidebar-has-badge in tss.sidebar.css). The badge is hidden with visibility rather than display where the commands take its place, so the measurement stays true.

public void Show()

Shows the button.

public void Collapse()

Collapses the button.

public SidebarButton NotSortable()

Marks the button as not sortable.

Returns

The current instance of the type.

public SidebarButton ClearProgress()

Clears the progress indication background.

Returns

The current instance of the type.

public SidebarButton Progress(float progress)

Sets a progress indication background.

Parameters

progress

The progress value (0 to 1).

Returns

The current instance of the type.

public SidebarButton SetText(string text)

Sets the text of the button.

Parameters

text

The text.

Returns

The current instance of the type.

public SidebarButton CommandsAlwaysVisible(bool alwaysVisible = true)

Ensures that commands associated with the button are always visible when the sidebar is open.

Returns

The current instance of the type.

public SidebarButton Light()

Sets the button to use a light style.

Returns

The current instance of the type.

public SidebarButton Rounded(BorderRadius radius = BorderRadius.Full)

Renders the button with rounded corners (defaults to a fully rounded "pill" shape), matching the rounded SidebarSearchBox style.

Parameters

radius

The border radius to apply. Defaults to Full.

Returns

The current instance of the type.

public SidebarButton Outlined()

Draws the button with a field's chrome - a border and the secondary surface behind it - instead of as a bare row. What a rail's own action wants when it stands next to a search box: the same outline, so the two read as a pair of controls rather than as a button beside a form field. Only the open button takes it; around a single glyph on the closed rail an outline is just a box.

Returns

The current instance of the type.

public SidebarButton AsSearchBox(params string[] shortcutKeys)

Dresses the button as a search field: a rounded outline, the label set as a placeholder rather than as a label, and - when keys are given - the shortcut that reaches it shown at the far end. For a search that answers somewhere else, which is most of them now: what the box would be for happens in a palette or on a page, so the thing on the rail only has to look like where a search starts and be pressable. A real input would take a caret it has nothing to do with.

Parameters

shortcutKeys

The keys to show at the end, e.g. ("Ctrl", "K"). None hides it. The chip is a label only - use SetKeyboardShortcut for the key to press the button as well, which a search that answers somewhere else usually does not want: the palette or page it opens owns that key, and answers it from inside a text field too, where a button's shortcut steps aside.

public SidebarButton SetKeyboardShortcut(params string[] keys)

Shows the shortcut that presses this button at its far end, and answers that shortcut for as long as the button is on screen - which is what makes the chip a promise rather than a note. The keys are the ones KeyboardShortcut displays, so ("Ctrl", "Shift", "O") reads Ctrl+Shift+O and triggers on ⌘⇧O on a Mac. Only the open button carries the chip - the closed rail has room for the glyph and nothing else - but the key works on either, because a collapsed rail is a smaller rail and not a different one. A button that is nowhere on screen holds no shortcut: there is nothing for the key to press.

Parameters

keys

The keys, e.g. ("Ctrl", "Shift", "O"). None removes chip and binding.

public SidebarButton ShortcutOnlyOnHover(bool onlyOnHover = true)

Keeps the shortcut chip out of sight until the pointer is on the row - or something inside it has focus, so a row reached by tabbing shows its key too. The binding is untouched: the key works the same whether or not the chip is on screen. For a rail where most rows carry a key: all the chips at once read as a column of noise beside the labels, while one chip on the row being pointed at is still how the key gets discovered. The room at the end stays reserved either way, so a label does not re-flow as the chip appears.

Parameters

onlyOnHover

Whether the chip waits for a hover. False shows it at all times, the default.

private Button ButtonOnScreen()

Whichever of the two renderings the user can actually see, or null when neither is. Mounted is not enough on its own: both are mounted at once while the sidebar hides the one it is not showing, and a collapsed button is mounted too.

public SidebarButton Danger()

Sets the button to use a danger style.

Returns

The current instance of the type.

public SidebarButton Warning()

Sets the button to use a warning style.

Returns

The current instance of the type.

public SidebarButton Default()

Sets the button to use the default style.

Returns

The current instance of the type.

public SidebarButton Success()

Sets the button to use a success style.

Returns

The current instance of the type.

public SidebarButton Primary()

Sets the button to use the primary style.

Returns

The current instance of the type.

public SidebarButton Selected(bool isSelected = true)

Sets whether the button is selected.

Parameters

isSelected

Whether the button is selected.

Returns

The current instance of the type.

public SidebarButton Id(string id)

Sets the ID of the button.

Parameters

id

The ID.

Returns

The current instance of the type.

public ISidebarItem OnRendered(Action<HTMLElement> onRendered)

Adds a rendered event handler.

Parameters

onRendered

The rendered event handler.

Returns

The current instance of the type.

public IComponent RenderClosed()

Renders the button for the closed state of the sidebar.

public IComponent RenderOpen()

Renders the button for the open state of the sidebar.

public bool IsCollapsed { get ; set ; }

Gets or sets whether the navigation is collapsed.

public bool IsSelected { get ; set ; }

Gets or sets whether the navigation is currently selected.

public IObservable<bool> CollapsedStatus

Gets an observable for the collapsed status.

public IObservable<bool> SelectedStatus

Gets an observable for the selected status.

public IComponent CurrentRendered

Gets the component that is currently rendered.

internal bool HasClickAction { get; private set; }

Whether the header does something when pressed, beyond expanding the group.

internal string Text

The group's name, for a surface that shows the group apart from its header.

public string Identifier { get; private set; }

Gets the full identifier of the navigation component.

public string OwnIdentifier

Gets the own identifier of the navigation component.

public void Show()

Shows the navigation component.

public void Collapse()

Collapses the navigation component.

public SidebarNav NotSortable()

Marks the navigation component as not sortable.

Returns

The current instance of the type.

public SidebarNav SetText(string text)

Sets the header text of the navigation.

Parameters

text

The text.

Returns

The current instance of the type.

public SidebarNav Collapsed(bool isCollapsed = true)

Sets whether the navigation is collapsed.

Parameters

isCollapsed

Whether it is collapsed.

Returns

The current instance of the type.

public SidebarNav Selected(bool isSelected = true)

Sets whether the navigation is selected.

Parameters

isSelected

Whether it is selected.

Returns

The current instance of the type.

public SidebarNav Toggle()

Toggles the collapsed state.

Returns

The current instance of the type.

public SidebarNav KeepCollapsedOnSelection(bool keepCollapsed = true)

Keeps the navigation collapsed when one of its items becomes selected. By default a collapsed navigation expands itself when a child (or a nested descendant) becomes selected, so the current selection is never hidden from the user.

Parameters

keepCollapsed

Whether to suppress the automatic expansion on selection.

Returns

The current instance of the type.

internal void PressHeader()

Presses the header, as a click on it would - what the group's own row does.

public void Clear()

Clears all items from the navigation.

public void Add(ISidebarItem item)

Adds an item to the navigation.

Parameters

item

The item to add.

public void Remove(ISidebarItem item)

Removes an item from the navigation.

Parameters

item

The item to remove.

public SidebarNav AddRange(IEnumerable<ISidebarItem> items)

Adds a range of items to the navigation.

Parameters

items

The items to add.

Returns

The current instance of the type.

public IComponent RenderClosed()

Renders the navigation for the closed state of the sidebar.

public IComponent RenderOpen()

Renders the navigation for the open state of the sidebar.

public ISidebarItem OnRendered(Action<HTMLElement> onRendered)

Adds a rendered event handler.

Parameters

onRendered

The rendered event handler.

Returns

The current instance of the type.

public void AddGroupIdentifier(string groupIdentifier)

Adds a group identifier prefix to the navigation component's identifier.

public void LoadSorting(Dictionary<string, string[]> itemOrder)

Loads the sorting order for navigation items.

Parameters

itemOrder

A dictionary mapping group identifiers to ordered item identifiers.

public Dictionary<string, string[]> GetCurrentSorting()

Gets the current sorting order of all items within this navigation.

Returns

A dictionary mapping group identifiers to ordered item identifiers.

public SidebarNav Sortable(bool sortable = true, string sortableGroup = null)

Sets whether items within this navigation are sortable.

Parameters

sortable

Whether items are sortable.

sortableGroup

An optional group name for cross-nav sorting.

Returns

The current instance of the type.

public SidebarNav OnSortingChanged(Action<Dictionary<string, string[]>> onSortingChanged)

Adds a sorting change event handler.

Parameters

onSortingChanged

The event handler action.

Returns

The current instance of the type.

public SidebarNav OnParentChanged(Action<ParentChangedEvent> onParentChanged)

Adds a parent changed event handler, for cross-nav sorting.

Parameters

onParentChanged

The event handler action.

Returns

The current instance of the type.

public event Action<Dictionary<string, string[]>> _onSortingChanged

Event fired when sorting changes within the navigation.

private const string KeepCollapsedClass = "tss-sidebar-nav-keep-collapsed"

A group that keeps its selection hidden says the selection is not the page the user is on (a theme picker, a mode switch), so a stylesheet that marks the group holding the current page can leave it out.

public string Text { get ; set ; }

The text in the box. Setting it does not raise OnSearch - a caller that clears the box usually has its own idea of what to do about the results.

public SidebarSearchBox Rounded(BorderRadius radius = BorderRadius.Full)

Renders the search box with rounded corners (defaults to a fully rounded "pill" shape, like the rounded SidebarButton). Removes the underlined style so the box shows a full rounded border.

Parameters

radius

The border radius to apply. Defaults to Full.

Returns

The current instance of the type.

public SidebarSearchBox SetText(string text)

Sets the text in the box, without raising OnSearch.

public SidebarSearchBox Focus()

Puts the caret in the box.

public SidebarSearchBox OnClick(Action onClick)

Makes the box a way in rather than a place to type: clicking it - open, or as the icon on the closed rail - runs the handler, and so does focusing it, which is what SetKeyboardShortcut does. Nothing can be typed into it, because what is typed belongs to whatever the handler opened. This is the shape a search that answers somewhere else takes: the box says where to start and which key gets there, and a palette or a page does the searching.

public SidebarSearchBox ShortcutOnlyOnHover(bool onlyOnHover = true)

Keeps the shortcut chip out of sight until the pointer is on the box - or the caret is in it, so a box reached by tabbing shows its key too. The binding is untouched: the key works the same whether or not the chip is on screen. The room the chip takes at the end is reserved either way, so what is typed does not re-flow as the chip appears.

Parameters

onlyOnHover

Whether the chip waits for a hover. False shows it at all times, the default.

public SidebarCommand Foreground(string color)

Sets the foreground color of the command button.

Parameters

color

The color.

Returns

The current instance of the type.

public SidebarCommand HookToParentContextMenu()

Configures the command to hook into the parent's context menu event.

Returns

The current instance of the type.

public SidebarCommand Background(string color)

Sets the background color of the command button.

Parameters

color

The color.

Returns

The current instance of the type.

public SidebarCommand Default()

Sets the command to use the default style.

Returns

The current instance of the type.

public SidebarCommand Primary()

Sets the command to use the primary style.

Returns

The current instance of the type.

public SidebarCommand Success()

Sets the command to use the success style.

Returns

The current instance of the type.

public SidebarCommand Danger()

Sets the command to use the danger style.

Returns

The current instance of the type.

public SidebarCommand Warning()

Sets the command to use the warning style.

Returns

The current instance of the type.

public SidebarCommand OnClickMenu(Func<ISidebarItem[]> generator)

Configures the command to show a menu when clicked.

Parameters

generator

A function that generates the sidebar items for the menu.

Returns

The current instance of the type.

public void ShowMenu()

Shows the associated menu for the command.

public SidebarCommand RaiseOnClick(MouseEvent mouseEvent)

Programmatically raises the click event.

Parameters

mouseEvent

The mouse event arguments.

Returns

The current instance of the type.

public SidebarCommand RaiseOnContextMenu(MouseEvent mouseEvent)

Programmatically raises the context menu event.

Parameters

mouseEvent

The mouse event arguments.

Returns

The current instance of the type.

public HTMLElement Render()

Renders the sidebar command.

Returns

The rendered HTMLElement.

public bool IsSelected { get; set; }

Gets or sets whether the group is currently selected.

public IComponent CurrentRendered { get; private set; }

Gets the component that is currently rendered.

public string Identifier { get; private set; }

Gets the full identifier of the command group.

public string OwnIdentifier

Gets the own identifier of the command group.

public IComponent RenderOpen()

Renders the commands for the open state of the sidebar.

public void Show()

Shows the commands.

public void Collapse()

Collapses the commands.

public IComponent RenderOpenFull()

Renders all commands for the open state without truncation.

public IComponent RenderClosed()

Renders the commands for the closed state of the sidebar.

public SidebarCommands AlignEnd()

Aligns the commands to the end of the line.

Returns

The current instance of the type.

public SidebarCommands NotSortable()

Marks the commands as not sortable.

Returns

The current instance of the type.

public void AddGroupIdentifier(string groupIdentifier)

Adds a group identifier prefix to the command group's identifier.

public SidebarText(string identifier, string text, string closedText = null, TextSize textSize = TextSize.Small, TextWeight textWeight = TextWeight.Regular)

Initializes a new instance of the SidebarText class.

Parameters

identifier

The identifier for the text item.

text

The text to display when the sidebar is open.

closedText

The optional text to display when the sidebar is closed.

textSize

The size of the text.

textWeight

The weight of the text.

public IComponent CurrentRendered

Gets the component that is currently rendered.

public bool IsSelected { get; set; }

Gets or sets whether the item is currently selected.

public string Identifier { get; private set; }

Gets the full identifier of the text component.

public string OwnIdentifier

Gets the own identifier of the text component.

public void Show()

Shows the text component.

public void Collapse()

Collapses the text component.

public SidebarText NotSortable()

Marks the text component as not sortable.

Returns

The current instance of the type.

public void AddGroupIdentifier(string groupIdentifier)

Adds a group identifier prefix to the text component's identifier.

public SidebarText SetText(string text)

Sets the text content for the open state.

Parameters

text

The text.

Returns

The current instance of the type.

public SidebarText Foreground(string color)

Sets the foreground color of the text.

Parameters

color

The color.

Returns

The current instance of the type.

public SidebarText PT(int pixels)

Sets the top padding of the text.

Parameters

pixels

The padding in pixels.

Returns

The current instance of the type.

public SidebarText PB(int pixels)

Sets the bottom padding of the text.

Parameters

pixels

The padding in pixels.

Returns

The current instance of the type.

public SidebarText PL(int pixels)

Sets the left padding of the text.

Parameters

pixels

The padding in pixels.

Returns

The current instance of the type.

public IComponent RenderClosed()

Renders the text for the closed state of the sidebar.

public IComponent RenderOpen()

Renders the text for the open state of the sidebar.

public SidebarBadge SemiTransparent()

Sets the badge icon to be semi-transparent.

Returns

The current instance of the type.

public SidebarBadge Foreground(string color)

Sets the foreground color of the badge.

Parameters

color

The color.

Returns

The current instance of the type.

public SidebarBadge Background(string color)

Sets the background color of the badge.

Parameters

color

The color.

Returns

The current instance of the type.

public SidebarBadge Default()

Sets the badge to use the default style.

Returns

The current instance of the type.

public SidebarBadge Primary()

Sets the badge to use the primary style.

Returns

The current instance of the type.

public SidebarBadge Success()

Sets the badge to use the success style.

Returns

The current instance of the type.

public SidebarBadge Danger()

Sets the badge to use the danger style.

Returns

The current instance of the type.

public SidebarBadge Warning()

Sets the badge to use the warning style.

Returns

The current instance of the type.

public SidebarBadge SetBadge(string badge)

Sets the text content of the badge.

Parameters

badge

The badge text.

Returns

The current instance of the type.

public HTMLElement Render()

Renders the sidebar badge.

Returns

The rendered HTMLElement.

private static IComponent WrapLogo(IComponent logo)

A box of its own around whatever the logo is, so that an image, a glyph and an emoji all take the same square beside the name - the stylesheet sizes the box rather than each of the three.

public SidebarBrand SetTitle(string title)

Sets the application's name.

Parameters

title

The name.

Returns

The current instance of the type.

public SidebarBrand WithSidebarControl( Action onOpen, Action onClose, string openTooltip = null, string closeTooltip = null, UIcons openIcon = UIcons.SidebarFlip, UIcons closeIcon = UIcons.Sidebar)

Makes the brand the rail's own open/close control, which is where an application that has one usually wants it: at the top, on the row that is there in both states. While the sidebar is open it is the last command on the row, so closing the rail is the rightmost thing on it. While the sidebar is closed there is no room for a command beside the logo, so the logo is the control: it stands as the brand at rest and turns into the open button under the pointer. The row reports the two intentions rather than driving a sidebar itself, because the rail a brand sits on is not always the one it opens - an application shifts between rails, and rebuilds them - so the caller is the one that knows which Sidebar to toggle and what else follows from it.

Parameters

onOpen

What opening the rail does. Called from the control the collapsed rail shows.

onClose

What closing it does. Called from the last command on the open row.

openTooltip

The tooltip on the open control. None uses "Open Sidebar".

closeTooltip

The tooltip on the close command. None uses "Close Sidebar".

openIcon

The icon of the open control. The rail's own glyph, mirrored.

closeIcon

The icon of the close command. The rail's own glyph.

Returns

The current instance of the type.

public SidebarProfile(string identifier, string name, string subtitle = null, string pictureUrl = null, string initials = null) : this(identifier, name, subtitle, InitialAvatars(pictureUrl, string.IsNullOrWhiteSpace(initials) ? InitialsFor(name) : initials))

Initializes a new instance of the SidebarProfile class.

Parameters

identifier

The identifier for the item.

name

The name to show on the first line.

subtitle

What identifies the account beside the name - an e-mail address, a company, a tenant. None leaves the row a single line.

pictureUrl

The picture to show. None - or one that fails to load - falls back to the initials.

initials

The initials to fall back to. None takes them from the name.

private static Avatar[] InitialAvatars(string pictureUrl, string initials)

The two avatars a row needs - one for the open row, one for the collapsed rail, since a single element cannot be in two places. Built before the base constructor runs, which is what the array is for. They are the same size: the collapsed rail shows the row's picture in a box of the row's own height, not a smaller row.

public SidebarProfile SetName(string name)

Sets the name shown on the first line, and the initials taken from it where none were given.

Parameters

name

The name.

Returns

The current instance of the type.

public SidebarProfile SetPicture(string pictureUrl)

Sets the picture. One that fails to load falls back to the initials, so a URL that answers only for accounts that have uploaded a photo can be passed unconditionally.

Parameters

pictureUrl

The picture URL.

Returns

The current instance of the type.

public SidebarProfile SetInitials(string initials)

Sets the initials the picture falls back to. None - the default - takes them from the name.

Parameters

initials

The initials.

Returns

The current instance of the type.

public SidebarProfile Presence(AvatarPresence presence)

Shows a presence dot on the picture - online, away, busy, offline.

Parameters

presence

The presence state.

Returns

The current instance of the type.

public static string InitialsFor(string name)

The initials a name falls back to when there is no picture: the first letter of the first word and of the last, so "M. Okafor" reads MO and "Okafor" reads O. Anything that is not a letter or a digit is skipped, which is what keeps an initial out of "M." and out of an emoji.

protected SidebarIdentityRow(string identifier, string rowClass, IComponent openLeading, IComponent closedLeading, string title, string subtitle)

Parameters

identifier

The identifier for the item.

rowClass

The class naming the concrete row, e.g. tss-sidebar-profile.

openLeading

The picture shown while the sidebar is open.

closedLeading

The picture shown on the collapsed rail. A second instance, since one element cannot be in two places.

title

The name on the first line.

subtitle

The second line, or null for a single-line row.

protected abstract T Self { get; }

The concrete row, so that a fluent method defined here returns the type it was called on.

protected Button OpenButton

The button the open row draws, for a subclass that has to reach it.

protected Button ClosedButton

The button the collapsed rail draws.

protected HTMLElement ClosedRoot

The element the collapsed rail draws, for a row that puts something else beside the picture there - see WithSidebarControl, which lays a control over it for the hover.

protected string TitleText

The name on the first line.

protected string SubtitleText

The second line, or an empty string when there is none.

public bool IsSelected { get ; set ; }

Gets or sets whether the item is currently selected.

public IObservable<bool> SelectedStatus

Gets an observable for the selected status.

public IComponent CurrentRendered

Gets the component that is currently rendered.

public string Identifier { get; private set; }

Gets the full identifier of the item, including group identifiers.

public string OwnIdentifier

Gets the own identifier of the item, without group identifiers.

public void AddGroupIdentifier(string groupIdentifier)

Adds a group identifier prefix to the item's identifier.

public void Show()

Shows the item.

public void Collapse()

Collapses the item.

public T SetSubtitle(string subtitle)

Sets the second line - an e-mail address, a company, an environment. Null or empty leaves the row a single line rather than an empty one.

Parameters

subtitle

The text for the second line.

Returns

The current instance of the type.

public T Commands(params SidebarCommand[] commands)

The commands drawn before the row's own - a search, a back arrow, the control that collapses the rail. Replaces whatever was set before.

Parameters

commands

The commands.

Returns

The current instance of the type.

public T CommandsOnHover(bool onHover = true)

Keeps the commands out of sight until the pointer is on the row, the way an ordinary row's commands behave. The default is the other way round, because the row's commands are usually the only way to what they open.

Parameters

onHover

Whether the commands wait for a hover.

Returns

The current instance of the type.

public T Separated(bool separated = true)

Draws a divider on the row's outer edge - above a row at the bottom of the rail, below one at the top - running the full width of the sidebar rather than stopping at its padding.

Parameters

separated

Whether to draw the divider.

Returns

The current instance of the type.

public T Selected(bool isSelected = true)

Sets whether the row is selected - what marks the page it opens as the one being shown.

Parameters

isSelected

Whether the row is selected.

Returns

The current instance of the type.

public T NotSortable()

Marks the item as not sortable, which is what a row of chrome wants.

Returns

The current instance of the type.

public T Class(string className)

Adds a class to both renderings of the item.

Parameters

className

The class name.

Returns

The current instance of the type.

public T OnContextMenu(Action<Button, MouseEvent> action)

Adds a context menu event handler.

Parameters

action

The event handler action.

Returns

The current instance of the type.

public ISidebarItem OnRendered(Action<HTMLElement> onRendered)

Adds a rendered event handler.

Parameters

onRendered

The rendered event handler.

Returns

The current instance of the type.

public IComponent RenderClosed()

Renders the item for the closed state of the sidebar.

public IComponent RenderOpen()

Renders the item for the open state of the sidebar.

protected void SetTitleText(string title)

Replaces the name on the first line. Kept protected so each row can name it for what it holds - the account's name, the product's name - and keep whatever else follows from it in step.

Parameters

title

The name.

protected void SetTitleBadge(HTMLElement badge, string text)

Puts an element on the name's line, after the name - a label that qualifies the name itself rather than adding a second line under it, like the environment a brand's application runs in. The name gives way before it does: a name too long for the row is ellipsized and the label stays whole. The name and the label share a line of their own only while there is a label, so a row without one keeps exactly the markup it always had.

Parameters

badge

The element to put after the name, or null to remove the one there.

text

What the label says, for the collapsed rail's tooltip, which has no room for the element.

protected void FitRailToText()

Has the open rail the row sits on grow to the width its name and second line need, so neither is ellipsized - for the row whose text is what the rail is for, the application's name. The rail never shrinks below the width it was given; this only raises its floor. The row measures itself rather than asking for a number, because what the text has to share the row with - the rail's padding, the logo, the gap, the strip of commands - is the stylesheet's and a skin's to change. The room the text has now is subtracted from the rail's width, and what the text wants is added back: whatever else is on the row cancels out, and so does the rail's own width. So the answer only moves with what is on the row, and that is when it is measured: each time the open row is mounted, when the text or the commands change, and once the fonts arrive. Never on a resize - a rail being dragged wider would otherwise force a layout read and restyle the whole sidebar on every frame, to write the number it already had.

private double TitleLineWidth()

The width the name's line wants: the name, and with a label after it the distance from the end of the name as drawn to the end of the label - the gap and the label, whatever a skin makes them, and the same whether or not the name is ellipsized at the moment, since the label follows it.

private void OnOpenRowRemoved()

The open row comes off the rail every time the rail closes, and the collapsed picture goes on in the same pass. The floor stays then - the stylesheet ignores it on a closed rail, and the rail opens straight to it - and goes only when the row has left the rail altogether.

private HTMLElement RailToFit()

The sidebar the row is on, unless that is a child sidebar shifted into another (ShiftTo): a child fills its host's panel and the host owns the width, so a child's row is left to ellipsize rather than widen a rail that is not its own.

protected void SetPrimaryCommand(SidebarCommand command)

The row's own command, drawn last - settings on a profile, configuration on a brand.

Parameters

command

The command, or null to remove it.

protected void SetSecondaryCommand(SidebarCommand command)

The row's second command, drawn after the first - logging out, on a profile.

Parameters

command

The command, or null to remove it.

private void RefreshDefaultTooltip()

The tooltip the collapsed rail gets when the caller has not set one: the name, and the second line after it where there is one. Re-applied whenever either changes, and left alone once a tooltip has been set by hand.

private const string RAIL_MIN_WIDTH_VARIABLE = "--tss-sidebar-identity-min-width"

The width the open rail needs for the row's text to be drawn whole, written on the rail by FitRailToText and turned into a min-width by tss.sidebar.css only while the rail is open - a variable rather than the property itself, so the closed rail's 54px and the page and navbar layouts are the stylesheet's to keep.

private const string RAIL_FITS_CLASS = "tss-sidebar-fits-identity"

The class that tells the stylesheet the rail carries RAIL_MIN_WIDTH_VARIABLE.

public SidebarSectionHeader(string identifier, UIcons icon, string title, string subtitle = null, UIconsWeight weight = UIconsWeight.Regular)

Initializes a new instance of the SidebarSectionHeader class.

Parameters

identifier

The identifier for the item.

icon

The section's glyph.

title

The section's name.

subtitle

What is in the section. None leaves the header a single line.

weight

The glyph's weight.

public bool IsSelected { get; set; }

Gets or sets whether the item is currently selected. A heading is not a destination, so this is only carried for the sidebar's sake.

public IComponent CurrentRendered

Gets the component that is currently rendered.

public string Identifier { get; private set; }

Gets the full identifier of the item, including group identifiers.

public string OwnIdentifier

Gets the own identifier of the item, without group identifiers.

public void AddGroupIdentifier(string groupIdentifier)

Adds a group identifier prefix to the item's identifier.

public void Show()

Shows the item.

public void Collapse()

Collapses the item.

public SidebarSectionHeader SetTitle(string title)

Sets the section's name.

Parameters

title

The name.

Returns

The current instance of the type.

public SidebarSectionHeader SetSubtitle(string subtitle)

Sets the second line. Null or empty leaves the header a single line.

Parameters

subtitle

What is in the section.

Returns

The current instance of the type.

public SidebarSectionHeader Separated(bool separated = true)

Draws a divider under the header, run out to the sidebar's own edges, between it and the rows it heads.

Parameters

separated

Whether to draw it.

Returns

The current instance of the type.

public SidebarSectionHeader NotSortable()

Marks the item as not draggable in a sortable sidebar.

Returns

The current instance of the type.

public IComponent RenderClosed()

Renders the item for the closed state of the sidebar.

public IComponent RenderOpen()

Renders the item for the open state of the sidebar.

public SidebarStatusCard(string identifier, UIcons icon, string title, string status = null, UIconsWeight weight = UIconsWeight.Regular)

Initializes a new instance of the SidebarStatusCard class.

Parameters

identifier

The identifier for the item.

icon

The section's glyph.

title

The section's name.

status

The status line. None leaves the card without one.

weight

The glyph's weight.

public bool IsSelected { get; set; }

Gets or sets whether the item is currently selected. A status card is not a destination, so this is only carried for the sidebar's sake.

public IComponent CurrentRendered

Gets the component that is currently rendered.

public string Identifier { get; private set; }

Gets the full identifier of the item, including group identifiers.

public string OwnIdentifier

Gets the own identifier of the item, without group identifiers.

public void AddGroupIdentifier(string groupIdentifier)

Adds a group identifier prefix to the item's identifier.

public void Show()

Shows the item.

public void Collapse()

Collapses the item.

public SidebarStatusCard SetTitle(string title)

Sets the section's name.

Parameters

title

The name.

Returns

The current instance of the type.

public SidebarStatusCard SetStatus(string status)

Sets the status line. Null or empty hides it.

Parameters

status

The status, e.g. "Index healthy · 2.4M nodes".

Returns

The current instance of the type.

public SidebarStatusCard Success()

Draws the status dot in the success colour.

Returns

The current instance of the type.

public SidebarStatusCard Warning()

Draws the status dot in the warning colour.

Returns

The current instance of the type.

public SidebarStatusCard Danger()

Draws the status dot in the danger colour.

Returns

The current instance of the type.

public SidebarStatusCard Neutral()

Draws the status dot in the neutral colour, which is the default.

Returns

The current instance of the type.

public SidebarStatusCard Progress(float percent, string caption = null)

Shows a progress bar for a running job, with an optional caption under it.

Parameters

percent

How far along the job is, from 0 to 100.

caption

The caption, e.g. "Re-index 72% · 4 min left". None leaves the bar on its own.

Returns

The current instance of the type.

public SidebarStatusCard Indeterminate(string caption = null)

Shows an indeterminate progress bar, for a job that cannot say how far along it is.

Parameters

caption

The caption. None leaves the bar on its own.

Returns

The current instance of the type.

public SidebarStatusCard ClearProgress()

Removes the progress bar and its caption.

Returns

The current instance of the type.

public SidebarStatusCard OnClick(Action onClick)

Runs an action when the card is clicked, typically to open the page with the full status.

Parameters

onClick

What clicking the card does.

Returns

The current instance of the type.

public SidebarStatusCard NotSortable()

Marks the item as not draggable in a sortable sidebar.

Returns

The current instance of the type.

public IComponent RenderClosed()

Renders the item for the closed state of the sidebar.

public IComponent RenderOpen()

Renders the item for the open state of the sidebar.

public SidebarPageBar(Sidebar sidebar)

Initializes a new instance of the SidebarPageBar class.

Parameters

sidebar

The sidebar its back button brings back.

public string Title { get ; set ; }

Gets or sets the title of the page on screen.

public SidebarPageBar Brand(IComponent brand)

Sets the brand shown between the back button and the title - typically the app's logo.

Parameters

brand

The brand, or null for none.

Returns

The current instance.

public SidebarPageBar SetTitle(string title)

Sets the title of the page on screen.

Parameters

title

The title.

Returns

The current instance.

public SidebarPageBar Commands(params IComponent[] commands)

Replaces the commands on the right of the bar.

Parameters

commands

The commands.

Returns

The current instance.

public HTMLElement Render()

Renders the bar.

Returns

The rendered HTMLElement.

public SidebarComponent(string identifier, IComponent component, IComponent closedComponent = null)

Initializes a new instance of the SidebarComponent class.

Parameters

identifier

The identifier for the item.

component

What the item shows while the sidebar is open.

closedComponent

What it shows while the sidebar is collapsed to its rail. Null - the default - shows nothing at all there.

public bool IsSelected { get; set; }

Gets or sets whether the item is currently selected. A hosted component owns its own selection, so this is only carried for the sidebar's sake.

public IComponent CurrentRendered

Gets the component that is currently rendered.

public string Identifier { get; private set; }

Gets the full identifier of the item, including group identifiers.

public string OwnIdentifier

Gets the own identifier of the item, without group identifiers.

public void AddGroupIdentifier(string groupIdentifier)

Adds a group identifier prefix to the item's identifier.

public void Show()

Shows the item.

public void Collapse()

Collapses the item.

public SidebarComponent NotSortable()

Marks the item as not draggable in a sortable sidebar - which is what a hosted component usually wants, since it is a region rather than an entry in a list.

public SidebarComponent Grow()

Lets the item take the leftover height of the sidebar's middle section, for a component that scrolls its own content (a list of chats, a tree).

public IComponent RenderClosed()

Renders the item for the closed state of the sidebar.

public IComponent RenderOpen()

Renders the item for the open state of the sidebar.

bool IsSelected { get; set; }

Gets or sets whether the item is currently selected.

IComponent CurrentRendered { get; }

Gets the component that is currently rendered.

string Identifier { get; }

Gets the full identifier of the item, including group identifiers.

string OwnIdentifier { get; }

Gets the own identifier of the item, without group identifiers.

IComponent RenderClosed()

Renders the item for the closed (collapsed) state of the sidebar.

IComponent RenderOpen()

Renders the item for the open (expanded) state of the sidebar.

void Show()

Shows the item.

void Collapse()

Collapses the item.

void AddGroupIdentifier(string groupIdentifier)

Adds a group identifier prefix to the item's identifier.