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)
• [X] 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

[ghost]

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