Surfaces
PanelService
Bit.BlazorUISheetServiceDrawerService
BitPanelService shows a BitPanel with any content - a component, a Type or markup - from anywhere in the app: a service, a view model, a handler. It is the BitModalService of panels: each Show hands back a BitPanelReference that closes the panel, completes with its answer and says whether the user dismissed it, and a BitPanelParameters customizes the panel around the content with the options of BitPanel - its placement, its size, its snap points - plus a close guard and a navigation policy.
Notes
Mount one BitPanelContainer in the layout, in the same interactive render mode as the components that
show panels - a panel shown with no container is not rendered, and the service logs it. Register the service
Scoped on Blazor Server; a singleton is only safe on WebAssembly and Hybrid. Every panel it shows is a
real BitPanel: it slides, swipes, traps the focus and gives it back
as a declared one does, and leaves the page only once it has slid out.
Usage
Every example is live. Open its code to see exactly what produced the component running underneath.
Basic
Show<T> renders the component as the content of a panel; the content closes its own panel through
the cascaded BitPanelReference. BitPanelParameters adds the header, which also names the dialog
for screen readers, and the close button.
Placement
Placement is the edge the panel slides in from, and Size its size in pixels along that axis.
Bottom sheet
A panel at the bottom with SnapPoints is a bottom sheet, dragged between them or moved with its grabber;
SnapPoint is the one it opens at, and the sheet keeps the one the user moves it to from there on.
Awaiting a result
Result completes with what the panel was closed with (CloseWith), or null when the user walked
away from it - which IsDismissed tells apart from an answer of null.
Picked:
Markup as content
Show also takes a RenderFragment, for content not worth a component of its own - or one taking
the panel's reference, so the markup can close it.
Guarding the close
CanClose is asked at every dismissal by the user - the overlay, Escape, the close button, a swipe - and every
TryClose: answering false keeps the panel open. Closing it from code with Close is never put to it.
Updating an open panel
Update changes the parameters of a panel while it is open, here its header every second.
API
Every parameter, public member, sub-class and enum this component exposes.
BitPanelService parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| OnAddModal | event Func<BitPanelReference, Task>? | Raised for every panel shown through this service, whoever showed it. | |
| OnCloseModal | event Func<BitPanelReference, Task>? | Raised once for every panel of this service that closes, however it closed. | |
| IsContainerAvailable | bool | Whether a BitPanelContainer is currently mounted for this service, i.e. whether a Show call right now would render its panel. | |
| OpenModals | IReadOnlyList<BitPanelReference> | A snapshot of the panels this service currently has open, in the order they were opened. | |
| GetModal | BitPanelReference? (string? id) | The open panel with the given id, or null when there is none. | |
| Close | Task (BitPanelReference panel, object? result = null) | Closes an open panel with the result its Result task completes with. This is the application closing the panel, so the CanClose guard is not asked. | |
| TryClose | Task<bool> (BitPanelReference panel, object? result) | Asks a panel to close and reports whether it did: a panel whose CanClose guard turns the close down stays open and this answers false. | |
| CloseAll | Task | Closes every panel this service currently has open, each with a null result, the last one opened first. The CanClose guards are not asked. | |
| Refresh | Task (BitPanelReference? panel) | Re-renders the open panels, after their parameters were changed in place. Without an argument it refreshes every open panel. | |
| Show<T> | Task<BitPanelReference> (Dictionary<string, object>? parameters, BitPanelParameters? panelParameters, bool persistent) | Shows a panel with the component T as its content, given the parameters. A persistent panel outlives the page it was opened from and a remount of its container. Overloads take the parameters as a BitModalContentParameters<T>, a factory handed the panel's reference, or no parameters at all. | |
| Show | Task<BitPanelReference> (Type componentType, ...) | The same, with the type of the content known at run time. | |
| Show | Task<BitPanelReference> (RenderFragment content, BitPanelParameters? panelParameters, bool persistent) | Shows a panel with markup as its content. An overload takes a RenderFragment<BitPanelReference>, handed the panel's own reference. |
BitComponentBase parameters
| Name | Type | Default value | Description |
|---|---|---|---|
| AriaLabel | string? | null | Gets or sets the accessible label for the component, used by assistive technologies. |
| Class | string? | null | Gets or sets the CSS class name(s) to apply to the rendered element. |
| Dir | BitDir? | null | Gets or sets the text directionality for the component's content. |
| Disabled | bool | false | Gets or sets a value indicating whether the component is disabled and cannot respond to user interaction. |
| ForceAnimation | bool | false | Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested. |
| HtmlAttributes | Dictionary<string, object> | new Dictionary<string, object>() | Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters. An attribute written on the component wins over an entry of the same name. |
| Id | string? | null | Gets or sets the unique identifier for the component's root element. |
| Style | string? | null | Gets or sets the CSS style string to apply to the rendered element. |
| TabIndex | string? | null | Gets or sets the tab order index for the component when navigating with the keyboard. |
| Visibility | BitVisibility | BitVisibility.Visible | Gets or sets the visibility state (visible, hidden, or collapsed) of the component. |
BitComponentBase public members
| Name | Type | Default value | Description |
|---|---|---|---|
| UniqueId | Guid | Guid.NewGuid() | Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed. |
| RootElement | ElementReference | Gets the reference to the root HTML element associated with this component. |
BitPanelReference properties
| Name | Type | Default value | Description |
|---|---|---|---|
| Id | string | The unique id of the panel. | |
| Persistent | bool | Whether the panel outlives the page it was opened from. | |
| IsClosed | bool | Whether the panel has been closed. | |
| IsDismissed | bool | Whether the panel was closed by the user rather than by the application: the overlay, the Escape key, the close button or a swipe. | |
| Content | object? | The instance of the component rendered as the content, once it is rendered. | |
| Parameters | BitPanelParameters? | The parameters the panel was shown with. | |
| Result | Task<object?> | Completes with what the panel was closed with, or null. | |
| Rendered | Task<bool> | Completes with true once a container has rendered the panel, or false when it is closed before that ever happens. | |
| Close / CloseWith | Task (object? result) | Closes the panel, with no result or with the given one. The CanClose guard is not asked. | |
| TryClose | Task<bool> (object? result = null) | Asks the panel to close, putting it to its CanClose guard first, and reports whether it did. | |
| Dismiss | Task<bool> | Closes the panel as the user would, for the content's own cancel action: put to the guard, and reported as dismissed. | |
| Update | Task (BitPanelParameters? parameters) / Task (Action<BitPanelParameters> change) | Replaces the parameters of the open panel, or changes the ones it names, and re-renders it. | |
| GetResult<T> / GetContentAsync<T> | Task<T?> | The result as a T, and the content once it is rendered as a T. |
BitPanelContainer properties
| Name | Type | Default value | Description |
|---|---|---|---|
| Service | BitPanelService? | null | The service whose panels this container renders, in place of the registered one. |
| ModalParameters | BitPanelParameters | new() | The defaults of every panel the container renders: a panel's own parameters win over them, one by one. |
BitPanelParameters properties
The options a panel is shown with. Every parameter of BitPanel a panel shown from code can be given - including Class, Style, Dir, AriaLabel and Disabled, and its placement, size and snap points - has a nullable counterpart here (null means "not set": the container's value, then the panel's own default is used), plus the options only a service can offer:
| Name | Type | Default value | Description |
|---|---|---|---|
| SnapPoint | int? | null | The snap point a bottom sheet opens at. The sheet keeps the one the user moves it to from there on. |
| CanClose | Func<Task<bool>>? | null | The guard every dismissal by the user and every TryClose is put to: answering false keeps the panel open. Close is never put to it. |
| CloseOnNavigation | bool? | null | Whether the panel closes when the app navigates somewhere else, which it does by default (a persistent panel only closes when this is set to true). Only a change of path counts; a query string or a fragment changed on the same page does not. |
BitVisibility enum
| Name | Value | Description |
|---|---|---|
| Visible | 0 | The content of the component is visible. |
| Hidden | 1 | The content of the component is hidden, but the space it takes on the page remains (visibility:hidden). |
| Collapsed | 2 | The component is hidden (display:none). |
BitDir enum
| Name | Value | Description |
|---|---|---|
| Ltr | 0 | Ltr (left to right) is to be used for languages that are written from the left to the right (like English). |
| Rtl | 1 | Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic). |
| Auto | 2 | Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element. |
Feedback
Found a mistake, a gap, or something that could be clearer? Every page and every component is one click from its source.