SPFx Top Actions Doc Clarification Suggestion

[andrewconnell]

Target SharePoint environment

SharePoint Online

What SharePoint development model, framework, SDK or API is this about?

💥 SharePoint Framework

Developer environment

macOS

What browser(s) / client(s) have you tested

• 💥 Internet Explorer
• 💥 Microsoft Edge
• 💥 Google Chrome
• 💥 FireFox
• 💥 Safari
• mobile (iOS/iPadOS)
• mobile (Android)
• not applicable
• other (enter in the "Additional environment details" area below)

Additional environment details

n/a

Describe the bug / error

The internal docs for Top Actions aren't clear which are used to generate the published docs & this make IntelliSense unclear in VSCode.

Specifically...

ITopActions.onExecute()

• @microsoft/sp-top-actions | index-internal.d.ts | ITopActions.onExecute
• ref to gen'd docs

The descriptions for the two parameters passed into the method could be improved to provide clarity for developers without having to go to the docs.

I suggest:

/**
 * Triggered once the top action configuration state has been executed for the specified property path
 * 
 * @param actionName - the `targetProperty` of the control that triggered the event
 * @param updatedValue - when the control that triggered the event is a dropdown field, this is the `key` of the selection dropdown option; otherwise when the control is a button, this is `true`
 */
onExecute(actionName: string, updatedValue: any): void;

Why?

• it's not clear that actionName === targetProperty from the API... as there's nothing that implies uniqueness on each Top Action control
• the name updatedValue implies something changed by clicking the control, which isn't the case... nothing updated... it's either true or is the key of the selected dropdown option

ITopActionsButtonProps.icon

• ref to gen'd docs

Furthermore, the icon property for a button is a string but doesn't give any context on where to get the icon from. It's confusing as to why this is different from the icon on a dropdown control which has its own interface ITopActionsDropdownOptionIconProps.

I can't suggest anything here because I'm confused...

• The sample in the docs set the button's icon to SharePointLogo...
• Where does this come from? Fluent UI Icon?
• What other options are available?
• Why is a button's icon different from a dropdown option icon?

Steps to reproduce

n/a

Expected behavior

n/a

Thank you for reporting this issue. We will be triaging your incoming issue as soon as possible.

[github-actions]

Thank you for taking the time to file an issue. We periodically archive older or inactive issues as part of our issue management process, which automatically closes them once they are archived.

If you’d like to understand more about why and how we handle archived (closed) issues, please see Our approach to closed issues.

We appreciate your contribution and if this is still an active issue with the latest SPFx versions, please do resubmit the details. We needed to perform a cleanup, so that we can start with a clean table with a new process. We apologize for the inconvenience this might cause.