diff --git a/.github/docs/Collapse.md b/.github/docs/Collapse.md index 29f86945..50c95713 100644 --- a/.github/docs/Collapse.md +++ b/.github/docs/Collapse.md @@ -42,10 +42,13 @@ Sets the `style` of the `background-color` when tab is not the Active tab. Use H - **`HoverColor`: `string { get; set; }` (default: "WhiteSmoke") - Required**
Sets the `style` of the `background-color` when button is hovered over with mouse. Use HTML specified: **Color Names**, **RGB**, **HEX** or with **HSL** values. - **`ContentHeight`: `int { get; set; }` (default: 200) - Required**
-Sets the height of Content panel in `px`. 0 is auto. +Sets the height (in reality sets max-height because of CSS transition issues) of Content panel in `px`. 0 is auto. +- **`MaxAllowedContentHeight`: `int { get; set; }` (default: 200) - Required**
+Sets the max-height if Content panel `ContentHeight` is set to 0 (auto). - **`Animate`: `bool { get; set; }` (default: true)**
Determines to apply CSS animation and transition on Collapse state changes or not. -**Note: in case of `auto` height some animation won't work.** +**Note: in case of Content panel `ContentHeight` is set to 0 (auto), then use `MaxAllowedContentHeight` to set max-height CSS property which will be animated. +Also important based on max-height value transition speed for expand/collapse might differ!.** - **`Disabled`: `bool { get; set; }` (default: false)**
Determines whether the rendered HTML `` element should be disabled or not. - **`InnerElementReference`: `ElementReference { get; }`**
diff --git a/.github/docs/JsInterop.md b/.github/docs/JsInterop.md index f677a47d..80fc42b9 100644 --- a/.github/docs/JsInterop.md +++ b/.github/docs/JsInterop.md @@ -15,7 +15,6 @@ For code examples [see usage](https://github.com/majorimi/blazor-components/blob You can try it out by using the [demo app](https://blazorextensions.z6.web.core.windows.net/jsinterop). # Features - - **Click JS**: - `ClickBoundariesElement` is a component which wraps the given content to a DIV and subscribes to all click events: `OnOutsideClick`, `OnInsideClick`. - Also an **injectable `IClickBoundariesHandler` service** for callback event handlers. @@ -31,8 +30,9 @@ You can try it out by using the [demo app](https://blazorextensions.z6.web.core. - **Language JS**: is an **injectable `ILanguageService` service** for detect the browser language preference. - **Browser Date JS**: is an **injectable `IBrowserDateService` service** is a simple JS call to `new Date();` to retrieve client machine date and time. - **Browser Theme JS**: is an **injectable `IBrowserThemeService` service** to handle Browser color scheme queries and changes. -- **Geo JS**: is an **injectable `IGeolocationService` service** for detect the device Geolocation (GPS position, speed, heading, etc.). +- **Geo JS**: is an **injectable `IGeolocationService` service** for detect the device [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API) (GPS position, speed, heading, etc.). - **Head JS**: is an **injectable `IHtmlHeadService` service** for accessing and setting HTML document `Head tags`. +- **Browser History JS**: is an **injectable `INavigationHistoryService` service** to access [HTML History API](https://developer.mozilla.org/en-US/docs/Web/API/History) functionality. ## Click JS (See: [demo app](https://blazorextensions.z6.web.core.windows.net/jsinterop#click-js)) **NOTE: Blazor supports `@onclick` event which is equivalent with `OnInsideClick`. @@ -169,14 +169,13 @@ Exposes a Blazor `ElementReference` of the wrapped around HTML element. It can b - **`DisposeAsync()`: `ValueTask IAsyncDisposable()` interface**
Component implements `IAsyncDisposable` interface Blazor framework components also can `@implements IAsyncDisposable` where the injected service should be Disposed. - ### `IScrollHandler` Functions -- **`ScrollToElementAsync`**: **`Task ScrollToElementAsync(ElementReference elementReference)`**
-Scrolls the given element into the page view area. -- **`ScrollToElementByIdAsync`**: **`Task ScrollToElementByIdAsync(string id)`**
-Finds element by Id and scrolls the given element into the page view area. -- **`ScrollToElementByNameAsync`**: **`Task ScrollToElementByNameAsync(string name)`**
-Finds element by name and scrolls the given element into the page view area. +- **`ScrollToElementAsync`**: **`Task ScrollToElementAsync(ElementReference elementReference, bool smooth)`**
+Scrolls the given element into the page view area. **Note: smooth scroll on element level might not supported by all browsers.** +- **`ScrollToElementByIdAsync`**: **`Task ScrollToElementByIdAsync(string id, bool smooth)`**
+Finds element by Id and scrolls the given element into the page view area. **Note: smooth scroll on element level might not supported by all browsers.** +- **`ScrollToElementByNameAsync`**: **`Task ScrollToElementByNameAsync(string name, bool smooth)`**
+Finds element by name and scrolls the given element into the page view area. **Note: smooth scroll on element level might not supported by all browsers.** - **`ScrollToPageEndAsync`**: **`Task ScrollToPageEndAsync(bool smooth)`**
Scrolls to end of the page (X bottom). - **`ScrollToPageTopAsync`**: **`Task ScrollToPageTopAsync(bool smooth)`**
@@ -197,18 +196,34 @@ Removes event listener for 'scroll' HTML event for the whole document/window by Implements `IAsyncDisposable` interface the injected service should be Disposed. ### `ElementReference` extensions -- **`ScrollToElementAsync`**: **`Task ScrollToElementAsync(this ElementReference elementReference)`**
-- **`ScrollToEndAsync`**: **`Task ScrollToEndAsync(this ElementReference elementReference)`**
-- **`ScrollToTopAsync`**: **`Task ScrollToTopAsync(this ElementReference elementReference)`**
-- **`ScrollToXAsync`**: **`Task ScrollToXAsync(this ElementReference elementReference, double xPos)`**
-- **`ScrollToYAsync`**: **`Task ScrollToYAsync(this ElementReference elementReference, double yPos)`**
-- **`GetScrollPositionAsync`**: **`Task GetScrollPositionAsync(this ElementReference elementReference)`**
+- **`ScrollToElementAsync`**: **`Task ScrollToElementAsync(this ElementReference elementReference, bool smooth = false)`**
+ Scrolls HTML page to given element. **Note: smooth scroll on element level might not supported by all browsers.** +- **`ScrollToEndAsync`**: **`Task ScrollToEndAsync(this ElementReference elementReference, bool smooth = false)`**
+Scrolls inside the given element to the bottom (end). **Note: smooth scroll on element level might not supported by all browsers.** +- **`ScrollToTopAsync`**: **`Task ScrollToTopAsync(this ElementReference elementReference, bool smooth = false)`**
+Scrolls inside the given element to the beginning (top). **Note: smooth scroll on element level might not supported by all browsers.** +- **`ScrollToXAsync`**: **`Task ScrollToXAsync(this ElementReference elementReference, double xPos, bool smooth = false)`**
+Scrolls inside the given element to the given X position. **Note: smooth scroll on element level might not supported by all browsers.** +- **`ScrollToYAsync`**: **`Task ScrollToYAsync(this ElementReference elementReference, double yPos, bool smooth = false)`**
+Scrolls inside the given element to the given Y position. **Note: smooth scroll on element level might not supported by all browsers.** +- **`ScrollToAsync`**: **`Task ScrollToYAsync(this ElementReference elementReference, double xPos, double yPos, bool smooth = false)`**
+Scrolls inside the given element to the given X and Y positions. **Note: smooth scroll on element level might not supported by all browsers.** +- **`GetScrollXPositionAsync`**: **`Task GetScrollXPositionAsync(this ElementReference elementReference)`**
+Returns given element scroll X (left) position. +- **`GetScrollYPositionAsync`**: **`Task GetScrollYPositionAsync(this ElementReference elementReference)`**
+Returns given element scroll Y (top) position. - **`IsElementHiddenAsync`**: **`Task IsElementHiddenAsync(this ElementReference elementReference)`**
+Returns given element is visible on HTML document or not. - **`IsElementHiddenBelowAsync`**: **`Task IsElementHiddenBelowAsync(this ElementReference elementReference)`**
+Returns given element is below of the view port. - **`IsElementHiddenAboveAsync`**: **`Task IsElementHiddenAboveAsync(this ElementReference elementReference)`**
+Returns given element is above of the view port. - **`ScrollToElementInParentAsync`**: **`Task ScrollToElementInParentAsync(this ElementReference parent, ElementReference innerElement)`**
+Scrolls inside the given parent element to the given inner element. - **`ScrollInParentByIdAsync`**: **`Task ScrollInParentByIdAsync(this ElementReference parent, string id)`**
+Scrolls inside the given parent element to the given inner element by Id. - **`ScrollInParentByClassAsync`**: **`Task ScrollInParentByClassAsync(this ElementReference parent, string className)`**
+Scrolls inside the given parent element to the given first found inner element by class name. ## Resize JS (See: [demo app](https://blazorextensions.z6.web.core.windows.net/jsinterop#resize-js)) **Resize JS** is an **injectable `IResizeHandler` service** for Window (global) and HTML Elements resize event callback handlers. @@ -275,7 +290,6 @@ Removes event listener for `prefers-color-scheme` HTML event for the Browser. - **`DisposeAsync`: `ValueTask IAsyncDisposable()` interface**
Implements `IAsyncDisposable` interface the injected service should be Disposed. - ## Geolocation JS (See: [demo app](https://blazorextensions.z6.web.core.windows.net/jsinterop#geo-js)) **Geolocation JS** is an injectable `IGeolocationService` service for **detect the device Geolocation (GPS position, speed, heading, etc.)**. It is using the Geolocation API which allows users to provide their location to web applications if they desire. @@ -313,6 +327,26 @@ If you have multiple fav icon tags set in the Head first call `GetHtmlFavIconsAs - **`DisposeAsync`: `ValueTask IAsyncDisposable()` interface**
Implements `IAsyncDisposable` interface the injected service should be Disposed. +## Browser History JS (See: [demo app](https://blazorextensions.z6.web.core.windows.net/jsinterop#history-js)) +**Browser History JS** is an injectable `INavigationHistoryService` service** to access HTML History API functionality. +It is useful when don't want to rely on Blazor `NavigationManager` which does not have access to full History list and when it navigates trigger a page load/update. + +### Functions +- **`GetLengthAsync`**: **`ValueTask GetLengthAsync()`**
+Returns an Integer representing the number of elements in the session history, including the currently loaded page. +- **`GetScrollRestorationAsync`**: **`ValueTask GetScrollRestorationAsync()`**
+Allows web applications to explicitly set default scroll restoration behavior on history navigation. This property can be either `auto` or `manual`. +- **`BackAsync`**: **`ValueTask BackAsync()`**
+This asynchronous method goes to the previous page in session history, the same action as when the user clicks the browser's Back button. Equivalent to history.go(-1). +- **`ForwardAsync`**: **`ValueTask ForwardAsync()`**
+This asynchronous method goes to the next page in session history, the same action as when the user clicks the browser's Forward button; this is equivalent to history.go(1). +- **`GoAsync`**: **`ValueTask GoAsync(int delta)`**
+Asynchronously loads a page from the session history, identified by its relative location to the current page, for example -1 for the previous page or 1 for the next page. +- **`ReplaceStateAsync`**: **`ValueTask ReplaceStateAsync(ExpandoObject? state, string title, string url)`**
+Updates the most recent entry on the history stack to have the specified data, title, and, if provided, URL. +- **`PushStateAsync`**: **`ValueTask PushStateAsync(ExpandoObject? state, string title, string url)`**
+Pushes the given data onto the session history stack with the specified title (and, if provided, URL). + # Configuration @@ -351,6 +385,8 @@ Add using statement to your Blazor .razor file. Or globally refe @using Majorsoft.Blazor.Components.Common.JsInterop.BrowserDate @*Only if you want to use Browser ColorTheme*@ @using Majorsoft.Blazor.Components.Common.JsInterop.BrowserColorTheme +@*Only if you want to use Browser History*@ +@using Majorsoft.Blazor.Components.Common.JsInterop.History ``` diff --git a/.github/docs/Maps.md b/.github/docs/Maps.md index c3c7d24c..e6f50038 100644 --- a/.github/docs/Maps.md +++ b/.github/docs/Maps.md @@ -19,16 +19,22 @@ It is available in the service provider (Google, Microsoft, etc.) developer site **NOTE: None of the Majorsoft Maps component tracking or exposing you _Token_ or _API Key_! Injecting and protecting this _Token_ or _API Key_ in your Blazor application is YOUR responsibility!** -# Components +# Components and Services + +#### Google: - **`GoogleStaticMap`**: component is wrapping **Google Static Maps services** into Blazor components. - **`GoogleMap`**: component is wrapping **Google JavaScript Maps services** into Blazor components. -- **`BindMap`**: _Planned in release v1.4.0_ +- **`IGoogleMapService`**: Injectable service to handle Google JavaScript Maps functionalities. Available on the instance of `GoogleMap` object ref as well. + +#### Bing: +- **`BindMap`**: _Planned in release v1.6.0_ Maps using `IGeolocationService` (see "Dependences") to center current position. It can be omitted and injected separately to your components as well to get or track device location. To see how it works please check **Geo JS** [documentation](https://github.com/majorimi/blazor-components/blob/master/.github/docs/JsInterop.md#geolocation-js-see-demo-app) and [demo](https://blazorextensions.z6.web.core.windows.net/jsinterop#geo-js). + ## `GoogleStaticMap` component (See: [demo app](https://blazorextensions.z6.web.core.windows.net/maps#google-static-maps)) :warning: **To use Google Maps Platform, you must have a billing account. The billing account is used to track costs associated with your projects.** @@ -93,7 +99,6 @@ Once operation has finished successfully `OnLocationDetected` event will be fire - **`DisposeAsync()`: `Task DisposeAsync()`**
Component implements `IAsyncDisposable` interface Blazor framework will call it when parent removed from render tree. - ## `GoogleMap` component (See: [demo app](https://blazorextensions.z6.web.core.windows.net/maps#google-js-maps)) :warning: **To use Google Maps Platform, you must have a billing account. The billing account is used to track costs associated with your projects.** @@ -111,6 +116,8 @@ You can learn about Google JavaScript Maps features and usage [here](https://dev Exposes a Blazor `ElementReference` of the wrapped around HTML element. It can be used e.g. for JS interop, etc. - **`MapId`: `string { get; }`**
Map HTML container Id. It can be used when multiple Maps added to one page. +- **`GoogleMapService`: `string { get; }`**
+Exposes `IGeolocationService` which is handling JsInterop. This instance can be used for access more GoogleMap features. - **`Width`: `int { get; set; }` (default: 400)**
Maps image Width in px. - **`Height`: `int { get; set; }` (default: 300)**
diff --git a/.github/docs/PermaLink.md b/.github/docs/PermaLink.md index 5e94be02..045bd811 100644 --- a/.github/docs/PermaLink.md +++ b/.github/docs/PermaLink.md @@ -32,9 +32,17 @@ For more details see Usage section. ### Functions - **`WatchPermaLinks()`**: **`void WatchPermaLinks()`**
Starts a navigation watcher which will check for Permalinks in the URLs. +- **`ChangePermalink()`**: **`void ChangePermalink(string? newPermalink, bool doNotNavigate)`**
+Modify the current URL with given new peralink value and trigger navigation or just update browser History. +- **`CheckPermalink()`**: **`string? CheckPermalink(bool triggerEvent = false)`**
+Checks the current URL for permalink again and re-triggers `PermalinkDetected` event if requested. - **`Dispose()`: `@implements IDisposable` interface**
Component implements `IDisposable` interface Blazor framework will call it when parent removed from render tree. +### Events +- **`PermalinkDetected`: `event EventHandler**
+Event handler for parmalinks detected on navigation. + ## `PermaLinkElement` component ### Properties @@ -68,9 +76,17 @@ Callback function called when Permalink icon clicked and **`PermaLinkIconActions ## PermaLinkBlazorServerInitializer Available from v1.4.0 It is convenient wrapper component to initialize navigation watcher in your Blazor Server App `MainLayout.razor` page. **Only one Initializer component allowed per Application.** +### Properties +- **`SmootScroll`: `bool { get; set; }` (default: false)**
+Scroll should be jump or smoothly scroll. **Note: smooth scroll on element level might not supported by all browsers.** + ## PermalinkBlazorWasmInitializer Available from v1.4.0 It is convenient wrapper component to initialize navigation watcher in your Blazor WebAssembly App `MainLayout.razor` page. **Only one Initializer component allowed per Application.** +### Properties +- **`SmootScroll`: `bool { get; set; }` (default: false)**
+Scroll should be jump or smoothly scroll. **Note: smooth scroll on element level might not supported by all browsers.** + # Configuration ## Installation @@ -141,7 +157,7 @@ Also instance should be disposed. ``` @*Permalink initialize*@ @using Majorsoft.Blazor.Components.PermaLink - + ``` #### Server hosted projects @@ -208,7 +224,7 @@ It has to be instantiated manually by using the following code. Also instance sh ``` @*Permalink initialize*@ @using Majorsoft.Blazor.Components.PermaLink - + ``` #### Creating permalink (#) navigation points inside a Blazor page diff --git a/.github/docs/Tabs.md b/.github/docs/Tabs.md index 74ae8d83..45b21969 100644 --- a/.github/docs/Tabs.md +++ b/.github/docs/Tabs.md @@ -37,6 +37,9 @@ Sets all `TabItem` elements height in `px`. Sets all `TabItem` elements element width in `px`. - **`Disabled`: `bool { get; set; }` (default: false)**
Determines whether all the rendered HTML elements should be disabled or not. +- **`AllowTabActivationByPermalink`: `bool { get; set; }` (default: true)**
+Enables or disables `TabItem` activation with URL Permalink fragment. +**NOTE: in order to make TabActivation work `Majorsoft.Blazor.Components.PermaLink` component is used and it MUST [set up correctly](https://github.com/majorimi/blazor-components/blob/master/.github/docs/PermaLink.md#configuration)!** - **`Animate`: `bool { get; set; }` (default: true)**
Determines to apply CSS animation and transion on Tab changes or not. - **`TabPositon`: `TabPositons { get; set; }` (default: TabPositons.Left)**
@@ -67,6 +70,9 @@ Required HTML content to show content of current TabItem. Determines whether the current rendered TabItem should be disabled or not. - **`Hidden`: `bool { get; set; }` (default: false)**
Determines whether the current rendered TabItem should be hidden or not. +- **`Permalink`: `string { get; set; }` (default: "")**
+Permalink value to append to the URL and activate the `TabItem` based on matching value. +**NOTE: in order to make TabActivation work `Majorsoft.Blazor.Components.PermaLink` component is used and it MUST [set up correctly](https://github.com/majorimi/blazor-components/blob/master/.github/docs/PermaLink.md#configuration)!** **Arbitrary HTML attributes e.g.: `tabindex="1"` will be passed to the corresponding rendered HTML element ``**. @@ -88,11 +94,42 @@ Add using statement to your Blazor `.razor` file. Or globally re @using Majorsoft.Blazor.Components.Tabs ``` +### Dependences +**Majorsoft.Blazor.Components.Tabs** package "partially" depends on other Majorsoft Nuget packages: +- [Majorsoft.Blazor.Components.Common.JsInterop](https://www.nuget.org/packages/Majorsoft.Blazor.Components.Common.JsInterop) +which handles JS Interop for many features e.g. scrolling, etc. +- [Majorsoft.Blazor.Components.Common.PermaLink](https://www.nuget.org/packages/Majorsoft.Blazor.Components.PermaLink) +which track navigations (URL changes) and identify permalink elements. + +**NOTE: only TabItem activation feature depend on Permalink. If you don't want to use that feature just leave `Permalink` parameters empty and do not setup PermalinkWatcher. +Also later this feature can be disabled by `AllowTabActivationByPermalink = false`.** + ### `TabsPanel` and `TabItem` usage Following code example shows how to use **`TabsPanel`** with **`TabItem`** component in your Blazor App. +**NOTE: to use TabActivation feature `Permalink="Tab1"` must be set and Permalink services must be [configured correctly](https://github.com/majorimi/blazor-components/blob/master/.github/docs/PermaLink.md#configuration)!** + ``` +@*Simple tab usage*@ + + + +
Tab1
+ Tab1 + + +
Tab2
+ Tab2 + + +
Tab3
+ Tab3 + + + + +@*Advanced tab usage*@ - + - + -