Panel

IsOpen is what shows and hides the panel, and binding to it is all a panel needs: the panel writes the value back when it dismisses itself, so the flag stays right whichever side closed it. The panel slides in from the end of the screen by default, sizes itself to its own content and scrolls whatever will not fit, covers the page without dimming it, and is dismissed by a click on the page behind it, the Escape key or a swipe towards the edge it came from.

The panel is also driveable through a reference to it: Open, Close and Toggle do what binding the flag would, from code that has no flag of its own.

ShowCloseButton puts a close button at the edge the panel slid in from, which is what a panel whose ways out have been taken away - a Blocking or a Modeless one - needs to be closable with the pointer at all. It names itself "Close" to a screen reader unless CloseButtonTitle says otherwise, and CloseIconName replaces the glyph in it.

A panel given a Header, a Footer or a ShowCloseButton builds the chrome that goes with them: a header row at the edge it slid in from, a body that takes the scrolling, and a footer at the far edge. The two parts around the body stay put however far the content between them is scrolled, which is what a panel whose actions have to stay reachable needs. A panel given none of the three is the plain surface of the section above, and its content fills it however it likes.

HeaderText and FooterText are the shorthands for the header and the footer that are nothing but a line of text, and the templates take precedence over them. Body is the content that reads right beside them - it is the same slot as ChildContent, named for what it becomes here, and it takes precedence when both are given.

The header also names the panel: a screen reader reads it out when the panel opens, without TitleAriaId having to point anywhere.

Position is the edge the panel slides in from. Start and End are the logical edges, so they follow the direction of the panel and swap over in right-to-left, while Top and Bottom are the same edges everywhere.

Size is the size of the panel in pixels along the axis it slides on - the width of a panel at the start or the end, the height of one at the top or the bottom. Leaving it unset sizes the panel to its own content, and either way a strip of the page stays visible beside it. FullSize gives up that strip and takes the whole screen, which is what a panel holding a page of its own needs on a small screen.

A panel covers the page with an overlay that takes the clicks meant for what is behind it, and a click on that overlay dismisses the panel. Blocking keeps the overlay and takes away the dismissal, for a panel whose content has to be completed or cancelled through the panel itself, and OnOverlayClick still reports the click - which is how a blocking panel can draw attention to itself instead of closing.

That overlay is a transparent catcher of clicks by default, so the page behind it is still read at full strength. ModeFull gives it a background of its own, which is what a panel that takes the work over rather than sitting beside it wants: the page underneath recedes and the panel reads as the thing to deal with.

Modeless leaves the page its own clicks by rendering no overlay at all, so the panel sits alongside the work rather than instead of it. NoDismissOnEscape takes the Escape key away from a panel that is only meant to be closed by its own content, and OnEscapeKeyDown still reports the key the way OnOverlayClick reports the click, so a panel that turns the Escape down can answer it on terms of its own. OnDismiss is called for every one of those closings - the overlay, the Escape key, a swipe, the Close and Toggle methods and the flag being set from the outside - so it is the one place a panel has to clean up in.

OnDismissing is called before the panel closes and is allowed to refuse the closing: set Cancel on the arguments it is handed and the panel stays where it is. It is awaited, so the answer can come from work of its own - a confirmation, a save, a look at what the user has typed so far.

Its Reason tells the closings apart: a click on the Overlay, the Escape key, a Swipe, or a Programmatic call to Close or Toggle. That is what lets a panel refuse the stray gesture that would throw away a half-filled form while still letting through the Close its own content asked for. The IsOpen flag being set from the outside has already happened by the time the panel sees it, so it never passes through here.

A panel that opens takes the keyboard with it: the focus moves to the first focusable element in it - or to the element marked data-autofocus, for the panels whose first one is not the one worth starting at - Tab and Shift+Tab cycle inside it instead of running on into the page behind it, and closing the panel hands the focus back to whatever opened it. NoAutoFocus leaves the focus where it is, NoFocusTrap lets the keyboard walk out of the panel, and NoRestoreFocus leaves the focus wherever the panel left it instead of handing it back - for the panels whose closing is meant to move the keyboard on somewhere else. A Modeless panel never traps the focus, since the page behind it is meant to be reached. Escape reaches the panel from wherever the keyboard is inside it, so a panel that never took the keyboard over is also one Escape does not reach until the user has tabbed or clicked into it.

The panel reports itself to a screen reader as a dialog, which needs a name: give it one with AriaLabel, or point TitleAriaId at the heading the panel already shows. SubtitleAriaId points at what describes it, and IsAlert reports it as an alert dialog instead, for a panel carrying something the user has to deal with before carrying on.

Role takes over from that dialog altogether, for the panel that is not one: a Modeless panel left beside the page is better announced as a complementary or a region, since a screen reader tells the user a dialog is something to deal with and leave.

A panel that covers the page holds it still while it is open: a page that carried on scrolling behind the panel would move what the user is coming back to out from under them. The scrollbar comes back when the panel closes - including when the panel is taken off the page while it is still open, so a navigation away from it never leaves the page stuck - and the room the scrollbar took is added back as padding while it is held, so nothing shifts sideways. The holds are counted: two panels open at once both hold the page, and it is handed back when the last of them closes, not the first.

ScrollerSelector names the element that is held, for the layouts that scroll something other than the document, and ScrollerElement hands one over directly where no selector reaches it. A panel inside a BitAppShell holds the shell's scroller without being told to, since the shell cascades it: the body of such a page never scrolls, so holding it would hold nothing.

NoScrollLock gives that up, for the panel that is meant to leave the page moving. A Modeless panel never holds the page in the first place. A panel that leaves the page scrolling still covers it with an overlay, and that layer is fixed to the viewport - so the wheel and the touch drag it catches are handed on to the scroller the panel names, and the page moves under the gesture the way it would with no panel over it. Anything inside the panel that scrolls itself takes its own gestures first.

AutoToggleScroll is the other way round: the panel takes the overflow off the scroller itself instead of taking the counted hold, and the room that gave back is what an AbsolutePosition panel is pushed down by so that it stays where the eye left it. The two never both apply - a panel doing its own scroll handling stands the hold down.

The panel scrolls its own content whenever there is more of it than the panel is allowed to take, and that scrolling stops at the panel: reaching the end of it does not carry on into the page underneath. Holding the page still is about the wheel that never reaches the panel at all.

Dragging the panel towards the edge it slid in from follows the pointer, and letting go past a quarter of the size of the panel dismisses it. SwipeTrigger moves that point - it is a fraction of the size of the panel, so a smaller value dismisses on a shorter drag - and NoSwipe turns the gesture off entirely, which is what a panel hosting something that is itself dragged needs.

OnSwipeStart, OnSwipeMove and OnSwipeEnd report the gesture as it happens, each with the distance along the axis the panel slides on.

A panel opened from inside another one sits at the same layer as the panel it came from, so its overlay lands underneath that panel: a click there reaches the outer panel rather than dismissing the inner one. ZIndex lifts the pair over it - the overlay takes the value given and the panel itself sits one above it - and the inner panel behaves like any other from there on.

The Escape key stops at the panel that acts on it, so the first press closes the inner panel and the outer one is only reached once the inner one is gone. The same holds for the swipe and for a click on the overlay.

AbsolutePosition lays the panel out against the nearest positioned ancestor instead of against the screen, so the panel and its overlay stay inside a container of the page rather than covering all of it. The container needs a position of its own for the panel to be placed against, and it clips the panel where it hides its overflow.

It leaves the page alone as well: the hold such a panel would otherwise take on the page is stood down, since taking the scrollbar off the whole page for a panel that covers one box of it moves the page around the very container being looked at. A scroller named by ScrollerSelector or ScrollerElement is still held, so a contained panel that is meant to hold the container it sits in names it there.

A panel builds its content when it opens and takes it back out once it has finished sliding away - it waits for the movement to end, so the closing is still seen with something in it. Nothing of it is rendered until the first opening, so a panel that is never opened costs nothing, and every opening starts over: a form inside one does not still hold the last thing typed into it. Type into the field below, close the panel, and open it again.

KeepMounted keeps it instead: the content goes into the page on the first opening and stays from then on, hidden while the panel is closed - which keeps it out of the tab order and out of the reach of a screen reader - so whatever state it holds survives the closing.

OnOpen is called once the panel is open and the page shows it, and OnToggle is called for both directions with the new state - which is the one callback a panel that only needs to know it changed can use. Both are called on the frame the panel changed state on; OnTransitionEnd waits until the panel has actually finished sliding, which is what measuring it or scrolling something into view inside it has to wait for.

CloseIcon takes the glyph of the close button from an external icon library - FontAwesome, Material Icons, Bootstrap Icons - through the CSS classes that library asks for, and takes precedence over the CloseIconName that names a built-in Fluent icon.

Style and Class reach the root element of the panel, and Styles and Classes reach every part it is made of - the Root, the Overlay that covers the page, the Container that is the panel itself, and, on a panel that builds the chrome, the HeaderContainer, the Header, the CloseButton, the CloseIcon, the Body and the Footer. The Container is also how a panel is given a size that is not a pixel value - a percentage, a rem - which Size does not take.

The Root member is also where the panel's own custom properties are set: --bit-pnl-max is how much of the screen a panel that is not FullSize may take along the axis it slides on, and it defaults to 85%.

Dir turns the panel right-to-left, which swaps the two logical edges over: a Start panel now slides in from the right of the screen and an End one from the left, and the swipe that dismisses them follows.