Tesserae - Modal Stack

ModalStack

Description

ModalStack is a static stack that shows several Modals as a deck of sheets: the newest in front, and the ones it was opened from lifted and scaled behind it, each showing a strip with its title. Clicking a peeking sheet goes back to it, Escape closes the sheet in front, clicking the backdrop closes the whole chain, and a breadcrumb of the chain is drawn above the deck while more than one sheet is open.

Use it when a modal opens another modal, such as a preview that links to another preview, instead of stacking independent overlays on top of each other. A stacked modal is opened with ModalStack.Push(...), not with Show(); its Hide() pops it.

Usage

Push each modal under a key and a display name. Pushing a key that is already in the stack goes back to that sheet instead of opening a second copy. Past ModalStack.MaxDepth (4) sheets the oldest is dropped.

modal-stack-sample.cs

using System;
using System.Collections.Generic;
using System.Linq;
using Transpose.Core;
using Tesserae;
using static Transpose.Core.dom;
using static Tesserae.UI;

namespace Tesserae.Tests
{
    internal static class App
    {
        private static void Main()
        {
            var component = Button("Open document 1").Primary().OnClick(() => Open(1));

            document.body.style.overflow = "hidden";
            MountCenteredToBody(component);
        }

        private static void Open(int n)
        {
            var modal = Modal($"Document {n}")
               .ShowCloseButton()
               .Content(VStack().Children(
                    TextBlock($"This is sheet {n} of the stack. It links to the next document.").Wrap(),
                    Button($"Open document {n + 1}").Primary().MT(16).OnClick(() => Open(n + 1)),
                    Button("Back to document 1").MT(8).OnClick(() => ModalStack.TryRewindTo("doc-1"))));

            ModalStack.Push($"doc-{n}", $"Document {n}", modal);
        }
    }
}

ModalStack.Replace(key, name, modal) swaps the sheet in front and keeps the chain behind it, which suits stepping through a list of results. Pop(), PopTo(key), Clear() and Remove(modal) close sheets from code, and the Changed event is raised on every change so a host can keep the URL in step with what is open.

API reference

class

ModalStackEntry

public sealed class ModalStackEntry

One sheet in the ModalStack: the modal, the key it was pushed under, and the name the chain shows for it.

Namespace: Tesserae

Properties

Name	Description
Key	Gets what this sheet was pushed under - what makes it the same sheet on a later push.
Name	Gets the name the chain shows for this sheet - its title, in one short line.
Modal	Gets the modal this sheet shows.

Property

ModalStackEntry.Key

public string Key { get; }

Gets what this sheet was pushed under - what makes it the same sheet on a later push.

Property

ModalStackEntry.Name

public string Name { get; internal set; }

Gets the name the chain shows for this sheet - its title, in one short line.

class

ModalStack

public static class ModalStack

A stack of modals shown as a deck of sheets: the newest one in front, the ones it was opened from peeking out behind it, each a little smaller and quieter than the one in front of it. A sheet is pushed under a key (Push); pushing a key that is already in the stack rewinds to it rather than opening a second copy of the same thing. Clicking a peeking sheet goes back to it, Escape closes the sheet in front, and clicking the backdrop dismisses the whole chain. Past MaxDepth sheets the oldest one is dropped, so a chain of this-led-to-that never grows without end. A sheet keeps whatever size it was given while it is in front. Once something is opened on top of it, it takes the front sheet's footprint instead - so a deck of sheets that opened at very different sizes still reads as one pile, with each sheet behind peeking out by the same strip - and gets its own size back when it is in front again. The deck also keeps the room those strips and the trail need at the top, and the sheet in front is fitted below it. The stack takes the modal's own surface and shows it itself, so Show is not what opens a stacked modal - Push is. Everything else about the modal still works: Hide pops it, and its show and hide handlers run as they would have.

Namespace: Tesserae

Properties

Name	Description
Depth	Gets how many sheets are open.
IsEmpty	Gets a value indicating whether nothing is open.
Top	Gets the sheet in front, or null when nothing is open.
IsTruncated	Gets a value indicating whether the chain has had its oldest sheets dropped to stay within `MaxDepth` - which is worth saying in a breadcrumb, and nowhere else.
Entries	Gets the open sheets, oldest first.

Property

ModalStack.Depth

public static int Depth

Gets how many sheets are open.

Property

ModalStack.IsEmpty

public static bool IsEmpty

Gets a value indicating whether nothing is open.

Property

ModalStack.Top

public static ModalStackEntry Top

Gets the sheet in front, or null when nothing is open.

Property

ModalStack.IsTruncated

public static bool IsTruncated

Gets a value indicating whether the chain has had its oldest sheets dropped to stay within MaxDepth - which is worth saying in a breadcrumb, and nowhere else.

Property

ModalStack.Entries

public static IReadOnlyList<ModalStackEntry> Entries

Gets the open sheets, oldest first.

Methods

Name	Description
Contains	Returns a value indicating whether a sheet is open under the given key.
Get	Returns the sheet open under the given key, or null when there is none.
IsStacked	Returns a value indicating whether the given modal is one of the open sheets - which is what tells a modal that answers Escape itself to leave the key to the stack instead.
Push	Opens the given modal as the sheet in front, under the given key and showing the given name in the chain. Pushing a key that is already open rewinds to it instead - a chain that leads back to something already in it goes back to that sheet rather than opening a second copy of it.
Replace	Swaps the sheet in front for another one, keeping the chain behind it as it was - what stepping through a list of results while one of them is open does. Pushes the modal when nothing is open.
Rename	Renames the sheet open under the given key, for a sheet whose title is only known once its content has loaded.
TryRewindTo	Goes back to the sheet open under the given key, closing everything opened from it. Returns false - and changes nothing - when no sheet is open under that key.
Pop	Closes the sheet in front, going back to the one it was opened from.
PopTo	Closes everything opened from the sheet under the given key, leaving that sheet in front.
Remove	Closes the sheet showing the given modal, wherever it is in the chain, leaving the rest of the chain as it was.
Clear	Closes the whole chain.

Method

ModalStack.Contains

public static bool Contains(string key)

Returns a value indicating whether a sheet is open under the given key.

Method

ModalStack.Get

public static ModalStackEntry Get(string key)

Returns the sheet open under the given key, or null when there is none.

Method

ModalStack.IsStacked

public static bool IsStacked(Modal modal)

Returns a value indicating whether the given modal is one of the open sheets - which is what tells a modal that answers Escape itself to leave the key to the stack instead.

Method

ModalStack.Push

public static void Push(string key, string name, Modal modal)

Opens the given modal as the sheet in front, under the given key and showing the given name in the chain. Pushing a key that is already open rewinds to it instead - a chain that leads back to something already in it goes back to that sheet rather than opening a second copy of it.

Method

ModalStack.Replace

public static void Replace(string key, string name, Modal modal)

Swaps the sheet in front for another one, keeping the chain behind it as it was - what stepping through a list of results while one of them is open does. Pushes the modal when nothing is open.

Method

ModalStack.Rename

public static void Rename(string key, string name)

Renames the sheet open under the given key, for a sheet whose title is only known once its content has loaded.

Method

ModalStack.TryRewindTo

public static bool TryRewindTo(string key)

Goes back to the sheet open under the given key, closing everything opened from it. Returns false - and changes nothing - when no sheet is open under that key.

Method

ModalStack.Pop

public static void Pop()

Closes the sheet in front, going back to the one it was opened from.

Method

ModalStack.PopTo

public static void PopTo(string key)

Closes everything opened from the sheet under the given key, leaving that sheet in front.

Method

ModalStack.Remove

public static void Remove(Modal modal)

Closes the sheet showing the given modal, wherever it is in the chain, leaving the rest of the chain as it was.

Method

ModalStack.Clear

public static void Clear()

Closes the whole chain.

Events

Name	Description
Changed	Raised whenever the chain changes - a sheet pushed, popped, replaced or dropped - so a host can keep the route (or anything else naming what is open) in step with it.

Event

ModalStack.Changed

public static event Action Changed

Raised whenever the chain changes - a sheet pushed, popped, replaced or dropped - so a host can keep the route (or anything else naming what is open) in step with it.

Fields

Name	Description
MaxDepth	How many sheets the stack keeps before it starts dropping the oldest one.

Field

ModalStack.MaxDepth

public const int MaxDepth = 4

How many sheets the stack keeps before it starts dropping the oldest one.

ModalStack

Description

Usage

API reference

Properties

ModalStackEntry.Key

ModalStackEntry.Name

ModalStackEntry.Modal

Properties

ModalStack.Depth

ModalStack.IsEmpty

ModalStack.Top

ModalStack.IsTruncated

ModalStack.Entries

Methods

ModalStack.Contains

ModalStack.Get

ModalStack.IsStacked

ModalStack.Push

ModalStack.Replace

ModalStack.Rename

ModalStack.TryRewindTo

ModalStack.Pop

ModalStack.PopTo

ModalStack.Remove

ModalStack.Clear

Events

ModalStack.Changed

Fields

ModalStack.MaxDepth

See also