Merge branch 'release/4.1.0' into main

docs/getting_started/connections_chart.md

@@ -4,4 +4,4 @@ The included Web Parts can be connected together to create a complete search cen
 
 !["Connections diagram"](../assets/connections_flow.png){: .center}
 
-> The connection between a _Search Results_ and _Data Filters_ is a **two-ways** connection. All other connection are **one-way**.
+> The connection between a _Search Results_ and _Filters_ web part is a **two-ways** connection. All other connection are **one-way**.

docs/how-to-contribute.md

@@ -12,7 +12,7 @@ You can contribute to this project at multiple levels:
 - Add new reusable [components](./extensibility/custom_web_component.md) or [suggestions providers](./extensibility/custom_suggestions_provider.md) to the extensibility library.
 - Add Web Part translations
 
-As a result, we accept pull requests fom the community. You can refer to [this post](https://tahoeninjas.blog/2019/08/18/my-github-cheat-sheet-for-pnp-contributions-an-interactive-cheat-sheet/) by Hugo Bernier to know how make a PR on a GitHub repository.
+As a result, we accept pull requests from the community. You can refer to [this post](https://tahoeninjas.blog/2019/08/18/my-github-cheat-sheet-for-pnp-contributions-an-interactive-cheat-sheet/) by Hugo Bernier to know how make a PR on a GitHub repository.
 
 !!! note
     Your PR must target the `develop` branch.
@@ -48,9 +48,10 @@ You can also refer to the official [SPFx documentation about library component u
 ## Setup the **search-parts** and **search-extensibility-demo** projects
 
 1. From the `search-parts` or `search-extensibility-demo` project, link a reference to the `@pnp/modern-search-extensibility` project by using the following command `npm link @pnp/modern-search-extensibility`.
-2. Build the project using `gulp bundle`.
+2. Run `npm i`.
+3. Build the project using `gulp bundle`.
 
 ## Debug the solution
 
 - From Visual Studio Code console or any other console, from the `search-parts` folder, use the `npm run serve` command to start the server. We use [SPFx Fast Serve Tool](https://github.com/s-KaiNet/spfx-fast-serve) from Sergei Sergeev to speed up development process.
-- From Visual Studio Code, use the 'Hosted Workbench' debug configuration with your URL to debug the Web Parts. Any changes to the code will trigger a new build and refresh your page automatically within seconds.
+- From Visual Studio Code, use the 'Hosted Workbench' debug configuration with your URL to debug the Web Parts. Any changes to the code will trigger a new build and refresh your page automatically within seconds.

docs/index.md

@@ -2,14 +2,28 @@
 
 # PnP Modern Search v4
 
+![Current version](https://img.shields.io/github/v/release/microsoft-search/pnp-modern-search)
+
 The PnP 'Modern Search' solution is a set of SharePoint Online modern Web Parts allowing SharePoint super users, webmasters and developers to create highly flexible and personalized search based experiences in minutes.
 
+Before modern pages and web parts built on SPFx was introduced search driven scenarios was covered by the highly flexible classic search web parts, which
+supported any developer to add any HTML, CSS or JavaScript they wanted to tailor their specific scenario. In the modern world this was replaced by the
+Highlighted Content Web Part and a not very configurable search solution for Microsoft Search.
+
+To close the gap of customization and freedom the PnP Modern Search web parts got stated back in 2017, and have stabilized on v3. While allowing flexibility
+it introduces security measures to block JavaScript and CSS injection, key to many of the enterprise companies using the web parts today in productions.
+
+As the project progressed and the search API's are moving from SharePoint to Microsoft Graph there was a need to restructure and re-invent the web parts.
+Hence v4 was born. The goal of v4 is to solve scenarios already solved by v3, but at the same time allow greater flexibility in how you extend the solution using web components and custom developer solutions outside of HTML/handlebars.
+
+As more and more Microsoft Search functionality is exposed via the Microsoft Graph Search API's, we will keep on investing in v4 to surface these great capabilities.
+
 **Looking for the v3 documentation? [Here you go!](./v3/index.md)**
 
 !!! important "PnP Modern Search v3.x deprecation"
-    **The v4 version uses a brand new code architecture and replaces the older v3 codebase**. There will be no new features added to v3.x, but we will continue to
-    provide bug fixes as needed. Because v4.x is not at feature parity yet with v3.x, you can still use the v3.x packages to meet your requirements. Also, there is not an
-    auto-upgrade path from v3 to v4 due to the new architecture, so you are perfectly ok
+    **v4 uses a brand new code architecture and replace the older v3 codebase**. There will be no new features added to v3.x, but we will continue to
+    provide bug fixes and minor changes as needed. As v4.x is not yet at feature parity with v3.x, you can still use the v3.x packages to meet your requirements.
+    Also not that there is not an auto-upgrade path from v3 to v4 due to the new architecture, so you are perfectly ok
     to stay on the v3 version until v4 provides the features validating your upgrade.
     However, the main focus is on the v4 version, and new search functionality backed by the Microsoft Graph Search API will be v4 only.
 
@@ -38,7 +52,7 @@ Here is the list of supported browsers:
 - Edge Chromium
 - Brave
 
-**We don't support Internet Explorer 11**. We think there are plenty of other options for enteprise scenarios in the market. Maybe it's time to move on. For developers, it represents an **huge** ammount of time to make the solution compatible for a very low benefit. Hope you understand, ain't personal ;).
+**PnP Modern Search do not explicitly support Internet Explorer 11**. We think there are plenty of other options for enteprise scenarios in the market. Maybe it's time to move on. For developers, it represents an **huge** amount of time to make the solution compatible for a very low benefit. Hope you understand, ain't personal ;).
 
 ## Extensibility model
 

docs/installation.md

@@ -1,25 +1,42 @@
 # Installation
 
-1. Download the latest SharePoint Framework packages **pnp-modern-search-parts.sppkg** and **pnp-modern-search-extensibility.sppkg** from the [GitHub repository](https://github.com/microsoft-search/pnp-modern-search/releases).
-2. Add the packages to your global app catalog or site collection app catalog. If you don't have an app catalog, follow this [procedure](https://docs.microsoft.com/en-us/sharepoint/use-app-catalog) to create one.
-
-    **You must deploy the two SPFx packages to get it work.**
+1. Download the latest SharePoint Framework packages **pnp-modern-search-parts.sppkg** from the [GitHub repository](https://github.com/microsoft-search/pnp-modern-search/releases).
+2. Add **pnp-modern-search-parts.sppkg** to the global teant app catalog or a site collection app catalog. If you don't have an app catalog, follow this [procedure](https://docs.microsoft.com/en-us/sharepoint/use-app-catalog) to create one. 
 
     !["App Catalog "](./assets/app_catalog.png){: .center}
 
     > * The packages are deployed in the general Office 365 CDN meaning **we don't host any code**.
 
     > * For the **pnp-modern-search-parts.sppkg** package, you can choose to make the solution available in [all sites](https://docs.microsoft.com/en-us/sharepoint/dev/spfx/tenant-scoped-deployment) or force to install an app to the site every time.
 
-    > * The solution asks the following API permissions by default to enhance the experience. These permissions are **not mandatory**. If you don't accept them, you will simpy have less available features.
+    > * The solution asks the following API permissions by default to enhance the experience. These permissions are **not mandatory**. If you don't accept them, you will simply have less available features.
+
+    > * You can approve scopes from the API Access screen in the SharePoint Admin Center: https://<tenant>-admin.sharepoint.com/_layouts/15/online/AdminHome.aspx#/webApiPermissionManagement If you'd like more details on this step, please see the [Approving Scopes](#approving-scopes) section below.
 
     | Requested API permission | Used for |
     | -------------- | --------- |
     | _User.Read_ | The Microsoft Graph Toolkit [persona card](https://docs.microsoft.com/en-us/graph/toolkit/components/person-card#microsoft-graph-permissions) in the people layout.  |
     | _People.Read_ | Same as above.
     | _Contacts.Read_ | Same as above.
-    | _User.ReadBAsic.All_ | Same as above.
+    | _User.ReadBasic.All_ | Same as above.
+    | _Files.Read.All_ | Allow search for files using Graph API (Drive / Drive Items).
+    | _Mail.Read_ | Allow search for user's e-mail using Graph API (Messages).
+    | _Calendars.Read_ | Allow search for user's calendar appointments using Graph API (Events).
+    | _Sites.Read.All_ | Allow search for sites using Graph API (Sites / List Items).
+    | _ExternalItem.Read.All_ | Allow search for connector items using Graph API (External Items).
 
 3. Add the Web Parts to a SharePoint and start building!
 
-!["Available Web Parts"](./assets/webparts.png){: .center}
+!["Available Web Parts"](./assets/webparts.png){: .center}
+
+# Approving Scopes
+
+You can approve the required scopes in the SharePoint Admin Center on the API Access page. When you visit that page, you will see any pending requests. The screenshot below shows the pending requests for the v4 solution.
+
+!["App Catalog"](./assets/api-access-pending.jpg){: .center}
+
+You'll need to approve each request one at a time. If you have questions about what the requested scopes mean and what permissions they provide, check the article [Manage access to Azure AD-secured APIs](https://docs.microsoft.com/en-us/sharepoint/api-access).
+
+After you approve each request your view will be as shown in the screenshot below.
+
+!["App Catalog"](./assets/api-access-approved.jpg){: .center}

docs/usage/search-box/index.md

@@ -2,28 +2,28 @@
 
 The 'Search box' Web Part allows users to enter free text search queries connected to a 'Search Results' Web Part.
 
-!["pnp Search Box Web Part"](../../assets/webparts/search_box/search_box_wp_picker.png){: .center}
+!["pnp Search Box Web Part"](../../assets/webparts/search-box/search_box_wp_picker.png){: .center}
 
-!["pnp Search Box Web Part"](../../assets/webparts/search_box/search_box_wp_default.png){: .center}
+!["pnp Search Box Web Part"](../../assets/webparts/search-box/search_box_wp_default.png){: .center}
 
 ## Configuration
 
 ### Search box settings
 
-!["Search Box settings"](../../assets/webparts/search_box/search_box_settings.png){: .center}
+!["Search Box settings"](../../assets/webparts/search-box/search_box_settings.png){: .center}
 
 | Setting | Description | Default value |
 | ------- |---------------- | ---------- |
 | **Placeholder text** | The placeholder text to display in the search box. | _"Enter your search terms..."_
-| **Send the query to a new page** | Sends the search query text to a new page. From here you can select the page URL, the open behavior and send method (URL fragment '#' or a query string parameter). | False.
+| **Send the query to a new page** | Sends the search query text to a new page. From here you can select the page URL, the open behavior and send method (URL fragment '#' or a query string parameter). The input value can be transformed before sending it to another page. `{inputQueryText}` is replaced with the value from the search box and [other tokens](../search-results/tokens.md) are also supported. | False.
 
 ### Query suggestions
 
-!["Search Box suggestions"](../../assets/webparts/search_box/search_box_suggestions.png){: .center}
+!["Search Box suggestions"](../../assets/webparts/search-box/search_box_suggestions.png){: .center}
 
 The query suggestions allows users to easily find relevant query keywords based on their entry:
 
-!["Search Box suggestions"](../../assets/webparts/search_box/suggestions_demo.png){: .center}
+!["Search Box suggestions"](../../assets/webparts/search-box/suggestions_demo.png){: .center}
 
 | Setting | Description | Default value |
 | ------- |---------------- | ---------- |
@@ -33,6 +33,6 @@ The query suggestions allows users to easily find relevant query keywords based
 
 ### Connections
 
-!["Search Box connections"](../../assets/webparts/search_box/dynamic_data_source.png){: .center}
+!["Search Box connections"](../../assets/webparts/search-box/dynamic_data_source.png){: .center}
 
-Optionally, you can set a default query text coming from an other dynamic data source on the page. For instance, connect the search box to a page environment variable like a query string parameter. The value retrieved from a connected data source will be displayed automatically at page load in the text box if present and broadcasted to any other Web Parts connected to the search box Web Part (ex: a 'Search Results' Web Part) resulting to a cascading effect.
+Optionally, you can set a default query text coming from an other dynamic data source on the page. For instance, connect the search box to a page environment variable like a query string parameter. The value retrieved from a connected data source will be displayed automatically at page load in the text box if present and broadcasted to any other Web Parts connected to the search box Web Part (ex: a 'Search Results' Web Part) resulting to a cascading effect.

docs/usage/search-filters/index.md

@@ -1,6 +1,6 @@
 # Search Filters Web Part
 
-The 'Data Filters' Web Part allows to filter the current results displayed in a 'Search Results' Web Part. This component is higly configurable to meet you requirements and it works for all data sources.
+The 'Filters' Web Part allows to filter the current results displayed in a 'Search Results' Web Part. This component is higly configurable to meet you requirements and it works for all data sources.
 
 !["PnP Search Filters Web Part"](../../assets/webparts/search-filters/search_filters_wp_picker.png){: .center}
 
@@ -11,7 +11,7 @@ The 'Data Filters' Web Part allows to filter the current results displayed in a
 
 ### Connection
 
-To use the data filters, we must first connect it to one or multiple 'Search Results' Web Parts. In the other hand, you must conenct back those Web Parts to the 'Data Filters' one. It is a **two-ways connection**.
+To use the filters, we must first connect it to one or multiple 'Search Results' Web Parts. In the other hand, you must connect back those Web Parts to the 'Filters' one. It is a **two-ways connection**.
 
 !["Filters connection"](../../assets/webparts/search-filters/wp_connection.png){: .center} 
 
@@ -33,7 +33,8 @@ The filter settings are as follow:
 |------------|-----------------|
 | **Display Name** | A friendly name for the filter |
 | **Filter field** | The internal data source field to use as filter. Here you can select a field from the current data source (if data have been already retrieved) of type your own custom value (press enter to validate).
-| **Template** | The template to use to display filter values. The builtin templates are: </br><ul><li>**Check box** <p align="center">!["Check box"](../../assets/webparts/search-filters/checkbox_template.png)</p></li><li>**Date range** <p align="center">!["Date range"](../../assets/webparts/search-results/daterange_template.png)</p></li><li>**Date interval** <p align="center">!["Date interval"](../../assets/webparts/search-filters/dateinterval_template.png)</p></li><li>**Combo** <p align="center">!["Combo"](../../assets/webparts/search-filters/combo_template.png)</p></br> You can search a value directly in the list by typing keywords in the combo text field.</li></ul>
+| **# of values** | The maximum number of filter values/buckets to return (may be restricted by the API).
+| **Template** | The template to use to display filter values. The builtin templates are: </br><ul><li>**Check box** <p align="center">!["Check box"](../../assets/webparts/search-filters/checkbox_template.png)</p></li><li>**Date range** <p align="center">!["Date range"](../../assets/webparts/search-filters/daterange_template.png)</p></li><li>**Date interval** <p align="center">!["Date interval"](../../assets/webparts/search-filters/dateinterval_template.png)</p></li><li>**Combo** <p align="center">!["Combo"](../../assets/webparts/search-filters/combo_template.png)</p></br> You can search a value directly in the list by typing keywords in the combo text field.</li></ul>
 | **Filter type** | Specify if the filter is a 'static' filter or a 'refiner' filter. See below for more information.
 | **Expand by default** | If applicable for the selected template, display values as expanded.
 | **Show count** | If applicable for the selected template, display counts for values.
@@ -44,7 +45,7 @@ The filter settings are as follow:
 
 ### Operator between filters
 
-!["Operator filters"](../../assets/webparts/search-results/operator_filters.png){: .center} 
+!["Operator filters"](../../assets/webparts/search-filters/operator_filters.png){: .center} 
 
 You can select the operator to use between filters (OR or AND).
 
@@ -63,5 +64,5 @@ Using an indexed property bag value could be useful to store information about a
 
 `L0|#a2cf1afb-44b6-4cf4-bf37-642bb2e9bff3|Category 1;L0|#02e3406c0-1048-4bce-90eb-e7a51dfa7f31|Category3;L0|#07e094327-23d7-48af-9699-781eb26dc40f|Category2`
 
-These taxonomy values can then be used in the Data Filters Web Part using a `RefinableStringXX` search managed property to filter specific sites or elements. As an example, you can refer to the ["Create an end-to-end Office 365 groups provisioning solution"](https://github.com/pnp/tutorial-workspace-provisioning) tutorial GitHub project to leverage this format.
+These taxonomy values can then be used in the Filters Web Part using a `RefinableStringXX` search managed property to filter specific sites or elements. As an example, you can refer to the ["Create an end-to-end Office 365 groups provisioning solution"](https://github.com/pnp/tutorial-workspace-provisioning) tutorial GitHub project to leverage this format.
 

docs/usage/search-results/connections/index.md

@@ -32,7 +32,7 @@ Optionaly, you can set a default query text **when there is no value for the con
 
 !["Verticals"](../../../assets/webparts/search-results/connections/verticals.png){: .center}
 
-When you connect the Web Part to a Data Verticals one, you must specify on which vertical the Web Part content should be displayed.
+When you connect the Web Part to a Verticals one, you must specify on which vertical the Web Part content should be displayed.
 
 !["Select vertical"](../../../assets/webparts/search-results/connections/select_vertical.png){: .center}
 

docs/usage/search-results/layouts/debug.md

@@ -12,7 +12,7 @@ The template context object exposes the following properties:
 "filters": {
     "selectedFilters": "<List of currently selected filters>",
     "filterOperator": "<Operator to use between filters>",
-    "instanceId": "<The connected Data Filters Web Part instance ID>",
+    "instanceId": "<The connected Filters Web Part instance ID>",
     "filtersConfiguration": "<The filters configuration>"
 },
 "inputQueryText": "<The current input query text (Ex: search box text)>",