Merge branch 'main' into live

Author: github-actions

docs/design/add-in-commands.md

@@ -1,7 +1,7 @@
 ---
 title: Basic concepts for add-in commands
 description: Learn how to add custom ribbon buttons and menu items to Excel, Outlook, PowerPoint, and Word as part of an Office Add-in.
-ms.date: 05/19/2025
+ms.date: 06/27/2025
 ms.topic: overview
 ms.localizationpriority: high
 ---
@@ -39,21 +39,24 @@ There are two types of add-in commands, based on the kind of action that the com
 
 ## Location of add-in commands
 
-When a user installs an add-in, the location of its commands depends on the application, platform, and context. Add-in commands are found on the ribbon, in a default or custom tab, or on an action bar (only applies to certain Outlook platforms). They appear in the UI as a button or an item in a drop-down menu.
+When a user installs an add-in, the add-in's commands are found on the ribbon, in a built-in Office tab or a custom tab that is specified in the manifest. (You can also put add-in commands on a [custom contextual tab](#contextual-tabs) that your add-in code defines at runtime.) They appear in the UI as a button or an item in a drop-down menu.
+
+> [!NOTE]
+> On certain Outlook platforms, the commands are on an action bar rather than the ribbon.
 
 For add-in commands that appear on the ribbon, if you're using the simplified ribbon layout, the add-in name is removed from the app bar. Only the add-in command button on the ribbon remains.
 
 As the ribbon or action bar gets more crowded, add-in commands are displayed in the overflow menu. Commands for the same add-in are usually grouped together.
 
 ### Excel, PowerPoint, and Word
 
-The default tab depends on the application and context. For Excel, PowerPoint, and Word, the default tab is **Home**.
+The following shows an example of add-in commands in a custom group on the **Data** tab of the Excel ribbon.
 
 ![Sample add-in commands highlighted in the Excel ribbon.](../images/add-in-commands-1.png)
 
 ### Outlook
 
-For Outlook, the default location of an add-in command is based on the platform and current Outlook mode. For guidance, see [Use add-ins in Outlook](https://support.microsoft.com/office/1ee261f9-49bf-4ba6-b3e2-2ba7bcab64c8).
+For Outlook, when you want an add-in command on a built-in ribbon tab, rather than creating your own, the command will appear on the default tab based on the platform and current Outlook mode. For guidance, see [Use add-ins in Outlook](https://support.microsoft.com/office/1ee261f9-49bf-4ba6-b3e2-2ba7bcab64c8).
 
 ### Drop-down menu
 
@@ -67,7 +70,10 @@ The following command capabilities are currently supported.
 
 ### Extension points
 
-- Ribbon tabs - Extend built-in tabs or create a new custom tab. An add-in can have just one custom tab.
+- Ribbon tabs - Extend built-in tabs or create a new custom core tab. An add-in can have just one custom core tab. (You can also put add-in commands on a [custom contextual tab](#contextual-tabs).)
+
+  > [!NOTE]
+  > For Outlook, custom tabs are only supported in classic Outlook on Windows. In Outlook on the web, on Mac, and in the new Outlook on Windows, you can put custom groups of controls on one of the built-in ribbon tabs instead.
 - Context menus - Extend selected context menus.
 
 ### Control types
@@ -82,7 +88,7 @@ You can specify whether the command is available when your add-in launches, and
 > [!NOTE]
 > This feature isn't supported in all Office applications or scenarios. For more information, see [Change the availability of add-in commands](disable-add-in-commands.md).
 
-### Position on the ribbon (preview)
+### Position on the ribbon
 
 You can specify where a custom tab appears on the Office application's ribbon, such as "just to the right of the Home tab".
 
@@ -98,7 +104,7 @@ You can insert the built-in Office ribbon buttons into your custom command group
 
 ### Contextual tabs
 
-You can specify that a tab is only visible on the ribbon in certain contexts, such as when a chart is selected in Excel.
+You can specify a custom contextual tab; that is, a tab that is only visible on the ribbon in certain contexts, such as when a chart is selected in Excel.
 
 > [!NOTE]
 > This feature isn't supported in all Office applications or scenarios. For more information, see [Create custom contextual tabs in Office Add-ins](contextual-tabs.md).

docs/design/contextual-tabs.md

@@ -1,7 +1,7 @@
 ---
 title: Create custom contextual tabs in Office Add-ins
 description: Learn how to add custom contextual tabs to your Office Add-in.
-ms.date: 03/26/2025
+ms.date: 06/30/2025
 ms.topic: how-to
 ms.localizationpriority: medium
 ---
@@ -72,7 +72,7 @@ The following is an example.
         "tabs": [
             "groups": [
                 {
-                    "id": "contextualTab",
+                    "id": "ContosoGroup",
                     ...
                     "icons": [
                         {
@@ -90,7 +90,7 @@ The following is an example.
                     ],
                     "controls": [
                         {
-                            "id": "contextualButton",
+                            "id": "WriteDataButton",
                             ...
                             "icons": [
                                 {
@@ -141,15 +141,15 @@ The following is an example.
 ---
 
 > [!IMPORTANT]
-> When you move your add-in from development to production, remember to update the URLs in your manifest as needed (such as changing the domain from `localhost` to `contoso.com`).
+> When you move your add-in from development to staging or production, remember to update the URLs in your manifest as needed (such as changing the domain from `localhost` to `contoso.com`).
 
 ## Define the groups and controls that appear on the tab
 
 Unlike custom core tabs, which are defined in the manifest, custom contextual tabs are defined at runtime with a JSON blob. Your code parses the blob into a JavaScript object, and then passes the object to the [Office.ribbon.requestCreateControls](/javascript/api/office/office.ribbon?view=common-js&preserve-view=true#office-office-ribbon-requestcreatecontrols-member(1)) method. Custom contextual tabs are only present in documents on which your add-in is currently running. This is different from custom core tabs which are added to the Office application ribbon when the add-in is installed and remain present when another document is opened. Also, the `requestCreateControls` method may be run only once in a session of your add-in. If it's called again, an error is thrown.
 
 We'll construct an example of a contextual tabs JSON blob step-by-step. The full schema for the contextual tab JSON is at [dynamic-ribbon.schema.json](https://developer.microsoft.com/json-schemas/office-js/dynamic-ribbon.schema.json). If you're working in Visual Studio Code, you can use this file to get IntelliSense and to validate your JSON. For more information, see [Editing JSON with Visual Studio Code - JSON schemas and settings](https://code.visualstudio.com/docs/languages/json#_json-schemas-and-settings).
 
-1. Begin by creating a JSON string with two array properties named `actions` and `tabs`. The `actions` array is a specification of all the functions that can be executed by controls on the contextual tab. The `tabs` array defines one or more contextual tabs, *up to a maximum of 20*.
+1. Begin by creating a JSON string with two array properties named `actions` and `tabs`. The `actions` array is a specification of all the functions that can be executed by controls on the contextual tab. The `tabs` array defines one or more contextual tabs.
 
     ```json
     '{
@@ -181,7 +181,7 @@ We'll construct an example of a contextual tabs JSON blob step-by-step. The full
 
     - The `id` property is required. Use a brief, descriptive ID that is unique among all contextual tabs in your add-in.
     - The `label` property is required. It's a user-friendly string to serve as the label of the contextual tab.
-    - The `groups` property is required. It defines the groups of controls that will appear on the tab. It must have at least one member *and no more than 20*. (There are also limits on the number of controls that you can have on a custom contextual tab and that will also constrain how many groups that you have. See the next step for more information.)
+    - The `groups` property is required. It defines the groups of controls that will appear on the tab. It must have at least one member.
 
     > [!NOTE]
     > The tab object can also have an optional `visible` property that specifies whether the tab is visible immediately when the add-in starts up. Since contextual tabs are normally hidden until a user event triggers their visibility (such as the user selecting an entity of some type in the document), the `visible` property defaults to `false` when not present. In a later section, we show how to set the property to `true` in response to an event.
@@ -204,9 +204,6 @@ We'll construct an example of a contextual tabs JSON blob step-by-step. The full
     - The `icon` property's value is an array of objects that specify the icons that the group will have on the ribbon depending on the size of the ribbon and the Office application window.
     - The `controls` property's value is an array of objects that specify the buttons and menus in the group. There must be at least one.
 
-    > [!IMPORTANT]
-    > *The total number of controls on the whole tab can be no more than 20.* For example, you could have 3 groups with 6 controls each, and a fourth group with 2 controls, but you can't have 4 groups with 6 controls each.  
-
     ```json
     {
         "id": "CustomGroup111",

docs/develop/dialog-api-in-office-add-ins.md

@@ -1,7 +1,7 @@
 ---
 title: Use the Office dialog API in your Office Add-ins
 description: Learn the basics of creating a dialog box in an Office Add-in.
-ms.date: 02/25/2025
+ms.date: 06/25/2025
 ms.topic: how-to
 ms.localizationpriority: medium
 ---
@@ -58,7 +58,7 @@ By default, the dialog box will occupy 80% of the height and width of the device
 Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 });
 ```
 
-For a sample add-in that does this, see [Build Office Add-ins for Excel](https://github.com/OfficeDev/TrainingContent/tree/master/OfficeAddin/02%20Building%20Add-ins%20for%20Microsoft%20Excel). For more samples that use `displayDialogAsync`, see [Code samples](#code-samples).
+For a sample add-in that does this, see [Excel Tutorial - Completed](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/tutorials/excel-tutorial). For more samples that use `displayDialogAsync`, see [Code samples](#code-samples).
 
 Set both values to 100% to get what is effectively a full screen experience. The effective maximum is 99.5%, and the window is still moveable and resizable.
 
@@ -425,7 +425,8 @@ Even when you don't have your own close-dialog UI, an end user can close the dia
 
 All of the following samples use `displayDialogAsync`. Some have NodeJS-based servers and others have ASP.NET/IIS-based servers, but the logic of using the method is the same regardless of how the server-side of the add-in is implemented.
 
-- [Training Content / Building Add-ins](https://github.com/OfficeDev/TrainingContent/tree/master/OfficeAddin/02%20Building%20Add-ins%20for%20Microsoft%20Excel)
+- [Excel Tutorial - Completed](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/tutorials/excel-tutorial)
+- [Excel Shared Runtime Scenario](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/excel-shared-runtime-scenario)
 - [Office Add-in Microsoft Graph ASPNET](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/auth/Office-Add-in-Microsoft-Graph-ASPNET)
 - [Office Add-in Microsoft Graph React](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/auth/Office-Add-in-Microsoft-Graph-React)
 - [Office Add-in NodeJS SSO](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/auth/Office-Add-in-NodeJS-SSO)
@@ -437,7 +438,6 @@ All of the following samples use `displayDialogAsync`. Some have NodeJS-based se
 - [Outlook Add-in Actionable Message](https://github.com/OfficeDev/Outlook-Add-In-Actionable-Message)
 - [Outlook Add-in Sharing to OneDrive](https://github.com/OfficeDev/Outlook-Add-in-Sharing-to-OneDrive)
 - [PowerPoint Add-in Microsoft Graph ASPNET InsertChart](https://github.com/OfficeDev/PowerPoint-Add-in-Microsoft-Graph-ASPNET-InsertChart)
-- [Excel Shared Runtime Scenario](https://github.com/OfficeDev/Office-Add-in-samples/tree/main/Samples/excel-shared-runtime-scenario)
 
 ## See also
 

docs/excel/custom-functions-data-types-concepts.md

@@ -1,15 +1,15 @@
 ---
 title: Custom functions and data types
 description: Use Excel data types with your custom functions and Office Add-ins.
-ms.date: 06/15/2025
+ms.date: 06/22/2025
 ms.topic: overview
 ms.custom: scenarios:getting-started
 ms.localizationpriority: medium
 ---
 
 # Use data types with custom functions in Excel
 
-Data types expand the Excel JavaScript API to support data types beyond the original four cell value types (string, number, boolean, and error). Data types include support for web images, formatted number values, entities, and arrays within entities.
+Data types expand the Excel JavaScript API to support data types beyond the original four cell value types (string, number, boolean, and error). Data types include support for web images, formatted numbers, entities, and arrays within entities.
 
 These data types amplify the power of custom functions, because custom functions accept data types as both input and output values. You can generate data types through custom functions, or take existing data types as function arguments into calculations. Once the JSON schema of a data type is set, this schema is maintained throughout the calculations.
 
@@ -28,21 +28,21 @@ Custom functions projects include a JSON metadata file. This JSON metadata file
 
 For a full description of the manual JSON metadata creation process, see [Manually create JSON metadata for custom functions](custom-functions-json.md). See [allowCustomDataForDataTypeAny](custom-functions-json.md#allowcustomdatafordatatypeany) for additional details about this property.
 
-## Output a formatted number value
+## Output a formatted number
 
-The following code sample shows how to create a [FormattedNumberCellValue](/javascript/api/excel/excel.formattednumbercellvalue) data type with a custom function. The function takes a basic number and a format setting as the input parameters and returns a formatted number value data type as the output.
+The following code sample shows how to create a formatted number with a custom function. This uses the [DoubleCellValue](/javascript/api/excel/excel.doublecellvalue) object. The function takes a basic number and a format setting as the input parameters and returns a formatted number as double data type for the output.
 
 ```js
 /**
- * Take a number as the input value and return a formatted number value as the output.
+ * Take a number as the input value and return a double as the output.
  * @customfunction
  * @param {number} value
  * @param {string} format (e.g. "0.00%")
  * @returns A formatted number value.
  */
 function createFormattedNumber(value, format) {
     return {
-        type: "FormattedNumber",
+        type: "Double",
         basicValue: value,
         numberFormat: format
     }

docs/excel/custom-functions-get-started.md

@@ -1,7 +1,7 @@
 ---
 description: Tips and best practices for Excel custom functions in your Office Add-ins.
 title: Best practices for custom functions in Excel
-ms.date: 12/20/2024
+ms.date: 06/22/2025
 ms.topic: overview
 ms.custom: scenarios:getting-started
 ms.localizationpriority: medium
@@ -94,7 +94,7 @@ Another way to return multiple results is to use multiple functions and return a
 
 ### Complex data structures
 
-[Data types](custom-functions-data-types-concepts.md) are the best way to handle complex data structures in custom functions add-ins. Data types support [Excel errors](custom-functions-errors.md) and [formatted number values](custom-functions-data-types-concepts.md#output-a-formatted-number-value). Data types also allow for designing [entity value cards](excel-data-types-entity-card.md), extending Excel data beyond the 2-dimensional grid.
+[Data types](custom-functions-data-types-concepts.md) are the best way to handle complex data structures in custom functions add-ins. Data types support [Excel errors](custom-functions-errors.md) and formatted numbers as [doubles](custom-functions-data-types-concepts.md#output-a-formatted-number). Data types also allow for designing [entity value cards](excel-data-types-entity-card.md), extending Excel data beyond the 2-dimensional grid.
 
 ## Improve the user experience of calls to external services
 

docs/excel/excel-add-ins-notes.md

@@ -1,7 +1,7 @@
 ---
 title: Work with notes using the Excel JavaScript API
 description: Information on using the APIs to add, remove, and edit notes.
-ms.date: 04/04/2025
+ms.date: 06/26/2025
 ms.localizationpriority: medium
 ---
 
@@ -71,7 +71,7 @@ await Excel.run(async (context) => {
 
 ## Change the size of a note
 
-By default, notes are automatically sized to fit the content. To make notes larger or smaller, use the [Note.height](/javascript/api/excel/excel.note#excel-excel-note-height-member) and [Note.width](/javascript/api/excel/excel.note#excel-excel-note-width-member) properties.
+To make notes larger or smaller, use the [Note.height](/javascript/api/excel/excel.note#excel-excel-note-height-member) and [Note.width](/javascript/api/excel/excel.note#excel-excel-note-width-member) properties.
 
 The following sample shows how to set the size of the first note in the `NoteCollection`.